Overview of the Parameter Builder Infrastructure

The Parameter Builder infrastructure generates the string of information used to create URLs and hidden inputs for forms. Every transform in MicroStrategy Web products directly or indirectly uses a ParameterBuilder object to create a serialized string that contains some or all of the elements listed below.  

• the numeric event id (evt parameter)  

• the source of the event—that is, a path from the root to the WebComponent (src parameter)
  

• a list of arguments that pertain to the event  

• a serialized set of states for all WebComponents  

Any or all of these elements can be serialized in several different forms, but the two most common forms are as a URL or as a set of hidden inputs in a form.

The topics in the following sections describe the major classes in the parameter builder infrastructure and provide examples of how to use the parameter builder infrastructure to generate the hidden inputs for an HTML form and construct  a URL.

• Parameter Builder Classes
• Examples of Using Parameter Builder

The diagram below illustrates the relationship between the classes in the parameter builder infrastructure.

Refer to the API Reference for a description of the interfaces and abstract classes that provide parameter builder functionality and the available implementation classes.

Using the Parameter Builder Infrastructure in customizations

ParameterBuilder objects are used to perform two important types of customization.

• Adding extra information to all of the links generated by the application.

Every link in a MicroStrategy Web product is generated using an AnchorTag. The AnchorTag in turn has a ParameterBuilder that it uses to generate its corresponding URL. All AnchorTags generated in transforms are created by the generateAnchor(WebEvent event) method of AbstractAppTransform. Since all transforms extend AbstractAppTransform, you can add additional parameters to a URL generated by a transform by extending any transform, overriding the generateAnchor method, and using the methods in the ParameterBuilder associated with the corresponding AnchorTag.

• Specifying that certain information should be persisted in every request.

Classes that extend AbstractConfigurableParameterBuilder give you the ability to specify parameters that should be persisted in each request, either in the URL or as hidden inputs in a form. To do this, you create an external properties file, called ParameterBuilder.properties, and place it under WEB-INF\classes in the MicroStrategy folder. This file contains a single name/value pair, with the format shown below. The name is always  "persist" and the value is a comma-delimited list of the names of parameters that should be persisted. The parameter names are case-sensitive.

persist =parameterName1,parameterName2,parameterName3, ...

The class automatically checks for the existence of this file when it is building a URL. If it finds the file, it saves the list of parameters that should be persisted. It then checks the request for the existence of those parameters, and, if it finds them, it adds them to the internal list of parameters in the ParameterBuilder object.  In the example above, the entry in the properties file instructs the application to check for parameters with the names parameter1, parameter2, or parameter3, and if it finds one or more of them in the form and query string collection on ContainerServices, to persist them into the ParameterBuilder collection.

This is an extremely useful feature in a portal environment. You can use this file to specify that the session ID and any other necessary information should be persisted from the request to every form and URL input built by the Web application. Although it is used by MicroStrategy almost exclusively in portal environments, this feature can also be used in a non-portal environment. For example, you might want to persist information such as the store ID, so that the GUI can be customized based on this information.