#38: Help system for Plone UI

Contents

1. Motivation
2. Proposal
3. Implementation

Proposed by

pupq

Proposal type

State

rejected

Motivation

While there has been considerable effort at creating help on plone.org, this has largely resulted in help for site designers and developers, not for end users. In addition, the organization system, description, and tone of this help is not suitable for end users.

By defining help in small chunks, it should be easier for the community to volunteer and maintain this help, and with a centralized registry, it should be easy for new products to register help for their templates, or, where appropriate, change the registry for existing help hooks if the product changes an already-existing behavior in the Plone UI.

Proposal

We will develop a help registry for interface help. This registry, similar to the Action Registry, will emit actions that can result in help tabs or buttons. In addition, template designers will be able to request that help appear at particular places within the page.

The help itself can be inlined or appear as link help.

In addition, there will be an infrastructure for the help to reference an external site where more in-depth (and potentially commercially-supported) conceptual or task-oriented help could be.

Implementation

Plone Help Action Tool

The help action tool is a registry of help actions. These are actions, like standard CMF actions, that can produce link help or inlined help.

Help actions will be registered with the Help Action Tool in similar ways to the the Action tool. As a convenience, there will be two addition elements to a help action. These are:

• Portal type: the portal type of the current context.
• Template: the template name the user must be on to receive this help.

Both of these could be included instead in the condition element, but since these will be commonly used, they are included explicitly as a convenience.

XXX WJB: is this a good idea? should we just take these out, so we're like every other action, and people can check this in the condition?

If an existing category for the help action is used (like object, global, etc.), the standard action machinery will pick up this help action. So, for example, consider the following help action::

• Name: Login Help
• Id: login_help
• Action: string:${portal_url}/login_help
• Condition: python: not member
• Permission: View
• Category: global
• Portal Type:
• Template: login_form

This would appear as a tab in the global site menu, and clicking that tab would bring you to the login_help page. This tab would only appear when the user is at the template "login_form".

A more common example would be:

            - Name: Login Help

            - Id: login_help

            - Action: nocall:here/login_help

            - Condition: python: not member

            - Permission: View

            - Category: help

            - Portal Type:

            - Template: login_form

Now, when the user is at the login_form, there would be an action in the "help" action list. This list would be consumed, by default, in the personal bar, so that the "Login Help" link would appear in the personal bar. However, this could be changed easily by skins, so having it appear elsewhere in UI could just be accomplished by requesting the "help" action list.

Unlike the global example, above, though, when the "help" action list is emitted, the action itself might not be a simple link -- it's likely to be a popup link, javascript hiden layer, or some other device. This is handled by having a python skin script that creates the actual HTML tags for the help action (see below).

In addition, there is a last type of help action:

            - Name: Login Help

            - Id: login_help

            - Action: nocall:here/login_help

            - Condition: python: not member

            - Permission: View

            - Category: help-inline

            - Portal Type:

            - Template: login_form

Inline help is not consumed by any particular action list rendered. Rather, it is available for manual rendering by templates. In a particular template, at the exact point that help should appear, the page designer will manually include this:

      <p><b>Label: </b>Blah, blah.
        <span tal:replace="here/help_render(here.login_help,'inline')" />
      </p>

This would have the help appear (inlined, or as a popup link, as described below) at this particular point.

It is assumed that the global help, above, would be most useful for site-wide help about Plone. The help action help would be most useful and common as help for processes, forms, etc. Inlined help would be most useful to offer specific help on complex forms or templates.

Helper Scripts

There will be several scripts::

help_render(help_object_or_string_url, render=default): """For a help action id, show render the help. The actual rendering is handled by one of the renderers."""

help_render_popup(object_or_string_url, name): """Render a popup link. The link will point to the URL."""

help_render_layer(object_or_string_url, name): """Render a DIV layer help. This will get the content for the layer from the content of the URL"""

help_render_inline(object_or_string_url, name): """Return the actual text of the URL"""

The default renderer used by help_render will be a sitewide preference, so sites can change how they normally expect help to work by changing this preference. Or, for individual cases, they can choose to render a link differently by passing in the renderer name.

XXX WJB: Generally, portal actions return URLs, since this has been a link-oriented technology. While we want to preserve this and allow help to come from external sources, we also want to optimize this so it would be helpful to know when we can just go to the object itself and render it and get it's content, rather than visit it as a URL. Probably best to have a the action be an object, rather than a string for the URL? Not sure here. Thinking.

XXX WJB: (re: above point) fixed this so that the action itself can be an object (not called!) and then the scripts can get at the object stuff directly, or a string, in which case we will assume its a url and point directly there or get stuff from it. Is this good idea?

Help Objects

The actual help objects will be a new Zope type, "HelpFile". These are subclasses of PageTemplates, and are called in the same way as a PageTemplate is called. However, they will be called with several items in the options dictionary:

XXX: pick from global_defines which will be the most commonly used things in help files.

• member: the current logged in member
• here_url: the current page
• isAnon: is user logged in?

If these are being called from a Plone page, these will have already been defined in global_defines, and can just be passed through. If being called as a new request, these will be calculated and placed into options.

XXX - is this worth it? Should they be available in the top-level (to match existing PageTemplates in Plone) instead? Or not at all, and people can just calculate these if they need them?

A sample HelpFile template, then, would be::

<html tal:use-macro="here/help_template/macros/main"> <body> <div tal:fill-slot="main"> <p> Blah blah blah. The help goes here. <i tal:condition="options/isAnon">You're logged in</i> </p> </div> </body> </html>

So, this can be rendered as a normal PageTemplate using the help_template. This would be used when the help is linked to in a popup or as a separate page.

For rendering inline, the help system will render and show only the "main" slot.

XXX WJB - we probably need a mechanism for handling pop-up HTML links differently from visited-as-normal-page pages, since the first would probably have smaller type, no header, etc., and the latter should look more like a "page".

XXX WJB - is it worth having the HelpFile be subclass of PageTemplate? One can't just take existing ZPT help files and make them HelpFiles without having to create new items that were HelpFile type. Plus, we wouldn't have the small annoyances that CMFFormController has--having the patch things to make .hpt types be visible to external products, etc. On the flip side, though, if the help files are in a distinct meta_type, it would make them easier to find, index, list separately, etc., which might be useful.

XXX WJB - note that help is NOT contentish--intentionally. I see it more as about the system and UI, as the forms, etc., are. A site might have some contentish help, but this should be handled by PloneHelpCenter, in contentish forms like FAQs, HOWTOs, etc.