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. 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
<?php
array(
'base_topic' => array(
'title' => 'Base Topic',
'path' => 'node/10/format_as_help',
),
'sub_topic' => array(
'title' => 'Sub Topic'
'path' => 'node/11/format_as_help',
'parent' =>'base_topic'
)
?>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?
Comments
Nice! When are we going to work together?
Erik, welcome - congrats on your new job. This looks like an excellent module. It's in a space that needs the attention. I'm also sure that Earl Miles is glad people are paying attention to improving Advanced Help, and I like the idea of the hook you're proposing.
Now, as you mention, there is also the Help Inject module: http://drupal.org/project/helpinject
It does something, well, frighteningly similar to what your module does. Let me quote from the project page:
Advanced Help Injection and Export addresses three workflows where help texts need to be written:
So our modules have in common the goal that you should be able to author help texts in Drupal using the node system. We've made a couple of slightly different decisions about the architecture, and I'm sure we can find advantages and disadvantages to both approaches. Not the point of what I'm writing.
My point is that there is a larger documentation need, and a reason why duplicate modules are avoided. The larger documentation need is that documenting your own website is nice, but most of the time what you need to document is a module, or a distribution. It turns out that by exporting to an advanced help compatible module, my Help Inject module solves all three of the needs identified above.
I dearly wish that you had shown up in the issue queue for Help Inject and started a dialog about your ideas that you've expressed with this module. If you had, we'd probably have a module that shares the strengths of both of our efforts. As it stands, now people have to work that much harder to decide which one to use.
So what's your next move with this? I'm pretty much ready to make you co-maintainer of Help Inject if you think we can merge. It's just too bad that now we'll either confuse people for a few years until one of us gives up maintaining, or have to put a note on one of the modules to the effect of "Despite this seeming like a great idea yesterday, today the recommended module to use is over there".
There's a reason the CVS account application says "It's important to note that CVS applications are often denied when an tendered module duplicates the features and functions of an existing module and in these cases applicants are referred to the module's maintainer to offer collaboration on improving that existing module."
Erik as co-maintainer of the Helpinject module
Erik and I have teamed up to be co-maintainers of the HelpInject module. We'll be merging all of the nice features described in this article and then adding even more. We'll focus our efforts on making HelpInject an awesome tool for authoring help texts so that the Drupal community writes more of them =)
I'm looking forward to working with Erik and am happy to have found a path that leads to collaboration.
Good plan
Robert/Erik, congrats on your merger. I was in a session today on Drupal here at the NTEN conference where the lack of available and useful node help was specifically discussed among several Drupal developers. I was happy to prove that once again the community is "on it".
Open Form Help Links In New Window module
I had very similar requirements recently for a project that resulted in the Open Form Help Links In New Window module. See also the issue node I created in your issue queue about this.
Cheers! Bevan/
Great one
Well, as both a newbie to Drupal, and web developer for some years, it always amazes me how proficient the Drual community is, and this module is a good example.
Will use this one for a client I'm building a community site for. Not savvy people can always use some extra help... :)
Cheers, Robert Recetas de mi cocina
With PathAuto, Needs Tweak
Hey, Great Module!
I've installed it and used it. The only problem I ran related to the path to the node.
On first pass, the link created under http://dev.drlove.com/admin/advanced_help/advanced_help_topic_nodes pointed initially to /help/advanced_help_topic_nodes/Advanced%20Help%20Help, which was the title of the node I created.
The first thing I realized (which the example in the tutorial above demonstrated, had I had the eyes to see) was that "Topic Name" should have been "topic link" - e.g. I should have entered "advanced-help-help" rather than "Advanced Help Help". So I fixed that.
The second change I made was in PathAuto to modify the node path settings to reflect /help/advanced_help_topic_nodes/[content-raw]
And that was that! For others, may this help.
With PathAuto, Needs Tweak
Hey, Great Module!
I've installed it and used it. The only problem I ran related to the path to the node.
On first pass, the link created under admin/advanced_help/advanced_help_topic_nodes pointed initially to /help/advanced_help_topic_nodes/Advanced%20Help%20Help, which was the title of the node I created.
The first thing I realized (which the example in the tutorial above demonstrated, had I had the eyes to see) was that "Topic Name" should have been "topic link" - e.g. I should have entered "advanced-help-help" rather than "Advanced Help Help". So I fixed that.
The second change I made was in PathAuto to modify the node path settings to reflect /help/advanced_help_topic_nodes/[content-raw]
And that was that! For others, may this help.
I am a newbie in Drupal. I
I am a newbie in Drupal. I always puzzle about it that how expert the Drupal community is, but this module is a good example. It's not too difficult to understand. Please receive the thankful from Asian friend ทำบุญวันเกิด. :)
Post new comment