API Reference

This document explores the API of this package.

OnlineHelp System.

Create the global OnlineHelp instance.

class zope.app.onlinehelp.helpNamespace(context, request=None)

Bases: object

help namespace handler

traverse(name, ignored)

Used to traverse to an online help topic.

Returns a proxy for the global OnlineHelp instance with the traversal context.

zope.app.onlinehelp.getTopicFor(obj, view=None)

Determine topic for an object and optionally a view.

Iterate through all directly provided Interfaces and see if for the interface (and view) exists a Help Topic.

Returns the first match.

Prepare the tests:

>>> import os
>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> from zope.app.onlinehelp.tests.test_onlinehelp import I1, Dummy1, Dummy2
>>> from zope.app.onlinehelp import tests as ztapi
>>> from zope.component.interfaces import IFactory
>>> from zope.component.factory import Factory
>>> from zope.app.onlinehelp.onlinehelptopic import OnlineHelpTopic
>>> from zope.app.onlinehelp.onlinehelptopic import RESTOnlineHelpTopic
>>> from zope.app.onlinehelp.onlinehelptopic import STXOnlineHelpTopic
>>> from zope.app.onlinehelp.onlinehelptopic import ZPTOnlineHelpTopic
>>> default = Factory(OnlineHelpTopic)
>>> rest = Factory(RESTOnlineHelpTopic)
>>> stx = Factory(STXOnlineHelpTopic)
>>> zpt = Factory(ZPTOnlineHelpTopic)
>>> ztapi.provideUtility(IFactory, default, 'onlinehelp.topic.default')
>>> ztapi.provideUtility(IFactory, rest, 'onlinehelp.topic.rest')
>>> ztapi.provideUtility(IFactory, stx, 'onlinehelp.topic.stx')
>>> ztapi.provideUtility(IFactory, zpt, 'onlinehelp.topic.zpt')
>>> path = os.path.join(testdir(), 'help.txt')

Register a help topic for the interface ‘I1’ and the view ‘view.html’

>>> onlinehelp = OnlineHelp('Help', path)
>>> path = os.path.join(testdir(), 'help2.txt')
>>> onlinehelp.registerHelpTopic('', 'help2', 'Help 2',
...     path, I1, 'view.html')

The query should return it (‘Dummy1’ implements ‘I1):

>>> getTopicFor(Dummy1(),'view.html').title
'Help 2'

A query without view should not return it

>>> getTopicFor(Dummy1()) is None
True

Do the registration again, but without a view:

>>> onlinehelp = OnlineHelp('Help', path)
>>> onlinehelp.registerHelpTopic('', 'help2', 'Help 2',
...     path, I1, None)
>>> getTopicFor(Dummy1()).title
'Help 2'

Query with view should not match

>>> getTopicFor(Dummy1(), 'view.html') is None
True

Query with an object, that does not provide ‘I1’ should also return None

>>> getTopicFor(Dummy2()) is None
True

If there is a second interface also provided with the same view name and registered for that interface, still only the first topic will be found.

>>> from zope.interface import Interface, implementer, alsoProvides
>>> class I3(Interface):
...     pass
>>> @implementer(I3)
... class Dummy3(object):
...     pass

>>> path = os.path.join(testdir(), 'help2.txt')
>>> onlinehelp.registerHelpTopic('a', 'help3', 'Help 3',
...     path, I3, None)

>>> getTopicFor(Dummy3()).title
'Help 3'
>>> getTopicFor(Dummy1()).title
'Help 2'

>>> @implementer(I1, I3)
... class Dummy4(object):
...     pass
>>> getTopicFor(Dummy4()).title
'Help 2'

>>> @implementer(I3, I1)
... class Dummy5(object):
...     pass
>>> getTopicFor(Dummy5()).title
'Help 3'

Interfaces

OnlineHelp Interfaces

These are the interfaces designed for the OnlineHelp system.

interface zope.app.onlinehelp.interfaces.IOnlineHelpTopic

Extends: zope.container.interfaces.IContainer

A Topic is a single help page that you can view. Topics are able to contain other Topics and so on.

You can also associate a Topic with a particular view.

The Topic’s content can be in the following four formats:

• Plain Text,
• HTML,
• Structured Text (STX) and
• Restructured Text (ReST).

The Content is stored in a file and not the Topic itself. The file is only read when required.

Note that all the Sub-Topic management is done via the utility service. The topic itself is stored in the IContainer implementation after add the right parent topic of a child. This mechanism ensures that we don’t have to take care on the registration order. The topic resources are stored in the zope.container.interfaces.IContainer implementation of the topic too.

id

Id

The Id of this Help Topic

parentPath

Parent Path

The Path to the Parent of this Help Topic

title

Help Topic Title

The Title of a Help Topic

path

Path to the Topic

The Path to the Definition of a Help Topic

interface

Object Interface

Interface for which this Help Topic is registered.

view

View Name

The View Name for which this Help Topic is registered

addResources(resources)

Add resources to this Help Topic.

The resources must be located in the same directory as the Help Topic itself.

getTopicPath()

Return the presumed path to the topic, even the topic is not traversable from the onlinehelp.

getSubTopics()

Returns IOnlineHelpTopic provided childs.

interface zope.app.onlinehelp.interfaces.ISourceTextOnlineHelpTopic

Extends: zope.app.onlinehelp.interfaces.IOnlineHelpTopic

REstructed text based online help topic.

source

Source Text

Renderable source text of the topic.

type

Source Type

Type of the source text, e.g. structured text

interface zope.app.onlinehelp.interfaces.IRESTOnlineHelpTopic

Extends: zope.app.onlinehelp.interfaces.ISourceTextOnlineHelpTopic

REstructed text based online help topic.

interface zope.app.onlinehelp.interfaces.ISTXOnlineHelpTopic

Extends: zope.app.onlinehelp.interfaces.ISourceTextOnlineHelpTopic

Structed text based online help topic.

interface zope.app.onlinehelp.interfaces.IZPTOnlineHelpTopic

Extends: zope.app.onlinehelp.interfaces.IOnlineHelpTopic

Page template based online help topic.

interface zope.app.onlinehelp.interfaces.IOnlineHelp

Extends: zope.app.onlinehelp.interfaces.ISourceTextOnlineHelpTopic

The root of an onlinehelp hierarchy.

Manages the registration of new topics.

registerHelpTopic(parent_path, id, title, doc_path, interface=None, view=None, resources=None)

This method registers a topic at the correct place.

Parameters:

• parent_path – Location of this topic’s parent in the OnlineHelp tree. Need not to exist at time of creation.
• id – Specifies the id of the topic
• title – Specifies title of the topic. This title will be used in the tree as Identification.
• doc_path – – Specifies where the file that contains the topic content is located.
• interface – Name of the interface for which the help topic is being registered. This can be optional, since not all topics must be bound to a particular interface.
• view – This attribute specifies the name of the view for which this topic is registered. Note that this attribute is also optional.
• resources – Specifies a list of resources for the topic, for example images that are included by the rendered topic content. Optional.

interface zope.app.onlinehelp.interfaces.IOnlineHelpResource

Extends: zope.app.file.interfaces.IFile, zope.app.publication.interfaces.IFileContent

A resource, which can be used in a help topic

path

Path to the Resource

The Path to the Resource, assumed to be in the same directory as the Help Topic

Configuration

Schemas for the help ZCML namespace

interface zope.app.onlinehelp.metadirectives.IOnlineHelpTopicDirective

Register an online topic.

Optionally you can register a topic for a component and view.

id

Topic Id

Id of the topic as it will appear in the URL.

title

Title

Provides a title for the online Help Topic.

parent

Parent Topic

Id of the parent topic.

for_

Object Interface

Interface for which this Help Topic is registered.

view

View Name

The view name for which this Help Topic is registered.

doc_path

Path to File

Path to the file that contains the Help Topic content.

class_

Factory

The factory is the topic class used for initializeing the topic

resources

A list of resources.

A list of resources which shall be used for the Help Topic. The resources must be located in the same directory as the Help Topic definition.

Meta-Configuration Handlers for “help” namespace.

These handlers process the registerTopic() directive of the “help” ZCML namespace.

Online Help

Implementation of OnlineHelp System.

This is the default implementation of the OnlineHelp. It defines the global OnlineHelp in which all basic Zope-core help screens are registered.

class zope.app.onlinehelp.onlinehelp.OnlineHelp(title, path)

Bases: zope.app.onlinehelp.onlinehelptopic.OnlineHelpTopic

Implementation of IOnlineHelp.

>>> import os
>>> from zope import component
>>> from zope.component.interfaces import IFactory
>>> from zope.component.factory import Factory
>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> from zope.app.onlinehelp.tests.test_onlinehelp import I1, Dummy1
>>> path = os.path.join(testdir(), 'help.txt')

Create an OnlineHelp instance

>>> onlinehelp = OnlineHelp('Help', path)

First do the interface verifying tests.

>>> from zope.interface.verify import verifyObject
>>> from zope.traversing.interfaces import IContainmentRoot
>>> verifyObject(IOnlineHelp, onlinehelp)
True
>>> verifyObject(IContainmentRoot, onlinehelp)
True

Register a new subtopic for interface ‘I1’ and view ‘view.html’

>>> from zope.app.onlinehelp.onlinehelptopic import OnlineHelpTopic
>>> from zope.app.onlinehelp.onlinehelptopic import RESTOnlineHelpTopic
>>> from zope.app.onlinehelp.onlinehelptopic import STXOnlineHelpTopic
>>> from zope.app.onlinehelp.onlinehelptopic import ZPTOnlineHelpTopic
>>> default = Factory(OnlineHelpTopic)
>>> rest = Factory(RESTOnlineHelpTopic)
>>> stx = Factory(STXOnlineHelpTopic)
>>> zpt = Factory(ZPTOnlineHelpTopic)
>>> component.provideUtility(default, IFactory, 'onlinehelp.topic.default')
>>> component.provideUtility(rest, IFactory, 'onlinehelp.topic.rest')
>>> component.provideUtility(stx, IFactory, 'onlinehelp.topic.stx')
>>> component.provideUtility(zpt, IFactory, 'onlinehelp.topic.zpt')
>>> path = os.path.join(testdir(), 'help2.txt')
>>> onlinehelp.registerHelpTopic('', 'help2', 'Help 2',
...     path, I1, 'view.html')

Test if the subtopic is set correctly >>> onlinehelp[‘help2’].title ‘Help 2’

Additionally it should appear as a utility >>> topic = component.getUtility(IOnlineHelpTopic,’help2’) >>> topic.title ‘Help 2’

add another topic without parent >>> onlinehelp.registerHelpTopic(‘missing’, ‘help3’, ‘Help 3’, ... path, I1, ‘view.html’)

The new topic should not be a child of the onlinehelp instance >>> ‘help3’ in onlinehelp.keys() False

But it is available as a utility >>> topic = component.getUtility(IOnlineHelpTopic,’missing/help3’) >>> topic.title ‘Help 3’

now register the missing parent >>> onlinehelp.registerHelpTopic(‘’, ‘missing’, ‘Missing’, ... path, I1, ‘view.html’)

This is a child on the onlinehelp >>> ‘missing’ in onlinehelp.keys() True

>>> missing = onlinehelp['missing']

This topic should now have ‘help3’ as a child >>> ‘help3’ in missing.keys() True

registerHelpTopic(parent_path, id, title, doc_path, interface=None, view=None, class_=None, resources=None)

See zope.app.onlineHelp.interfaces.IOnlineHelp

Topics

Implementation of an Online Help Topic.

class zope.app.onlinehelp.onlinehelptopic.OnlineHelpResource(path='', contentType='')

Bases: persistent.Persistent

Represents a resource that is used inside the rendered Help Topic - for example a screenshot.

Implements IOnlineHelpResource.

>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> path = os.path.join(testdir(), 'test1.png')

>>> resource = OnlineHelpResource(path)
>>> resource.contentType
'image/png'
>>> resource._fileMode
'rb'

>>> path = os.path.join(testdir(), 'help2.txt')

>>> resource = OnlineHelpResource(path)
>>> resource.contentType
'text/plain'
>>> resource._fileMode
'r'
>>> resource.data.splitlines()[0]
u'This is another help!'
>>> u'\u0444\u0430\u0439\u043b' in resource.data
True

getSize()

See IFile

class zope.app.onlinehelp.onlinehelptopic.BaseOnlineHelpTopic(id, title, path, parentPath, interface=None, view=None)

Bases: zope.container.sample.SampleContainer

Base class for custom Help Topic implementations.

>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> path = os.path.join(testdir(), 'help.txt')

Create a Help Topic from a file

>>> topic = BaseOnlineHelpTopic('help','Help',path,'')

Test the title

>>> topic.title
'Help'

Test the topic path

>>> topic.getTopicPath()
'help'
>>> topic.parentPath = 'parent'
>>> topic.getTopicPath()
'parent/help'

Resources can be added to an online help topic.

>>> topic.addResources(['test1.png', 'test2.png'])
>>> topic['test1.png'].contentType
'image/png'
>>> topic['test2.png'].contentType
'image/png'

Initialize object.

addResources(resources)

see IOnlineHelpTopic

getTopicPath()

See IOnlineHelpTopic

class zope.app.onlinehelp.onlinehelptopic.SourceTextOnlineHelpTopic(id, title, path, parentPath, interface=None, view=None)

Bases: zope.app.onlinehelp.onlinehelptopic.BaseOnlineHelpTopic

Source text methods mixin class.

Initialize object.

class zope.app.onlinehelp.onlinehelptopic.OnlineHelpTopic(id, title, path, parentPath, interface=None, view=None)

Bases: zope.app.onlinehelp.onlinehelptopic.SourceTextOnlineHelpTopic

Represents a Help Topic. This generic implementation uses the filename extension for guess the type. This topic implementation supports plain text topics, restructured and structured text topics. HTML topics get rendered as structured text. If a file doesn’t have the right file extension, use a explicit topic class for representing the right format.

Implements ISourceTextOnlineHelpTopic.

>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> path = os.path.join(testdir(), 'help.txt')

Create a Help Topic from a file

>>> topic = OnlineHelpTopic('help','Help',path,'')

Test the title

>>> topic.title
'Help'

Test the topic path

>>> topic.getTopicPath()
'help'
>>> topic.parentPath = 'parent'
>>> topic.getTopicPath()
'parent/help'

The type should be set to plaintext, since the file extension is ‘txt’

>>> topic.type
'zope.source.plaintext'

Test the help content.

>>> topic.source
u'This is a help!'

>>> path = os.path.join(testdir(), 'help.stx')
>>> topic = OnlineHelpTopic('help','Help',path,'')

The type should now be structured text

>>> topic.type
'zope.source.stx'

HTML files are treated as structured text files

>>> path = os.path.join(testdir(), 'help.html')
>>> topic = OnlineHelpTopic('help','Help',path,'')

The type should still be structured text

>>> topic.type
'zope.source.stx'

>>> path = os.path.join(testdir(), 'help.rst')
>>> topic = OnlineHelpTopic('help','Help',path,'')

The type should now be restructured text

>>> topic.type
'zope.source.rest'

Resources can be added to an online help topic.

>>> topic.addResources(['test1.png', 'test2.png'])
>>> topic['test1.png'].contentType
'image/png'
>>> topic['test2.png'].contentType
'image/png'

Initialize object.

class zope.app.onlinehelp.onlinehelptopic.RESTOnlineHelpTopic(id, title, path, parentPath, interface=None, view=None)

Bases: zope.app.onlinehelp.onlinehelptopic.SourceTextOnlineHelpTopic

Represents a restructed text based Help Topic which has other filename extension then ‘.rst’ or ‘rest’.

Implements IRESTOnlineHelpTopic.

>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> path = os.path.join(testdir(), 'help.rst')

Create a Help Topic from a file

>>> topic = RESTOnlineHelpTopic('help','Help',path,'')

Test the title

>>> topic.title
'Help'

Test the topic path

>>> topic.getTopicPath()
'help'
>>> topic.parentPath = 'parent'
>>> topic.getTopicPath()
'parent/help'

The type should be set to rest, since the file extension is ‘rest’

>>> topic.type
'zope.source.rest'

Test the help content.

>>> topic.source.splitlines()[0]
u'This is a ReST help!'
>>> u'\u0444\u0430\u0439\u043b' in topic.source
True

Resources can be added to an online help topic.

>>> topic.addResources(['test1.png', 'test2.png'])
>>> topic['test1.png'].contentType
'image/png'
>>> topic['test2.png'].contentType
'image/png'

Initialize object.

class zope.app.onlinehelp.onlinehelptopic.STXOnlineHelpTopic(id, title, path, parentPath, interface=None, view=None)

Bases: zope.app.onlinehelp.onlinehelptopic.SourceTextOnlineHelpTopic

Represents a restructed text based Help Topic which has other filename extension then ‘.stx’.

Implements ISTXOnlineHelpTopic.

>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> path = os.path.join(testdir(), 'help.stx')

Create a Help Topic from a file

>>> topic = STXOnlineHelpTopic('help','Help',path,'')

Test the title

>>> topic.title
'Help'

Test the topic path

>>> topic.getTopicPath()
'help'
>>> topic.parentPath = 'parent'
>>> topic.getTopicPath()
'parent/help'

The type should be set to stx, since the file extension is ‘stx’

>>> topic.type
'zope.source.stx'

Test the help content.

>>> topic.source.splitlines()[0]
u'This is a STX help!'
>>> u'\u0444\u0430\u0439\u043b' in topic.source
True

Resources can be added to an online help topic.

>>> topic.addResources(['test1.png', 'test2.png'])
>>> topic['test1.png'].contentType
'image/png'
>>> topic['test2.png'].contentType
'image/png'

Initialize object.

class zope.app.onlinehelp.onlinehelptopic.ZPTOnlineHelpTopic(id, title, path, parentPath, interface=None, view=None)

Bases: zope.app.onlinehelp.onlinehelptopic.BaseOnlineHelpTopic

Represents a page template based Help Topic which has other filename extension than .pt.

Implements IZPTOnlineHelpTopic.

>>> from zope.publisher.browser import TestRequest, BrowserView
>>> from zope.app.pagetemplate.viewpagetemplatefile import \
...     ViewPageTemplateFile
>>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
>>> path = os.path.join(testdir(), 'help.pt')

Create a page template based Help Topic from a file

>>> topic = ZPTOnlineHelpTopic('help','Help',path,'')

Test the title

>>> topic.title
'Help'

Test the topic path

>>> topic.getTopicPath()
'help'
>>> topic.parentPath = 'parent'
>>> topic.getTopicPath()
'parent/help'

Test the help content.

>>> class TestView(BrowserView):
...     def index(self):
...         path = self.context.path
...         view = ViewPageTemplateFile(path)
...         return view(self)
>>> request = TestRequest()
>>> view = TestView(topic, request)
>>> res = view.index()
>>> u'<span>This is a ZPT help!</span>' in res
True
>>> u'\u0444\u0430\u0439\u043b' in res
True

Resources can be added to an online help topic.

>>> topic.addResources(['test1.png', 'test2.png'])
>>> topic['test1.png'].contentType
'image/png'
>>> topic['test2.png'].contentType
'image/png'

Initialize object.

Browser

Views

OnlineHelp views

class zope.app.onlinehelp.browser.OnlineHelpTopicView(context, request)

Bases: zope.publisher.browser.BrowserView

View for one particular help topic.

topicContent()

render the source of the help topic

class zope.app.onlinehelp.browser.ZPTOnlineHelpTopicView(context, request)

Bases: zope.publisher.browser.BrowserView

View for a page template based help topic.

renderTopic()

Render the registred topic.

class zope.app.onlinehelp.browser.ContextHelpView(context, request)

Bases: zope.publisher.browser.BrowserView

Contextual help view.

getContextualTopicView()

Retrieve and render the source of a context help topic

getContextHelpTopic()

Retrieve a help topic based on the context of the help namespace.

If the context is a view, try to find a matching help topic for the view and its context. If no help topic is found, try to get a help topic for the context only.

If the context is not a view, try to retrieve a help topic based on the context.

If nothing is found, return the onlinehelp root topic

contextHelpTopic

Retrieve a help topic based on the context of the help namespace.

If the context is a view, try to find a matching help topic for the view and its context. If no help topic is found, try to get a help topic for the context only.

If the context is not a view, try to retrieve a help topic based on the context.

If nothing is found, return the onlinehelp root topic

Tree

OnlineHelp tree view

class zope.app.onlinehelp.browser.tree.OnlineHelpTopicTreeView(context, request)

Bases: zope.publisher.browser.BrowserView

Online help topic tree view.

getTopicTree()

Return the tree of help topics.

We build a flat list of tpoics info dict. Iterate this dict oan build from the level info a navigation tree in the page tmeplate. Each time you get a level 0 means this is a subitem of the Onlinehelp itself:

>>> info = [('id',{infoDict}),(),()]

<ul class="tree" id="tree">
  <li><a href="#">items</a>
    <ul>
      <li><a href="#">item</a></li>
    </ul>
  </li>
  <li><a href="#">items</a>
    <ul>
      <li><a href="#">items</a>
        <ul>
          <li><a href="#">item</a></li>
          <li><a href="#">item</a></li>
          <li><a href="#">item</a></li>
        </ul>
      </li>
      <li><a href="#">items</a>
        <ul>
          <li><a href="#">item</a></li>
          <li id="activeTreeNode"><a href="#">active item</a></li>
          <li><a href="#">item</a></li>
        </ul>
      </li>
    </ul>
  </li>
<ul>

renderTree(root)

Reder a unordered list ‘ul’ tree with a class name ‘tree’.

renderItemList(topic, intend)

Render a ‘ul’ elements as childs of the ‘ul’ tree.

renderLink(topic)

Render a href element.