6 The mapping Object

The purpose of the mapping object is to define a semantic action, which is called during a transformation for a specific node in an XML tree or in an IDM object hierarchy), when a match between the mapping object and the node is found. Mapping objects are defined as children of a transformer object and describe a transformation of data in conjunction with it.

Definition

{ export | reexport } { model } mapping { <Identifier> }
{
  [ <atribute definition> ]
  [ <method definition> ]
}

Events

None

Children

Parents

None

Methods

:action()

6.1 Attributes

.transformer[integer]

.userdata

6.2 Object-specific Attributes

.name

Here, a pattern is given (similar to an XPath expression) to define the nodes within an XML tree or an IDM object hierarchy which the mapping object should match. This determines if the :action method should be called for the node during the transformation or not.

6.3 Pattern for .name

A pattern is very similar to an IDM identifier. The pattern represents a path of element names. The path starts at the root of the document or IDM object hierarchy (i.e. dialog or module). Each hierarchy level is compared to the corresponding part of the path. In addition, certain properties of the parent, such as the existence of an attribute or the position within the children or the parent can be given:

{ <Name> [[.<Attr>{<Op>"<Value>"}]] {[<Idx>]} }
  [ .<Name> [[.<Attr>{<Op>"<Value>"}]] {[<Idx>]} ]

<Name>

XML: Is compared to the name attribute of the cursor. The cursor must have the node type nodetype_element. Alternatively, * can be used. In this case the name attribute is ignored.

IDM: Is compared to the label of an IDM object. Alternatively, * can be used, which means that every label matches.

<Attr>

XML: The XML node that the cursor points to must have the indicated attribute.

IDM: The IDM object must have the indicated attribute.

<Op>

XML and IDM: Comparison operator which compares the attribute given in <Attr> with <Value>. I can be tested for equality = and inequality <>.

<Value>

XML and IDM: The value to which <Attr> is compared.

<Idx>

XML: The XML node must be at this position within the child nodes of the same parent.

IDM: The IDM object must be at this position within the children of the same parent. Here, all children of hierarchical attributes are regarded as combined.

Particularities

XML: If the pattern starts with a dot, it is relative to the current node. This means that the path begins at the current node.

XML and IDM: Two consecutive dots define, that an arbitrary number of hierarchy levels may be skipped.

[<Idx>]

XML: An index, without any further information, selects the XML node at this position. In this case, the type of node is insignificant. Thus each DOM node can be uniquely referenced by an expression like {[<Idx>][.[<Idx>]]} (path attribute).

All comparisons are case sensitive.

Example

The pattern ..CD[.Title = Yellow] matches all nodes within an XML tree (regardless of their hierarchy level) that have the tag CD and an attribute .Title with the value Yellow.

When the same pattern is applied to IDM objects, all objects possessing the label CD, and an user-defined attribute .Title with the value Yellow will match.

6.4 Object-specific Methods

:action()

This method is invoked from the :action method of the parent transformer, when a match between a node in an XML tree or an IDM object hierarchy and the pattern in the .name attribute of the mapping objects is found. The default implementation of this method does nothing other than always returning true.

Because this method can be redefined, it is possible for the programmer to determine what should happen with the data from the node.