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.

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.

Note

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 in the @value attribute.

Warning!

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
count
property-count

no

The value count for the property or "n" for unbounded.

datatype
xs:string

no

The data type for the property. Including:

  • "string"
  • "date"
  • "xref"
  • "markdown"
name
label-name

yes

The name of the property.

title
xs:string

no

What title to display in the user interface for the property.

value

xs:string

no

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

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

Example 2 – multi-value property

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

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