CiviCRM 4.3: using the new help functions in custom forms

If you write your own CiviCRM extensions, you probably have custom forms.

In CiviCRM 4.2 and previous, you could show help icons in the following way:

<div class="helpicon">
    <span id="mymodule-myfield-help" style="display:none">
        <div class="crm-help">Help text here.</div>

This shows a small help icon, and clicking on it would display a help bubble.

In CiviCRM 4.3, to (presumably) make it more dynamic, and lessen the page load size, help texts are loaded using Ajax. To convert:

1- In your template (tpl) file, replace the "helpicon" with:

{help id="mymodule-myfield-help" file="CRM/MyExtension/Form/MyForm.hlp"}

2- Create a MyForm.hlp file in the same directory as the template file:

{htxt id="mymodule-myfield-help-title"}
    My Field Title

{htxt id="mymodule-myfield-help"}
    My help text here
    <strong>may include html</strong>

There are no restrictions on how to name the ID of the help item, but to avoid CSS/JS namespace clashes, you should use something that reflects your filename hierarchy. Only the "-title" id is requested explicitely, and is appended to your help ID.

You can put multiple help definitions in the same ".hlp" file. That's the aim of the "htxt" blocks: it is equivalent to a "if" statement ("if $ == "mymodule-myfield-help"). You can see more examples in the CiviCRM core .tpl files in the templates/ directory.

A few options are available:

  • {help id="mymodule-myfield-help" file="CRM/MyExtension/Form/MyForm.hlp" title="My help title"}

    • "title" will be used as the mouse-over text shown over the help icon in the form. Otherwise, defaults to the id-title (ex: mymodule-myfield-help-title), and appends "Help" to it. (try it, you'll see)
  • {help id="mymodule-myfield-help" file="CRM/MyExtension/Form/MyForm.hlp" foo="hello world"}

    • you can add custom parameters to the help ajax request, and it will be explosed in the .hlp file as an option in the {$params} element.

For example:

{htxt id="mymodule-myfield-help"}
    <div>My help text here.</div>
    <div>Foo value: {$}</div>