Passing arguments to actions

 

The Input Mappings group allows you to specify argument names and values to pass to an action.

The Designer contains several builders that execute some action during their OnClick event. These builders, Button, Image Button, Form Submit Action, HTML Event Action, and Link, can submit a form, link to another model action or external Web site, or execute a JavaScript script.

If the specified action for these builder calls takes one or more arguments, we can specify those arguments in the InputMappings input, which allows you to specify the argument name and the value for that argument that you want to pass.

When you specify argument values in an Arguments list, we need to ensure that the argument names and values you specify match the names and the data types declared for the action. If you specify a method as the action, the names of the arguments (if any) are displayed in the Arguments list.

Special characters that are passed in an argument such as a single quote ( ' ), double quote ( " ) and backslash ( \ ) must be escaped ). For example, here is how you might pass double quote characters: \"Hello World Button\"

 

Passing Values from the Model to Actions

When specifying argument values, we can enter a String or use the Reference Chooser to select the value from a variable or method in your model. The following list shows the indirect reference syntax used to supply an argument value from various elements in the model:

  • Pass the results of a Java expression -- ${Java/webAppAccess.getRequestData().getContextURL()}

  • Pass the results of a service call -- ${MethodCall/ServiceCallName_reply}

  • Pass the value of a variable -- ${Variables/VariableName}

  • Pass the value of an XML element in a variable -- ${Variables/VariableName/parentElement/childElement}

  • Pass the value of a form input -- ${Inputs/FieldName}

  • Pass the value returned by a method -- ${MethodCall/MethodName}

  • Pass the value returned by an LJO method -- ${MethodCall/LJOName.MethodName}

  • Pass the value stored in a repeated region's loop variable -- ${Variables/LoopVar/ElementName}

See the section below, "Using Input Mappings for Builder Calls in a Repeated Region," for more information about passing values to actions from a repeated region.

 

Using Input Mappings for Builder Calls in a Repeated Region

Typically, when you use a Button, Image Button, Form Submit Action, or Link builder call within a Repeated Region, you want to execute some action and pass data specific to the "row" as arguments to that action. For example, if you had a Portfolio structure that contained company names and their corresponding stock symbols, you could create a repeated region that displayed the list of company names, with each name being the displayed text of a Link builder call. The intended behavior is that when a user clicks on a link to a stock quote URL, the appropriate stock symbol gets passed as an argument.

To pass arguments to an action from a repeated region:

  1. Set up your repeated region and any other builder calls in that region, so that it displays the contents of the region as you intend.

  2. In the Button, Image Button, or Link builder call, pass "row" specific data, using the repeated region's Loop Variable (accessible through the Reference Chooser) to access the desired element in the "row."

For example, if the Repeated Region iterates over each <company> element in the structure below:

<portfolio>

   <company>

      <name>Acme Supply Co.</name>

      <symbol>ACME</symbol>

   </company>

   ...

</portfolio>

and you declared CurrentCompany as the Loop Variable, the appropriate values for the Input Mappings input would be similar to the one below:
Name Value
quote ${Variables/CurrentCompany/symbol}

When the user clicks on the company name in the repeated region, the action is passed the corresponding stock symbol as the value for its "quote" argument.

We can use the Reference Chooser to select the appropriate loop variable and then use XPath-like notation to specify the value of an element in the loop variable to pass to the action.

If the selected action is a method in the model, the builder call editor pre-populates the argument name field. If you are passing arguments to a URL the order you specify the arguments is not important, but you do need to name the arguments exactly as the URL expects them. And make sure that the evaluate action occurs as the page is rendered.

For more information about the Repeated Region builder, see "How to Use the Repeated Region Builder."

 

Using the Evaluating Arguments Input

If the argument you specify to an action builder takes an argument, the "Evaluate Argument" input is displayed in the Builder Call editor. This input allows you to specify when the argument is to be evaluated. The two main cases where this input is useful are:

  • When the Action is Run - Use this choice get the value the user just entered in a form passed to your method. A typical example of this might be when the user enters a code in a form, and a button calls a method passing the value that the user typed

  • As the page is rendered - Repeated region loop variables provide a use case for this choice. In this case, you want the current value as the page is being rendered. A typical example of this case is a repeated region with a link inside. Here you want to use a part of the repeating data to be able to tell which link was clicked, so you pass it as an argument to a method.

The builders that provide this input (Button, Link, HTML Action, etc.) will attempt to detect these two cases and warn you if your selection is inappropriate. In most cases, we can accept to take the default choice provided.