PSML

A complete reference of PageSeeder's markup language PSML

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

Single and multiple values

A single value <property> has the @count attribute omitted or equal to "1" and uses the @value attribute to store the value.

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

For a multiple value <property> the @count attribute is greater than "1" or equal to "n" and the values are stored as <value> elements or <xref> elements. Although the @count attribute on a multiple value <property> must be greater than "1",  the <property> is not required to have any <value> element to be valid.

Note

If a <property> has more than one value (for example it is configured as a checkbox in the PSML properties editor) and the @count attribute is not "n" or not greater than "1" then the values will appear comma separated in the @value attribute (e.g. value="English,Spanish"). However it is recommended to set @count correctly and use <value> elements..

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> <markdown>
Permitted parent<properties-fragment> <properties>
HTML equivalent
OpenXML equivalent
PSStandard equivalent<inlineLabel> wrapped in <para>

Attributes

This element includes the following attributes

NameTypeRequiredDescription
countproperty-countnoThe property's value count or "n" for unbounded.
datatypexs:stringnoThe property's data type (e.g. "string", "date", "xref", "markdown").
namelabel-nameyesThe property's name.
titlexs:stringnoThe property's title (for UI).
valuexs:stringnoThe property's value (if single).

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.

datatype

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

The predefined data types are:

  • 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.
  • markdown  – specifies markdown formatted text .

Note

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

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

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"/>
<property name="part-number" count="1" @value="PX-67S93Q"/>

Example #2

For a <property> element to support multiple values,  the @count must be greater than "1" or equal to "n".

<property name="languages" count="n">
   <value>de</value>
   <value>en</value>
   <value>fr</value>
</property>

Example #3

A <property> with a @datatype of "xref".

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

Example #4

A <property> with a @datatype of "markdown".

<property name="example" datatype="markdown">
   <markdown>The **quick** brown *fox* jumps over the `lazy` dog.</markdown>
</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="markdown" minOccurs="0" maxOccurs="1" />
      </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>
    </xs:complexType>
  </xs:element>

Relax Schema

element property {
   attribute name { label },
   attribute title { text }?,
   attribute datatype { text }?,
   attribute count { text }?,
   attribute value { text }?,
   (element value* | element xref* | element markdown)
}

Compatibility

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

See also

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

Created on , last edited on