Commit c1ad1be2 authored by Hanno Schlichting's avatar Hanno Schlichting

Started updating the Five documentation to avoid referencing Zope 3.

parent c0bb1665
=================================
ZCML Directives supported by Five
=================================
===================================
ZCML Directives supported by Zope 2
===================================
Five tries to use the Zope 3 ZCML directives where possible, though
does sometimes subset the possible attributes. It also introduces a
Zope 2 tries to use the directives from zope.* packages where possible,
though does sometimes subset the possible attributes. It also introduces a
few directives of its own under the ``five`` namespace.
Directives are listed per namespace, in alphabetic order.
......@@ -24,8 +24,7 @@ Declare interface and permissions on classes. Declares Zope 2 permissions.
permission
----------
Way to make Zope 2 permissions available to Five, ``title`` is
permission name.
Way to make Zope 2 permissions available, ``title`` is permission name.
redefinePermission
------------------
......@@ -53,8 +52,7 @@ browser ``http://namespaces.zope.org/browser``
page
----
Declare a page view for an interface. Permission is a Zope 2
permission.
Declare a page view for an interface. Permission is a Zope 2 permission.
pages
-----
......@@ -105,7 +103,7 @@ Loads overriding ZCML in all products (``overrides.zcml``).
sizable
-------
Retrieve size information for a Zope 2 content class via a Zope 3
Retrieve size information for a Zope 2 content class via a zope.size
style ``ISized`` adapter.
deprecatedManageAddDelete
......@@ -123,4 +121,4 @@ Loads all files with .pt extension in a directory as pages.
registerClass
-------------
Registers Five content with Zope 2.
Registers Zope 2 content classes with Zope 2.
Events in Zope 2.9
==================
Events in Zope 2
================
Zope 2.9 (and Zope 2.8 when using Five 1.2) introduces a big change:
Zope 3 style container events.
Zope 2 supports zope.lifecycleevent style events including container events.
With container events, you finally have the ability to react to things
happening to objects without have to subclass ``manage_afterAdd``,
......@@ -39,11 +38,11 @@ current path. Code like::
super(CoolDocument, self).manage_beforeDelete(item, container)
getToolByName(self, 'portal_cool').unregisterCool(self)
This would be the best practice in Zope 2.8. Note the use of ``super()``
to call the base class, which is often omitted because people "know"
that SimpleItem for instance doesn't do anything in these methods.
This had been the best practice in old Zope 2 versions. Note the use of
``super()`` to call the base class, which is often omitted because people
"know" that SimpleItem for instance doesn't do anything in these methods.
If you run this code in Zope 2.9, you will get deprecation warnings,
If you run this code today, you will get deprecation warnings,
telling you that::
Calling Products.CoolProduct.CoolDocument.CoolDocument.manage_afterAdd
......@@ -70,7 +69,7 @@ methods, and ask it to still call them in the proper manner. So Zope
will be sending events when an object is added, for instance, and in
addition call your old ``manage_afterAdd`` method.
One subtlety here is that you may have to modify you methods to just do
One subtlety here is that you may have to modify your methods to just do
their work, and not call their super class. This is necessary because
proper events are already dispatched to all relevant classes, and the
work of the super class will be done trough events, you must not redo it
......@@ -90,8 +89,7 @@ code. This would be bad.
Using subscribers
-----------------
In the long run, and before Zope 2.11 where ``manage_afterAdd`` and
friends will be removed, you will want to use proper subscribers.
In the long run, you will want to use proper subscribers.
First, you'll have to write a subscriber that "does the work", for
instance::
......@@ -157,7 +155,7 @@ of the removed object wouldn't know what happens to them, and for
instance they wouldn't have any way of doing some cleanup before they
disappear.
To solve these two problems, Zope 3 has an additional mechanism by which
To solve these two problems, Zope has an additional mechanism by which
any IObjectEvent is redispatched using multi-adapters of the form ``(ob,
event)``, so that a subscriber can be specific about the type of object
it's interested in. Furthermore, this is done recursively for all
......@@ -189,8 +187,7 @@ respect to events (but you might want to read the full story in
Five/tests/event.txt).
The first use case is the one where the object has to be aware of its
path, like in the CoolDocument example above. That's strictly a Zope 2
concern, as Zope 3 has others ways to deal with this.
path, like in the CoolDocument example above.
In Zope 2 an object has a new path through creation, copy or move
(rename is a kind of move). The events sent during these three
......@@ -200,7 +197,7 @@ IObjectMovedEvent.
So to react to new paths, we have to subscribe to IObjectMovedEvent, but
this will also get us any IObjectRemovedEvent, which we'll have to
filter out by hand (this is unfortunate, and due to the way the Zope 3
filter out by hand (this is unfortunate, and due to the way the Zope
interface hierarchy is organized). So to fix the CoolDocument
configuration we have to add::
......@@ -282,5 +279,5 @@ of the one to which the event was redispatched using the
multi-subscribers we have registered.)
The ``IObjectWillBe...`` events are specific to Zope 2 (and imported
from ``OFS.interfaces``). Zope 3 doesn't really need them, as object
identity is often enough.
from ``OFS.interfaces``). zope.lifecycleevent doesn't really need them, as
object identity is often enough.
=============
Five features
Zope features
=============
Five features are mostly Zope 3 features, though Five has some extras,
and some limitations.
Zope features are mostly features from zope.* packages, though it has some
extras and some limitations.
ZCML
====
ZCML is the Zope Configuration Markup Language, an XML application.
Zope 3 (and Five) code consists of a lot of components that can be
plugged together using ZCML.
ZCML is the Zope Configuration Markup Language, an XML application. Zope code
consists of a lot of components that can be plugged together using ZCML.
If you put a ``site.zcml`` in the home directory of your Zope
If you put a ``site.zcml`` in the etc directory of your Zope
instance, this is the root of the ZCML tree. An example of
``site.zcml`` is in ``site.zcml.in``. If you don't place a
``site.zcml``, Five falls back on ``fallback.zcml``.
ZCML in Five has special directive, ``five:loadProducts``, to load the
ZCML in Zope 2 has a special directive, ``five:loadProducts``, to load the
ZCML (``meta.zcml``, ``configure.zcml``) of all installed Zope 2
products, if available.
......@@ -29,16 +28,15 @@ this or in other products.
Security declarations
=====================
Five aims to eradicate ``declareProtected``, ``ClassSecurityInfo`` and
``initializeClass`` from your Zope 2 code.
Zope 2 aims to eradicate ``declareProtected``, ``ClassSecurityInfo`` and
``initializeClass`` from your code.
In order to do this, Five provides the Zope 3 way of declaring
permissions from ZCML, but uses the Zope 2 mechanisms to actually set
them. To declare permissions for methods and templates on views you
use the ``permission`` attribute on the ``browser:page`` directive,
and specify a Zope 2 permission (given a Zope 3 name). You can find a
list of these permissions in ``permissions.zcml`` in Five. The
permission check takes place before the view is executed.
In order to do this, Zope 2 provides a way of declaring permissions from ZCML.
To declare permissions for methods and templates on views you use the
``permission`` attribute on the ``browser:page`` directive, and specify a
Zope 2 permission (given a dotted name). You can find a list of these
permissions in ``permissions.zcml`` in AccessControl's permissions.zcml.
The permission check takes place before the view is executed.
The ``class`` directive can also be used to declare permissions on
Zope 2 content classes. Note however that these permissions will be
......
......@@ -4,8 +4,7 @@ Internationalization
Translation
-----------
To register Zope 3 style translation domains, use the following ZCML
statement::
To register translation domains, use the following ZCML statement::
<i18n:registerTranslations directory="locales" />
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment