Introduction
Adding a help system to any application is usually the last item on any developer's list of things to do. But with Iron Speed Designer and a single table, it's easy to have a completely customizable multi-language help system that can be integrated into any application.
Figure 1: Guide for application user
I've always been annoyed by help systems because they are usually static. I can't add my own notes, but need a completely separate application for them.
When a customer uses your application, they usually have their own business process that works in conjunction with the application. The software can be distributed among many companies with different languages and business practices, so it makes sense to deliver a customizable help. With a little effort, it is easy to create a fully customizable field-level help system.
In this article, I'm going to discuss how Iron Speed Designer, along the with open source FCKeditor, can be used to integrate a help system into any Iron Speed Designer generated application. I used the FCKeditor, but you can use the web editor of your choice. The FCKeditor can be found here.
In this example, I am using Iron Speed Designer Free Edition V5.0 and a Microsoft Access database to create my help system.
Procedure
As with any Iron Speed Designer generated application, you need to start with a well-designed database. So, let's start by building two tables. The first and the core table will be the help table named HelpNodes (see Figure 1). Use whatever name is appropriate for your application. The second table will be the Customer table, which we'll use to demonstrate how to link the field-level help.
Figure 2: Help table layout
We'll focus mainly on the HelpNodes table since it's our primary table for the help system. See Figure 2 for an explanation of each field in the table. The basic idea is that there are root nodes, and off of the root nodes many child nodes can be created to any level. This is done by self-joining the help table from the ParentNode to the NodeID. This could be done at the database level, but I want to demonstrate how Iron Speed Designer can be used (see Figure 3). When you create the self join, Iron Speed Designer automatically creates the drop down list for selecting the parent node and displays the node caption.
NodeID - Primary key field. NodeCaption - The node caption that will be displayed in the tree view. RootNodeID - Points to the base node (NodeID) for quicker access to parent nodes. ParentNode - Points to the parent node (NodeID). Language - Specifies the language for the current node. Sequence - Sequences the sibling nodes that should be displayed. Form - Reference for field level help. Another relevant anchor could be used as well. HelpMessage - The actual help message.
Figure 3: Set virtual foreign key for self join
Creating an Iron Speed Designer application is outside the scope of this article. My discussion will focus on building the help forms in Iron Speed Designer. When you use the Application Wizard in Iron Speed Designer, the show, add, edit, and browse pages are generated for the Help table. The generated pages are mostly complete, but we still want to integrate a third-party control for the web editor and add some of our own visual queues to the web forms.
By placing a tree view next to the add form, the user can see where their entry will be placed (see Figure 4). They can also select the parent node, and the add/edit form will automatically reflect their change by selecting it as the parent node drop-down list. The language input was changed to a drop-down list entry field and populated using a custom function. The sequence was changed to a drop-down list and populated inside of the designer by specifying the values. The input field Form was changed to a drop-down list, and by overriding the generated drop-down list population, I was able to call a custom routine to iterate through the site and populate it with all of the forms. The last input field to be changed was the Help Message itself, which was replaced with an open source editor. The knowledge base can be searched for articles covering how to integrate third-party controls.
Figure 4: Modified add form
Now that there is a way to enter the data, the add node form needs to save each field to the database. The generated code takes care of all the entries except the third-party control. With the Iron Speed Designer framework, this is simple. The framework allows many of the generated methods to be overridden. If we are overriding GetUIData, the add help record control can now reference the Help Message control and populate the data source (see Figure 5). This is a good place to populate any non-visual elements.
Figure 5: Override the GetUIData method
We just took an out-of-the-box generated page and extended it to suit the application's specific requirements. All of this speaks to the extensibility of Iron Speed Designer generated applications.
In order for the user to interact with the generated help document, we created a standard ASP.NET page to display it. The user interface (UI) components display the help document in a tree view, with two <div> tags and some style sheet markup. The populated tree view calls a single recursive method to populate each node. One <div> holds the tree view, while the other is used to output the content as the user clicks each node (see Figure 6). Although I've only included text in the documentation, many server-side elements can be included in the content, such as images or links to other pages.
Figure 6: Display of generated help document
Since field level help content is already in the help table, connecting the help to the user interface is easy. The editor uses standard HTML, so anchor tags are used as a reference to a block of HTML. In the example below, the customer name, address info, and billing address info have anchors attached to them. We'll use the anchors later when linking to individual fields.
Figure 7: Anchor tags for field level help
In Figure 8, there is an add customer page. It shows a call-out that displays the field-level help for the customer name. This is the same content used in the customer help document. We extracted the content relevant to the customer name by using the anchors. To get this functionality, a single image button was placed next to each field. Then a mouse over event was set from within Iron Speed Designer to call a JavaScript function.
The function then called a web method to retrieve the content and pass it back to be displayed. There are several different technologies involved and some coding, but it is do-able.
Figure 8: Integrated help system
There are some other ways to get additional use from the help sub-system. For example, you can generate a PDF manual. With some minor modifications, an application can be generated using the examples above to create an entire documentation application. One addition desirable for the future is allowing the end user to dynamically link the field level help icon to specific help document/anchors. It would also be good to have the ability to update field level content from the application page.
Conclusion
In this article, I've pointed out the benefits of creating help systems using an Iron Speed Designer generated application. I hope you have enjoyed this article.
