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 right of the administration Template configuration 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.

To create xrefs to any document (including non-PSML) use the following:

<xref-config ...>
  <target filters="pstype:document" />
</xref-config>

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

To restrict this to PDF files, for example, change the filter to:

filters="pstype:document,pssubtype:pdf"

To reference multiple subtypes, for example, PDF and image files, use:

filters="pstype:document,pssubtype:pdf,pssubtype:image"

Options

Three aspects of the editor are configurable:

Attributes of the xref.
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.

Attribute	Description	Default 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).
`frag`	The ID of the target fragment in the target document (a value of `default` points to the entire document).
`labels`	Comma-separated list of mandatory xref labels added to the cross-reference
`optionallabels`	Comma-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`
`level`	An 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`
`reverselink`	Boolean flag to specify a two-way xref. Possible values are `true` or `false`.	`true`
`reversetitle`	The 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:

Attribute	Description	Default value
`documenttype`	A comma-separated list of document types allowed for the target document.
`group`	The 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`	OBSOLETE as of PageSeeder v6, this functionality is no longer supported. 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`

Specifying any target attributes will stop files from being listed under browse on the xref dialog.
When using an inline label as a filter, remember that they are case-sensitive. (see Index for more information).

Folder attribute examples

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

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

in a group with the name:

acme-specs

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` value	actual 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`

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:

Attribute Description Default value

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

Attribute	Description	Default value
`questionfields`	A comma-separated list of index fields to search	`pstitle,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`

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" 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" />
  </xref-config>
</xref-configs>

Created on 13 June 2012, last edited on 14 August 2024 at 10:38

Configuration