Action Model Reference

JasperReports® Server 9.0.0

Action Model Reference

The action model is a complex mechanism for generating menus dynamically. In particular, menus in Ad Hoc must be generated programmatically based on the contents of the reports, for example the context menu on a column. The following high-level steps explain how menus are generated:

When generating menus, the Ad Hoc Editor follows these steps:

Whenever a page with menus is to be displayed for the first time, the server looks up the corresponding action model XML definition and uses JDOM (Java-based Document Object Model for XML) to build and cache a Document.

Subsequent viewings reference the cached Document.

After the page is modified (usually triggered by an Ajax Request) the server generates a client side action model in the form of a JSON expression. Based on the current page state, the client model is a filtered version of the full action model in which internationalized names and generated options are resolved, and so forth.

Every time a menu is requested on the client, the server looks up the context in the JSON model, and for each action, clones the appropriate HTML template for the menu and tweaks its attributes accordingly.

Some pages have mostly static menus that don’t change based on page contents. Other pages, such as the Ad Hoc Editor, have dynamic menus that are updated in this way in response to changes the user makes on a page.

The following sections document the XML elements used in the action model definition files. In particular, you can define various conditions at several levels so menus appear only to certain users or based on the current state of the page.

Context

Each context represents a distinct menu type and refers to the part of the design page that launches that menu. Examples are reportLevel, columnLevel, fieldLevel. They're directly equivalent to the menu levels defined in the popup-style JSP files used in previous releases.

Condition

A condition element invokes the specified server side test as a method on the view model. The enclosed actions are included in the client action model only if the test returns true.

If the test has a leading exclamation point (!), the condition tests for false:

• test – The name of the java method to be invoked on the view model.

• testArgs – Array of parameters to be passed to the above test, expressed as a comma-separated string.

Actions

Each defined action produces one or more rows in the generated menu. The following tables describe the several action types.

`simpleAction`
A standalone menu action that, when clicked, fires the specified JavaScript method.
Attributes
`id`	The ID of the menu row DOM object.
`disabled`	If set to true, disable this row initially (shows a gray block instead).
`labelKey`	The text the menu should display. If it corresponds to an localization bundle key it is translated, otherwise it is displayed as is.
`labelCondition`	Sometimes the label value is contingent on the current state. The label condition references a Java method on the view model and should return a Boolean. A labelCondition defines two labelOption sub elements (see below).
`clientTest`	Only generate a row for this action if it passes the specified JavaScript method. If the clientTest has a leading exclamation point (!), tests for false.
`clientTestArgs`	An array of parameters pass to the above test, expressed as a comma delimited string.
`action`	The JavaScript method to be fired when the action is taken.
`actionArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant.
`leaveMenuOpen`	If true the menu stays displayed after action.

separator
Not strictly an action. Outputs a separator bar. The style of the bar automatically adjusts to the current nesting level.
Attributes
`attributesclientTest`	Only generate a row for this action if it passes the specified JavaScript method.
`clientTestArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant.
`disabled`	Disable this row initially (shows a gray block instead).

selectAction
A drop down (roll down) parent. Selectors can be nested up to three levels deep. The menu automatically renders the roll-downs in a nested fashion.
Attributes
`attributesdisabled`	If set to true, disable this row initially (shows a gray block instead).
`opened`	If set to true, selector is opened initially.
`labelKey`	The text for the menu to display. If it corresponds to an localization bundle key it is translated, otherwise it is displayed as is.
`labelCondition`	Sometimes the label value is contingent on the current state. The label condition references a java method on the view model and should return a Boolean. A labelCondition defines two labelOption sub elements (see below).
`clientTest`	Only generate a row for this action if it passes the specified JavaScript method.
`clientTestArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant.

Options

Some actions can have child elements, as described in the following tables.

option
Child of selectAction. Defines a static menu option. Use this when you can't define options programmatically.
Attributes
`id`	The ID of the menu row DOM object.
`disabled`	If set to true, disable this row initially (shows a gray block instead).
`button`	If set to true the option displayed as a button (as in formula builder).
`labelKey`	The text for the menu to display. If it corresponds to an localization bundle key it is translated, otherwise it is displayed as is.
`labelCondition`	Sometimes the label value is contingent on the current state. The label condition references a java method on the view model and should return a Boolean. A labelCondition defines two labelOption sub elements (see below).
`clientTest`	Only generate a row for this action if it passes the specified JavaScript method.
`clientTestArgs`	An array of parameters to be passed to the above test, expressed as a comma delimited string.
`allowsInputTest`	Show an input box in this option if it passes the specified JavaScript method.
`allowsInputTestArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant.
`action`	The JavaScript method to be fired when the action is taken.
`actionArgs`	An array of parameters to be passed to the above test, expressed as a comma delimited string.
`isSelectedTest`	Indicate a check mark next to this option if it passes the specified JavaScript method.
`isSelectedTestArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant.

generatedOptions
Child of selectAction. Defines a set of dynamically-defined options.
Reserved Variables (in addition to standard reserved variables)
`${optionId}`	Programmatically assigned ID. If function returns a Map this is the key part of each key-value pair, if it returns a Collection it is the toString value of each element.
`${optionValue}`	Programmatically assigned display value. If function returns a Map this is the value part of each key-value pair, if it returns a Collection it is the toString value of each element.
`$R{<String>}`	When used in a label expression attempts to internationalize the enclosed String and if it fails it returns the literal value.
Attributes
`id`	The ID of the menu row DOM object.
`function`	The name of the java method to invoke on the view model that is used to generate the options. The function can return either a Map or a Collection. The type of object returned affects how the ${optionValue} and ${optionId} reserved variables are interpreted (see above).
`functionArgs`	An array of parameters to pass to the above test, expressed as a string delimited by the @@ string constant.
`labelKey`	The text for the menu to display. If it corresponds to an localization bundle key it is translated, otherwise it is displayed as is.
`labelCondition`	Sometimes the label value is contingent on the current state. The label condition references a java method on the view model and should return a Boolean. A labelCondition defines two labelOption sub elements (see below).
`labelExpression`	Allows a custom label to be defined and allows full use of all reserved variables. (for example, labelExpression="${optionValue}") $R{ADH_252_DATA_ROWS}").
`clientTest`	Only generate a row for this action if it passes the specified JavaScript method.
`clientTestArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant. If no actionArgs are specified, the ${optionId} variable is automatically assigned as an argument.
`allowsInputTest`	Show an input box in this option if it passes the specified JavaScript method.
`allowsInputTestArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant. If no actionArgs are specified, the ${optionId} variable is automatically assigned as an argument.
`action`	The JavaScript method to be fired when the action is taken.
`actionArgs`	An array of parameters to be passed to the above test, expressed as a comma delimited string. If no actionArgs are specified, the ${optionId} variable is automatically be assigned as an argument.
`leaveMenuOpen`	If true the menu stays displayed after action (for all generated options).
`isSelectedTest`	Indicate a check mark next to this option if it passes the specified JavaScript method.
`isSelectedTestArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant. If no actionArgs are specified, the ${optionId} variable is automatically assigned as an argument.
Default Settings (DOM attributes set automatically on each generated Option)
`id`	If not specified as an a attribute defaults to the ${optionId} variable.
`clientTestArgs`	If not specified as an a attribute defaults to the ${optionId} variable.
`actionArgs`	If not specified as an a attribute defaults to the ${optionId} variable.
`isSelectedArgs`	If not specified as an a attribute defaults to the ${optionId} variable.

labelOption
Child of labelFunction. Every labelFunction element should have two labelOption elements as children. One of them is used to define the action label depending on the result of the labelCondition.
Attributes
`attributesfunction Response`	A Boolean string. If the parent labelCondition result matches this Boolean value, this labelOption is used.
`labelKey`	The text for the menu to display. If it corresponds to an localization bundle key it is translated, otherwise it is displayed as isgenerateFromTemplate.

generateFromTemplate
Programmatically generates multiple actions by specifying a function to iterate over the enclosed template. The template can be any valid action structure, it can include multiple actions and/or nested actions.
Reserved Variables (in addition to standard reserved variables)
`${templateInjection Index}`	The zero-based index of the current iteration.
`${templateInjection Id}`	Programmatically assigned ID. If function returns a Map this is the key part of each key-value pair, if it returns a Collection it is the toString value of each element.
`${templateInjection Value}`	Programmatically assigned value. If function returns a Map this is the value part of each key-value pair, if it returns a Collection it is the toString value of each element.
Attributes
`function`	The name of the java method to be invoked on the view model that is used as the template iterator. The function can return either a Map or a Collection. The type of object returned affects how the reserved variables ${templateInjectionId} and ${templateInjectionValue} are interpreted (see above).
`functionArgs`	An array of parameters to be passed to the above test, expressed as a string delimited by the @@ string constant.
Child Elements
Any valid action structure, which is used as the template.

Special Expressions

The following special expressions are converted to built-in variable values when used as arguments for client functions:

Expression	Definition
`${selected}`	The JavaScript array of selected objects on the client.
`${event}`	The JavaScript event object.
`${label}`	The generated label for this menu.

Menu DHTML API

This is a set of JavaScript functions defined on actionModel.js to dynamically manipulate a menu’s look and feel after it's been displayed. You can use them to change the Ad Hoc Editor menus in run-time. Most of them take the menuRow or the menuRow’s identifier as arguments. Some have additional arguments as well. For more information about the additional arguments, refer to the code itself.

Function	Description
`hideInputForOption`	Hide the input box on the option.
`showInputForOption`	Show the input box on the option.
`setRowColor`	Set the backgroundColor to the specified color.
`resetRowColor`	Restore original background color.
`getLabel`	Return the current label for this row.
`setLabel`	Set the label for this row.
`disableRow`	Grey out the row.
`enableRow`	Restore the row to active state.

Did you find this helpful?

Yes No

Sign In