Zope3宝典/在线帮助

Chapter 21: Providing Online Help Screens （第 21 章：提供在线帮助屏幕）

---

原文出处：The Zope 3 Developers Book - An Introduction for Python Programmers

原文作者：StephanRichter, zope.org

授权许可：创作共用协议

翻译人员：

• FireHare <[email protected]>

校对人员：Leal

适用版本：Zope 3

文章状态：校正阶段

---

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.
  一些 ZCML 知识是有帮助的。

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.
以GUI的方式给用户提供帮助对于所有应用程序来说都是个重要的特点。我们的消息栏包在提供帮助这一点上无疑做得很差。本章将使用 Zope 3 的在线帮助包来改变它。这并不需要太多的Python编程，但却是开发过程的一部分。

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.
这应该是非常短的一章，因为本章只有两个任务。首先你需要写真正的帮助屏幕（可以用 text, STX, ReST 或 HTML)，然后简单地注册它们。因此让我们纠正它。因为帮助是基于浏览器视图的，所以我喜欢将帮助文件所在的目录放到 messageboard/browser 里。

First create a file called package_intro.rst and enter the following content:
首先创建名为 package_intro.rst 的文件，并键入以下内容：

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
然后是名为 board_review.rst 的文件，包含以下内容：

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:
最后将下列文字添加到 msg_edit.rst 文件中：

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:
所有这一切都是为了注册新的帮助屏幕。帮助主题可以用层级的方式组织起来。为了将所有消息栏包屏幕保留在一棵子树上，我们将 package_info.rst 帮助主题设为其他所有帮助主题的父。打开你的配置文件(messageboard/browser/configure.zcml)。然后我们需要在 zope:configure 元素中添加帮助名称空间，并使用以下声明：

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.
  第 2 行: 这是帮助主题的ID，它将用于URL。
• Line 3: The title of the Help Topic that is displayed above the topics content.
  第 3 行: 帮助主题的标题，它显示在主题内容上方。
• 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.
  第 4 行: 父帮助主题的路径。ui帮助主题是 Zope 3 缺省的，你应该将你所有的“screen help” 附在它的下面。
• Line 5: This registers the Help Topic as the default context help for message board objects. This is an optional attribute.
  第 5 行: 为消息栏对象作为缺省上下文帮助注册帮助主题。这是个可选属性。
• 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.
  第 6 行: 到帮助文件的相对路径。Zope 3 将通过文件后缀来识别文件并为输出创建适当的过滤器。可能的后缀包括 txt，rst，html 和 stx。
• Line 12-13: Here we register a topic specifically for the review.html view of a message in the messageboard.
  第 12-13 行: 这里我们明确地为消息栏的消息 review.html 视图注册了一个主题。
• Line 11 & 19: Be careful to use URI-like syntax to specify the parent.
  第 11 & 19 行: 在指定父时小心使用类 URI 语法。

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.
现在你要做的就是重启 Zope 并到消息栏的消息查看视图。象所有的管理页面一样，在标签下面的右首有一个“Help” 链接。通常该链接只是带你到通用在线帮助屏幕，但如果你从消息栏的消息查看屏幕点它的话，你可以看到该指定视图的帮助。另一个可能是创建一个指定消息和消息栏对象的介绍屏幕，但我发现在这种情况下那样就显得过火了

PIC Figure 21.1: The help screen for the message board’s “Review Messages” tab.
图 21.1: 消息栏中 “Review Messages” 标签的帮助屏幕

Exercises（练习）

• Implement online help screens for all other views.
  实现其他视图的在线帮助屏幕