Skip to main content

 Element reference

PSML elements from <author> to <xref>

<property>

Summary

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

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

Values – type and occurrence

When the value of the @datatype attribute is xref, the property value is stored as an <xref> element. 

A single value <property> omits the @count attribute, or has it set to 1 and stores the property in the @value attribute.

For a multiple value <property>, the @count attribute must be equal to n or greater than 1 and each property is stored as <value> elements or <xref> elements, however, the <property> does not require any <value> element to be valid.

While it is recommended that the @count attribute and <value> elements are correctly set, there are applications that require multiple values in a single <property>. For example, to configure a checkbox in the PSML properties editor with a value="English,Spanish".  In this situation, the @count attribute is not n or greater than 1 but the values are stored as a comma-separated list in the @value attribute.

It is not valid for a <property> to have both a @value attribute and a <value> or <xref> element. Neither is it valid to mix <value> and <xref> elements.

Usage context

Element category
PSML levelportable
Permitted content<value> <xref> <link> <markdown> <heading> <para> <list> <nlist> <preformat>
Permitted parent<properties-fragment> <properties>
HTML equivalent
OpenXML equivalent

Attributes

This element includes the following attributes:

NameTypeRequiredDescription
countproperty-countnoThe value count for the property or n for unbounded. DEPRECATED.
datatypexs:stringno

The data type for the property. Including:

  • string
  • date
  • xref
  • link
  • markdown
  • markup
multipletruenoIf present, this indicates the property can have multiple values
namelabel-nameyesThe name of the property
titlexs:stringnoWhat title to display in the user interface for the property
valuexs:stringnoWhether there is a single value for the property

@count

A value greater than 1 or equal to n, 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.

The @count is deprecated as of PSML v1.1 in PageSeeder 5.98, use @multiple="true" instead if required.

@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 an ISO 8601 date.
  • 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.

Custom data types are allowed, however, they might require a specific editor. If the data type is not recognized by PageSeeder, it treats the <property> as if the @datatype was string.

@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.

Created on , last edited on