[Zope-CVS] CVS: Products/CompositePage - README.txt:1.2

Mon Sep 29 12:30:30 EDT 2003

Update of /cvs-repository/Products/CompositePage
In directory cvs.zope.org:/tmp/cvs-serv28966

Modified Files:
	README.txt 
Log Message:
more fleshed out

=== Products/CompositePage/README.txt 1.1 => 1.2 ===

--- Products/CompositePage/README.txt:1.1	Sat Sep 27 23:46:01 2003
+++ Products/CompositePage/README.txt	Mon Sep 29 12:30:29 2003
@@ -12,6 +12,9 @@
 PDLib, a Javascript library.  CompositePage is designed for browsers
 that support the DOM (Document Object Model) and CSS (Cascading Style
 Sheets) level 2: Mozilla, Internet Explorer 5+, Opera, Konqueror, etc.
+Not all of these browsers have been tested, but it should be possible
+to solve most problems that occur.
+
 
 
 How to use CompositePage
@@ -54,10 +57,115 @@
 menu.
 
 
+How to write a template
+=======================
+
+Templates can be any Zope object, but ZPTs (Zope Page Templates) are
+the most useful.  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::
+
+  <html>
+   <head>
+   </head>
+  <body>
+   <div tal:content="structure here/slots/center/single">
+   This will be replaced with one element from one slot.
+   </div>
+  </body>
+  </html>
+
+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 the 'structure' keyword, since the
+returned strings contain HTML that should not be escaped.
+
+
+
 How it works
 ============
 
+Rendering:
 
+When you render (view) a composite, it calls its template.  When the
+template refers to a slot, the composite looks for the named slot in
+the filled_slots folder.  If it finds the slot, it returns it; if it
+doesn't find it, the composite creates a temporary empty slot.  Then
+the template calls either the single() or multiple() method and the
+slot renders and returns its contents.
+
+
+Rendering in edit mode:
+
+When requested, the composite renders its template and slots with edit
+mode turned on.  In edit mode, slots add 'class', 'source_path',
+'target_path', and 'target_index' attributes to HTML tags to mark
+movable objects and available drop targets.  Slots add HTML markup for
+drop targets automatically.  When rendering using the single() method,
+slots provide a drop target only if the slot is empty.  When rendering
+using the multiple() method, slots insert drop targets between the
+elements and to the beginning and end of the slot.
+
+After the composite is rendered, the rendered HTML is passed through a
+transformer.  The transformer uses regular expressions to find the
+'head' and 'body' tags.  Then the transformer inserts scripts, styles,
+and HTML elements.  The result of the transformation is sent back to
+the browser.
+
+
+Drag and drop:
+
+At the bottom of a page rendered in edit mode is a call to the
+pd_setupPage() Javascript function.  pd_setupPage() searches all of
+the elements on the page, looking for elements with particular 'class'
+attributes.  When it finds a 'slot_element', a handler adds event
+listeners to that element that react when the user presses the mouse
+button in that element.  When pd_setupPage() finds a 'slot_target',
+another handler adds event listeners that react when the user drags
+into that element.
+
+If the user releases the mouse while dragging into a target, the
+Javascript code puts the appropriate source paths, target paths, and
+target indexes into a hidden form and submits that form to the
+composite tool in Zope.  The composite tool moves the elements then
+redirects the browser to the original page.  The browser loads the
+page in edit mode again and the moved element gets rendered in its new
+spot.
+
+
+Context menus:
+
+Like drag and drop, context menus depend on pd_setupPage().  When
+pd_setupPage() finds a 'slot_element', a handler adds a context menu
+listener to that element.  The context menu listener, when activated,
+positions and displays an otherwise invisible HTML element that looks
+just like a context menu.  Once displayed, the user is expected to
+either select an item from the context menu or click outside the
+context menu to make it disappear.  A similar process exists for
+'slot_target' elements, but a different invisible HTML element is
+used.
+
+Just before popping up a context menu, its contents are filtered using
+Javascript expressions.  Some actions are valid only when the user has
+selected at least one item, and other actions are valid only when
+exactly one item item is selected.  Filter expressions provide a way
+to express these constraints.
 
 
 Scope


