<macro>

Macro Names

Add a <macro> element and define the name of the custom statement in the name attribute, such as this:

<macro name="myCustomMacro"></macro>

Macro names define the name of the custom statement that you add to the mashup script, so they must follow XML rules for a valid name:

Macro names must also be unique within the EMML Engine where you deploy them.

Macro Inputs and Output

Typically, you define some input parameters for the macro, although this is not required. If the macro returns results, you must also define an output parameter.

For example:

... 
<macro name="conditionalInvoke"> 
  <input name="url" type="string"/> 
  <input name="op" type="string"/> 
  <input name="condition" type="string"/> 
  <output name="macroResult" type="document"/> 
</macro> 
...

If the macro will work with complex results from services or other mashup statements, you should define input parameters that are a document type.

Variable Access

Macros have access to the inputs and variables that are declared within the macro. They also have access to any input parameter or global variable defined in mashup scripts that call the macro.

The output parameter (<output>) declared in the macro is not accessible by name outside the scope of the macro. So for the example shown previously, references to $macroResult outside of the macro would not return the macro result. However, the results of the macro are automatically assigned to the output variable that is identified when the macro is called. See <macro:custom-macro-name> for more information.

Macro Inputs and Dynamic Mashup Expressions

Like generic mashup scripts, macros may need to allow calling mashups to send XPath expressions or variables as input parameters that are then used within statements in the macro.

To support passing XPath expressions in a macro input parameter, you must use Dynamic Mashup Expressions to refer to these parameters within the macro. See the sample macro, conditionalInvoke, in Macro Logic for an example of dynamic mashup expressions used for an <if> condition.

Namespaces in Macros

When you define a macro in a mashup script, you can simply declare any namespaces used in within the data or logic of the macro on the <mashup> element for the mashup script, just as you do with any namespace.

For macros that you define in macro libraries, however, you should declare all namespaces used within a specific macro on the <macro> element. For example:

<macros xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://www.openemml.org/2009-04-15/EMMLSchema ../schema/EMMLSpec.xsd" 
    xmlns="http://www.openemml.org/2009-04-15/EMMLSchema" 
    name="someMacroLibrary"> 
... 
  <macro name="calculateCustomWeight" 
      xmlns:myFunc="java:com.mycompany.mashups.CustomFunctions"> 
    ... 
    <assign fromexpr="myFunc:customWeight($currentWeight/weight)" 
        outputvariable="newWeight"/> 
    ... 
  </macro> 
... 
</macros>

Macro Logic

Within the <macro> element, you can use any mashup declaration or statement to define macro behavior except for the following:

The following example is a macro to invoke any service or web site if a condition is met:

... 
<macro name="conditionalInvoke"> 
  <input name="url" type="string"/> 
  <input name="op" type="string"/> 
  <input name="condition" type="string"/> 
  <output name="macroResult" type="document"/> 
  <if condition="{$condition}"> 
    <directinvoke endpoint="$url" method="$op" 
        outputvariable="$macroResult"/> 
  </if> 
</macro> 
...

This example uses a dynamic mashup expression within the condition attribute for <if> to ensure that the XPath expression defined in the condition input parameter is evaluated.

The next example adds latitude and longitude data to an address based on the Yahoo! Maps service which can then be used to display service results in a map.

<macro name="AnnotateMacro" 
    xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" 
    xmlns:y="urn:yahoo:maps"> 
  <!-- location document should be <address> root with <city>, <state> and 
       <zip> children --> 
  <input name="location" type="document" /> 
  <output name="macroResult" type="document"/> 
  <variables> 
    <variable name="locationstr" type="string"/> 
  </variables> 
  <!-- join address input into a string --> 
  <assign fromexpr="string-join(($location//city, $location//state, 
    $location//zip), ',')" outputvariable="$locationstr"/> 
  <!-- call Yahoo maps --> 
  <directinvoke endpoint="http://local.yahooapis.com/MapsService/V1/geocode" 
                appid="YahooDemo" 
                output="xml" 
                location="$locationstr" 
                outputvariable="$georesult"/> 
  <!-- add geographic result to location data --> 
  <annotate variable="$location" expr="." > 
    element geo:lat { $georesult//y:Latitude/string() }, 
    element geo:long { $georesult//y:Longitude/string() } 
  </annotate> 
  <!-- put annotated location data in macro output --> 
  <assign outputvariable="$macroResult" fromvariable="$location"/> 
</macro>