[z3-checkins] r5374 - in z3/Five/trunk: . doc

[faassen at codespeak.net]

Author: faassen
Date: Mon Jun 28 10:10:14 2004
New Revision: 5374

Added:
   z3/Five/trunk/doc/features.txt
Modified:
   z3/Five/trunk/README.txt
Log:
Added a features.txt file and reference to it.


Modified: z3/Five/trunk/README.txt
==============================================================================
--- z3/Five/trunk/README.txt	(original)
+++ z3/Five/trunk/README.txt	Mon Jun 28 10:10:14 2004
@@ -36,6 +36,8 @@
 
 * Zope 2 security declarations in ZCML instead of in Python code.
 
+For more information, see ``doc/features.txt``.
+
 How to install Five
 -------------------
 

Added: z3/Five/trunk/doc/features.txt
==============================================================================
--- (empty file)
+++ z3/Five/trunk/doc/features.txt	Mon Jun 28 10:10:14 2004
@@ -0,0 +1,92 @@
+=============
+Five features
+=============
+
+Five features are mostly Zope 3 features, though Five has some extras,
+and some limitations.
+
+Zope 3 interfaces
+=================
+
+Everything in the ``zope.interface`` package should work. Zope 3
+interfaces are the foundation of the component architecture, and also
+the foundation of schemas.
+
+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.
+
+If you put a ``site.zcml`` in the home 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 (``meta.zcml``, ``configure.zcml``) of all installed Zope 2
+products, if available.
+
+Another special directive, ``five:loadProductsOverrides`` is available
+to load any overriding ZCML (``override.zcml``) in these products. In
+the ``override.zcml`` you can override existing views or adapters, in
+this or in other products.
+
+Adapters
+========
+
+You can use adapters in Five, just like in Zope 3.
+
+Zope 3 views
+============
+
+Zope 3 views work in Five, including layers and skins, though there
+are some limitations:
+
+* You need to make a Zope 2 class "viewable". This can be done by
+  mixing in ``Products.Five.api.Viewable`` into your class, or
+  alternatively, using the ``five:viewable`` directive in ZCML.
+
+* At the the time of writing, special constructs using ``@@`` or
+``++`` do not yet work in URLs. Views with subviews also do not work.
+
+You can use ``five:viewable`` on any Zope 2 class, unless it declares
+its own ``__bobo_traverse__``. We plan to lift the ``bobo_traverse``
+restriction soon.
+
+At the time of writing there is also no provision for default views in
+Five.
+
+Zope 3 page templates
+=====================
+
+The Zope 3 page template engine mostly works at the time of this
+writing, and is automatically used if you use the ``template``
+attribute to the ``browser:page`` directive.
+
+One thing to be aware of is that the page template engine runs
+completely in trusted mode, just like Python code. That is, as soon as
+the page template engine is running, no Zope 2 or Zope 3 security
+checks are made.
+
+Security declarations
+=====================
+
+Five aims to eradicate ``declareProtected``, ``ClassSecurityInfo`` and
+``initializeClass`` from your Zope 2 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.
+
+The ``content`` directive can also be used to declare permissions on
+Zope 2 content classes. Note however that these permissions will be
+ignored by views anyway, as they are trusted -- it only serves to
+protect directly exposed methods on content classes (the python
+scripts and the ZPublisher).
+