Skip to main content

 Configuration

Configuration manual for PageSeeder

Xref config

For writers that create a lot of links, customizing the xref-config improves consistency and productivity by pre-configuring cross reference (xrefs) targets into the user interface. This saves writers from having to set values with each link.

Like other configurations, the xref-config exists at the project-level, so the file is available at:

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

It is also available through the Edit XRef configs button at the top of the Document types administration page.

xref-config uses the following structure:

<xref-configs>
  <xref-config name="[name of config]"
               title="[title in UI]" >
    <xref ... />
    <target .../>
    <autosuggest .../>
  </xref-config>

  <xref-config ...>
             ...
  </xref-config>
  ...
</xref-configs>

There is no limit to the number of <xref-config> elements—the only required attribute or element is @name.

In v6, use the following code to configure an option for creating an xref to a URL: 

<xref-config>
  <target filters="pstype:url,psmediatype:application/vnd.pageseeder.url+xml" />
</xref-config>

The same code can be used in the editor-config.xml.

To configure an option for creating an xref to a PDF file, change the filter:

filters="application/pdf"

To reference both, use:

filters="pstype:document,pstype:url,psmediatype:application/pdf,psmediatype:application/vnd.pageseeder.url+xml" 

Options

Three aspects of the editor are configurable:

  • Attributes of the cross-reference.
  • Where to look for the target document, and
  • Auto-suggest search options to find a target document.

None of these options are required.

Attributes

The attributes on the <xref> element are described in the following table. The creation of an xref from a definition in the xref-config forces the attributes onto the link. The only exception is the @optionallabels attribute. That attribute gives the user an opportunity to select xref labels.

AttributeDescriptionDefault value
display

What title is used to represent the link in the document.

Possible values are:

  • document (the title of the target document).
  • document+fragment (the title of the document and the title of the section).
  • document+manual (the title of the document and manually entered text).
  • manual, template (see @title attribute below).
fragThe ID of the target fragment in the target document (a value of default points to the entire document)
labelsComma-separated list of mandatory xref labels added to the cross-reference
optionallabelsComma-separated list of xref labels for users to select from
title

Manually entered text when the value of @display is:

  • manual
  • document+manual, or
  • template – (can include placeholder tokens that resolve to dynamic data, see Cross-reference display).
type

The cross-reference type that determines how to process the xref, possible values are:

  • none
  • alternate
  • transclude (usable with <blockxref> only).
  • embed (usable with <blockxref> only), and
  • math (usable with <xref> only).
embed
levelAn incremental value to demote the heading levels of a target document when processing the xref. Allowable values are [0-5] – 0 leaves the level of the target headings unchanged after the xref has been resolved.0
reverselinkBoolean flag to specify a two-way xref. Possible values are true or false.true
reversetitleThe reverse xref title. In other words, the title to display at the target end of the link, not the source

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
documenttypeA comma-separated list of document types allowed for the target document.
groupThe project and group to search for target documents (for example, acme-specs)[current group]
folder

See notes following this table.

The document search path relative to the group.

  • Use “.” or “..” for a path relative to the current document.
  • To search an absolute folder path start  with “/”.
  • The asterisk “ *” substitutes for any path segment except where the path is relative to the current document. In other words, any value that starts with “.” or “...
filters

A comma-separated list of filters (field:value) to focus search results. For example:

pslabel:car,pssubtype:image

filters also apply to the xref browse-document page.

Adding a plus sign before pslabel allows users to select additional labels (v5 UI only). For example:

+pslabel:car

new

Allowable values for creating a new target document.

  • none – do not allow the creation of a target document.
  • create – allow the creation of a target document.
  • edit – create, and then open to edit, a new target document.
create
this

If the xref target is in the current document, a value of true  overrides the auto-suggest configuration. This sets the value on @new as follows:

@new="none"

false

For the @folder attribute, use of the wildcard character “*” in any path segment re-orients the search to the equivalent folder in the path of the current document.

If the wildcard does not match a segment in the current path, the system displays an alert message and prevents the xref-config from creating or editing a link.

Folder attribute examples

Following are examples of specifying a search location starting from the following path and filename:

/ps/acme/specs/documents/folder/myfile.xml

in a group with the name:

acme-specs

@folder valueactual location
documents/*/ps/acme/specs/documents/folder
*/*/ps/acme/specs/documents/folder
*/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

When using an inline label as a facet, remember that they are case-sensitive. (see Index for more information).

Example:

<target folder="documents/*" filters="psstatus:Approved" />

Auto-suggest configuration

This uses the same search as the search box. It is configured through the following attributes on the <autosuggest> element:

AttributeDescriptionDefault value
questionfieldsA comma-separated list of index fields to searchpstitle,psfilename, psdocid,psid
displayfields

A comma-separated list of fields to display in the search results.

pstitle and psid are always displayed. To include the path, add these fields – psfolder, psfilename

psfolder,psfilename

Sample config

<xref-configs>
  <xref-config name="footnote" title="Footnote" >
    <xref display="template" title="f{fragment}" type="none" />
    <target documenttype="footnotes" folder="." />
  </xref-config>
  <xref-config name="definition" title="Definition">
    <xref display="template" title="{heading}" type="none" />
    <target documenttype="definitions" new="none" 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