Chapter 21
Providing Online Help Screens

Difficulty

Newcomer

Skills

While this chapter has almost no direct prerequisites, the developer should still be familiar with at least the first two chapters of this section.
Some ZCML knowledge is of advantage.

Problem/Task

Offering help to the user at any point of a GUI is an important feature for all applications. Our message board package does a really bad job with providing help up to this point. This chapter will change that by using Zope 3’s online help package. This has not much to do with Python programming, but is part of the development process.

Solution

This should be a very quick chapter, since there are only two tasks. First you need to write the actual help screens (can be either pain text, STX, ReST or HTML) and then you simply register them. So let’s dive right into it. Since the help will be for browser views, I prefer to place the help files in a help directory inside messageboard/browser.

First create a file called package_intro.rst and enter the following content:

1  ==========================
2  Message Board Demo Package
3  ==========================
4
5  This package demos various features of the Zope 3 Framework. If you
6  have questions or concerns, please let me know.

Then a file called board_review.rst containing

1  This view lists all messages in the board that are pending for
2  publication. Each listed method is a link that brings you to the
3  message's "Workflow" view where you can initiate a transition.

Finally add msg_edit.rst with the following text:

1  This screen allows you to edit the data (i.e. the subject and body) of
2  the Message object.
3
4  title - A one line unicode text string that briefly describes the
5          purpose/subject of the message.
6
7  body - A multiple line unicode text string that is the actual content of
8         the message. It is accepting HTML, but restricts the user to a
9         couple of selected tags. Feel free to type anything you wish.

Notice how I do not have titles for the text itself. We will define titles in the configuration, which is displayed as header on the Web site, so that there is no need for another title.

All that’s left to do is to register the new help screens. Help Topics can be organized in a hierarchical manner. In order to keep all of the message board package screens together in one sub-tree, we make the package_info.rst help topic the parent of all the other help screens. Open your configuration file ( messageboard/browser/configure.zcml). Then we need to add the help namespace in the zope:configure element using the following declaration:

1 xmlns:help="http://namespaces.zope.org/help"

Now you can add the following directives:

1  <help:register
2      id="messageboard"
3      title="Message Board Help"
4      parent="ui"
5      for="book.messageboard.interfaces.IMessageBoard"
6      doc_path="./help/package_intro.rst"/>
7
8  <help:register
9      id="board.review"
10      title="Publication Review"
11      parent="ui/messageboard"
12      for="book.messageboard.interfaces.IMessageBoard"
13      view="review.html"
14      doc_path="./help/board_review.rst"/>
15
16  <help:register
17      id="message.edit"
18      title="Change Message"
19      parent="ui/messageboard"
20      for="book.messageboard.interfaces.IMessage"
21      view="edit.html"
22      doc_path="./help/msg_edit.rst"/>

Line 2: This is the id of the Help Topic as it will be available in the URL.
Line 3: The title of the Help Topic that is displayed above the topics content.
Line 4: The path of the parent help topic. The ui Help Topic comes by default with Zope 3, and you should attach all your “screen help” to it.
Line 5: This registers the Help Topic as the default context help for message board objects. This is an optional attribute.
Line 6: The relative path to the help file. Zope 3 will recognize file endings and create the appropriate filters for the output. Possible endings include txt, rst, and html and stx.
Line 12-13: Here we register a topic specifically for the review.html view of a message in the messageboard.
Line 11 & 19: Be careful to use URI-like syntax to specify the parent.

Now all you need to do is to restart Zope and go to a message board’s message review view. Like all management pages, there a “Help” link on the very right side below the tabs. Usually this link just brings you to the generic online help screen, but if you click on it from the message board’s review screen, you will see the help for this particular view. Another possibility would be to create special Message and MessageBoard object introduction screens, but I found this to be overkill in this situation.

Figure 21.1:

The help screen for the message board’s “Review Messages” tab.

Exercises

Implement online help screens for all other views.