view release on metacpan or  search on metacpan

lib/RT/Extension/InlineHelp.pm  view on Meta::CPAN

attributes to any HTML elements.

=over

=item * C<data-help>
Required. The name of the help topic. If C<data-content>
is omitted, content will come from an article with this Name.
See L</Async>.

=item * C<data-content>
Optional. The help content. If omitted, asynchronous mode will be used to dynamically retrieve
the help content. See L</Async>.

=item * C<data-action>
Optional. The action to use when adding the help icon to the DOM. Defaults to C<"append">. See
L</Help Selector Rules> section for more details.

=back

=head3 Example

A Mason template might add the C<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 C<data-content> altogether to have RT return the help content from the
matching C<"List Sprockets"> article when the user hovers over the help icon

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

=head2 JavaScript

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

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

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

This includes the default rule

    { selector: "[data-help]" }

which matches anything with a C<data-help> attribute and therefore powers the L</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.

=head3 Help Selector Rules

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

=over

=item * C<selector> - I<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.

=over

=item * I<String>
A JQuery selector string that defines the matching DOM elements

=back

=item * C<title> - I<String>

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

=over

=item * I<String>
The name of the help topic that should be matched against the article Name. If the C<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.

=back

=item * C<content> - I<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 L</Async>)

=over

=item * I<String>
The help content. May contain HTML. Will be applied for all elements matched by C<selector>.

=back

=item * C<action> - I<String>

Optional. The action that should be taken with each help icon that results from the application
of C<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, C<"append"> is the default.

=over

=item * I<String>

=over