CiviCRM 4.3: using the new help functions in custom forms

lun, 2013-03-04 11:03

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>
    </span>
</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}

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

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 $params.id == "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: {$params.foo}</div>
{/htxt}
civicrm

Archives

...