Log message for revision 107511: More documentation updates Changed: U Zope/trunk/src/Products/Five/browser/pagetemplatefile.py U Zope/trunk/src/Products/Five/browser/resource.py U Zope/trunk/src/Products/Five/browser/tests/classes.py U Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt U Zope/trunk/src/Products/Five/browser/tests/provider.txt U Zope/trunk/src/Products/Five/component/__init__.py U Zope/trunk/src/Products/Five/component/component.txt U Zope/trunk/src/Products/Five/doc/main.txt U Zope/trunk/src/Products/Five/doc/manual.txt D Zope/trunk/src/Products/Five/doc/presentations/ D Zope/trunk/src/Products/Five/doc/products/ U Zope/trunk/src/Products/Five/fiveconfigure.py
-=- Modified: Zope/trunk/src/Products/Five/browser/pagetemplatefile.py =================================================================== --- Zope/trunk/src/Products/Five/browser/pagetemplatefile.py 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/browser/pagetemplatefile.py 2010-01-01 18:53:56 UTC (rev 107511) @@ -47,8 +47,8 @@ def __call__(self, __instance, *args, **keywords): # Work around BBB foul. Before Zope 2.12 there was no first argument - # but the Zope 3 version has one called instance. Some people used - # instance as an additional keyword argument. + # but the zope.pagetemplate version has one called instance. Some + # people used instance as an additional keyword argument. instance = __instance namespace = self.pt_getContext( request=instance.request, Modified: Zope/trunk/src/Products/Five/browser/resource.py =================================================================== --- Zope/trunk/src/Products/Five/browser/resource.py 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/browser/resource.py 2010-01-01 18:53:56 UTC (rev 107511) @@ -35,7 +35,7 @@ class Resource(object): """A mixin that changes the URL-rendering of resources (__call__). - In Zope 3, resource URLs are of the form + In zope.browserresource, resource URLs are of the form nearest_site/@@/resource_name. Since Zope 2 didn't have support for sites from the beginning of the Five integration, resource URLs in Zope 2 are of the form context/++resource++resource_name. Modified: Zope/trunk/src/Products/Five/browser/tests/classes.py =================================================================== --- Zope/trunk/src/Products/Five/browser/tests/classes.py 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/browser/tests/classes.py 2010-01-01 18:53:56 UTC (rev 107511) @@ -19,7 +19,7 @@ from Products.Five import BrowserView class IOne(Interface): - """This is a Zope 3 interface. + """This is an interface. """ class One(object): Modified: Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt =================================================================== --- Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/browser/tests/pages_ftest.txt 2010-01-01 18:53:56 UTC (rev 107511) @@ -19,7 +19,7 @@ ---------- In Zope 2, objects normally have to have a docstring in order to be -published. This crazy requirement luckily isn't true for Zope 3, so +published. This crazy requirement luckily isn't true for zope.publisher, so it should be possible to write docstring-less view classes that are still published through ZPublisher. Modified: Zope/trunk/src/Products/Five/browser/tests/provider.txt =================================================================== --- Zope/trunk/src/Products/Five/browser/tests/provider.txt 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/browser/tests/provider.txt 2010-01-01 18:53:56 UTC (rev 107511) @@ -18,9 +18,9 @@ Content Provider is a term from the Java world that refers to components that can provide HTML content. It means nothing more! How the content is found and -returned is totally up to the implementation. The Zope 3 touch to the concept -is that content providers are multi-adapters that are looked up by the -context, request (and thus the layer/skin), and view they are displayed in. +returned is totally up to the implementation. The Zope touch to the concept is +that content providers are multi-adapters that are looked up by the context, +request (and thus the layer/skin), and view they are displayed in. So let's create a simple content provider: Modified: Zope/trunk/src/Products/Five/component/__init__.py =================================================================== --- Zope/trunk/src/Products/Five/component/__init__.py 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/component/__init__.py 2010-01-01 18:53:56 UTC (rev 107511) @@ -43,7 +43,7 @@ @zope.interface.implementer(IComponentLookup) def siteManagerAdapter(ob): """Look-up a site manager/component registry for local component - lookup. This is registered in place of the one in Zope 3 so that + lookup. This is registered in place of the one in zope.site so that we lookup using acquisition in addition to the ``ILocation`` API. """ site = findSite(ob) Modified: Zope/trunk/src/Products/Five/component/component.txt =================================================================== --- Zope/trunk/src/Products/Five/component/component.txt 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/component/component.txt 2010-01-01 18:53:56 UTC (rev 107511) @@ -5,7 +5,7 @@ ----------------------------- In order to do context-based component look-up, the Component -Architecture adapts the context to ``IComponentLookup``. Zope 3's +Architecture adapts the context to ``IComponentLookup``. zope.site's default adapter uses the ``ILocation`` API to walk up the object tree and find a site that way. Five provides its own adapter that also supports acquisitional parents. Modified: Zope/trunk/src/Products/Five/doc/main.txt =================================================================== --- Zope/trunk/src/Products/Five/doc/main.txt 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/doc/main.txt 2010-01-01 18:53:56 UTC (rev 107511) @@ -1,79 +1,22 @@ -Five, the Zope 3 in Zope 2 project -================================== +Five, a Zope Integration project +================================ What is Five? ------------- -Five is a Zope 2 product that allows you to integrate Zope 3 -technologies into Zope 2, today. Among others, it allows you to use -Zope 3 interfaces, ZCML-based configuration, adapters, browser pages -(including skins, layers, and resources), automated add and edit forms -based on schemas, object events, as well as Zope 3-style i18n message -catalogs. +A couple of years back an attempt was made to rewrite Zope 2 from scratch and +provide an upgrade path from current Zope 2 to the new version. This project +used the name Zope 3. The attempt of writing a newer version of a full blown +application server similar to Zope 2 failed. Instead the project generated a +whole lot of underlying technologies and new concepts packaged up in reusable +libraries. -We've tried to keep the Five experience as close to Zope 3 as -possible, so this means that what you learn while using Five should -also be applicable to Zope 3, and viceversa. We're in the process of -evaluating lots more Zope 3 technologies for integration into Zope 2. -This is the right moment for interested Zope 2 and Zope 3 developers -to jump in. We're looking for cooperation between different Zope 2 -projects so that this can be a foundational system for us all. +Five is the project that integrates those technologies and packages into +Zope 2. It's name is a pun on the original naming of Zope 2 + Zope 3 = Zope 5. +Among others, it allows you to use zope.interface, ZCML-based configuration, +adapters, browser pages (including layers, and resources), zope.schemas, +object events, as well as zope.i18n message catalogs. -Download --------- - -We have released Five 1.2.6 on 13 August 2006. You may download it -here: - -http://codespeak.net/z3/five/release/Five-1.2.6.tgz - -We have released Five 1.3.8 on 4 November 2006. This is a bugfix -release for Five 1.3 and will be included in the next Zope 2.9 bugfix -release. You may download it here: - -http://codespeak.net/z3/five/release/Five-1.3.8.tgz - -We have also released Five 1.4.2. This is a feature release and is -compatible with Zope 2.9. You may download it here: - -http://codespeak.net/z3/five/release/Five-1.4.2.tgz - -We have also released Five 1.5.1. It will be included with the next -Zope 2.10 bugfix release. You may download it here: - -http://codespeak.net/z3/five/release/Five-1.5.1.tgz - -To check which version of Five is compatible with which version of -Zope, please refer to the `compatibility matrix -<http://codespeak.net/z3/five/INSTALL.html>`_. - -Joining the project -------------------- - -Five is kindly hosted on codespeak.net, and is part of the larger -*Zope 3 Base* project that offers an approachable area for -developers of Zope 3 related software. - -Five has a mailing list: - -http://codespeak.net/mailman/listinfo/z3-five - -We're also active on IRC, at ``#z3-base`` on freenode. - -Five is hosted in a subversion repository on codespeak.net. You can -browse this on the web here: - -http://codespeak.net/svn/z3/Five/ - -You can check out Five using the following subversion command:: - - svn co svn://svn.zope.org/repos/main/Products.Five/trunk Five - -There's also a checkins mailing list for the Z3 project, here: - -http://codespeak.net/mailman/listinfo/z3-checkins - -If you want checkin access, please join the z3-five mailing list or -the ``#z3-base`` IRC channel, and ask us there. - -We hope to hear from you! +We've tried to keep the Five experience as close to that of the integrated +Zope packages as possible, so this means that what you learn while using Five +should also be applicable to the Zope packages directly. Modified: Zope/trunk/src/Products/Five/doc/manual.txt =================================================================== --- Zope/trunk/src/Products/Five/doc/manual.txt 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/doc/manual.txt 2010-01-01 18:53:56 UTC (rev 107511) @@ -2,36 +2,9 @@ Five Manual =========== -Introduction ------------- +Zope interfaces +--------------- -Five's goal is to let you, the Zope 2 developer, use Zope 3 code in -Zope 2. Our aim is to make as much of Zope 3 code work in Zope 2 as -possible, while integrating it with Zope 2. - -Five can be used inside your current Zope 2 project. The benefits are: - -* availability of Zope 3 technologies in Zope 2 like the component - architecture and declarative configuration. - -* you can gradually evolve your Zope 2 project so it is better - positioned for the migration to Zope 3. - -* you start learning about Zope 3 right now, preparing yourself better - for the future. Since Zope 3 is open to contributions, you could - even influence your future for the better. - -Five can also be used to develop new Zope 2 products, though depending -on your deployment requirements it might in that case make more sense -to develop for Zope 3 directly. - -Five is only useful on the Python (Product) level in Zope 2, not from -within the Zope Management Interface. Five makes no attempt to provide -a user interface, but is aimed squarely at the Python developer. - -Zope 3 interfaces ------------------ - Interfaces? =========== @@ -95,61 +68,32 @@ hopefully improving it. * If an object provides an interface, that object is considered to be - a *component*. This means you can use Zope 3's component + a *component*. This means you can use Zope's component architecture with these objects. -In order to use Five, you'll have to make your objects provide -interfaces. Sometimes, you cannot change the code of class (as you are +In order to use the component architecture, you'll have to make your objects +provide interfaces. Sometimes, you cannot change the code of class (as you are not the maintainer), but you still want to make it implement an -interface. Five provides a ZCML directive to do this:: +interface. Zope provides a ZCML directive to do this:: - <five:implements class="tolkien.Oliphant" - implements="interfaces.IElephant" /> + <class class="tolkien.Oliphant"> + <implements interface=".interfaces.IElephant" /> + </class> -Interfaces in Zope 2 versus Zope 3 -================================== - -You may be familiar with Zope 2's way of declaring interfaces. Zope 2 -has used the ``__implements__`` class attribute for interface -declarations. Zope 2 cannot detect Zope 3 interfaces and the Zope 3 -machinery cannot detect Zope 2 interfaces. This is a good thing, as -Zope 2 has no way to deal with Zope 3 interfaces, and Zope 3 cannot -comprehend Zope 2 interfaces. This means you can safely make a class -declare both a Zope 2 and Zope 3 interface independently from each -other. It's a rare case where you need this though; you're usually -better off just switching to ``implements()`` for your application if -you are using Five. - -Switching from Zope 2 interfaces to Zope 3 interfaces is easy -- just -make your interfaces inherit from ``zope.interface.Interface`` instead -of ``Interface.Interface`` (or ``Interface.Base``). Next, change all -``__implements__`` to ``implements()``. - -This should get you going and your application may very well still -work. Later on, you will also have to change calls to -``isImplementedBy`` and such in your application to ``providedBy``, as -``isImplementedBy`` has been deprecated (you'll see the -DeprecationWarnings in your Zope log). - -N.B.: As of Zope 2.12, the old Zope2 interfaces are *removed*. - Adapters -------- From a Python programmer's perspective, the immediate thing that Five brings to do the table are adapters. This section goes through some -demo code to explain how everything is tied -together. ``demo/FiveDemo`` is a demo Product you can install and -examine that has all the presented here together. +demo code to explain how everything is tied together. -Zope 3 adapters depend on Zope 3 interfaces. To create a Zope 3 -interface you need to subclass it from -``zope.interface.Interface``. Here is an example:: +Zope adapters depend on Zope interfaces. To create a Zope interface you need +to subclass it from ``zope.interface.Interface``. Here is an example:: from zope.interface import Interface class IMyInterface(Interface): - """This is a Zope 3 interface. + """This is an interface. """ def someMethod(): """This method does amazing stuff. @@ -167,9 +111,6 @@ def someMethod(self): return "I am alive! Alive!" -For an explanation of the relation of Zope 3 interfaces to Zope 2 -interfaces, see below. - Now let's set up the interface that we are adapting to:: class INewInterface(Interface): @@ -212,7 +153,7 @@ </configure> -Five will automatically pickup ``configure.zcml`` when it's placed in +Zope will automatically pickup ``configure.zcml`` when it's placed in the product's directory. Any object that provides ``IMyInterface`` can now be adapted to ``INewInterface``, like this:: @@ -223,26 +164,18 @@ adapted = INewInterface(object) print adapted.anotherMethod() -Views in Five -------------- +Views +----- -This section will give a brief introduction on how to use the five -view system. ``demo/FiveViewsDemo`` is a demo Product you can install -and examine that has all the presented here tied together, please -consult it for more details. ``tests/products/FiveTest`` actually -contains a more detailed set of test views, trying a number of -features. Finally, read up on the way Zope 3 does it. While Five is a -subset of Zope 3 functionality and has been adapted to work with Zope -2, much of Zope 3's documentation still works. +This section will give a brief introduction on how to use the Zope view system. -Five enables you to create views for your own objects, or even built-in +Zope enables you to create views for your own objects, or even built-in Zope objects, as long as two things are the case: -* The object provides an Zope 3 interface, typically through its class. +* The object provides a Zope interface, typically through its class. -* The object (typically its class) is made Zope 3 traversable. This - allows Zope 3 views, resources and other things to be attached to a - Zope 2 object. +* The object (typically its class) is made traversable. This allows Zope + views, resources and other things to be attached to a Zope object. Typically you give your classes an interface using the ``implements`` directive in the class body:: @@ -256,36 +189,32 @@ implement ``IFolder`` (an interface you defined), you can do the following in ZCML:: - <five:implements class="OFS.Folder.Folder" - interface=".interfaces.IFolder" /> + <class class="OFS.Folder.Folder" + <implements interface=".interfaces.IFolder" /> + </class> -``five`` in this case refers to the XML namespace for Five, -``http://namespace.zope.org/five``. +Views in Zope are simple classes. The only requirements for a view class are: - -Views in Five are simple classes. The only requirements for a Five -view class are: - * They need an ``__init__()`` that take a context and a request attribute. Typically this comes from a base class, such as ``BrowserView``. An example of a simple view:: - from Products.Five import BrowserView + from zope.publisher.browser import BrowserView class SimpleFolderView(BrowserView): def eagle(self): """Test """ - return "The eagle has landed: %s" % self.context.objectIds() + return "The eagle has landed: %s" % self.context.keys() Note that it is not a good idea to give a view class its own -``index_html``, as this confuses Five's view lookup machinery. +``index_html``, as this confuses Zope's view lookup machinery. -This view uses methods in Python, but you can also use other Zope 2 mechanisms -such as ``PageTemplateFile``. +This view uses methods in Python, but you can also use other mechanisms +such as ``ViewPageTemplateFile``. Finally, we need to hook up the pages through ZCML:: @@ -297,9 +226,8 @@ permission="zope2.ViewManagementScreens" /> -``browser`` in this refers to the XML namespace of Zope 3 for browser -related things; it's -``http://namespace.zope.org/browser``. ``permission`` declares the +``browser`` in this refers to the XML namespace for browser related things; +it's ``http://namespace.zope.org/browser``. ``permission`` declares the Zope 2 permission needs in order to access this view. The file -``permissions.zcml`` in Five contains a mapping of Zope 2 permissions -to their Zope 3 names. +``permissions.zcml`` in AccessControl contains a mapping of Zope 2 permissions +to their zope.security names. Modified: Zope/trunk/src/Products/Five/fiveconfigure.py =================================================================== --- Zope/trunk/src/Products/Five/fiveconfigure.py 2010-01-01 18:24:44 UTC (rev 107510) +++ Zope/trunk/src/Products/Five/fiveconfigure.py 2010-01-01 18:53:56 UTC (rev 107511) @@ -13,7 +13,7 @@ ############################################################################## """Five-specific directive handlers -These directives are specific to Five and have no equivalents in Zope 3. +These directives are specific to Five and have no equivalents outside of it. $Id$ """ _______________________________________________ Zope-Checkins maillist - Zope-Checkins@zope.org https://mail.zope.org/mailman/listinfo/zope-checkins