Defining Blox

The following table lists the user interface Blox and their JSP custom tags:

Blox Name: Blox Tag
ChartBlox: <blox:chart>
DataBlox: <blox:data>
DataLayoutBlox: <blox:dataLayout>
GridBlox: <blox:grid>
PageBlox: <blox:page>
PresentBlox: <blox:present>

Note: Details on these Blox and complete syntax for their tags, attributes, and usage can be found in the Alphablox JSP Tag Libraries.

Note: There are no spaces between the blox prefix, the colon, and the name of the tag. If you put a space after the colon, you will generate JSP compiler errors.

Note: In discussions about Blox tags throughout Developing with Analytics APIs, you will see references to the shorthand syntax for tags. This is to help you be clear when the tag is being discussed instead of the Blox itself. For example, instead of referring to the Blox GridBlox tag, this guide will frequently refer to the <blox:grid> tag.

As discussed earlier in Alphablox applications and the underlying Blox, Blox can be standalone or nested as children within other parent Blox, depending on which Blox is being used and their particular usage. By default, a standalone Blox includes nested Blox set to their default values. A PresentBlox, for example, includes a nested ChartBlox, DataBlox, DataLayoutBlox, GridBlox, PageBlox, and ToolbarBlox.

The following table lists the nested Blox components for each standalone presentation Blox:

Standalone Blox: Nested Blox Components
ChartBlox: DataBlox, ToolbarBlox
DataBlox: CommentsBlox [optional]
DataLayoutBlox: DataBlox
GridBlox: DataBlox, ToolbarBlox
PageBlox: DataBlox
PresentBlox: ChartBlox, DataBlox, DataLayoutBlox, GridBlox, PageBlox, ToolbarBlox

Rather than have to include nested tags for the nested Blox, you can just include just the top-level parent Blox tag (the nested Blox listed above are implicitly included).

A minimal PresentBlox, for example, defined with <blox:present> tag would look like this when coded with opening and closing tags:

<blox:present id="myPresentBlox"></blox:present>

or like this, when using the shorthand method:

<blox:present id="myPresentBlox"/>

The shorthand method is recommended most of the time — opening and closing tags are only required when content (called the body) needs to be added between the tags.

Note: The minimal examples above include an id attribute, since this is the minimum definition required for a Blox to be rendered properly. All parent Blox within an application must be uniquely identified, but nested Blox don’t require id attributes.

If you included all of the possible nested Blox tags that are implicit to the PresentBlox, this is what the same PresentBlox would look like:

<blox:present id="myPresentBlox">
   <blox:grid/>
   <blox:chart/>
   <blox:toolbar/>
   <blox:page/>
   <blox:dataLayout/>
   <blox:data/>
</blox:present>

Since the nested Blox are implicitly included, even when you do not explicitly add the nested Blox tag, include nested Blox tags only when you need to include required tag attributes or tag attributes for properties that you need to change from their default settings.

If you placed a PresentBlox tag on a page without any defined nested Blox or defined tag attributes, a PresentBlox would be rendered on the page, but the Blox would not do anything interesting — without defining a data source and query on the nested <blox:data> tag at least, no data would be retrieved. In order for Blox to do something useful, you usually need to add tag attributes or nested property tags.

At this point, you should understand how to get a Blox to appear on a JSP page and how to include nested Blox. The next section explains how to add simple tag properties to Blox.