Advanced

Advanced topics

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 will serve 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 Document Types page under the Dev menu  in the Developer perspective. Go to the Editor Config column and select the row for document type to customize. This will create or open a editor-config.json file that stores the custom editor configuration for one or more of the fragment types in the document type. The configuration details are documented after the Use Case section.

Background

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

  • String editor
    • check boxes ("checkbox")
    • select lists ("select")
    • patterns constrained by regular expression ("text")
  • Date editor ("date")
    • date
  • a cross reference editor that is preconfigured to autosuggest 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

Each property is listed by name in the appropriate "fields" array, with options set for each one.

"fields": {
   "name1" : { // options for field },
   "name2" : { // options for field },
   "name3" : { // options for field },
   ...
}

 The allowable options for each property are as follows. 

OptionDescription
typeOne of "text", "select", "checkbox", "date", "xref" or "markdown"
labelTo be displayed as a title, next to the editable field.
valuesPossible values (for a field of type "select" or "checkbox")
placeholderText that has been 'ghosted' into the text fields as guidance for the users.
patternA regular expression that constrains the value of the field (property). In other words, to be valid, the text string must conform to the pattern.
autosuggestUsed to customize the behavior of the autosuggest box for fields of type "xref", see PSML XRefs editor: Auto-suggest configuration
autocompleteList the values of other documents as the value of this property (default false)
uniqueTo flag whether the property value is referenced in other documents (default false)
readonlyWhether the field should be editable (default false)

Types

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

datatypetextselectcheckboxdatexrefmarkdown
string
date
xref
markdown

Text

The text type will display a simple input box for text to be entered manually. The placeholder option can be used to display a hint in the text box 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 will display a simple drop-down list. Only one value can be selected by the user. The list of possible values can be set using the values option as a JavaScript array. 

Checkbox

The checkbox type will display a list of check boxes so that multiple values can be selected. The list of possible values can be set using the values option as a JavaScript array. Normally the PSML property should have count="n", but if count="1" the options will be comma separated in the value attribute.

Date

The date type will provide a date picker to the user and store the value as ISO8601 (yyyy-mm-dd).

XRef

The XRef type allows users to set or edit cross references within a label.

Markdown

The markdown type is for formatted text, see markdown.

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 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 will list 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:

    "category" : { "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 will perform 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 list values starting with the same string which have already been used. For example, if '1234' and '1235' already exist, and the user types '123' both values will be displayed below 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:

    "isbn" : { "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 will not 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:

    "payment" : { "readonly": 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.json  if you have used the developer tools, it should already be the case.
  • The file must be in the correct location template/[project]/psml/[document type]/  if you have used the developer tools, it should already be the case.
  • It must be a valid JSON file, you can use JSON validator such as  http://jsonlint.com to check 

Sample config

{ 
  "PSMLPropertiesConfig": {
    "fields": {
      "author" : {
        "type": "text",
        "label": "Author"
      },
      "category" : {
        "type": "checkbox",
        "label": "Category",
        "values": ["English", "History", "Maths", "Science"]
      },
      "in-stock" : {
        "type": "select",
        "label": "In Stock",
        "values": ["Yes", "No"]
      },
      "available-date" : {
        "type": "date",
        "label": "Available Date"
      },
      "isbn" : {
        "type": "text",
        "label": "ISBN",
        "placeholder": "Enter a valid ISBN 13 number (97xxxxxxxxxxx)",
        "pattern": "97[89][0-9]{10}"
      },
      "publisher": {
        "type": "xref",
        "label": "Publisher",
        "placeholder": "Lookup XRef"
      }
    }
  }
}

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>

Full example

In the example screens below, the Jurisdiction field of a document type has been configured with a list of allowable values. Because only one value is valid in this field, the editor has been configured as a select list.

image 1 – select editor PageSeeder interface

Example properties editor

In this example, the editor-config.json references a fragment type ("jurisdiction") declared in the document template for this document type. After it has been declared, the field can be populated with the appropriate list of values. 

 

image 2 – select property editor json

Once properly configured, any request to edit a fragment type will invoke a customized properties editor. Combining  this interface with read-only content, means it is possible to deliver both the editing interface and the user instructions on the same page.

properties XML in dev editor

With no modification or configuration, the <property> element can be displayed as a table in the Search results page. Also, text properties can be edited using the Edit Sheet under the Lab menu in the Lab perspective.

search properties

 

The Edit Sheet does not support edits for <property> elements with a @datatype of  "xref" or "date".

 

properties edit sheet

Created on , last edited on