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)[source]¶ Bases:
object
help namespace handler
-
traverse
(name, ignored)[source]¶ 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)[source]¶ 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
[source]¶ 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
[source]¶ 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
[source]¶ Extends:
zope.app.onlinehelp.interfaces.ISourceTextOnlineHelpTopic
REstructed text based online help topic.
-
interface
zope.app.onlinehelp.interfaces.
ISTXOnlineHelpTopic
[source]¶ Extends:
zope.app.onlinehelp.interfaces.ISourceTextOnlineHelpTopic
Structed text based online help topic.
-
interface
zope.app.onlinehelp.interfaces.
IZPTOnlineHelpTopic
[source]¶ Extends:
zope.app.onlinehelp.interfaces.IOnlineHelpTopic
Page template based online help topic.
-
interface
zope.app.onlinehelp.interfaces.
IOnlineHelp
[source]¶ 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
[source]¶ 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
[source]¶ 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)[source]¶ 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
Topics¶
Implementation of an Online Help Topic.
-
class
zope.app.onlinehelp.onlinehelptopic.
OnlineHelpResource
(path='', contentType='')[source]¶ 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
-
class
zope.app.onlinehelp.onlinehelptopic.
BaseOnlineHelpTopic
(id, title, path, parentPath, interface=None, view=None)[source]¶ 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.
-
class
zope.app.onlinehelp.onlinehelptopic.
SourceTextOnlineHelpTopic
(id, title, path, parentPath, interface=None, view=None)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Bases:
zope.publisher.browser.BrowserView
View for one particular help topic.
-
class
zope.app.onlinehelp.browser.
ZPTOnlineHelpTopicView
(context, request)[source]¶ Bases:
zope.publisher.browser.BrowserView
View for a page template based help topic.
-
class
zope.app.onlinehelp.browser.
ContextHelpView
(context, request)[source]¶ Bases:
zope.publisher.browser.BrowserView
Contextual help view.
-
getContextHelpTopic
()[source]¶ 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)[source]¶ Bases:
zope.publisher.browser.BrowserView
Online help topic tree view.
-
getTopicTree
()[source]¶ 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>
-