PSML properties editor

Overview

In PSML, a property is a single or multi-value object, typed as either a string, a date or a cross-reference. With no modification, PageSeeder serves properties in a type-specific editing interface. However, for improved productivity or data quality, the editing interface for properties can be customized.

To create a custom properties editor, go to the Template configuration administration page. Go to the Editing column and select the row for the document type to customize. You can create or edit the editor-config.xml file that stores the custom editor configuration for one or more of the fragment types in the document type.

Background

The default PageSeeder editing interface can be specialized according to the @datatype of the <property> element. Examples include:

String editor:

checkboxes (checkbox).
select lists (select).
patterns constrained by regular expression (text).

Date editor (date):

date.

A cross-reference editor that is preconfigured to auto-suggest only link targets that are: (xref)

contained by a certain folder structure.
with a certain document type or document label.
with a certain filename or ID.

Configuration options

The PSML properties editor can be customized using the <editor-config name="PSMLProperties"> element.

<editor-config name="PSMLProperties">
  <field ... />
  <field ... /> 
  ...
</editor-config>

The allowed attributes for each <field> are as follows.

Attribute	Description	Default value
`@name`	The name of the property (required)
`@type`	One of `text`, `select`, `checkbox`, `date`, `datetime`, `xref`, `link`, `markup` or `markdown` (required)
`@label`	To be displayed as a title, next to the editable field	`[name]`
`@placeholder`	Text that has been ‘ghosted’ into the text fields as guidance for the users
`@pattern`	A regular expression that constrains the value of the field (property). In other words, to be valid, the text string must conform to the pattern.
`@autocomplete`	List the values of the same property in other document instances as suggestions for this property (for `PSMLCreation` config, the `<t:param>` name must match the property name).	`false`
`@unique`	Whether the property value should be unique in all document instances (for `PSMLCreation` config, the `<t:param>` name must match the property name).	`false`
`@readonly`	Whether the field should be editable	`false`
`@required`	Whether the field value is required (only applies to `PSMLCreation` config)	`false`

<xref-config>

If type="xref", the <field> element can contain one <xref-config> element with the same content as for the xref config except that @name is optional.

If @name is specified, then the configuration from the PSML xref config for the project (xref-config.xml) with the same name is used and this <xref-config> element should be empty.

As properties can’t contain <blockxref>, only options for <xref> should be used in the xref config. Also, the @fragmenttype attribute on <xref-config> is ignored in the properties editor.

<value>

If type= select or checkbox, the <field> element can contain one or more <value> elements which contain the allowed values for the property.

Types

The field type in the properties editor configuration defines the input type for the property and is related to the @datatype attribute of the property.

datatype	text	select	checkbox	date	datetime	xref	link	markdown	markup
string
date
datetime
xref
link
markdown
markup

In the PSMLCreationconfiguration, a field corresponds to a <t:param> in the PSML document template with the same @name. The t:param/@type determines how the field value is formatted in the template as shown in the following table (?means optional and +means zero or more). Requires PageSeeder v5.98 or higher.

t:param/ @type	text	select	checkbox	date	datetime	xref	link	markdown	markup
text	text	text	comma-separated text	text	text			text
integer	integer	integer	comma-separated integer
date				date
xml	`<value>?`	`<value>?`	`<value>+`	`<value>?`	`<value>?`	`<xref>?`	`<link>?`	`<markdown>+`	`<para>+`

Text

The text type displays an input field for text to be entered manually. The placeholder option can be used to display a hint in the field when no value has been specified.

The pattern option can specify a regular expression that the value must match to be submitted. This can be useful mechanism to constrain the format or possible values.

Select

The select type displays a drop-down list. Only one value can be selected by the user. The list of possible values can be set using <value> elements.

Checkbox

The checkbox type displays a list of checkboxes so that multiple values can be selected. The list of possible values can be set using <value> elements. Normally the PSML property should have @count="n" or @multiple="true", but if @count="1" and there is no @multiple the options are comma-separated in the value attribute (note: @count is deprecated as of PageSeeder 5.9800).

Date

The date type provides a date picker to the user and stores the value as ISO8601 (yyyy-mm-dd).

Datetime

The datetime type provides a date and time picker to the user and stores the value as ISO8601 (yyyy-mm-ddThh:mm:ss±hh:mm). Requires PageSeeder v6.00 or higher.

Xref

The xref type allows users to set or edit cross-references with a label.

Link

The Link type allows users to set or edit a link to a URL with a label. Requires PageSeeder v5.99 or higher.

Markdown

The markdown type is for formatted text, see markdown.

Markup

Markup allows any of the elements <heading>, <para>, <list>, <nlist> or <preformat> and anything that they can contain. However, the UI doesn’t currently support <xref>, <image>or <inline>elements. Requires PageSeeder v5.98 or higher.

Autocomplete

This option is designed to promote better consistency in values used for a property. It is less restrictive than the select input type, but it provides suggestion from usage data that is more useful than free text or suggestions from the browser (which are restricted to the user & machine).

It only applies to fields of type text – both single and multi-valued.

The editor lists the values previously used for that property so that the user can select one of them. The scope of the lookup is based on the property name but not the document type within the current group.

Example:

<field name="category" type="text" autocomplete="true" />

Unique

This option is designed to prevent users entering duplicate values in properties which should be considered unique.

It only applies to single valued fields of type text and for values of at least 3 characters.

The editor performs a lookup in the index for that specific property to check whether any other document uses the same value to determine whether the field value is unique.

The editor also lists values starting with the same strings which have already been used. For example, if ‘1234’ and ‘1235’ already exist, and the user types ‘123’ both values are displayed underneath in red with the name of documents these values are used in.

The scope of the ID is based on the property name but not the document type within the current group. This could be changed in the future to reduce the scope of uniqueness within documents of the same type rather than all documents or expand it to other groups.

This option defaults to false and takes precedence over autocomplete.

Example:

<field name="isbn" type="text" unique="true" />

Readonly

This option is used to prevent some values from being editable. It is useful when values have been previously generated by a template or uploaded.

It could also be used when shared documents include some properties that can be edited by one group but not the other. But remember that if the permissions allow users to edit the document, PageSeeder doesn’t prevent the property from being modified.

It only applies to date, text and xref input types.

This option defaults to false and takes precedence over autocomplete and unique – they are ignored if specified.

Example:

<field name="payment" type="text" readonly="true" />

Required

This option is used to require the user to enter a value for this field when creating a document or fragment. It is only applicable in the PSMLCreation config. Requires PageSeeder v5.98 or higher.

This option defaults to false.

Example:

<field name="payment" type="text" required="true" />

Troubleshooting

If you’re having trouble getting your configuration file to work, check the following:

The name of the file must be editor-config.xml – if you have used the Template configuration administration page, it is already the case.
The file must be in the correct location template/[project]/psml/[document type]/ – if you have used the Template configuration administration page, it is already the case.
Click the Validate all button on the Template configuration administration page which validates the contents of all config files.

Sample config

<editor-config name="PSMLProperties">
  <field name="author"
         type="text"
         label="Author"
         autocomplete="true"/>
  <field name="category"
         type="select"
         label="Category">
      <value>English</value>
      <value>History</value>
      <value>Maths</value>
      <value>Science</value>
  </field>
  <field name="in-stock"
         type="select"
         label="In Stock">
      <value>Yes</value>
      <value>No</value>
  </field>
  <field name="available-date"
         type="date"
         label="Available Date"/>
  <field name="isbn"
         type="text"
         label="ISBN"
         placeholder="Enter a valid ISBN 13 number (97xxxxxxxxxxx)"
         pattern="97[89][0-9]{10}"
         unique="true"/>
  <field name="publisher"
         type="xref"
         label="Publisher"
         placeholder="Lookup publisher"/>
</editor-config>

Before the properties editor can display the fields, it requires some default content in the PSML, which is usually added to the PSML document template for that document type.

The sample config above would require something similar to the following default content:

<properties-fragment id="2">
  <property title="Author"
            name="author"
            count="n" />
  <property title="Category"
            name="category"
            count="n" />
  <property title="In Stock"
            name="in-stock" />
  <property title="Available Date"
            name="available-date"
            datatype="date" />
  <property title="ISBN"
            name="isbn" />
  <property title="Publisher"
            name="publisher"
            datatype="xref" />
</properties-fragment>

Created on 15 May 2012, last edited on 23 January 2023 at 12:25