MicroStrategy ONE

Layout Definition Elements Reference

The following is the complete list of available elements in a layout definition file. In many cases, the use of an element implies that a method exists in the transform or bean with a particular signature. This reference provides information about the existence of such methods.

layout—This is the root element for the layout definition. It does not have any attribute.

All layout definition files must include this layout element as the root node of the definition.

render—Renders a piece of HTML at the point of the render instruction. It has the following attribute:

  • name—the name of the render method on the transform.

The render element is the core instruction of the layout definition. By using this, the layout definition file instructs the application to include a piece of HTML. To do this, the application takes the value of the name attribute and looks for a method named render [Name attribute value](MarkupOutput, [argument list]); The argument list is optional and allows the method to accept arguments, although the MarkupOutput argument is added by the application and is used to output the HTML. If an argument is listed in the method, then it must appear in the layout definition file as an argument. It is possible to provide for optional arguments by overloading the method in the transform class. Refer to the following example:

Copy 
<mstrlayout:render name="IconInfo">
   <mstrlayout:argument list="FolderObjects"type="com.microstrategy.web.objects.WebObjectInfo"/>
   <mstrlayout:argument type="boolean" value="true"/>
</mstrlayout:render>

From the above example, the render element requires a method named renderIconInfo which has arguments MarkupOutput, WebObjectInfo and Boolean. The MarkupOutput is not listed in the element but the WebObjectInfo and Boolean arguments must be supplied. The WebObjectInfo represents the object that is being rendered and is obtained from the list. The Boolean argument indicates whether or not to create the style attribute in the HTML output. Thus, the complete signature of the method is as follows:

Copy 
public void renderIconInfo(MarkupOutput out, WebObjectInfo object, boolean includeStyleAttribute)

If the renderIconInfo method is overloaded to additionally include a method with the following structure, then the Boolean argument becomes optional (the second implementation calls the first with a default value for that argument).

Copy 
public void renderIconInfo(MarkupOutput out, WebObjectInfo object)

argument—Supplies an argument to a render element. It has the following attributes:

  • type—the data type of this argument such as integer, string or type

  • value—a constant value to supply as the value of the argument

  • list—the name of a list from where to obtain the value of the argument

Refer to the following example:

Copy 
<mstrlayout:render name="IconInfo">
   <mstrlayout:argument list="FolderObjects" type="com.microstrategy.web.objects.WebObjectInfo"/>
   <mstrlayout:argument type="boolean" value="true"/>
</mstrlayout:render>

The example highlights two forms of the argument element. The simple form supplies an argument of a particular type with a particular constant value (<mstrlayout:argument type="boolean" value="true"/>). The second form obtains the current value from a named list (<mstrlayout:argument list="FolderObjects" type="com.microstrategy.web.objects.WebObjectInfo"/>).

Thus, the above example indicates, render the icon for the current object in the list named FolderObjects. Note that in addition to simple data types, the data type of the argument can also include a Java type; in this case an instance of WebObjectInfo.

list—Creates a list of objects that can be iterated through to form a repeating structure. It has the following attributes:

  • id—identifies the list in the layout definition elements

  • name—what transform or bean method as the source for the list

  • base—whether the method specified in name is found on the transform class or corresponding bean class. Possible values are bean or transform with the default being transform

In many transforms, the display is constructed by taking a list of objects such as the contents of a folder or the available projects and repeating a section of HTML until the display is constructed. This is done by using the list element. Unless the next element is used, the contents of the list element define the piece of HTML to repeat for each item in the list.

The structure of the list element is as follows:

Copy 
<mstrlayout:list id="FolderObjects" name="getFolderObjects">
      (layout XML to be repeated)
</mstrlayout:list>

In the layout definition file, the id FolderObjects is used to render elements to indicate the folder object to use. The name getFolderObjects indicates that the transform Java class or the bean must include a method with the following signature: public java.util.ArrayList getFolderObjects();

The base attribute is used to indicate whether the method is found on the bean or on the transform. If the attribute is not specified, then the method is assumed to be found in the transform class.

If the layout definition file does not explicitly indicate when to move to the next item in the list by using the next element, then the closing of the list element acts as a next element and moves the list cursor to the next element. This prevents the occurrence of an infinite loop.

Just like the render element, the list element can include argument elements. These arguments must correspond to the arguments of the method in the Java class. For example, the getFolderObjects() method can include an argument which indicates what type of objects to retrieve.

next—Forces the named list object to move to the next item. It has the following attribute:

  • list—identifier which corresponds to the id attribute of the required list

In some repeating list structures, it is necessary to force the list to move to the next item in the list but not end the list element. A typical example is the multiple column table structure, such as the two column folder view mode. The HTML output structure for this view can be an HTML table structure, such as the following:

Copy 
<table>
   <tr>
      <td>Folder item 1</td>
      <td>Folder item 2</td>
   </tr>
   <tr>
      <td>Folder item 3</td>
      <td>Folder item 4</td>
   </tr>
</table>

In the HTML above, there are two levels of repeating structure. For every folder item there is a table cell element (td) but the structure is also repeated for every two folder items to form the table row element (tr). This is accomplished using the next element.

The overall list element is created at the level of the table row and then the next element is used to force the list to the next element. A simplified version of the layout definition file is as follows:

Copy 
<table>
   <mstrlayout:list id="FolderObjects" name="getFolderObjects">
      <tr>
         <td>
         <mstrlayout:render name="folderItem">
         …
         </mstrlayout:render>
         </td>
         <mstrlayout:next list="FolderObjects"/>
         <td>
         <mstrlayout:render name="folderItem">
         …
         </mstrlayout:render>
         </td>
         <mstrlayout:next list="FolderObjects"/>
      </tr>
   </mstrlayout:list>
</table>

You can see from this that the next element is used to force the list to the next element. Note that once a next element is used, then the close tag of the list element moves the list to the next element automatically and a second next element is required.

if…then…else—Allows for conditional logic within the layout definition. The if element has the following attributes:

  • name—name of a method on the Java class which returns a boolean value

  • base—whether the method specified in ‘name’ is found on the transform class or corresponding bean class

In some cases it is convenient to include logic in the layout definition. For example, you can include logic to switch the HTML created based on the capabilities of the target Web browser. This can be achieved using the if…then…else set of elements. A typical example is as follows:

Copy 
<mstrlayout:if name="isDhtml">
   <mstrlayout:then>
      ...
   </mstrlayout:then>
   <mstrlayout:else>
      ...
   </mstrlayout:else>
</mstrlayout:if>

The above HTML indicates that there exists a method on the transform or bean with the following signature: public boolean isDHTML();

As with other elements such as the render and list, the if element allows for argument elements which correspond to the arguments of the method in the transform. Refer to the following example that shows the usage of an argument:

Copy 
<mstrlayout:if name="isFolderNotNull">
    <mstrlayout:argument list="FolderObjects" type="com.microstrategy.web.objects.WebObjectInfo"/>
       <mstrlayout:then>
          ...
       </mstrlayout:then>
</mstrlayout:if>

The above HTML indicates that there exists a method on the transform or bean with the following signature: public boolean isFolderNotNull(WebObjectInfo object)

This example illustrates a condition where a section of the layout is only to be used if the current element from the list with identifier FolderObjects is not null. Note that the else element is not required but the then element must always be present.

attr—Indicates the attribute of a parent element. It has the following attribute:

  • name—name of a method on the transform class which returns a 'java.util.Map' value.

The attr element allows you to add or modify the value of a HTML element dynamically. For example, you can modify the CSS class attribute to be used based on the type of object that is displayed. In the following example, the class attribute of a div element is inserted by the attr element based on the type of object in the folder list.

Copy 
<div>
   <mstrlayout:attr name="addCSSForObjectType">
      <mstrlayout:argument list="FolderObjects" type="com.microstrategy.web.objects.WebObjectInfo"/>
   </mstrlayout:attr>
   ...
</div>

The above code creates the following attribute in the parent div element: <div class=”folderObject”>.

This allows the transform to supply the correct CSS class based on the object type. The element delegates the actual work of inserting the attribute to a method on the transform. In this case, the method has the following signature: public java.util.Map addCSSForObjectType(WebObjectInfo object).

Note that the method returns a java.util.Map instance with the attribute name as the key and the value of the attribute as the attribute. An argument of type WebObjectInfo is required and you can see that is populated by the list named FolderObjects.

include— Used by prompt-related layout definition files. Instructs the layout definition file for a specific prompt style to include a file (in this case, the template layout definition file). It has the following attribute:

  • file—defines the location of an external layout definition file. In this case, template layout definition file

A typical example is as follows:

Copy 
<mstrlayout:include file="/WEB-INF/xml/layouts/PromptObjectLayout.xml">
   ...
   ...
</mstrlayout:include>

The include element can only have replace element as the direct child tag since the replace tags are not ordered similar to other HTML tags.

replace— Used by prompt-related layout definition files. Overwrites the content from the template layout definition file with the prompt style-specific section. It has the following attribute:

  • slot—identifies the prompt style-specific section using an unique value that is replaced in the template layout definition file

A replace tag can have zero or more child elements.

A typical example is as follows:

Copy 
<mstrlayout:include file="/WEB-INF/xml/layouts/PromptObjectLayout.xml">
     <mstrlayout:replace slot="s1">
          <div class="prmCheckbox">
            ...
            ...
          </div>
     </mstrlayout:replace>
</mstrlayout:include>

In the above example, the prompt-related layout definition file includes the PromptObjectLayout.xml template layout definition file using the include element. The replace element with a slot value of "s1" includes the prompt style-specific XML enclosed within the <mstrlayout:replace ...> ... </mstrlayout:replace> into the slot section defined with a value of "s1" into the template layout definition file, PromptObjectLayout.xml for rendering the prompt.

slot— Used by prompt-related layout definition files. Specifies the location in the template layout definition file where the prompt-style specific XML needs to be inserted. It has the following attribute:

  • name—identifies the prompt-style specific section using an unique value

A slot element can have zero or more child elements.

A typical example is as follows:

Copy 
<mstrlayout:slot name="s1"/>

In the above example, the slot element with a value of "s1" in the template layout definition file gets replaced with the slot section defined with a value of "s1" in the layout definition file for a specific prompt style. The PromptObjectLayout.xml template layout definition file currently includes one slot named “s1”.