<macro> Examples

<macro> Examples

Macro Names

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

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:

They must begin with an ASCII letter

They can contain ASCII letters and numbers, periods (.),underscores (_) and dashes (-).

They cannot contain spaces or othersymbols or punctuation.

Macro names must be unique within the domain they belong to.

Important: Macros are defined as EMML statements in the macro reference namespace to ensure that they are separate and unique from EMML declarations and statements that belong to the mashup namespace. See Calling a Macro for more information.

Namespaces in Macros

You must add any namespaces that are used within a macro to the <macro> element, similar to declaring namespaces on <mashup>. You should add namespaces:

Used within the data or logic of the macro.

If the macro calls another macro. Add the Macro Referencenamespace.

If the macro is designed as a custom block for Wires.Add the MashZone NextGenMashups Extensions namespace.

See EMML Namespaces for the current Macro Reference namespace and MashZone NextGen Mashups Extensions namespace. For example:

<macros xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.openmashup.org/schemas/v1.0/EMML/ ../xsd/EMMLPrestoSpec.xsd"
xmlns="http://www.openmashup.org/schemas/v1.0/EMML"
domain="myDomain">
...
<macro name="mySalesForceTest"
xmlns:presto="http://www.jackbe.com/v1.0/EMMLPrestoExtensions"
xmlns:macro="http://www.openmashup.org/schemas/v1.0/EMMLMacro"
xmlns:urn="urn:enterprise.soap.sforce.com">
...
<constructor outputvariable="$contactrequest">
<urn:query prefix="urn" uri="urn:enterprise.soap.sforce.com">
<urn:queryString>{$sf_where}</urn:queryString>
</urn:query>
</constructor>
<invoke service="salesforce" operation="query"
inputvariables="contactrequest"
outputvariable="$sf_result"
header="$requestheader"/>
...
</macro>
...
</macros>>

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"
xmlns:presto="http://www.jackbe.com/v1.0/EMMLPrestoExtensions
xmlns:macro="http://www.openmashup.org/schemas/v1.0/EMMLMacro" >
<input name="sid" type="string"/>
<input name="oid" type="string"/>
<input name="inputs" type="string"/>
<input name="condition" type="string"/>
<output name="macroResult" type="document"/>
</macro>
...

See Declaring Mashup and Macro Variables and Parameters for more information on variables and parameters for macros.

If the macro will be used as a custom block in Wires, you can also use <presto:macro-meta> to control the look and behavior for the property fields in Wires corresponding to macro input parameters. See Macro Metadata for more information and additional links.

Variable Access

Both inner and reusable macros have access only to their input parameters and any variables that are declared within 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 or macros 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.

Macro Metadata

All reusable macros that have been registered in MashZone NextGen can be used in EMML for mashup scripts or macros created in the Mashup Editor or an XML editor. Reusable macros are also visible as custom action blocks in Wires for use in mashups that users create graphically, unless you disable this with the MashZone NextGen extension statement <presto:macro-meta>.

To disable a macro as a custom action block for Wires, set the block usage to System, such as this example:

For macros that are visible as custom blocks in Wires, you can use <presto:macro-meta> to provide additional information, such as help, or to configure the look and behavior of the custom block in Wires. For more information and links on configuring custom blocks, see Configure Properties for Custom Blocks.

Macro Logic

Within the <macro> element, you can use any EMML declaration or statement to define macro behavior including <macro>, to define an inner macro, <include> or <macro:name domain="domain-name">, to call another macro.

The following example is a macro to invoke any registered mashable in MashZone NextGen if a condition is met:

...
<macro name="conditionalInvoke"
xmlns:presto="http://www.jackbe.com/v1.0/EMMLPrestoExtensions"
xmlns:macro="http://www.openmashup.org/schemas/v1.0/EMMLMacro"> >
<input name="sid" type="string"/>
<input name="oid" type="string"/>
<input name="inputs" type="string"/>
<input name="condition" type="string"/>
<output name="macroResult" type="document"/>
<if condition="{$condition}">
<invoke service="$sid" operation="$oid"
inputvariables="inputs" 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 mashable which can then be used to display mashable results in a map.

<macro name="AnnotateMacro"
xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
xmlns:y="urn:yahoo:maps">


<input name="location" type="document" />
<output name="macroResult" type="document"/>
<variables>
<variable name="locationstr" type="string"/>
</variables>

<assign fromexpr="string-join(($location//city, $location//state,
$location//zip), ',')" outputvariable="$locationstr"/>

<directinvoke endpoint="http://local.yahooapis.com/MapsService/V1/geocode"
appid="YahooDemo"
output="xml"
location="$locationstr"
outputvariable="$georesult"/>

<annotate variable="$location" expr="." >
element geo:lat { $georesult//y:Latitude/string() },
element geo:long { $georesult//y:Longitude/string() }
</annotate>

<assign outputvariable="$macroResult" fromvariable="$location"/>
</macro>