view release on metacpan or  search on metacpan

README  view on Meta::CPAN

  HTML Attributes
    Add data-help="My Topic" and (optionally) data-content="The help
    content" attributes to any HTML elements.

    *   data-help Required. The name of the help topic. If data-content is
        omitted, content will come from an article with this Name. See
        "Async".

    *   data-content Optional. The help content. If omitted, asynchronous
        mode will be used to dynamically retrieve the help content. See
        "Async".

    *   data-action Optional. The action to use when adding the help icon to
        the DOM. Defaults to "append". See "Help Selector Rules" section for
        more details.

   Example
    A Mason template might add the data-help attribute to an element along
    with some static help content that includes custom HTML

        <button data-help="Save Widget"
                data-content="Saves the Widget to RT"
                data-action="after">Save</button>

    Or we could omit the data-content altogether to have RT return the help
    content from the matching "List Sprockets" article when the user hovers
    over the help icon

        <button data-help="List Sprockets" data-action="after">List</button>

  JavaScript
    Call addPopupHelpItems to add one or more rules to the list of help
    topics on a page that should be decorated with help icons.

    The addPopupHelpItems function populates the pagePopupHelpItems array
    with a list of declarative rules that define elements in the DOM that
    should have associated help icons. If a rule's selector key matches one
    or more elements, its action key will determine where a help icon should
    be added to the DOM with help content corresponding to the content key
    or from a valid help article with the same name as the title key.

    Any rules thus added will be picked up and processed on page load when
    all of the accumulated rules are executed when renderPopupHelpItems is
    called (for example, in the Elements/Footer component in the page
    footer).

    This includes the default rule

        { selector: "[data-help]" }

    which matches anything with a data-help attribute and therefore powers
    the "HTML Attributes" method.

    This method of using JavaScript allows for tremendous flexibly
    annotating the DOM with help items, even after it has been
    rendered--perhaps by other templates altogether, making it attractive as
    a mechanism for users to annotate aspects of RT--however it has been
    installed for them, including any and all extensions--simply by
    inspecting what is rendered to the browser and writing the appropriate
    rules. Importantly, these rules can usually be added to one place (e.g.
    in a page callback somewhere) so they do not need to overlay virtually
    every template in RT just to add help icons throughout.

   Help Selector Rules
    A help selector rule is a JavaScript object with the following keys:

    *   selector - *String*

        Required. Defines which DOM elements should receive a help icon. Can
        match 0, 1, or many elements. Selectors matching 0 elements have no
        impact on the DOM.

        *   *String* A JQuery selector string that defines the matching DOM
            elements

    *   title - *String*

        Optional. The help topic(s) that should be associated with the
        element(s) matching the selector

        *   *String* The name of the help topic that should be matched
            against the article Name. If the selector matches exactly one
            element, this will be its help topic. If more than one element
            are matched, they will all get this same help topic.

    *   content - *String*

        Optional. The help content to be displayed in the popup when the
        user hovers over the help icon.

        If missing, asynchronous mode is automatically triggered (see
        "Async")

        *   *String* The help content. May contain HTML. Will be applied for
            all elements matched by selector.

    *   action - *String*

        Optional. The action that should be taken with each help icon that
        results from the application of selector. Responsible for actually
        adding the help icons to the DOM. This controls, for example, where
        the icon should be rendered relative to the matching DOM element.

        If missing, "append" is the default.

        *   *String*

            *   *before* The help icon will be prepended to the DOM *before*
                the element(s) matched by selector

            *   *after* Default. The help icon will be appended to the DOM
                *after* the element(s) matched by selector

            *   *append* The help icon will be appended to the end of the
                DOM element(s) matched by selector

            *   *prepend* The help icon will be prepended to the beginning
                of the DOM element(s) matched by selector

            *   *replace* The help icon will be inserted into the DOM *in
                place of* the element(s) matched by selector. This action is