Get the Chosen Path as Text
In some cases, especially in macros that are generic, what you need for a particular block property is the XPath expression to a node that the user selects rather than actual the value of that node. Typically these expressions are used within the logic of the macro when the macro can be used with a wide variety of inputs. See
Make Macros Generic for Custom Blocks for more information and examples.
In this case, you want
Wires to force users to pick an appropriate node from the
Path Selection list, as discussed in
Limit Dynamic Choices and Forbid Literal Entries. But the block property
must be assigned the XPath expression for the selected node rather than the runtime value. To do this, the macro for a custom block must:
Have an input parameter with a
string datatype to hold the XPath expression.
Have metadata for that string parameter that:
Includes <type>.
Assigns a datatype of
path to <type>.
Includes <xpath> within <type> and uses the
limitTo attribute to identify the document-type input parameter that contains the results that users may choose from, and optionally a specific branch within those results.
Optionally, uses the
usage attribute in <xpath> to define the types of nodes that users may validly select for this block property.
This next example defines a block property that accepts an XPath expression for the stringPath input parameter. It limits user choices for stringPath to any node within the results connected to the srcDoc input parameter:
When limitTo=$result-input-parameter-name, the format of the XPath expression that is passed to the macro input parameter is in the form:
/root/path/to/node.
This includes the full path, starting from the root node of the selected results, but does not include the input parameter name that identifies the results.
You can further limit user choices for this XPath expression to:
A specific branch within the selected input parameter.
Simply add path information along with the input parameter name to the limitTo attribute. For example:
When limitTo=$result-input-parameter-name/some/path, the XPath expression that is passed to the macro input parameter is in the form:
relative/path/to/node
This is a relative path, relative to $result-input-parameter-name/some/path.
Specific types of nodes.
Wires cannot predetermine what type of node users should select in the Path Selection list for this case. By default users may select any node within the results of the selected document-type input parameter.
You can use the usage attribute on <xpath> to limit user choices to specific types of nodes:
array = users can only select repeating nodes, either simple (with data) or complex (with children)
branch = users can only select complex nodes with children, either a single node or repeating nodes
leaf = users can only select simple nodes with data, either a single node or repeating nodes
path = users can only select any node
This next example limits user choices to repeating nodes within the results connected to the srcDoc input parameter: