===========
Five Manual
===========

Introduction
------------

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?
===========

An interface is simply a description of what an object provides to the
world, i.e. its public attribute and methods. It looks very much like
a class, but contains no implementation::

  from zope.interface import Interface

  # by convention, all interfaces are prefixed with ``I``
  class IElephant(Interface):
      """An elephant is a big object that barely fits in the cupboard.
      """

      def getAngerLevel():
          """Anger level, maximum of 100.

          The longer the elephant has been in the cupboard, the angrier.
          """

      def isInCupboard():
          """Returns true if the elephant is indeed in cupboard.
          """

      def trunkSmash(target):
          """Smash the target with trunk.

          The anger level determines the force of the hit.
          """

      def trample(target):
          """Trample the target.
          
          The anger level determines the rate of flattening of the target.
          """

A concrete class somewhere can now claim that it implements the
interface (i.e. its instance will provide the interface)::

  class PinkElephant:
      # this says all instances of this class provide IElephant
      implements(IElephant)

      def getAngerLevel(self):
          return 0 # this elephant is peaceful

      def isInCupboard(self):
          return False # it's never in a cupboard but can be found in bottles

      def trunkSmash(self, target):
          target.tickle()

      def trample(self, target):
          target.patOnHead()

Interfaces themselves are good for a number of reasons:

* They provide API documentation.

* They help you make explicit the design of your application,
  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
  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
not the maintainer), but you still want to make it implement an
interface. Five provides a ZCML directive to do this::

  <five:implements class="tolkien.Oliphant" 
      implements="interfaces.IElephant" />

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).

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.

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::

  from zope.interface import Interface

  class IMyInterface(Interface):
      """This is a Zope 3 interface.
      """
      def someMethod():
          """This method does amazing stuff.
          """

Now to make some class declare that it implements this interface, you
need to use the ``implements()`` function in the class::

  from zope.interface import implements
  from interfaces import IMyInterface

  class MyClass:
      implements(IMyInterface)

      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):
      """The interface we adapt to.
      """

      def anotherMethod():
          """This method does more stuff.
          """

Next we'll work on the class that implements the adapter. The
requirement to make a class that is an adapter is very simple; you
only need to take a context object as the constructor. The context
object is the object being adapted. An example::

  from zope.interface import implements
  from interfaces import INewInterface

  class MyAdapter:
      implements(INewInterface)
 
      def __init__(self, context):
          self.context = context

      def anotherMethod(self):
          return "We have adapted: %s" % self.context.someMethod()

Next, we hook it all up using zcml. If the classes are in a module
called ``classes.py`` and the interfaces in a module called
``interfaces.py``, we can declare ``MyAdapter`` to be an adapter for
``IMyInterface`` to ``INewInterface`` like this (in a file called
``configure.zcml``)::

  <configure xmlns="http://namespaces.zope.org/zope">

    <adapter 
      for=".interfaces.IMyInterface"
      provides=".interfaces.INewInterface"
      factory=".classes.MyAdapter" /> 
    
  </configure>

Five 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::

  from classes import MyClass
  from interfaces import INewInterface

  object = MyClass()
  adapted = INewInterface(object)
  print adapted.anotherMethod()

Views in Five
-------------

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.

Five 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 (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.

Typically you give your classes an interface using the ``implements``
directive in the class body::

  class MyClass:
      implements(ISomeInterface)

For existing objects that you cannot modify this is not
possible. Instead, we provide a ZCML directive to accomplish this. As
an example, to make Zope's ``Folder`` (and all its subclasses)
implement ``IFolder`` (an interface you defined), you can do the
following in ZCML::

  <five:implements class="OFS.Folder.Folder" 
                   interface=".interfaces.IFolder" />

``five`` in this case refers to the XML namespace for Five,
``http://namespace.zope.org/five``.


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``.

* They need to be initialized with the Zope 2 security system, as
  otherwise you cannot use the view.

* This also means they need to be part of the Zope 2 acquisition
  system, as this is a requirement for Zope 2 security to
  function. The ``BrowserView`` base class, available from
  ``Products.Five``, already inherits from ``Acquisition.Explicit`` to
  make this be the case. Acquisition is explicit so no attributes can
  be acquired by accident.

An example of a simple view::
 
  from Products.Five import BrowserView

  class SimpleFolderView(BrowserView):
      security = ClassSecurityInfo()

      security.declarePublic('eagle')
      def eagle(self):
          """Test
          """
          return "The eagle has landed: %s" % self.context.objectIds()

  InitializeClass(SimpleFolderView)

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.

As you can see, the class is initialized with the Zope 2 security
system. This view uses methods in Python, but you can also use other
Zope 2 mechanisms such as ``PageTemplateFile``.

Finally, we need to hook up the pages through ZCML::

  <browser:page 
    for=".interfaces.IFolder"
    class=".browser.SimpleFolderView"
    attribute="eagle"
    name="eagle.txt"
    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
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.