Calyxo Panels Concepts

Many aspects of a web application's presentation layer are common to all views. For example, pages may be composed of header, footer, menu and content areas. To keep maintainability and consistency, reuse of view components is an important issue. Thus, we need a mechanism to define our views as compositions of reusable page fragments.

Templates

To achieve this, we split our views into templates, which are combined into pages at runtime. A template may include other templates and may be included by other templates. In this model, an actual view may be seen as a template tree.

To be reusable, a template uses symbolic names to specify templates to be included. The actual template path has to be resolved according to some definition. Such a definition defines a template tree mentioned before.

Panels

In Calyxo terminology, these definitions are called panels.

  • Panels may be nested to arbitrary depth. We'll call a panels's children subpanels. We distinguish between toplevel panels and nested panels.
  • A panel has a name. Since this is the symbolic name used by a template to include a child template, it must be unique under its panel siblings.
  • A panel definition may extend a toplevel panel definition. That is, panel definitions are reusable by themselves through inheritance.
  • A panel may pass parameters to its associated template. These parameters are made available to the template through a Calyxo accessor.
  • Toplevel panel definitions may be localized. That is, a panel definition can be associated with a locale. During panel lookup this is taken into account using generalization.
  • A panel is dynamically associated with a template path. The associated template is resolved at instantiation time using inheritance and generalization. This selection process assigns concrete paths to the subpanel names used by templates to include their child templates.

Instantiation

Toplevel panels are visible to the controller. In a Calyxo Panels environment, you can use their names as resource paths, just as you do with static resources. Calyxo will dynamically lookup subpanels and compose and render the corresponding templates. Thus, you may see toplevel panels as virtual views.

We call the process of selecting a panel and rendering its associated template instantiation. When a toplevel panel is requested for instantiation,

  1. a stack is created with the panel pushed onto it
  2. the template associated with the panel is resolved
  3. the request is dispatched to the associated template

During instantiation, the panel element on top of the maintained stack is called the current panel. The stack itself is kept in request scope.

When a template is executed, it includes templates associated with subpanels of the current panel. When a nested panel is requested for instantiation,

  1. the requested subpanel is looked up in the current panel
  2. the subpanel is pushed onto the stack (making it the current panel)
  3. the template associated with the subpanel is resolved
  4. the request is dispatched to the associated template
  5. the subpanel is removed from the stack by performing a pop

This way, we traverse the tree of associated templates and render the results into the current response.