Using Nodes to store Advance Help Topics

A few weeks a go a colleague, Kelly, approached me about helping her use the advanced help module to insert contextual help on node edit forms. She was looking for ways to expand the help options available and make using Drupal just a little easier for first-timers.

I wrote a small module to insert the advanced help themed icons on form elements, based on the name of advanced help topic (as defined in the ini file). This worked ok but it was clear that this could be much better if the topics could be stored in nodes instead of the an html file.

Erik Summerfield, Director of Engineering
#Drupal | Posted

A few weeks a go a colleague, Kelly, approached me about helping her use the advanced help module to insert contextual help on node edit forms. She was looking for ways to expand the help options available and make using Drupal just a little easier for first-timers.

I wrote a small module to insert the advanced help themed icons on form elements, based on the name of advanced help topic (as defined in the ini file). This worked ok but it was clear that this could be much better if the topics could be stored in nodes instead of the an html file. There is a module, help injector, that allows the creation of topics in nodes, and then exports it to a module that provides the topics. To take it a bit further, I was hoping that the topics could then be edited and added on the fly, and at the same time, gain all of the added functionality of cck and theming. So I began to see if it was possible to make nodes into help topics. Here’s what I’ve come up with:

Patching Advanced Help

The first step was to see if there was a hook for adding topics to advanced help. While there is a straight forward way to add help files via an ini config file, there was no hook for adding help topics in other ways. So I created a patch to the advanced help module, which provides a hook_advanced_help_topics hook. This hook expects an associative array of topic names and topics, each topic itself an array of the following properties

‘title’ (required)
‘path’ (required)
‘weight’
‘parent’
‘popup width’
‘line break’
‘navigation’
‘css’

so the hook might return

  1. <span style="color: #000000;"><span style="color: #0000bb;"><?php
  2. </span><span style="color: #007700;">array(
  3. </span><span style="color: #dd0000;">'base_topic' </span><span style="color: #007700;">=> array(
  4. </span><span style="color: #dd0000;">'title' </span><span style="color: #007700;">=> </span><span style="color: #dd0000;">'Base Topic'</span><span style="color: #007700;">,
  5. </span><span style="color: #dd0000;">'path' </span><span style="color: #007700;">=> </span><span style="color: #dd0000;">'node/10/format_as_help'</span><span style="color: #007700;">,
  6. ),
  7. </span><span style="color: #dd0000;">'sub_topic' </span><span style="color: #007700;">=> array(
  8. </span><span style="color: #dd0000;">'title' </span><span style="color: #007700;">=> </span><span style="color: #dd0000;">'Sub Topic'
  9. 'path' </span><span style="color: #007700;">=> </span><span style="color: #dd0000;">'node/11/format_as_help'</span><span style="color: #007700;">,
  10. </span><span style="color: #dd0000;">'parent' </span><span style="color: #007700;">=></span><span style="color: #dd0000;">'base_topic'
  11. </span><span style="color: #007700;">)
  12. </span><span style="color: #0000bb;">?></span></span>

This patch has not been accepted yet so if anyone has feedback about it please let me know! patch thread

Advance Help Topic Nodes Module

Now that I have a hook to add topics to advanced help, I started on a way to store those topics in nodes. This gave birth to the advanced_help_topic_nodes module.

This module creates the option to make a content type a help topic content type.

and then adds two fields to the node, the topic_name and topic_parent.

after filling this out and saving the node, it will now appear in the advanced help index under the advanced_help_topic_nodes

And here is the topic being displayed by advanced help!

So now we have topic nodes that integrate in to the advanced help system, but this module also does one more thing. It provides a theme function
advanced_help_node_topic. Which is a wrapper around the advanced_help_topic theme function. This function takes an extra argument of suggested_parent_name, it will add the advanced help icon if a node exists, it will also add and edit icon . If the node with that name does not exists it will add an icon to create a help topic here .

Advanced Help Topic Nodes For Forms Module

Now, the last step was to have these help topics be available on forms, this i did in the Advance Help Topic Nodes For Forms module. It call the them function provided by Advanced Help Topic Nodes at the top of each form and before the title of each form element. It pass a topic page name of FORM_ID—ELEMENT-ID.

Both modules working together.

With both of these modules enabled we can see the effect of the Advance Help Topic Nodes Module. First, turn on editing by going to admin/advanced_help/toggle-edit-help-topic


Then when we visit a form we will be presented with help edit and help add icons, an edit icon if there is already a help topic for that item; an add icon if the topic does not yet exist.

If one clicks on a add, they are then presented with a screen to select which type of help topic they would like to create (remember you can have different content types that are help topic nodes).

Then they will be present with the creation screen.

note, if a form help topic exists it will default to the parent topic.

After saving the help topic, the user is returned to the form where they were adding help.

If a user does not have the administer help topics nodes permission setting, they will only see the normal help topic icons.

What do you think?

The modules are available on the Advance Help Topic Nodes Project on drupal.org.

I am definitely interested in what you think about the approach I’ve taken here. The patch could really open up many possibilities for using the nice features of advanced help. And I think the Advanced Help Topic Nodes is a pretty solid way of storing and maintaining topics. Maybe the Advanced Help Form Nodes may not be the best way to inject the topics into forms. There may be many other possible injection needs I have not thought of.

What do you think?

Erik Summerfield

Erik Summerfield

Director of Engineering