<xref>

Summary

This element is used to create the in-line cross references that typically represent footnotes, endnotes or paragraph references in contracts or legislation.

For block-level cross references, where processing the xref injects or ‘transcludes’ entire paragraphs or documents into the xref source, see the <blockxref> element.

The @frag attribute is required, plus at least one of the following:

@href
@docid
@uriid

See example xref markup.

The content of this element, displayed as the link title, is generated. Although the original content is only INFORMATIONAL and is discarded by the upload process, there are two exceptions to this:

If @display="manual" and @title is missing or empty, the content is used for the value of @title.
If the cross-reference cannot be resolved, some content helps users to understand or debug what went wrong with the xref.

For these reasons, it is always a good idea to include text in the element content.

Usage context

Element category	inline
PSML level	portable
Permitted content	text
Permitted parent
HTML equivalent	`<a>`
OpenXML equivalent

Attributes

This element includes the following attributes:

Name	Type	Required	Description
`archived`	boolean	no	Whether the target document is archived
`config`	xref-config	no	The xref config name for this xref
`display`	xref-display	no	Defines format of target link text
`docid`	document-id	maybe	The document ID of the target
`documenttype`	document-type	no	The target document’s type
`external`	boolean	no	If `true`, the target is a URL
`frag`	fragment-id	yes	The fragment ID of the target
`href`	`xs:string`	maybe	Path to the target document
`id`	xs:long	no	XLink ID of the cross-reference
`labels`	label-list	no	A list of xref labels
`level`	xref-level	no	The level of heading the target document should start at
`mediatype`	`xs:string`	no	The target document media type
`reverselink`	`boolean`	no	A flag indicating if the link is bidirectional
`reversetitle`	`xs:string`	no	The title in the reverse direction
`reversetype`	xref-type	no	Always `none`
`reversefrag`	`fragment-id`	no	The fragment ID on the source
`title`	`xs:string`	no	The manually entered title
`type`	`xref-type`	no	Type for link processing (default is `none`)
`unresolved`	`boolean`	no	If `true`, the target document could not be resolved
`uriid`	`xs:long`	maybe	URI ID of the target document
`urititle`	`xs:string`	no	Title of the target URI (generated)
`urilabels`	label-list	no	Labels of the target URI (generated)

`@archived`

A boolean flag indicating whether the target document is archived. INFORMATIONAL - ignored by upload.

This attribute was introduced in PSML v1.3 in PageSeeder 5.99.

`@config`

The xref config name used when creating/editing this xref.

`@display`

Defines how the target link text of this cross-reference is displayed (Default is document).

The following values are allowed:

document – [document title].
document+manual – [document title]: [manual title].
document+fragment – [document title]: [target fragment id].
manual – [manual title].
template – see Xref display.

`@docid`

The document ID of the target, this value overrides the @uriid on upload.

`@documenttype`

The target document's type. INFORMATIONAL - ignored by upload.

`@external`

If true, the target is a URL. INFORMATIONAL - ignored by upload.

`@frag`

The target fragment ID. When this value is default, it refers to the entire document.

`@href`

When uploading, this might be a path relative to the current document or an absolute path that begins with a / character. If it is #, the current document is the target. It must always be URL encoded unless document/@level="processed".

It overrides the docid and uriid on upload.

When @href is relative and in a metadata format URL being uploaded, it is relative to the upload folder. So the folder that URLs are uploaded to may affect xref resolution.

`@id`

The ID of the XLink corresponding to this cross-reference. INFORMATIONAL - ignored by upload.

`@labels`

A comma-separated list of xref labels.

`@level`

The level that the heading numbering of the target document should start from (1 to 5).

`@mediatype`

The media type of the target document. INFORMATIONAL - ignored by upload.

The media type of PSML documents is application/vnd.pageseeder.psml+xml.

`@reverselink`

A boolean attribute to indicate whether the cross reference is bidirectional, that is, a reverse cross reference. When set to true (default), the cross reference also appears on the target document as part of its metadata.

`@reversetitle`

The manually entered title to appear on the reverse cross-reference.

`@reversetype`

Type for link processing of reverse cross-reference (only none is currently supported).

`@reversefrag`

The fragment ID on the source. INFORMATIONAL - ignored by upload.

`@title`

The manually entered title to appear on the link (only used when @display='manual' or @display='document+manual'). When @display='manual' and @title is missing or empty, then @title takes the value of the element’s content text.

`@type`

The type defines how PageSeeder should process the cross-reference.

The following values are allowed:

none – No link processing.
alternate – An alternate representation of the current document.
math – An in-line transclude link to a file or <media-fragment> with mediatype of application/mathml+xml or text/asciimath. Used for equations.

To create cross references which have a different type (for example transclusions) use a <blockxref> element instead.

`@unresolved`

If true, the target document doesn’t exist. INFORMATIONAL - ignored by upload.

`@uriid`

The URI ID of the target document. Ignored by upload if the PSML file came from a different PageSeeder server.

`@urititle`

An informational attribute providing title of the target URI. INFORMATIONAL - ignored by upload.

`@urilabels`

A comma-separated list of labels of the target URI. Introduced in v0.11 of the PSML schema in PageSeeder v5.95. INFORMATIONAL - ignored by upload.

Examples

When constructing <xref> elements, it is useful to remember that PageSeeder automatically expands a minimally-expressed link. All that is required is the address of the document and fragment and some content to make the link visible. PageSeeder sees all the following examples as valid:

<xref href="filename.psml" frag="default">link title</xref>

<xref docid="server-wide_uniqueid" frag="default">link title</xref>

<xref uriid="9999" frag="5">link title</xref>

Also, documents containing these minimal links* can be uploaded before the other end of the link is available.

After both ends of the xref are available, any user with the appropriate permission can go to the Group maintenance page under the Admin menu and select the option to Resolve references.

The PageSeeder server then resolves the <xref> element, adds the implied attributes and values and creates a <reversexref> element at the link destination.

* The third example is using a URIID. As this value is generated by the system, the target of this xref is already known.

Schema

XML Schema

<xs:element name="xref">
  <xs:complexType>
    <xs:simpleContent>
      <xs:attribute name="archived" type="xs:boolean"/>
      <xs:attribute name="config" type="xref-config"/>
      <xs:attribute name="id" type="xs:long"/>
      <xs:attribute name="docid" type="document-id"/>
      <xs:attribute name="href" type="xs:string"/>
      <xs:attribute name="uriid" type="xs:long"/>
      <xs:attribute name="frag"
                    type="fragment-id"
                    use="required"/>
      <xs:attribute name="title" type="xs:string"/>

      <xs:attribute name="level">
        <xs:simpleType>
          <xs:restriction base="xs:integer">
            <xs:pattern value="[1-5]"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

      <xs:attribute name="display">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="document" />
            <xs:enumeration value="document+manual" />
            <xs:enumeration value="document+fragment" />
            <xs:enumeration value="manual" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

      <xs:attribute name="labels" type="xs:string"/>
      <xs:attribute name="urititle" type="xs:string"/>
      <xs:attribute name="mediatype" type="xs:string"/>
      <xs:attribute name="documenttype" type="xs:string"/>
      <xs:attribute name="reverselink" type="xs:boolean"/>
      <xs:attribute name="reversetitle" type="xs:string"/>

      <xs:attribute name="reversetype">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="none" />
            <xs:enumeration value="alternate"/> 
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

      <xs:attribute name="reversefrag" type="fragment-id"/> 
      <xs:attribute name="unresolved" type="xs:boolean"/>
      <xs:attribute name="external" type="xs:boolean"/>      
    </xs:simpleContent>
  </xs:complexType>
</xs:element>

Relax Schema

element xref {
   attribute archived { xs:boolean }?,
   attribute config { xref-config }?,
   attribute id { xs:long }?,
   attribute docid { document-id }?,
   attribute href { text }?,
   attribute uriid { xs:long }?,
   attribute frag { fragment-id },
   attribute title { text },
   attribute level { xs:integer }?,
   attribute type { string "none" | string "alternate" },
   attribute display { "document" | "document+manual"
                        | "document+fragment" | "manual"},
   attribute labels { text }?,
   attribute urititle { text }?,
   attribute mediatype { text }?,
   attribute documenttype { text }?,
   attribute reverselink { xs:boolean }?,
   attribute reversetitle { text }?,
   attribute reversetype { string "none"}?,
   attribute reversefrag { fragment-id },
   attribute unresolved { xs:boolean }?,
   attribute external { xs:boolean }?
}

Compatibility

This element was introduced in the first draft of PSML and is well-supported from PageSeeder 5.1.

Created on 20 December 2013, last edited on 23 September 2024 at 15:46

PSML elements

<xref>

Summary

Usage context

Attributes

@archived

@config

@display

@docid

@documenttype

@external

@frag

@href

@id

@labels

@level

@mediatype

@reverselink

@reversetitle

@reversetype

@reversefrag

@title

@type

@unresolved

@uriid

@urititle

@urilabels