Module aquarium.layout.LayoutAPI

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.