Author: Shane Hathaway



- `Introduction`_
- `How to use CompositePage`_
- `How to write a template`_
- `How it works`_
- `Adapting CompositePage to other applications`_


CompositePage is a way to assemble web pages from page fragments.
Through the use of Zope page templates, browser-based drag and drop, and
custom context menus, CompositePage makes it easy to visually combine
page fragments into complete pages.

CompositePage supercedes the PageDesign product and makes use of
PDLib, a Javascript library.  CompositePage is designed for browsers
that support the DOM (Document Object Model) and CSS (Cascading Style
Sheets) level 2: Firefox, Internet Explorer 5+, Opera, Konqueror, etc.

How to use CompositePage

Follow these steps:

- Install the CompositePage product in Zope by unpacking the archive
  into your Products directory.  I've tested only with a current Zope
  checkout, which is something like Zope 2.7.

- Create a Composite Tool instance in a central location, possibly the
  root folder.

- Create a Composite object.  On the creation form, there is a
  checkbox for creating a sample template.  Leave the checkbox checked.

- Visit the Composite object and select the "Design" tab.  You should
  see a three-column layout with blue dotted lines in the places where
  you are allowed to insert content.

- Click just beneath one of the blue lines.  A context menu will pop
  up.  Select "Add...".

- You will be directed to a slot (a folderish object.)  In slots, you
  can add composite elements.  Add a composite element that points to a

- Find the composite created earlier and select the "Design" tab
  again.  Your new object should now show up in the slot.

- Move the object to a different slot using drag and drop.  When the
  mouse cursor is hovering over a permitted target (the blue dotted
  lines are targets), the target will be highlighted.  Let go and watch
  your object appear in the new place.

- Right-click over your object and select "Delete" from the context

How to write a template

Templates can be any Zope object, but ZPTs (Zope Page Templates) are
the most common.  A template designed for use with composites uses the
'slots' attribute of the composite.  The 'slots' attribute is a
mapping-like object.

Here is a simple composite-aware page template::

   <div tal:content="structure here/slots/center/single">
   This will be replaced with one element from one slot.

The expression 'here/slots/center/single' gets the 'slots' attribute
of the composite, finds a slot named 'center', and calls the single()
method of the slot, returning a string containing an HTML structure.

The only place you have to name a slot is in the template.  If the
template refers to a slot that does not yet exist, the composite will
create and return an empty slot.  If you place something in that slot
using the drag and drop interface, the composite will transparently
add a new slot to the 'filled_slots' folder.  Note that Zope prevents
you from storing slots with names that start with an underscore or
that clash existing folder attributes.

Templates use either the single() or the multiple() method of a slot.
single() returns a string, while multiple() returns a list of strings.
Use single() when you expect the slot to never contain more than one
element.  Use multiple() to allow more than one element.  In either
case, don't forget to use the ZPT 'structure' keyword, since the
returned strings contain HTML that should not be escaped.

``slot`` expressions

You can also use the special ``slot`` expression type to define
slots in a template::

   <div tal:content="slot: center">
   This will be replaced with elements in the center slot.

This syntax allows the template author to define slot titles
in addition to slot names.  The template author could write::

  <div tal:content="slot: ce