[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/ OnlineHelp
Restructuring
Eckart Hertzler
eckart at hertzler.de
Fri May 28 10:22:59 EDT 2004
Log message for revision 25083:
OnlineHelp Restructuring
- Changed onlinehelp servic to a utility
- moved namespace handling from zope.app.traversing to zope.app.onlinehelp
- added support for help resources (i.e. images).
- changed standard help topics to STX format
- added and updated help topic contents
- moved OnlineHelp / OnlineHelpTopic to their own modules
-=-
Modified: Zope3/trunk/src/zope/app/onlinehelp/DEPENDENCIES.cfg
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/DEPENDENCIES.cfg 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/DEPENDENCIES.cfg 2004-05-28 14:22:59 UTC (rev 25083)
@@ -1,3 +1,4 @@
+persistent
zope.app
zope.app.file
zope.app.renderer
Deleted: Zope3/trunk/src/zope/app/onlinehelp/README.stx
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/README.stx 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/README.stx 2004-05-28 14:22:59 UTC (rev 25083)
@@ -1,65 +0,0 @@
-What's the Online Help System?
-
- Stephan Richter has implemented a very basic Online Help that supports
- plain text and HTML files for content in help topics. Topics are a piece
- of the help document that contains useful information. Topics are also
- containers and can simply contain further Topics. This way we can have
- nested help pages, which will help with content organization. It is
- possible to associate a topic with a particular view of an interface.
- The online help system is implemented as global service.
-
-
-Usage:
-
- To register help topic for your code, you need to add 'register'
- directive in the configuration file (see example below). You can
- specify the following attributes:
-
- - 'parent' - Location of this topic's parent in the OnlineHelp tree.
- Optional.
-
- - 'id' - The id of the help topic. Required.
-
- - 'title' - The title of the topic. It will be used in the tree as
- Identification. Required.
-
- - 'doc_path' - Path to the file that contains the topic. Required.
-
- - 'doc_type' - Defines the type of document this topic will be. Optional.
-
- - 'for' - The interface this topic apllies to. Optional.
-
- - 'view' - The name of the view for wich this topic is registered.
- Optional.
-
- To unregister a particular help topic use directive unregister. You need
- to specify the path to the help topic.
-
-
-Examples::
-
- <configure
- xmlns="http://namespaces.zope.org/zope"
- xmlns:help="http://namespaces.zope.org/help"
- >
-
- ....
-
- <!-- Register Help Topics -->
-
- <help:register
- id="ui"
- title="Zope UI Help"
- doc_path="./ui.txt"
- />
-
- <help:register
- id="welcome"
- title="Welcome"
- parent="ui"
- for="zope.app.onlinehelp.interfaces.IOnlineHelpTopic"
- view="index.html"
- doc_path="./help.stx"
- />
-
- </configure>
Modified: Zope3/trunk/src/zope/app/onlinehelp/__init__.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/__init__.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/__init__.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -1,4 +1,4 @@
- ##############################################################################
+##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors.
# All Rights Reserved.
@@ -11,170 +11,36 @@
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
-"""Implementation of OnlineHelp System.
+"""OnlineHelp System.
-This the default implmentation of the OnlineHelp. It defines the global
-OnlineHelp in which all basic Zope-core help screens are registered.
+Create the global OnlineHelp instance.
$Id$
"""
import os
-import zope.app
+import zope
from zope.app import zapi
-from zope.app.container.sample import SampleContainer
-from zope.app.traversing.interfaces import IContainmentRoot
+from onlinehelp import OnlineHelp
+from onlinehelptopic import OnlineHelpTopic
+from zope.app.onlinehelp.interfaces import IOnlineHelp
-from zope.app.onlinehelp.interfaces import IOnlineHelpTopic, IOnlineHelp
-from zope.interface import implements
-class OnlineHelpTopic(SampleContainer):
- """
- Represents a Help Topic.
-
- >>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
- >>> path = os.path.join(testdir(), 'help.txt')
+class helpNamespace:
+ """ help namespace handler """
- Create a Help Topic from a file
-
- >>> topic = OnlineHelpTopic('Help',path)
+ def __init__(self, context, request=None):
+ self.context = context
- Test the title
-
- >>> topic.title
- 'Help'
+ def traverse(self, name, ignored):
+ """Used to traverse to an online help topic."""
+ onlinehelp = zapi.getUtility(IOnlineHelp,
+ 'OnlineHelp', self.context)
+ onlinehelp.context = self.context
+ return onlinehelp
- The type should be set to plaintext, since
- the file extension is 'txt'
-
- >>> topic.type
- 'zope.source.plaintext'
-
- Test the help content.
-
- >>> topic.source
- 'This is a help!'
-
- >>> path = os.path.join(testdir(), 'help.stx')
- >>> topic = OnlineHelpTopic('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',path)
-
- The type should still be structured text
- >>> topic.type
- 'zope.source.stx'
-
- >>> path = os.path.join(testdir(), 'help.rst')
- >>> topic = OnlineHelpTopic('Help',path)
-
- The type should now be restructured text
- >>> topic.type
- 'zope.source.rest'
-
- """
- implements(IOnlineHelpTopic)
-
- title = u""
-
- source = None
-
- path = u""
-
- type = None
-
- def __init__(self, title, path):
- """Initialize object."""
- self.title = title
- self.path = path
-
- filename = os.path.basename(path.lower())
- file_ext = 'txt'
- if len(filename.split('.'))>1:
- file_ext = filename.split('.')[-1]
-
- self.type = 'zope.source.plaintext'
-
- if file_ext in ('rst', 'rest') :
- self.type = 'zope.source.rest'
- elif file_ext == 'stx':
- self.type = 'zope.source.stx'
- elif file_ext in ('html', 'htm'):
- self.type = 'zope.source.stx'
-
- self.source = open(self.path).read()
-
- super(OnlineHelpTopic, self).__init__()
-
-
-class OnlineHelp(OnlineHelpTopic):
- """
- >>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
- >>> from zope.app.onlinehelp.tests.test_onlinehelp import I1
- >>> path = os.path.join(testdir(), 'help.txt')
-
- Create an onlinehelp instance
-
- >>> onlinehelp = OnlineHelp('Help', path)
-
- First do the inteface verifing tests.
-
- >>> from zope.interface.verify import verifyObject
- >>> from zope.app.traversing.interfaces import IContainmentRoot
- >>> verifyObject(IOnlineHelp, onlinehelp)
- True
- >>> verifyObject(IContainmentRoot, onlinehelp)
- True
-
- Register a new subtopic for interface 'I1' and view 'view.html'
-
- >>> 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'
-
- >>> onlinehelp._registry[(I1, 'view.html')][0].title
- 'Help 2'
-
- The help topic must be found if the onlinehelp is queried
- with interface and view name.
-
- >>> onlinehelp.getTopicsForInterfaceAndView(I1, 'view.html')[0].title
- 'Help 2'
-
- """
- implements(IOnlineHelp, IContainmentRoot)
-
- def __init__(self, title, path):
- self._registry = {}
- super(OnlineHelp, self).__init__(title, path)
-
- def getTopicsForInterfaceAndView(self, interface=None, view=None):
- "See Zope.App.OnlineHelp.interfaces.IOnlineHelp"
- return self._registry.get((interface, view), [])
-
- def registerHelpTopic(self, parent_path, id, title,
- doc_path, interface=None, view=None):
- "See Zope.App.OnlineHelp.interfaces.IOnlineHelp"
- parent = zapi.traverse(self, parent_path)
- # Create and add topic
- parent[id] = OnlineHelpTopic(title, doc_path)
- topic = parent[id]
- # Add topic to registry
- if interface is not None:
- if not self._registry.has_key((interface, view)):
- self._registry[(interface, view)] = []
- self._registry[(interface, view)].append(topic)
-
# Global Online Help
path = os.path.join(os.path.dirname(zope.app.__file__),
- 'onlinehelp', 'welcome.txt')
+ 'onlinehelp', 'help','welcome.stx')
+
help = OnlineHelp('Online Help', path)
Modified: Zope3/trunk/src/zope/app/onlinehelp/browser/__init__.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/browser/__init__.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/browser/__init__.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -16,12 +16,13 @@
$Id$
"""
from zope.proxy import removeAllProxies
-from zope.interface import providedBy
-from zope.app.publisher.interfaces.browser import IBrowserView
+
from zope.app import zapi
from zope.app.pagetemplate.viewpagetemplatefile import ViewPageTemplateFile
-from zope.app.onlinehelp.interfaces import IOnlineHelpTopic
+from zope.app.publisher.interfaces.browser import IBrowserView
+from zope.app.onlinehelp.interfaces import IOnlineHelpTopic, IOnlineHelp
+
class TopicTreeView(object):
def __init__(self, context, request, base_url=''):
@@ -35,24 +36,25 @@
# set up the root values
if self.base_url == '':
self.base_url = '/++help++'
- self.treecontext = zapi.getService("OnlineHelp")
+ self.treecontext = zapi.getUtility(IOnlineHelp,"OnlineHelp")
return self.subtopics()
def listHelpItems(self):
""" recurse through the help topic tree"""
children=[]
for name, helpitem in self.treecontext.items():
- info={}
- info['title'] = helpitem.title
- info['path'] = self.base_url+'/'+name
- topic = TopicTreeView(
- helpitem,
- self.request,
- self.base_url+'/'+name)
+ if IOnlineHelpTopic.providedBy(helpitem):
+ info={}
+ info['title'] = helpitem.title
+ info['path'] = self.base_url+'/'+name
+ topic = TopicTreeView(
+ helpitem,
+ self.request,
+ self.base_url+'/'+name)
+
+ info['topics']=topic.subtopics()
+ children.append(info)
- info['topics']=topic.subtopics()
- children.append(info)
-
return children
subtopics = ViewPageTemplateFile('topiclink.pt')
@@ -111,44 +113,22 @@
if self.topic is not None:
return self.topic
- onlinehelp = zapi.getService("OnlineHelp")
+ onlinehelp = removeAllProxies(self.context)
help_context = onlinehelp.context
self.topic = self.context
if IBrowserView.providedBy(help_context):
# called from a view
- for iface in providedBy(zapi.getParent(help_context)):
- # try for interface and view match
- topics = onlinehelp.getTopicsForInterfaceAndView(
- iface,
- zapi.getName(help_context)
- )
- if len(topics)>0:
- self.topic = topics[0]
- break
+ self.topic = onlinehelp.getTopicForObjectAndView(
+ zapi.getParent(help_context),
+ zapi.getName(help_context)
+ )
if self.topic == self.context:
# nothing found for view try iface only
- for iface in providedBy(zapi.getParent(help_context)):
- topics = onlinehelp.getTopicsForInterfaceAndView(
- iface,
- None
- )
- if len(topics)>0:
- self.topic = topics[0]
- break
+ self.topic = onlinehelp.getTopicForObjectAndView(
+ zapi.getParent(help_context)
+ )
else:
# called without view
- for iface in providedBy(help_context):
- topics = onlinehelp.getTopicsForInterfaceAndView(
- iface,
- None
- )
- if len(topics)>0:
- self.topic = topics[0]
- break
+ self.topic = onlinehelp.getTopicForObjectAndView(help_context)
- # XXX returns only the first of the matching topics.
- # The page template only processes one topic
return self.topic
-
-
-
Modified: Zope3/trunk/src/zope/app/onlinehelp/browser/ftests.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/browser/ftests.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/browser/ftests.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -17,7 +17,6 @@
"""
import os
import unittest
-import re
from zope.app.folder.interfaces import IRootFolder
from zope.app.file import File
Modified: Zope3/trunk/src/zope/app/onlinehelp/configure.zcml
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/configure.zcml 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/configure.zcml 2004-05-28 14:22:59 UTC (rev 25083)
@@ -11,38 +11,57 @@
/>
</content>
- <!-- Setup OnlineHelp as Service -->
- <serviceType
- id="OnlineHelp"
- interface="zope.app.onlinehelp.interfaces.IOnlineHelp"
- />
+ <content class=".onlinehelptopic.OnlineHelpResource">
+ <require
+ permission="zope.View"
+ interface=".interfaces.IOnlineHelpResource"
+ />
+ </content>
- <service serviceType="OnlineHelp"
+ <!-- Setup OnlineHelp as a Utility -->
+ <utility
+ provides=".interfaces.IOnlineHelp"
permission="zope.Public"
component="zope.app.onlinehelp.help"
+ name="OnlineHelp" />
+
+ <view
+ name="help"
+ type="*"
+ provides="zope.app.traversing.interfaces.ITraversable"
+ for="*"
+ factory=".helpNamespace"
/>
+ <adapter
+ name="help"
+ provides="zope.app.traversing.interfaces.ITraversable"
+ for="*"
+ factory=".helpNamespace"
+ />
+
<!-- Register initial Help Topics -->
<help:register
id="ui"
title="Zope UI Help"
- doc_path="./ui.txt"
+ doc_path="./help/ui.stx"
+ resources="mgmt-main-1.png"
/>
<help:register
id="welcome"
title="Welcome"
parent="ui"
- doc_path="./help.txt"
+ doc_path="./help/welcome.stx"
/>
<help:register
id="onlinehelp"
- title="Online help system"
- doc_path="./README.stx"
+ title="Online Help System"
+ doc_path="./help/README.stx"
/>
<!-- include browser package -->
<include package=".browser" />
-
+
</configure>
Added: Zope3/trunk/src/zope/app/onlinehelp/help/README.stx
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/help/README.stx 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/help/README.stx 2004-05-28 14:22:59 UTC (rev 25083)
@@ -0,0 +1,84 @@
+What's the Online Help System?
+
+ The Online Help provides a way to write, organize and display
+ help documents for applications.
+
+ The Online Help is basically a hierarchy of Help Topics.
+
+ Topics are a pieces of the help that contain useful information.
+ The contents of a Help Topic can be defined in different formats,
+ which will all displayed as HTML.
+ The Online Help supports
+
+ - plain text documents
+
+ - structured text documents
+
+ - restructured text documents
+
+ - HTML documents
+
+ Topics are also containers and can contain further Topics or
+ resources associated with the Help Topic.
+ This way we can have
+ nested help pages, which will help with content organization. It is
+ possible to associate a topic with an interface or even
+ a particular view of an interface.
+
+ The Online Help System is implemented as global service.
+
+
+Usage:
+
+ To register help topic for your code, you need to add 'register'
+ directive in the configuration file (see example below). You can
+ specify the following attributes:
+
+ - 'parent' - Location of this topic's parent in the OnlineHelp tree.
+ Optional.
+
+ - 'id' - The id of the help topic. Required.
+
+ - 'title' - The title of the topic. It will be used in the tree as
+ Identification. Required.
+
+ - 'doc_path' - Path to the file that contains the topic. Required.
+
+ - 'doc_type' - Defines the type of document this topic will be. Optional.
+
+ - 'for' - The interface this topic apllies to. Optional.
+
+ - 'view' - The name of the view for wich this topic is registered.
+ Optional.
+
+ - 'resources' - A list of resources that can be referenced by the Help Topic (e.g. images). Optional.
+
+
+Examples::
+
+ <configure
+ xmlns="http://namespaces.zope.org/zope"
+ xmlns:help="http://namespaces.zope.org/help"
+ >
+
+ ....
+
+ <!-- Register Help Topics -->
+
+ <help:register
+ id="ui"
+ title="Zope UI Help"
+ doc_path="./help/ui.stx"
+ resources="mgmt-main-1.png"
+ />
+
+ <help:register
+ id="welcome"
+ title="Welcome"
+ parent="ui"
+ for="zope.app.onlinehelp.interfaces.IOnlineHelpTopic"
+ view="index.html"
+ doc_path="./help/welcome.stx"
+ />
+
+ </configure>
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/help/README.stx
___________________________________________________________________
Name: svn:eol-style
+ native
Added: Zope3/trunk/src/zope/app/onlinehelp/help/mgmt-main-1.png
===================================================================
(Binary files differ)
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/help/mgmt-main-1.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: Zope3/trunk/src/zope/app/onlinehelp/help/ui.stx
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/help/ui.stx 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/help/ui.stx 2004-05-28 14:22:59 UTC (rev 25083)
@@ -0,0 +1,33 @@
+
+
+The UI offers powerful tools to build applications using Zope 3.
+The UI is aimed at Site Developers and not hard-core developers and content managers.
+
+Zope Management Interface (ZMI)
+
+ This is what the management screen looks like
+
+ <img src="mgmt-main-1.png">
+
+ In the left side bar you can see two boxes.
+ The upper box has the title **Navigation**. This box contains
+ a tree view on the contens of your site.
+ The lower box contains a list of content types that can
+ be added to the current location. Some location have constraints
+ on the content types that can be added, so the content of this box
+ is dependend on where you are.
+
+ The upper right corner contains the name of the current user and
+ links to the Login/Logout.
+
+ You see the path to your current location below.
+
+ Below the location you can see the **Tabs**. The Tabs display
+ the registered views for the object you are currently visiting.
+ The Tabs are also referenced as the 'zmi_views'.
+
+ Below the Tabs you see another menu called 'zmi_actions'.
+ This menu contains links that will allow you to perform some
+ managment activities on the object.
+
+
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/help/ui.stx
___________________________________________________________________
Name: svn:eol-style
+ native
Added: Zope3/trunk/src/zope/app/onlinehelp/help/welcome.stx
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/help/welcome.stx 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/help/welcome.stx 2004-05-28 14:22:59 UTC (rev 25083)
@@ -0,0 +1,15 @@
+Welcome to the Zope 3 Online Help System. Here you can find much of the
+documentation that is relevant to the usage of this UI and Zope 3 in general.
+
+
+ Other Help / Documentation
+
+ - <a href="/++apidoc++" target="_blank">API Docs</a>
+
+ - <a href="http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/FrontPage" target="_blank">Documentation Wiki</a>
+
+ - <a href="http://dev.zope.org/Zope3/FAQ" target="_blank">FAQ</a>
+
+ - <a href="http://dev.zope.org/Zope3/ProgrammerTutorial" target="_blank">Programmers Tutorial</a>
+
+ - <a href="http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitecture/FrontPage/Zope3Book">The Zope3 Book</a>
\ No newline at end of file
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/help/welcome.stx
___________________________________________________________________
Name: svn:eol-style
+ native
Deleted: Zope3/trunk/src/zope/app/onlinehelp/help.txt
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/help.txt 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/help.txt 2004-05-28 14:22:59 UTC (rev 25083)
@@ -1,4 +0,0 @@
-Welcome to the Help System
-
-
-This is a warm welcome text right here.
\ No newline at end of file
Modified: Zope3/trunk/src/zope/app/onlinehelp/interfaces.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/interfaces.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/interfaces.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -20,6 +20,7 @@
from zope.schema import TextLine, SourceText, Choice
from zope.app.container.interfaces import IContainer
from zope.i18n import MessageIDFactory
+from zope.app.file.interfaces import IFile, IFileContent
_ = MessageIDFactory('messageboard')
@@ -48,7 +49,8 @@
title=_(u"Source Text"),
description=_(u"Renderable source text of the topic."),
default=u"",
- required=True)
+ required=True,
+ readonly=True)
path = TextLine(
title = _(u"Path to the Topic"),
@@ -63,14 +65,22 @@
required = True,
vocabulary = "SourceTypes")
+ def addResources(resources):
+ """ Add resources to this Help Topic.
+ The resources must be located in the same directory
+ as the Help Topic itself."""
class IOnlineHelp(IOnlineHelpTopic):
"""This service manages all the HelpTopics."""
- def getTopicsForInterfaceAndView(interface=None, view=None):
+ def getTopicsForInterfaceAndView(interface, view=None):
"""Returns a list of Topics that were registered to be
applicable to a particular view of an interface."""
+ def getTopicForObjectAndView(obj, view=None):
+ """Returns the first matching help topic for
+ the interfaces provided by obj."""
+
def registerHelpTopic(parent_path, id, title, doc_path,
interface=None, view=None):
"""This method registers a topic at the correct place.
@@ -94,3 +104,13 @@
this topic is registered. Note that this attribute is also
optional.
"""
+
+class IOnlineHelpResource(IFile, IFileContent):
+ """A resource, which can be used in a help topic """
+
+ path = TextLine(
+ title = _(u"Path to the Resource"),
+ description = _(u"The Path to the Resource, assumed to be "
+ "in the same directory as the Help Topic"),
+ default = u"",
+ required = True)
Modified: Zope3/trunk/src/zope/app/onlinehelp/metaconfigure.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/metaconfigure.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/metaconfigure.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -13,7 +13,7 @@
##############################################################################
"""Meta-Configuration Handlers for "help" namespace.
-These handlers process the registerTopic() and unregisterTopic() directives of
+These handlers process the registerTopic() directive of
the "help" ZCML namespace.
$Id$
@@ -21,10 +21,10 @@
from zope.app.onlinehelp import help
def register(_context, id, title, parent="", doc_path=None, for_=None,
- view=None):
+ view=None, resources=None):
"""Register an OnlineHelp topic"""
_context.action(
discriminator = ('registerHelpTopic', parent, id),
callable = help.registerHelpTopic,
- args = (parent, id, title, doc_path, for_, view) )
+ args = (parent, id, title, doc_path, for_, view, resources) )
Modified: Zope3/trunk/src/zope/app/onlinehelp/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/metadirectives.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/metadirectives.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -15,9 +15,9 @@
$Id$
"""
-from zope.configuration.fields import GlobalObject, Path, MessageID
+from zope.configuration.fields import GlobalObject, Path, MessageID, Tokens
from zope.interface import Interface
-from zope.schema import BytesLine
+from zope.schema import BytesLine, TextLine
class IRegisterDirective(Interface):
"""Register directive for onlien help topics."""
@@ -54,3 +54,14 @@
title=u"Path to File",
description=u"Path to the file that contains the Help Topic content.",
required=True)
+
+ resources = Tokens(
+ title=u"A list of resources.",
+ description=u"""
+ A list of resources which shall be user for the Help Topic.
+ The resources must be located in the same directory as
+ the Help Topic definition.
+ """,
+ value_type=TextLine(),
+ required=False
+ )
Added: Zope3/trunk/src/zope/app/onlinehelp/onlinehelp.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/onlinehelp.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/onlinehelp.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -0,0 +1,123 @@
+##############################################################################
+#
+# Copyright (c) 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Implementation of OnlineHelp System.
+
+This the default implementation of the OnlineHelp. It defines the global
+OnlineHelp in which all basic Zope-core help screens are registered.
+
+$Id$
+"""
+from zope.interface import implements, providedBy
+
+from zope.app import zapi
+from zope.app.traversing.interfaces import IContainmentRoot
+
+from zope.app.onlinehelp.interfaces import IOnlineHelp
+from zope.app.onlinehelp.onlinehelptopic import OnlineHelpTopic
+
+class OnlineHelp(OnlineHelpTopic):
+ """
+ >>> import os
+ >>> 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 inteface verifing tests.
+
+ >>> from zope.interface.verify import verifyObject
+ >>> from zope.app.traversing.interfaces import IContainmentRoot
+ >>> verifyObject(IOnlineHelp, onlinehelp)
+ True
+ >>> verifyObject(IContainmentRoot, onlinehelp)
+ True
+
+ Register a new subtopic for interface 'I1' and view 'view.html'
+
+ >>> 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'
+
+ >>> onlinehelp._registry[(I1, 'view.html')][0].title
+ 'Help 2'
+
+ The help topic must be found if the onlinehelp is queried
+ with interface and view name.
+
+ >>> onlinehelp.getTopicsForInterfaceAndView(I1, 'view.html')[0].title
+ 'Help 2'
+
+ If queried with an instance the help topic must still be found
+ >>> onlinehelp.getTopicForObjectAndView(Dummy1(), 'view.html').title
+ 'Help 2'
+
+ To register help for an interface only simple skip the view parameter
+ while registering.
+ >>> onlinehelp.registerHelpTopic('', 'help3', 'Help for Interface',
+ ... path, I1)
+ >>> onlinehelp.getTopicForObjectAndView(Dummy1()).title
+ 'Help for Interface'
+
+
+ """
+ implements(IOnlineHelp, IContainmentRoot)
+
+ def __init__(self, title, path):
+ self._registry = {}
+ super(OnlineHelp, self).__init__(title, path)
+
+ def getTopicsForInterfaceAndView(self, interface, view=None):
+ "See zope.app.onlinehelp.interfaces.IOnlineHelp"
+ return self._registry.get((interface, view), [])
+
+ def getTopicForObjectAndView(self, obj, view=None):
+ "See zope.app.Onlinehelp.interfaces.IOnlineHelp"
+ topic = self
+ for iface in providedBy(obj):
+ topics = self.getTopicsForInterfaceAndView(
+ iface,
+ view
+ )
+ if len(topics)>0:
+ topic = topics[0]
+ break
+ return topic
+
+ def registerHelpTopic(self, parent_path, id, title,
+ doc_path, interface=None, view=None,
+ resources=None):
+ "See Zope.App.OnlineHelp.interfaces.IOnlineHelp"
+ parent = zapi.traverse(self, parent_path)
+ # Create and add topic
+ parent[id] = OnlineHelpTopic(title, doc_path)
+ topic = parent[id]
+
+ # add resources to topic
+ if resources is not None:
+ topic.addResources(resources)
+
+ # Add topic to registry
+ if interface is not None:
+ if not self._registry.has_key((interface, view)):
+ self._registry[(interface, view)] = []
+ self._registry[(interface, view)].append(topic)
+
+
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/onlinehelp.py
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: Zope3/trunk/src/zope/app/onlinehelp/onlinehelptopic.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/onlinehelptopic.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/onlinehelptopic.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -0,0 +1,174 @@
+##############################################################################
+#
+# Copyright (c) 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Implementation of an Online Help Topic.
+
+
+$Id$
+"""
+import os
+
+from persistent import Persistent
+from zope.interface import implements
+from zope.configuration.exceptions import ConfigurationError
+
+from zope.app.container.sample import SampleContainer
+from zope.app.content_types import guess_content_type
+from zope.app.file.image import getImageInfo
+
+from zope.app.onlinehelp.interfaces import IOnlineHelpTopic, \
+ IOnlineHelpResource
+
+
+class OnlineHelpResource(Persistent):
+ """
+ Represents a resource that is used inside
+ the rendered Help Topic - for example a screenshot.
+
+ >>> from zope.app.onlinehelp.tests.test_onlinehelp import testdir
+ >>> path = os.path.join(testdir(), 'test1.png')
+
+ >>> resource = OnlineHelpResource(path)
+ >>> resource.contentType
+ 'image/png'
+
+ """
+ implements(IOnlineHelpResource)
+
+ def __init__(self, path='', contentType=''):
+ self.path = path
+ _data = open(os.path.normpath(self.path)).read()
+ self._size=len(path)
+
+ if contentType=='':
+ content_type, encoding = guess_content_type(self.path, _data, '')
+ if content_type.startswith('image/'):
+ self.contentType, width, height = getImageInfo(_data)
+ else:
+ self.contentType = content_type
+
+ def _getData(self):
+ return open(os.path.normpath(self.path)).read()
+
+ data = property(_getData)
+
+ def getSize(self):
+ '''See IFile'''
+ return self._size
+
+
+class OnlineHelpTopic(SampleContainer):
+ """
+ Represents a Help Topic.
+
+ >>> 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',path)
+
+ Test the title
+
+ >>> topic.title
+ '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
+ 'This is a help!'
+
+ >>> path = os.path.join(testdir(), 'help.stx')
+ >>> topic = OnlineHelpTopic('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',path)
+
+ The type should still be structured text
+ >>> topic.type
+ 'zope.source.stx'
+
+ >>> path = os.path.join(testdir(), 'help.rst')
+ >>> topic = OnlineHelpTopic('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'
+
+
+ """
+ implements(IOnlineHelpTopic)
+
+ def __init__(self, title, path):
+ """Initialize object."""
+ self.title = title
+ self.path = path
+
+ filename = os.path.basename(path.lower())
+ file_ext = 'txt'
+ if len(filename.split('.'))>1:
+ file_ext = filename.split('.')[-1]
+
+ self.type = 'zope.source.plaintext'
+
+ if file_ext in ('rst', 'rest') :
+ self.type = 'zope.source.rest'
+ elif file_ext == 'stx':
+ self.type = 'zope.source.stx'
+ elif file_ext in ('html', 'htm'):
+ self.type = 'zope.source.stx'
+
+ if not os.path.exists(self.path):
+ raise ConfigurationError(
+ "Help Topic definition %s does not exist" % self.path
+ )
+
+ super(OnlineHelpTopic, self).__init__()
+
+ title = u""
+
+ path = u""
+
+ type = None
+
+ def _getSource(self):
+ return open(os.path.normpath(self.path)).read()
+
+ source = property(_getSource)
+
+
+ def addResources(self, resources):
+ """ see IOnlineHelpTopic """
+ dirname = os.path.dirname(self.path)
+ for resource in resources:
+ resource_path=dirname+'/'+resource
+ if os.path.exists(resource_path):
+ self[resource] = OnlineHelpResource(resource_path)
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/onlinehelptopic.py
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Modified: Zope3/trunk/src/zope/app/onlinehelp/tests/help.zcml
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/tests/help.zcml 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/tests/help.zcml 2004-05-28 14:22:59 UTC (rev 25083)
@@ -11,6 +11,7 @@
title = "Help"
for = ".test_helpdirectives.I1"
view = "view.html"
- doc_path = "help.txt" />
+ doc_path = "help.txt"
+ resources = "test1.png"/>
</configure>
Added: Zope3/trunk/src/zope/app/onlinehelp/tests/test1.png
===================================================================
(Binary files differ)
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/tests/test1.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: Zope3/trunk/src/zope/app/onlinehelp/tests/test2.png
===================================================================
(Binary files differ)
Property changes on: Zope3/trunk/src/zope/app/onlinehelp/tests/test2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: Zope3/trunk/src/zope/app/onlinehelp/tests/test_helpdirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/tests/test_helpdirectives.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/tests/test_helpdirectives.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -47,8 +47,9 @@
self.context = xmlconfig.file("help.zcml", tests)
self.assertEqual(help.keys(), ['help1'])
self.assertEqual(help._registry[(I1, 'view.html')][0].title, 'Help')
+ topic = help['help1']
+ self.assert_('test1.png' in topic.keys())
-
def test_suite():
return unittest.TestSuite((
unittest.makeSuite(DirectivesTest),
Modified: Zope3/trunk/src/zope/app/onlinehelp/tests/test_onlinehelp.py
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/tests/test_onlinehelp.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/tests/test_onlinehelp.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -18,7 +18,7 @@
import os
import unittest
-from zope.interface import Interface
+from zope.interface import Interface, implements
from zope.testing.doctestunit import DocTestSuite
from zope.app.tests import ztapi
from zope.app.tests import placelesssetup
@@ -30,6 +30,9 @@
class I1(Interface):
pass
+class Dummy1:
+ implements(I1)
+
def testdir():
import zope.app.onlinehelp.tests
return os.path.dirname(zope.app.onlinehelp.tests.__file__)
@@ -44,7 +47,8 @@
def test_suite():
return unittest.TestSuite((
- DocTestSuite('zope.app.onlinehelp', setUp=setUp),
+ DocTestSuite('zope.app.onlinehelp.onlinehelptopic', setUp=setUp),
+ DocTestSuite('zope.app.onlinehelp.onlinehelp', setUp=setUp),
))
if __name__ == '__main__':
Deleted: Zope3/trunk/src/zope/app/onlinehelp/ui.txt
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/ui.txt 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/ui.txt 2004-05-28 14:22:59 UTC (rev 25083)
@@ -1,2 +0,0 @@
-The UI offers powerful tools to build applications using Zope 3. The UI is
-aimed at Site Developers and not hard-core developers and content managers.
\ No newline at end of file
Deleted: Zope3/trunk/src/zope/app/onlinehelp/welcome.txt
===================================================================
--- Zope3/trunk/src/zope/app/onlinehelp/welcome.txt 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/onlinehelp/welcome.txt 2004-05-28 14:22:59 UTC (rev 25083)
@@ -1,2 +0,0 @@
-Welcome to the Zope 3 Online Help System. Here you can find much of the
-documentation that is relevant to the usage of this UI and Zope 3 in general.
\ No newline at end of file
Modified: Zope3/trunk/src/zope/app/traversing/configure.zcml
===================================================================
--- Zope3/trunk/src/zope/app/traversing/configure.zcml 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/traversing/configure.zcml 2004-05-28 14:22:59 UTC (rev 25083)
@@ -61,18 +61,7 @@
factory="zope.app.traversing.namespace.acquire"
/>
-<adapter
- name="help"
- provides="zope.app.traversing.interfaces.ITraversable" for="*"
- factory="zope.app.traversing.namespace.help"
- />
<view
- name="help" type="*"
- provides="zope.app.traversing.interfaces.ITraversable" for="*"
- factory="zope.app.traversing.namespace.help"
- />
-
-<view
name="view" type="*"
provides="zope.app.traversing.interfaces.ITraversable" for="*"
factory="zope.app.traversing.namespace.view"
Modified: Zope3/trunk/src/zope/app/traversing/namespace.py
===================================================================
--- Zope3/trunk/src/zope/app/traversing/namespace.py 2004-05-28 13:59:16 UTC (rev 25082)
+++ Zope3/trunk/src/zope/app/traversing/namespace.py 2004-05-28 14:22:59 UTC (rev 25083)
@@ -324,14 +324,6 @@
return method()
-class help(SimpleHandler):
-
- def traverse(self, name, ignored):
- """Used to traverse to an online help topic."""
- onlinehelp = component.getService(self.context, 'OnlineHelp')
- onlinehelp.context = self.context
- return onlinehelp
-
class view(object):
zope.interface.implements(ITraversable)
More information about the Zope3-Checkins
mailing list