<macro> Examples
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:
They must begin with an ASCII letter
They can contain ASCII letters and numbers, periods (.), underscores (_) and dashes (-).
They
cannot contain spaces or other symbols 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 Reference namespace.
If the macro is designed as a custom block for
Wires. Add the
Presto Mashups Extensions namespace.
See
EMML
Namespaces for the current Macro Reference namespace and
Presto 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
Presto 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
Presto 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 Presto 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">
<!-- 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>
