Package com.top_logic.mig.html.layout

Layouts help managing Complex ensembles of HTML pages.

A Layout consists of a Number of LayoutComponents. A Structuring Component is the the Layout that represents a Framset or a HTML-Table. The TopLevel component can be a MainLayout. It has a set of static Functions that help manage the layout as a whole.

Usage

Simple JSP or static HTML pages can be integrated with the PageComponent. JSP pages in this context can access their PageComponent and through it their model and other components using the layout tag library.The html tag starts the Layout-aware part. The action tag is the right position to manipulate the model. In the MVC-concept it represents the controller. Model changes should only occure if the request is valid using LayoutComponent.validSubmitNumber. The head tag marks the position at which default head data is printed. The body tag marks the position at which the body is printed.
Note: All links to LayoutComponents includung links to the same component/JSP must include the layout id (at the LayoutConstants.PARAM_LAYOUT parameter) and should contain the submit number (at the LayoutConstants.PARAM_SUBMIT_NUMBER parameter). If forms are submitted it is clearest to use LayoutConstants.PARAM_SUBMIT for forms that use only one submit button and LayoutConstants.PARAM_SUBMIT + "." + somevalue for forms that have more than one submit button. Consider using the writeSubmitLink or the getFrameURL method to generate links.

Extending

In some cases it will be necessary to subclass LayoutComponent. In this case, besides the things necesarry for XML-Serialization the basic methods for rendering the component must be overwritten. These are:

getModel is an abstract method. You should have your own getter and setter methods for your model. getModel should simply return your accessor method.
getOnLoadFunctionCalls to call javascript functions that are declared in the header when the page has been loaded completely.
getOnLoadFunctionCalls to call javascript functions that are declared in the header when the page is replaced by another page.
isCompleteRenderer, if you don't want the component to write the the html structure. Consider using a JSP instead.
isFrameSet, if the page is a frame set. Consider sublcassing -- or maybe just using -- the class Layout.
writeHeader, to write the contents of the html header -- just the contents, not the html-tag
writeBody, to write the contents of the html body -- just the contents, not the body-tag

Also the prepare methods can be overwriten. Here the controller function of the MVC concept is implemented.

XML-Serlialization

Usage of the XML-Serialization

Layouts can be serialized to an XML-File, by calling the static method MainLayout.writeLayoutAsXML. A file, containing xml of the expected form, can be deserialized to a Layout by calling MainLayout.getLayoutFromXML. The state of the LayoutComponent's models is not written to file. Thus after deserializing the model is null or the component's defaultmodel in the default state.

Design of the XML-Serialization

Each LayoutComponent must overwride the following methods to be XML-serializable

A constructor taking org.xml.sax.Attributes. Must call the super constructor and read in all its directly implemented fields from the attributes.
writeFieldsAsXML. Must call the super method and write out all its non-transient fields as attributes using TagWriter.writeAttribute.
writeInnerCollectionsAsXML. Must call the super method and write all non-transient inner Sets or Lists using writeListAsXML. The set-version is not implemented yet.
findList. Must return the list, that was serialized by the given name or call the super method if the name is unknown.
setSelectedXMLList. If specific actions need to be taken on begin or ending the deserialization of a list.
postLoad. If actions need to be taken after all components have been deserialized

List elements are expected to either be LayoutComponents -- which is necesary to write the the subclasses of Layout and shouldn't be used anywhere else -- implement XMLSerializable or contain their value within their toString method and have a string constructor.