"""Document the API for layout classes.
Layout classes are responsible for laying out the page. Layout classes are in
the AquariumClass hierarchy and are themselves parent classes of screen
classes. When developing an application, it is customary to write one or more
layout classes for the one or more look and feels that your Web application
provides. These application-level classes usually subclass Aquarium's
aquarium.layout.CssAndJavaScript_ class. Occassionally, you may need to step
outside of normal HTML, for instance to write a screen that generates an XML
report. In this case, it is customary to subclass the aquarium.layout.Bare_
layout.
At the most basic level, a layout is responsible for having a ``__call__``
method that returns a string. Since this is what Cheetah is really good at,
layouts are usually written using Cheetah templates. Aquarium's layouts are
like base classes in Mason_ in that Mason's ``callnext`` behavior inspired the
current behavior of layouts. Put simply, layouts are invoked using
aquarium.util.InternalLibrary.inverseExtend_ on the ``__call__`` method. I
suggest you read ``inverseExtend``'s documentation as this is central to the
way layouts work.
Now that you understand ``inverseExtend``, it would be nice for screens to be
able to define methods that use parameters passed to their ``__call__`` method.
This includes methods that override methods from the layout (e.g. getTitle).
However, layouts may call these methods before they make use of ``callNext``.
Unfortunately, the arguments have not been passed to the screen yet. Hence, I
declare that a layout may not call any of its methods or the screen's methods
until it has called ``callNext``. Naturally, the layout is free to save the
result of ``callNext`` until the proper time for it to output it.
There is one last responsibility of layout classes. A screen may have several
layout classes in its inheritance hierarchy. Exactly one of those layout
classes is responsible for outputing the value of ``actionResults``. See the
aquarium.screen.ScreenAPI_ for more details.
Here's a trivial example of a Cheetah layout::
#extends CssAndJavaScript
#def __call__(callNext, *args, **kargs)
## Call the screen before doing anything else. Save the results
## in a string.
#set $callNextStr = callNext(*args, **kargs)
## Do some layout. Perhaps you'll open a table here. Here's a
## sample navigation module inclusion:
$iLib.call("navigation.TopNavigation")
## Output actionResults. Perhaps you'll embed it in a navigation
## class.
$callNextStr ## Output the screen.
## Do some more layout. Perhaps you'll close a table here.
#end def
The following methods are required:
``__call__(self, callNext, *args, **kargs)``
Layout the page and return it in a string.
.. _aquarium.layout.Bare: aquarium.layout.Bare.Bare-class.html
.. _aquarium.layout.CssAndJavaScript:
aquarium.layout.CssAndJavaScript.CssAndJavaScript-class.html
.. _aquarium.screen.ScreenAPI:
aquarium.screen.ScreenAPI-module.html
.. _aquarium.util.InternalLibrary.inverseExtend:
aquarium.util.InternalLibrary.InternalLibrary-class.html#inverseExtend
.. _Mason: http://www.masonhq.com
"""
__docformat__ = "restructuredtext"
# Created: Mon Mar 29 13:15:40 PST 2004
# Author: Shannon -jj Behrens
# Email: jjinux@users.sourceforge.net
#
# Copyright (c) Shannon -jj Behrens. All rights reserved.
|