Introduction

As a component programmer or user, it is important to meet the same general concepts through the different kind of components. Indeed, whatever their behaviors, all of them are aimed to be included, called, customized and handle or provide interactions. And when implementing or using components, it is important that the same function implies the same way to deal with it.

This article describes the concepts shared by all components. We will first introduce the way a component should be designed, included, and how parameters can be passed to it. Then we will describe some specific parameters that can be found in all (or most of) the components: the insert target, the global node management, the callbacks interface and the way to enable and disable it.

View and Content

Components can be divided in two groups: the static ones (like carousels and loading wheels) and the ones that handle dynamic values that come from a content provider (like lists and search results). For this latter group, the design leads to a component developed in two parts:

• the View: this part contains the graphics, the layout and all elements free from dynamic values. The scene including the View part of a component can often be stored in cache for a long time.
• the Content: this part handles the dynamic content. Basically, it should consist of multiple Replace that will update the scene graph elements set by the View (e.g. Text nodes strings...), and never create brand new scene graph nodes. It should be the most lightweight possible, reduced to its strictness expression and should contain only RSP elements that cannot be in the View. For faster browsing, scenes including the Content part of a component are often cached, but for a shortest time.

• Note that both parts of a View-Content component can be included in a single RSP. You will meet that in some samples, but this is probably not a good practice when developing a genuine rich media service.

Include

A component is designed to be inserted into a RSP file using the tag. The unit allows including the result of the processing of another RSP (included) within the current RSP (including). This concept is similar to the JSP one, for instance.
You can call the tag with the name of the targeted RSP as if it was in your source folder.

You will read in the documentation that is only available for server-side scenes. But thanks to their ".jar" packaging, it is entirely possible to include components in client-side scenes processing too.

When using in order to use a component, an important point is to forget the shareLocalID parameter and to let it take its default value "false": this will avoid unexpected behaviors due to potential conflicts between ids (DEF).

Parameters

Including a component is designed to "almost" look like a function call. As components are customizable, we use parameters to configure them. More precisely, the component can be customized by passing request attributes to the included page.

In order to make things easier for the developer, 2 tools are provided to make the inclusion of a component as easy as pie:

• The Parameters API: each component proposes Java constant classes that define all the parameters used by the component. Goodbye typing mistakes and hello content assist!
• The RequestParameterContext object: this object acts as an abstraction layer over the stzRequest object and handles request attributes in a straightforward way. All you have to do is:
  1. Create the context
  2. Add the parameters
  3. Set up the context
  4. Include the component
  5. Clean the context

• Therefore a typical component call will look like this:

<% RequestParameterContext params = new RequestParameterContext(); params.addParameter(MyComponentParameters.MY_PARAMETER_1,"Value_1"); params.addParameter(MyComponentParameters.MY_PARAMETER_2,"Value_2"); params.setup(stzRequest); %> <% params.clean(stzRequest); %>