Attributes

OmniMark provides several features that allow you to manipulate the attribute values that are a central aspect of SGML and XML. There are two kinds of attributes: element attributes, which are specified in the start tag of an element, and data attributes, which are specified in an external entity declaration.

In general, OmniMark uses the keyword attribute to refer to element attributes, and data-attribute to refer to data attributes. There are exceptions to this, as follows:

In these cases, either attribute or data-attribute can be used.

The %v format item allows you to manipulate or display the attributes of the currently opened element, except when it is used in the body of an external-data-entity rule, where it provides access to the entity's data attributes.

When you want to access the value of an attribute that belongs to an element or entity reference that is not currently open, the using prefix can be used.

You can test for the type of attribute or data attribute by using the attribute is or data-attribute is test. For example:

  attribute foo is name

This test will succeed if that attribute foo is of type name, and fail otherwise. Alternately, you can test whether an attribute or data attribute is not of a specified type:

  attribute foo isnt name

If you try to test an attribute or data attribute that isn't declared in the element or entity reference currently being examined, OmniMark will generate an error message and the program will halt. This type of error is easily avoided, however, by using the is specified, is defaulted, or is implied test. For example, you could use the is specified test to make sure that attribute foo exists prior to testing for its type.

OmniMark also provides two built-in shelves which store all of the declared or specified attributes of an element or external entity. These are the attributes and data-attributes shelves. Note, however, that there are some restrictions on how these shelves can be manipulated.

OmniMark treats list-valued attributes as shelves, also with a variety of restrictions. Where the attributes shelf allows you to manipulate the values of the various attributes of an element, list-valued attributes can be individually treated as shelves, and the various values of that attribute can be referenced using the [...] keyword. For example, the following code refers to the third value of the attribute foo:

  attribute foo[3]

The restrictions on how list-valued attributes can be treated as shelves are as follows:

  • List-valued attributes do not have a default "current item". If you reference a list-valued attribute without specifying which item you're referring to with the [...] keyword, the entire list of values will be selected as if it were a single string with the individual values separated by a space.
  • Items in list-valued attributes cannot be assigned keys; they can be indexed using the [...] selector only.
  • Since list-valued attributes cannot have keys, the has key test is not permitted on a list-valued attribute.

Attribute aliases can be defined by the repeat over action and the using prefix. An attribute alias serves to simplify attribute identification when more than one opened element has an attribute with the same name.

An attribute alias can be specified for any form of repeat over loop or using prefix. Within such a context, the attribute alias name takes precedence over an element attribute or data attribute of the same name. If the alias name happens to be the same as an attribute name, the use of that name always refers to the attribute associated with the alias.

The only time an attribute alias is required is when either repeat over or using is used with attributes, specified attributes, data-attributes, or specified data-attributes. In these cases, an alias is required so that the selected attribute or attributes can be properly identified within the situation created by the repeat over loop or using prefix.

When the key of indexer is applied in these situations, the real name of the attribute is returned instead of the alias name.