Configuration

Configuration manual for PageSeeder

PSML XRef config

The xref-config.xml file can be used to configure cross references across a whole project to make it easy for users to create XRefs consistently for different purposes.

The file is located in the template/[project]/config folder and can be accessed most easily via the XRef config link at the top of the Dev > Document Config page in the Developer prespective.

The file has the following format:

<xref-configs>
  <xref-config name="[name of config]" title="[title for use interface]">
    <xref ... />
    <target .../>
    <autosuggest .../>
  </xref-config>
  <xref-config ...>
    ...
  </xref-config>
  ...
</xref-configs>

There can be any number of <xref-config> elements and the only required attribute or element is @name.

Configuration options

There are three aspects of the editor that can be configured: the cross-reference's attributes, the target document and the auto-suggest search options for the target (none of the options are required).

Cross-reference's attributes

These are defined using attributes on the <xref> element as follows:

AttributeDescriptionDefault value
display

The display of the link, possible values are document (use the document title), document+fragment (document title and section title), document+manual (document title and a manual title), manual, template.

frag

The fragment referenced in the target document ("default" points to the entire document).

labelsComma-separated list of mandatory labels to add to the cross-reference.
optionallabelsComma-separated list of optional labels that users can add to the cross-reference.
title

The manual title to use as the display, only used if display is manual, document+manual or template. For template the title can contain any combination of text and the following tokens which will be replaced dynamically:

  • {document}: display title of the target document;
  • {filename}: filename of the target document;
  • {docid}: docid of the target document;
  • {fragment}: target fragment ID;
  • {prefix}: the @prefix of the first heading or para in the target fragment (<xref> only);
  • {parentnumber}: the number of the parent heading or para for the target fragment (<xref> only);
  • {heading}: the text of the first heading in the target fragment (<xref> only).
type

Type of the cross-reference, possible values are: none, alternate, transclude (<blockxref> only), embed (<blockxref> only) and math (<xref> only).

embed
levelThe amount to increment heading levels in the target document by [0-5] - 0 means no level.0
reverselink

Boolean flag specifying if the reference is two ways, possible values are true and false.

true
reversetitle

The reverse title of the cross-reference.

Example:

<xref
   display="manual"
   title="My Link Title"
   labels="label1,label2"
   reverselink="false" />

Target document

The target document is defined using attributes on the <target> element as follows:

AttributeDescriptionDefault value
documenttype

The document type of the target document.

new

The options for creating a new target document. Allowed values:

  • none: don't allow creation of target document;
  • create: allow creation of target document;
  • edit: allow creation and open target document for editing after creation.
create
this

Whether the target is the same document. If true this overrides the auto-suggest configuration and sets new="none".

false

 

Auto-suggest configuration

The auto-suggest feature is the document search that is run when the user starts typing in the omnibox.

This is configured using attributes on the <autosuggest> element as follows:

AttributeDescriptionDefault value
groupa group to search in (e.g. "acme-specs" )[current group]
foldera folder to search in relative to the group folder or starting / means absolute (may also have * for any path segment) or starting . or .. means relative to current document.

 

questionfieldsa comma-separated list of index fields to searchpstitle,psfilename,
psdocid,psid
filtera comma-separted list of filters (field:value) for the results (e.g. pslabel:car,pssubtype:image). These are also applied to the XRef browse document page.
displayfieldsa comma-separated list of fields to display in the search results. The "pstitle" and "psid" are always displayed. To display the document path add the fields "psfolder", "psfilename" in that order.psfolder,psfilename

For folder the wildcard character "*" is allowed for any path segment. It will then be replaced with the equivalent folder in the current document's path. This allows to search for documents only within the current context. If the wildcard does not match the current path an alert message is displayed and an XRef with this configuration cannot be created or edited.

The folder attribute can also beginning with "." or ".." (as long as it does not contain "*"). This means the facet value will be constructed relative to the current document.

Here are a few examples when editing a document in the acme-specs group with a path of: /ps/acme/specs/documents/folder/myfile.xml:

folder attributeactual folder
group/documents/*/ps/acme/specs/documents/folder
group/*/*/ps/acme/specs/documents/folder
group/*/ps/acme/specs/documents
images/*[xref cannot be created or edited]
documents/ps/acme/specs/documents
/ps/acme/specs/documents/ps/acme/specs/documents
./ps/acme/specs/documents/folder
../ps/acme/specs/documents
./assets/ps/acme/specs/document/folder/assets
../assets/ps/acme/specs/document/assets
../../assets/ps/acme/specs/assets

Note

If an inline label is used as a facet, only documents with an exact match (case sensitive) will be returned. This is because inline label fields are not analyzed in the index (see the Index for more information).

Example:

<autosuggest
  questionfields="pstitle,pslabel,pscontent",
  folder="documents/*"
  filters="psstatus:Approved"
  displayfields="psdocid,pslabel" />

Sample config

<xref-configs>
  <xref-config name="footnote" title="Footnote">
    <xref display="template"
          title="f{fragment}"
          type="none" />
    <target documenttype="footnotes" />
    <autosuggest folder="." />
  </xref-config>
  <xref-config name="definition" title="Definition">
    <xref display="template"
          title="{heading}"
          type="none" />
    <target documenttype="definitions" new="none" />
    <autosuggest folder="." />
  </xref-config>
  <xref-config name="para" title="Paragraph">
    <xref display="template"
          title="{parentnumber}{prefix}"
          type="none" />
  </xref-config>
  <xref-config name="internal-para" title="Internal paragraph">
    <xref display="template"
          title="{prefix}"
          type="none" />
    <target this="true" />
  </xref-config>
  <xref-config name="numbered-heading" title="Numbered heading">
    <xref display="template"
          title="{prefix} {heading}"
          type="none" />
  </xref-config>
  <xref-config name="asciimath" title="AsciiMath">
    <xref display="document"
          frag="media"
          type="math"/>
    <target documenttype="asciimath" new="edit" />
  </xref-config>
</xref-configs>

Created on , last edited on