Configuration

Configuration manual for PageSeeder

XRef config

Preconfiguring cross references (XRefs) helps users to be consistent when authoring links. It can also make them more productive. To create XRef configurations for a project, access the config file at:

template/[project]/config/xref-config.xml

Or via the XRef config link at the top of the Dev > Document Config page in the Developer prespective.

The XRef config file uses the following structure:

<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 (see title below).

frag

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


labels
Comma-separated list of mandatory labels to add to the cross-reference.

optionallabels
Comma-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 it can contain tokens which are dynamically replaced, see Cross-reference display.


type

Type of the cross-reference, possible values are:

  • none,
  • alternate,
  • transclude (<blockxref> only),
  • embed (<blockxref> only), and
  • math (<xref> only).
embed

level

The 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

group

a group to search in (e.g. "acme-specs" )

[current group]

folder

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

 


questionfields
a comma-separated list of index fields to search
pstitle,psfilename,
psdocid,psid

filter

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

Note

To allow users to select additional labels add a plus before pslabel (e.g. +pslabel:car).


displayfields

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

Following are examples of 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