Configuration

Configuration manual for PageSeeder

XRef config

For writers that use a lot of links, customizing the XRef config improve consistency and productivity.  This allows authors to choose an XRef configuration that points directly to the cross reference (XRefs) targets.

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 via the XRef config link at the top of the Dev > Document Config page in the Developer prespective.

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.

Note

To create an XRef to a URL in the v6 UI the following config is required (this can also be used in the editor-config.xml):

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

Similarly to reference PDFs  in v6 use filters="application/pdf". To reference both use filters="pstype:document,pstype:url,psmediatype:application/pdf,psmediatype:application/vnd.pageseeder.url+xml" .

Configuration options

Three aspects of the editor are configurable:

  • attributes of the cross-reference.
  • where to look for the target document, and
  • search options to auto-suggest the target.

none of these options are required.

Cross-reference's attributes

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

AttributeDescriptionDefault value
display

The display of the link in the document.

Possible values are:

  • document (display the title of the target document),
  • document+fragment (display the title of the document and the section),
  • document+manual (display the title of the document and a 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 to add to the cross-reference.

optionallabels

Comma-separated list of optional XRef labels for users to add to the cross-reference.

title

The manual text to display if 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 determine the XRef processing, the 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. Allowable values are [0-5] - with 0 meaning the target headings stay at the same level in the new structure.

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:

AttributeDescriptionDefault value
documenttype

A comma-separated list of document types allowed for the target document.

group

The project and group to search for target documents (e.g. "acme-specs" )

[current group]
folder

see notes below 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.

Note

Adding a plus sign before pslabel will allow users to select additional labels. 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" will override the auto-suggest configuration. This will set  the value on @new as follows:

@new="none"
false

Note

For the @folder attribute, use of the wildcard character "*" in any path segment will re-orient 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 will display an alert message and prevent 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

Note

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 omnibox. It is configured through the following attributes on the <autosuggest> element:

AttributeDescriptionDefault 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

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