<property>

Summary

The <property> element is a container and editing primitive for a “name / value pair”. It can appear inside a <properties-fragment> or a <properties> element.

For further information regarding customized property editing, see PSML properties editor.

Values – type and occurrence

The <property> object supports a number of predefined value types, as well as single or multiple values.

• When the value of the @datatype attribute is "xref", the property value is stored as an <xref> element. 
• A single value <property> omits the @multiple attribute, or it has a value of "false" and stores the content in the @value attribute.
• For a multiple value <property>, the @multiple attribute is "true" and each value is stored as a <value>, <xref> or <link> element. However, the <property>doesn’t require any of these elements to resolve.

Usage context

Attributes

This element includes the following attributes:

@count

A value greater than 1 or equal to n, indicates the <property> can contain multiple values. If so, the values of the property are stored in <value> elements instead of a @value attribute. By default, <property> has a single value.

@datatype

Indicates the types of data the <property> is configured to store.

The predefined data types are as follows:

• string – specifies unbounded text (that corresponds to editor config types: text, select, checkbox). This is the default value when no other value is specified.
• date – specifies a type of ISO 8601 date.
• datetime – specifies a type of ISO 8601 which includes both date and time. Added in PSML v1.4 for PageSeeder v6.00.
• xref – specifies a PSML cross-reference.
• link – specifies a link to a URL. Added in PSML v1.3 for PageSeeder v5.99.
• markdown  – specifies markdown formatted text .
• markup  – allows the elements <heading>, <para>, <list>, <nlist>, or <preformat> and anything that they can contain except for <image>, <xref>, <placeholder>, @indent, @prefix or @numbered. Added in PSML v1.2 for PageSeeder v5.98.

@multiple="true"

If present this attribute indicates the <property> can contain multiple values. If so, the values are stored in <value> elements instead of a @value attribute. By default, <property> has a single value.

Added as a replacement for @count in PSML v1.1 for PageSeeder v5.98.

@name

The @name must be unique within the <properties-fragment>, valid against the following regular expression:  [a-zA-Z0-9_-] and must not start with a ‘-’.

@title

The @title is a user-friendly display name that is not constrained to the allowable characters of the @name.

For example, where a @name value might be “warehouse”, the corresponding @title value might be “Delivery address in business hours”.  The value of @title is displayed in the document and editing views, the value of @name is displayed in the search facets.

@value

The @value is only for a <property> with a single value. When <property> can have more than one value, <value> elements are used instead of this attribute.

Examples

Example 1 – single value property

The following expressions of a single value <property> element are all equivalent:

<property name="part-number" value="PX-67S93Q"/>

<property name="part-number" datatype="string" value="PX-67S93Q"/>

Example 2 – multi-value property

For a <property> element to support multiple values.

<property name="languages" multiple="true">
  <value>de</value>
  <value>en</value>
  <value>fr</value>
</property>

Example 3 – xref property

A <property> with a @datatype of xref.

<property name="author" datatype="xref">
  <xref href="/ps/authors/english/" ... >Lewis Carroll
  </xref>
</property>

Example 4 – markdown property

A <property> with a @datatype of markdown.

<property name="example" datatype="markdown">
  <markdown>The **quick** brown *fox* jumps over the `lazy` dog.
  </markdown>
</property>

Example 5 – markup property

A <property> with a @datatype of markup.

<property name="example" datatype="markup">
  <para>The <bold>quick</bold> brown <italic>fox</italic>
  </para>
  <para>jumps over the <monospace>lazy</monospace> dog
  </para>
</property>

Schema

XML Schema

<xs:element name="property">
  <xs:complexType>

    <xs:choice>
      <xs:element name="value"
                  minOccurs="0"
                  maxOccurs="unbounded"
                  type="xs:string"/>
      <xs:element ref="xref" minOccurs="0" maxOccurs="unbounded" />
      <xs:element ref="link" minOccurs="0" maxOccurs="unbounded" />
      <xs:element ref="markdown" minOccurs="0" maxOccurs="1" />
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element ref="heading" />
        <xs:element ref="para" />
        <xs:element ref="list" />
        <xs:element ref="nlist" />
        <xs:element ref="preformat" />
      </xs:choice>
    </xs:choice>
    <xs:attribute name="title" type="xs:string"/>
    <xs:attribute name="name" type="label" use="required"/>
    <xs:attribute name="value" type="xs:string" use="optional"/>
    <xs:attribute name="datatype" type="xs:string"/>
    <xs:attribute name="count" default="1"> 
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:pattern value="[0-9n]+"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute> <!-- DEPRECATED -->
    <xs:attribute name="multiple" type="xs:boolean" fixed="true"/>
  </xs:complexType>
</xs:element>

Relax Schema

element property {
   attribute name { label },
   attribute title { text }?,
   attribute datatype { text }?,
   attribute count { text }?,
   attribute multiple { boolean }?,
   attribute value { text }?,
   (element value* | element link* | element xref* | element markdown
    | (element heading | element para | element list |
       element nlist | element preformat )* )
}

Compatibility

This element was introduced in the first draft of PSML and is well-supported from PageSeeder 5.1.