Sections

Owned by John Ousterhout
Last updated: Aug 15, 2009Version comment
3 min read

Sections are the main building blocks for Fiz applications. Each section is a Java class that manages a portion of a Web page, such as a table, a form, a navigation bar, or a sponsored advertisement. A section manages the entire lifecycle of its portion of the page: in addition to generating the initial HTML for the portion, it also manages any follow-up requests for that portion, such as Ajax requests for additional data or the posting of a form. Ideally, each section should encapsulate the management of an interesting piece of application functionality, hiding implementation complexities such as Javascript code and providing a simple interface to the application developer. Fiz provides several built-in sections, but it is also easy for you to implement sections of your own. If you create sections that may be useful to other application developers, please consider sharing them on the Fiz Web site.

Sections included with Fiz

Fiz currently includes the following built-in sections:

  • ChartSection: allows you to create graphs and charts; only works on browsers that support the HTML 5 canvas object.
  • CompoundSection: allows several existing sections to be grouped into a larger section, with an optional border around the group.
  • FormSection: displays HTML forms containing a collection of fields. FormSection provides numerous conveniences such as displaying labels and help text, form validation (both when the form is submitted and in real-time as elements are edited), and displaying error messages next to form elements when there are validation errors and other problems. Fields are represented with FormElement objects; Fiz provides several built-in and form elements, but you can also define additional ones.
  • TableSection: generates two-dimensional tabular displays of data.
  • TabSection: displays a collection of tabs, of which one tab can be displayed differently to indicate that it is selected.
  • TemplateSection: this is the simplest Fiz section. It allows you to generate raw HTML and substitute data values into the HTML.
  • TreeSection: displays hierarchical data with + and - boxes that the user can click to expand and hide portions of the hierarchy. The expansion is done with Ajax, so you don't need to provide data for nested portions of the tree until the data is actually needed.

Using sections

Sections are typically used by creating an array of them and then passing the array to cr.showSections:

Section sections[] = {
      new TemplateSection(...),
      new TabSection(...);
      new TemplateSection(...),
      new TableSection(...);
      new TemplateSection(...),
      new FormSection(...);
    };
cr.showSections(sections);

Typically this happens in interactor entry methods; the call to cr.showSections causes the sections to be rendered into HTML that is output to the browser.

Normally the first argument to each section constructor is a Dataset containing configuration properties. The configuration properties are name-value pairs that allow you to customize the appearance and behavior of the section. For example, many sections support a request property that names a data request that will provide data for the section to display. The configuration properties for each section are documented in the Javadoc class documentation for the section. Some section constructors take additional arguments besides the configuration properties; typically these arguments specify subcomponents for the section, such as columns within a table or elements within a form.

Writing new sections

To define a new section, create a Java class that subclasses Section. The class needs to define only two methods, addDataRequests and render. These methods reflect the way that HTML is generated in Fiz, which is a two-pass approach. First, Fiz invokes the addDataRequests method of each section in the page; this gives the section a chance to initiate data requests that are specific to that section. Once all of the data requests have been initiated, Fiz makes a second pass through all of the sections, invoking their render methods, which generate the HTML for that section (along with Javascript, CSS, etc.); at this point each section waits for all of its data requests to complete, if they haven't already finished. This two-phase approach allows all of the data requests for a page to execute in parallel, which can provide significant performance improvements for complex pages. If your new section class doesn't need to initiate any data requests then it can omit the addDataRequests method: the Section class provides a default implementation that does nothing.

See the Javadoc for the Section class for more details on writing new sections.