Package: zam.api
This package provides an API for ZAM (Zope Application Management).ContentsCHANGES0.7.0 (2011-01-13)0.6.1 (2009-07-06)0.6.0 (2009-07-06)0.5.3 (2008-06-07)0.5.2 (2008-04-11)0.5.1 (2008-04-13)0.5.0 (2008-04-11)zam.apiZAM Plugin FrameworkBase Registry PluginsLayersBig noteIZAMCoreLayerIZAMPluginLayerIZAMBrowserLayerIZAMSkinLayerIZAMBrowserSkinCHANGES0.7.0 (2011-01-13)Updated test set up and tests to run with ZTK 1.0 and current z3c.form
version.Removed dependency onzope.app.twisted,zc.configurationand most
of thezope.app.*packages.Using Python’sdoctestmodule instead of depreactedzope.testing.doctestunit.Fixed package metadata, added doctests toplong_description.0.6.1 (2009-07-06)Removed deprecation warnings.0.6.0 (2009-07-06)Updating tests and dependencies to work with latest versions of packages.0.5.3 (2008-06-07)A test dependency (zope.app.session) was missing
(still checking with KGS 3.4)0.5.2 (2008-04-11)Simplify ftesting setup, removed duplicated configuration. Make it better
reusable. Now we can include app.zcml and mixin ftesting.zcml at the same
time in plugin tests.0.5.1 (2008-04-13)Added new plugin layer for zamplugin.contents plugin0.5.0 (2008-04-11)Now plugin provides it’s own management form. By default the PluginManagement
page can be used which is a mixin of IContentProvider and IForm. This makes
it possible to write intelligent plugin management views which can do more
then just install and uninstall.Initial Releasezam.apiThis package contains the Zope Application Management api. We support a test
skin for this package which allows us to test the plugin management page.
There is also a ZAMTest site available whcih this test will use. This test site
can also be used in any other zam.* or zamplugin.* package.Login as manager first:>>> from zope.testbrowser.testing import Browser
>>> manager = Browser()
>>> manager.addHeader('Authorization', 'Basic mgr:mgrpw')Check if we can access the page.html view which is registred in the
ftesting.zcml file with our skin:>>> manager = Browser()
>>> manager.handleErrors = False
>>> manager.addHeader('Authorization', 'Basic mgr:mgrpw')
>>> skinURL = 'http://localhost/++skin++ZAMTest/index.html'
>>> manager.open(skinURL)
>>> manager.url
'http://localhost/++skin++ZAMTest/index.html'Now let’s create a test site calledfirstand add them to the root:>>> import zam.api.testing
>>> root = getRootFolder()
>>> firstSite = zam.api.testing.ZAMTestSite(u'first')
>>> root['first'] = firstSiteAnd create another one calledsecond:>>> secondSite = zam.api.testing.ZAMTestSite(u'second')
>>> root['second'] = secondSiteGo the the new zam test site:>>> firstSiteURL = 'http://localhost/++skin++ZAMTest/first'
>>> manager.open(firstSiteURL + '/index.html')
>>> manager.url
'http://localhost/++skin++ZAMTest/first/index.html'and to thesecondsite:>>> secondSiteURL = 'http://localhost/++skin++ZAMTest/second'
>>> manager.open(secondSiteURL + '/index.html')
>>> manager.url
'http://localhost/++skin++ZAMTest/second/index.html'and go to theplugins.htmlpage:>>> manager.open(firstSiteURL + '/plugins.html')Now we see the plugins.html page:>>> print manager.contents
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
      lang="en">
<head>
<title>ZAM</title><meta http-equiv="cache-control" content="no-cache" />
<meta http-equiv="pragma" content="no-cache" />
</head>
<body>
<form action="./plugins.html" method="post" enctype="multipart/form-data" class="plugin-form">
  <h1>ZAM Plugin Management</h1>
  <fieldset id="pluginManagement">
    <strong class="notInstalledPlugin">ZAM test plugin</strong>
    <div class="description">ZAM test plugin.</div>
  <div class="viewspace">
    <div>
    </div>
  </div>
  <div>
    <div class="buttons">
      <input id="zam-api-testing-buttons-install"
             name="zam.api.testing.buttons.install"
             class="submit-widget button-field" value="Install"
             type="submit" />
    </div>
  </div>
  </fieldset>
</form>
</body>
</html>Before we install the plugin, we try to access the page which only is available
if the zam test plugin is installed:>>> manager.open(firstSiteURL + '/test.html')
Traceback (most recent call last):
...
NotFound: Object: <ZAMTestSite u'first'>, name: u'test.html'Thesecondsite does also not provide such a test page:>>> manager.open(secondSiteURL + '/test.html')
Traceback (most recent call last):
...
NotFound: Object: <ZAMTestSite u'second'>, name: u'test.html'As you can see there is no suchtest.htmlpage. Let’s install our zam test
plugin:>>> manager.open(firstSiteURL + '/plugins.html')
>>> manager.getControl(name='zam.api.testing.buttons.install').click()Now we can see that the plugin is installed:>>> print manager.contents
<!DOCTYPE...
<h1>ZAM Plugin Management</h1>
<fieldset id="pluginManagement">
  <strong class="installedPlugin">ZAM test plugin</strong>
  <div class="description">ZAM test plugin.</div>
<div class="viewspace">
...
<div>
  <div class="buttons">
    <input id="zam-api-testing-buttons-uninstall"
           name="zam.api.testing.buttons.uninstall"
           class="submit-widget button-field" value="Uninstall"
           type="submit" />
  </div>
</div>
...Now make test coverage happy and test different things. The zam plugin test
page is available at thefirstsite>>> manager.open(firstSiteURL + '/test.html')
>>> manager.url
'http://localhost/++skin++ZAMTest/first/test.html'But not at thesecondsite:>>> manager.open(secondSiteURL + '/test.html')
Traceback (most recent call last):
...
NotFound: Object: <ZAMTestSite u'second'>, name: u'test.html'Let’s unsinstall the plugin:>>> manager.open(firstSiteURL + '/plugins.html')
>>> manager.getControl(name='zam.api.testing.buttons.uninstall').click()And check if the site is not available anymore:>>> manager.open(firstSiteURL + '/test.html')
Traceback (most recent call last):
...
NotFound: Object: <ZAMTestSite u'first'>, name: u'test.html'ZAM Plugin FrameworkThe plugin framework allows us to write “3rd party” software that depends on
the base system’s API, but the base system does not in any way depend on the
new software. This allows us to keep the base system compact, and separate
optional features into clearly separated packages.There are two different type of plugins offered. Simple plugin do what they
needs to do during the install and uninstall process. Base registry
supported plugins will install a custom component registry.The fundamental concept of the package is that a plugin can be installed for a
particular site. At any time, you can ask the plugin, whether it has been
installed for a particular site. The third API method allows you to uninstall
the plugin from a site.So let’s implement a trivial plugin that stores an attribute:>>> from zam.api import plugin>>> class SamplePlugin(plugin.Plugin):
...     title = u'Sample'
...     description = u'Sample Attribute Plugin'
...
...     def isInstalled(self, site):
...         """See interfaces.IPlugin"""
...         return hasattr(site, 'sample')
...
...     def install(self, site):
...         """See interfaces.IPlugin"""
...         if not self.isInstalled(site):
...             setattr(site, 'sample', 1)
...
...     def uninstall(self, site):
...         """See interfaces.IPlugin"""
...         if self.isInstalled(site):
...             delattr(site, 'sample')The title and description of the plugin serve as pieces of information for the
user, and are commonly used in the UI.So let’s use the sample plugin:>>> from zam.api import testing
>>> site = testing.ZAMTestSite(u'ZAM Test Site')
>>> sm = site.getSiteManager()>>> sample = SamplePlugin()At the beginning the plugin is not installed, so let’s take care of that.>>> sample.isInstalled(site)
False>>> sample.install(site)
>>> site.sample
1>>> sample.isInstalled(site)
TrueHowever, once the plugin is installed, it cannot be installed again:>>> site.sample = 2>>> sample.install(site)
>>> site.sample
2This is a requirement of the API. Now you can also uninstall the plugin:>>> sample.uninstall(site)
>>> sample.isInstalled(site)
False
>>> site.sample
Traceback (most recent call last):
...
AttributeError: 'ZAMTestSite' object has no attribute 'sample'You cannot uninstall the plugin again:>>> sample.uninstall(site)Base Registry PluginsAn important base implementation is a plugin that installs a new base registry
to the to the site.We also need a base registry for the plugin:>>> import zope.component
>>> from z3c.baseregistry import baseregistry>>> sampleRegistry = baseregistry.BaseComponents(
...     zope.component.globalSiteManager, 'sampleRegistry')Now we can create the plugin, either through instantiation or sub-classing:>>> class SampleRegistryPlugin(plugin.BaseRegistryPlugin):
...     title = u'Sample Registry'
...     description = u'Sample Registry Plugin'
...     registry = sampleRegistry>>> regPlugin = SampleRegistryPlugin()We use the same API methods as before. Initially the plugin is not installed:>>> sampleRegistry in sm.__bases__
False
>>> regPlugin.isInstalled(site)
FalseNow we install the plugin:>>> regPlugin.install(site)>>> sampleRegistry in sm.__bases__
True
>>> regPlugin.isInstalled(site)
TrueAs before, installing the plugin again does nothing:>>> len(sm.__bases__)
2>>> regPlugin.install(site)>>> len(sm.__bases__)
2And uninstalling the plugin is equally simple:>>> regPlugin.uninstall(site)>>> sampleRegistry in sm.__bases__
False
>>> regPlugin.isInstalled(site)
False
>>> len(sm.__bases__)
1Uninstalling a second time does nothing:>>> regPlugin.uninstall(site)>>> sampleRegistry in sm.__bases__
False
>>> len(sm.__bases__)
1LayersWe offer a fine grained layer concept which allows you to use the ZAM skin
out of the box, or lets you define your own skins, offering what you need.
Each ZAM plugin should configure it’s component for the IZAMBrowserLayer and
not for the IZAMCoreLayer. This allows others to use the IZAMCoreLayer without
any plugin configuration. See the different layer descriptions below for more
information about the ZAM layer concept.Big noteThis is only important if you’d like to define your own skin which uses
selective zam plugins.The layer concept has some limitations when it comes to adapter lookups. It’s
not possible to define a custom layer and make an existing layer act like it
whould inherit this layer.Implementsandprovideconcept only work on
classes but not on interfaces. Let’s be more precise: they work but don’t affect the
request. Which means the request doesn’t know about such applied layers. This
means there is no[*] way to apply a later defined layer to an existing layer.
This is the reason why we offer all plugin layers in the zam.api.layer package.
But what does this mean if you’d like to define custom plugins and their layers?
You have to define your own skin and inherit your new layers in this skin.
You can skip the named skin configuration and configure your custom skin.[*] Ok, there is a way to apply layers to an existing layer or at least it will
be effectively the same thing. There are two ways: you can add a SkinChangedEvent which
will do an alsoProvide and inject your layer, or you can use a ‘before traversal
event’ subscriber which does the same. I decided not to use these patterns here
as defaults, because such subscribers will affect every skin and will cost
processing time on every request. The option we have with defining an explicit
configuration for a custom skin is to small to pay that price.IZAMCoreLayerThe core layer provides the ZAM core management views but no plugins and
skin configuration. This allows us to write skins with a selective choice
of plugins. Of course each plugin must be configured again for your
custom skin. Out of the box, there is no way to offer a working set without
configuring a plugin twice using two different layers.IZAMPluginLayerThe zam plugin layer should not be used in plugins. You need to define a
plugin layer for your plugin in zam.api.layer and use this newly defined layer.
This layer then becomes a part of the IZAMPluginLayer. This makes it
possible to use the IZAMPluginLayer and get all it’s configuration.But what happens if you don’t develop in the zamplugin.* namespace? Then you
only have the option to configure your plugins for an additional layer and use
another skin which uses the IZAMPluginLayer and your custom layer. Using the
IAZMPluginLayer for your configuration and sharing such packages ends in
bad configuration and others needs to exclude your configuration if it
is not needed in every skin they provide and is based on IZAMPluginLayer.
Of course you can do this in your own private projects, but please do not
use it for public shared packages. Help us provide a clean IZAMPluginLayer!Any improvement which offers us a better layer usage concept is very welcome if
it doesn’t need to configure additional subscribers.IZAMBrowserLayerThis is the “all in one” layer which can be used for build skins which knows
about all plugin configurations. All plugins should use this layer.IZAMSkinLayerThe IZAMSkinLayer offers the UI part for ZAM but is not registered as skin.
You can use this layer as base if you’d like to develop a custom skin. This
layer contains the nested div menu implementation.IZAMBrowserSkinThe IZAMBrowserSkin uses the IZAMSkinLayer and IZAMBrowserLayer and offers the
UI part for ZAM as named skin. This means the IZAMBrowserSkin is accessible
as ++skin++ZAM.