Text File
browser.txt

Utilities Menu and Details Views

Menu class

This is a class that helps building the menu. The menu_macros expect the menu view class to have the getMenuTitle(node) and getMenuLink(node) methods implemented. node is a zope.app.tree.node.Node instance.

Let's start by creating the menu:

>>> from zope.app.apidoc.utilitymodule.browser import Menu
>>> menu = Menu()

Now we want to get the menu title and link for a utility interface. To do that we first have to create a utility interface

>>> from zope.app.apidoc.tests import Root
>>> from zope.app.apidoc.utilitymodule.utilitymodule import UtilityInterface
>>> uiface = UtilityInterface(Root(), 'foo.bar.iface', None)

and then wrap it in a node:

>>> from zope.app.tree.node import Node
>>> node = Node(uiface)

You can now get the title and link from the menu:

>>> menu.getMenuTitle(node)
'iface'
>>> menu.getMenuLink(node)
'../Interface/foo.bar.iface/index.html'

Next, let's get the menu title and link for a utility with a name. We first have to create a utility registration

>>> foobar_reg = type(
...     'RegistrationStub', (),
...     {'name': 'FooBar', 'provided': None,
...      'component': None, 'info': ''})()

which is then wrapped in a Utility documentation class and then in a node:

>>> from zope.app.apidoc.utilitymodule.utilitymodule import Utility
>>> util = Utility(uiface, foobar_reg)
>>> node = Node(util)

We can now ask the menu to give us the tile and link for the utility:

>>> menu.getMenuTitle(node)
'FooBar'
>>> menu.getMenuLink(node)
'./foo.bar.iface/Rm9vQmFy/index.html'

Finally, we get menu title and link for a utility without a name:

>>> from zope.app.apidoc.utilitymodule.utilitymodule import NONAME
>>> noname_reg = type(
...     'RegistrationStub', (),
...     {'name': NONAME, 'provided': None,
...      'component': None, 'info': ''})()
>>> util = Utility(uiface, noname_reg)
>>> node = Node(util)
>>> menu.getMenuTitle(node)
'no name'
>>> menu.getMenuLink(node)
'./foo.bar.iface/X19ub25hbWVfXw==/index.html'

UtilityDetails class

This class provides presentation-ready data about a particular utility.

getName()

Get the name of the utility.

>>> from zope.app.apidoc.utilitymodule.browser import UtilityDetails
>>> details = UtilityDetails()
>>> details.context = Utility(None, foobar_reg)
>>> details.getName()
'FooBar'

Return the string no name, if the utility has no name.

>>> details.context = Utility(None, noname_reg)
>>> details.getName()
'no name'

getInterface()

Return the interface details view for the interface the utility provides.

Let's start by creating the utility interface and building a utility registration:

>>> from zope.interface import Interface
>>> class IBlah(Interface):
...     pass
>>> blah_reg = type(
...     'RegistrationStub', (),
...     {'name': 'Blah', 'provided': IBlah,
...      'component': None, 'info': ''})()

Then we wrap the registration in the utility documentation class and create the details view:

>>> details = UtilityDetails()
>>> details.context = Utility(None, blah_reg)
>>> details.request = None

Now that we have the details view, we can look up the interface's detail view and get the id (for example):

>>> iface = details.getInterface()
>>> iface.getId()
'__builtin__.IBlah'

getComponent()

Return the Python path and a code browser URL path of the implementation class.

This time around we create the utility class and put it into a utility registration:

>>> class Foo(object):
...     pass
>>> foo_reg = type(
...     'RegistrationStub', (),
...     {'name': '', 'provided': Interface, 'component': Foo(), 'info': ''})()

Then we create a utility documentation class and its details view:

>>> details = UtilityDetails()
>>> details.context = Utility(Interface, foo_reg)

Now we can get the component information:

>>> pprint(details.getComponent())
{'path': '__builtin__.Foo', 'url': None}