`<expand>`

The <expand> element allows you to expand a <block> of Macro Language code in the calling context, as well as access and modify variables from the outer scope.

Description

The <block> you <expand> must be defined in your current query or in a <library>. A <library> can be defined in your current query or stored as part of a Quick Query. If you need a <block> from a <library> defined outside your current query, you must use <import> to make that library available in your current query. The <expand> element is similar to <insert>, but <expand> can actually modify variables from the outer scope, while <insert> cannot.

Syntax

<expand block="[NAME_OF_BLOCK]" [[VAR_1]="[VALUE_1]"
        [VAR_2]="[VALUE_2]"...
        [VAR_N]="[VALUE_N]"]/>

Attributes

block: Specifies the <block> (code and defined variables) to insert into the current query.

The <expand> tag may take any number of additional attributes, which should match the attributes in the <block> tag that defines the expanded block. The [VALUE] of a [VAR]="[VALUE]" attribute is substituted wherever {@[VAR]} appears within the expanded <block>.

Example

In this example, <expand> captures a variable from the outer scope and modifies it permanently.

<defblock name="query" prefix="">
  <setv name="{@prefix}_var" value="2"/>
</defblock>
<dynamic foo_var="" bar_var="" go="0">
  <do onsubmit_="submit">
	<set go="1"/>
  </do>
  <widget class_="grid" require_="{@go=1}" invmode_="hide" name="foo">
	<expand block="query" prefix="bar"/>
	<willbe name="bar" value="'{@bar_var}'"/>
  </widget>
  <widget class_="button" type_="submit" submit_="submit"/>
  <widget class_="scope" refreshon_="1"/>
</dynamic>

<setv> allows for user-defined variables where one variable's name is determined by another variable. In this example, the name of the variable {@prefix}_var depends on the value of prefix and has a value of 2. When we <expand> the <block> named query, the prefix variable is assigned the value "bar", so the variable name is changed to bar_var and the value is still 2. The <willbe> statement sets the value of the column bar to the variable bar_var. Note that the value of bar below is 2.

By contrast, if you were to use <insert> instead of <expand> for the query block, the block is unable to change the name of the variable in the outer scope. The variable bar_var would remain "" and would not be modified: