Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update tag.md #287

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Update tag.md #287

wants to merge 5 commits into from

Conversation

rogercreagh
Copy link
Contributor

@rogercreagh rogercreagh commented Jul 21, 2024

User description

  • added note on default to mode attribute
  • added remote-search to attribute list (required for nested to work correctly owing to joomla-cms bug #43803)
  • added note to ajax mode search min chars
  • added note to nested mode on joomla-cms bug #43705 destroying the hierarchical display

The bug notes (in italics) will need removing as the bugs are fixed


PR Type

Documentation


Description

  • Added note on default value for mode attribute in the tag form field.
  • Introduced remote-search attribute, including its necessity for nested mode and a link to issue #43803.
  • Clarified the minimum character requirement for AJAX search and its configuration.
  • Explained the sorting behavior of tags in AJAX mode.
  • Added note on hierarchy sorting in nested mode and referenced issue #43705.

Changes walkthrough 📝

Relevant files
Documentation
tag.md
Update `tag.md` with additional attributes and bug notes 

docs/general-concepts/forms-fields/standard-fields/tag.md

  • Added note on default value for mode attribute.
  • Added remote-search attribute with explanation and link to issue
    #43803.
  • Added note on minimum characters for AJAX search.
  • Added note on sorting behavior in AJAX mode.
  • Added note on hierarchy sorting and issue #43705 in nested mode.
  • +7/-2     

    💡 PR-Agent usage:
    Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

     - added note on default to mode attribute
     - added remote-search to attribute list (required for nested to work correctly owing to joomla-cms bug #43803)
     - added note to ajax mode search min chars
     - added note to nested mode on joomla-cms bug #43705 destroying the hierarchical display
    @codiumai-pr-agent-pro codiumai-pr-agent-pro bot added the documentation Improvements or additions to documentation label Jul 21, 2024
    Copy link
    Contributor

    PR Reviewer Guide 🔍

    ⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪
    🧪 No relevant tests
    🔒 No security concerns identified
    ⚡ No key issues to review

    Copy link
    Contributor

    codiumai-pr-agent-pro bot commented Jul 21, 2024

    PR Code Suggestions ✨

    CategorySuggestion                                                                                                                                    Score
    Possible issue
    ✅ Correct a typo in the attribute name to ensure proper functionality

    Correct the typo in the attribute name from remote-seach to remote-search to ensure
    consistency and avoid potential issues with attribute recognition in the
    implementation.

    docs/general-concepts/forms-fields/standard-fields/tag.md [19]

    -**remote-seach** (optional) Enables Ajax search - if using mode="nested" you need to set this to "false" or you will only get a partial option list and a broken hierarchy.
    +**remote-search** (optional) Enables Ajax search - if using mode="nested" you need to set this to "false" or you will only get a partial option list and a broken hierarchy.
     

    [Suggestion has been applied]

    Suggestion importance[1-10]: 10

    Why: The typo correction from remote-seach to remote-search is crucial for the attribute to be recognized correctly, preventing potential issues in the implementation.

    10
    Correct the hyperlink to an issue to ensure it directs to the correct page

    Update the issue link for "issue #43705" to match the correct format and ensure it
    is accessible, as the current link is malformed and might lead to a 404 page.

    docs/general-concepts/forms-fields/standard-fields/tag.md [36]

    -**NB** *Currently (J5.1.2 and earlier) selected tags are removed from the list which breaks the hierarchy display* (*see* [*issue #43705*](https://github.com/joomla/joomla-cms/issues/43803])
    +**NB** *Currently (J5.1.2 and earlier) selected tags are removed from the list which breaks the hierarchy display* (*see* [*issue #43705*](https://github.com/joomla/joomla-cms/issues/43705))
     
    • Apply this suggestion
    Suggestion importance[1-10]: 10

    Why: Correcting the malformed hyperlink ensures that users can access the referenced issue, which is important for understanding the context and details.

    10
    Enhancement
    Correct spelling errors to enhance document clarity and professionalism

    Correct the spelling of "heirarchy" to "hierarchy" in two places to maintain
    professionalism and accuracy in documentation.

    docs/general-concepts/forms-fields/standard-fields/tag.md [19-35]

    -only lists a amximum of 30 tags until you search, and orders the list by most used tags first which destroys the heirarchy display.
    -This list is sorted by heirarchy order (ordering in the com_tags tag list view) rather than alphabetically by path name
    +only lists a maximum of 30 tags until you search, and orders the list by most used tags first which destroys the hierarchy display.
    +This list is sorted by hierarchy order (ordering in the com_tags tag list view) rather than alphabetically by path name
     
    • Apply this suggestion
    Suggestion importance[1-10]: 8

    Why: Correcting the spelling of "heirarchy" to "hierarchy" improves the readability and professionalism of the documentation, though it is a minor issue.

    8
    Add a comment to clarify the default setting of an attribute in the example code

    Add a default value for the remote-search attribute in the example code snippet to
    align with the documentation provided above and ensure clarity for users.

    docs/general-concepts/forms-fields/standard-fields/tag.md [65]

    -remote-search="false"
    +remote-search="false"  # default value as per documentation
     
    • Apply this suggestion
    Suggestion importance[1-10]: 7

    Why: Adding a comment to indicate the default value of remote-search enhances clarity for users, but it is a minor enhancement.

    7

    - **id** (optional) is the id to add to the field. Note if none is set this will be the name of the field.
    - **class** (optional) is the class to add to the field.
    - **published** (optional) determines if non published tags should be allowed.
    - **language** (optional) is language to filter the existing tags by.
    - **multiple** (optional) is the ability to add more than 1 tag to the form field.
    - **custom** (optional) if the ajax mode is chosen setting this to "deny" will prevent users from adding in new tags.
    - **remote-seach** (optional) Enables Ajax search - if using mode="nested" you need to set this to "false" or you will only get a partial option list and a broken hierarchy. (*remote-serach="true" (default) only lists a amximum of 30 tags until you search, and orders the list by most used tags first which destroys the heirarchy display. See* [*issue #43803*](https://github.com/joomla/joomla-cms/issues/43803#issuecomment-2234376819))
    Copy link
    Contributor

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Suggestion: Correct a typo in the attribute name to ensure proper functionality [Possible issue, importance: 10]

    Suggested change
    - **remote-seach** (optional) Enables Ajax search - if using mode="nested" you need to set this to "false" or you will only get a partial option list and a broken hierarchy. (*remote-serach="true" (default) only lists a amximum of 30 tags until you search, and orders the list by most used tags first which destroys the heirarchy display. See* [*issue #43803*](https://github.com/joomla/joomla-cms/issues/43803#issuecomment-2234376819))
    **remote-search** (optional) Enables Ajax search - if using mode="nested" you need to set this to "false" or you will only get a partial option list and a broken hierarchy.

    Copy link
    Member

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    Don't merge this change, it's only here for demonstrating an issue for codiumai

    rogercreagh and others added 4 commits July 21, 2024 18:30
    Co-authored-by: codiumai-pr-agent-pro[bot] <151058649+codiumai-pr-agent-pro[bot]@users.noreply.github.com>
    Correct spelling typo in "Quicktask link" sub -head
    
    Changed Quicktask link section text to refer to title which appears as a mouseover the icon, and to state that the language string needs to be in the .sys.ini lanuage file
    
    Added new sub-section Quicktask Icon with explanation and example.
    
    Added fontawesome icon example to the Example section
    
    NB there is also a <quicktask-permission> tag but I can find no information how to use it.

    **Nested mode**

    - The tag dropdown list displays a hierarchical list of tags (shown in a similar way to how categories are shown)
    - You cannot create new tags on the fly
    - This list is sorted by heirarchy order (ordering in the com_tags tag list view) rather than alphabetically by path name
    - **NB** *Currently (J5.1.2 and earlier) selected tags are removed from the list which breaks the hierarchy display* (*see* [*issue #43705*](https://github.com/joomla/joomla-cms/issues/43803])
    Copy link
    Member

    Choose a reason for hiding this comment

    The reason will be displayed to describe this comment to others. Learn more.

    I'm not really happy referencing issues in the manual, this would get an maintenance nightmare and could fill the manual with 1000 of referenced issues and pull requests which often is irrelevant and need to be removed if a pr exists or worse keep in the manual if it never get fixed or if it's an expected behavior.

    It's a different story in the changelog/migration section which automatically gets obsolete with new versions at some point in time.

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    documentation Improvements or additions to documentation Review effort [1-5]: 1
    Projects
    None yet
    Development

    Successfully merging this pull request may close these issues.

    2 participants