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 list 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
countproperty-count

no

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

datatypexs:string

no

The data type for the property. Including:

  • "string"
  • "date"
  • "xref"
  • "markdown"
multiple"true"

no

If present this indicates the property can have multiple values.

namelabel-name

yes

The name of the property.

titlexs:string

no

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

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

Deprecation warning!

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:

  • 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 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,  the @count must be greater than "1" or equal to "n".

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

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