PSML

A complete reference of PageSeeder's markup language PSML

<blockxref>

Summary

A block level cross reference.

This type of cross reference is usually used to insert content from another document using the "embed" or "transclude" type. Or, it can be used to build table of contents.

Note

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

  • @href
  • @docid
  • @uriid

The content of this element, displayed as the link title, is generated. So, although the content is only INFORMATIONAL and will be 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;
    OR
  • If the cross reference can not be resolved, the content may provide useful information about the intent of the unresolved XRef.

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

It is the only type of link allowed inside an <xref-fragment>.

When the PSML is processed, <blockxref> may contain the content of the targeted document or fragment.

Note

Best practice recommends that information models limit PSML documents to no more than 1,000 inline <xref> and block <blockxref> elements in a single document.

Usage context

Element categoryblock content
PSML levelportable
Permitted contenttext *
Permitted parent<fragment> <xref-fragment>...
HTML equivalent<a>
OpenXML equivalent
PSStandard equivalent <blockXref>

Note

 * In PSML processed level, the content can be <document>, <locator>, <fragment>, <xref-fragment>, <properties-fragment> or <media-fragment>.

Attributes

This element includes the following attributes

NameTypeReq​uiredDescription

config

xref-configno

The configuration name for this XRef

display

xref-displayno

Defines format of target link text

docid

document-idno

The document ID of the target 

documenttype

document-typeno

The target document's type.

external

booleanno

If "true" the target is a URL (external URI).

frag

fragment-idyes

The fragment ID of the target

href

xs:stringno

Path to the target document

id

xs:longno

XLink ID of the cross-reference 

labels

label-listno

A list of XRef labels

level

xref-levelno

The level of heading the target document should start at

mediatypexs:stringno

The target document media type

reverselinkbooleanno

A flag indicating if the link is bidirectional

reversetitlexs:stringno

The title in the reverse direction

reversetypexref-typeno

Always "none"

reversefragfragment-idno

The fragment ID on the source

titlexs:stringno

The manually entered title

typexref-typeno

Type for link processing (default is "embed"). 

unresolvedboolean no

If "true", the target document could not be resolved.

uriidxs:longno

URI ID of the target document

urititlexs:stringno

Title of the target URI (generated)

urilabelslabel-listno

Labels of the target URI (generated)

@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 Cross-reference display.

@docid

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

@documenttype

Refers to the XRef target documenttype. INFORMATIONAL - ignored by upload.

@external

If attribute value is "true", the XRef target is a URL (external URI). INFORMATIONAL - ignored by upload.

@frag

Refers to the XRef target fragment ID. When this value is "default", it refers to the entire document. This value can also reference fragments other than PSML fragments.

@href

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

This value overrides the @docid and @uriid on upload.

@id

The ID of the XLink that corresponds 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. 

@mediatype

Refers to the mediatype of the XRef target document. INFORMATIONAL - ignored by upload.

Note

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

@reverselink

A boolean attribute to indicate whether the cross reference is bidirectional or “reverse” link. When set to "true" (the default value), the cross reference will also appear in the metadata of target document.

@reversetitle

A manually entered title to appear on the reverse link.

@reversetype

Type for link processing of reverse link. As of version 5.97, there is only support for a value of "none".

@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;
  • embed – Replace this element's content with the document/fragment pointed to when publishing;
  • transclude – Replace this element's content with the document/fragment pointed to when displaying.

Note

The default type for <blockxref> is "embed". For an inline <xref>, the default type is "none".

@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 on a different PS 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 <blockxref> elements, it is useful to remember that PageSeeder will automatically expand 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 will see all the following examples as valid:

<blockxref href="filename.psml"
                frag="default">link title</xref>
<blockxref docid="server-wide_uniqueid"
                        frag="default">link title</xref>
<blockxref 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 Manage page under the Admin menu and select the option to Resolve References.

The PageSeeder server will then resolve the <blockxref> element, add the implied attributes and values and create 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="blockxref">

 <xs:complexType>
  <xs:simpleContent>

            <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"
                  type="xs:integer" />

    <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="type">
          <xs:simpleType>
    <xs:restriction base="xs:string">
        <xs:enumeration value="none" />
   <xs:enumeration value="alternate" />
       <xs:enumeration value="embed" />
  <xs:enumeration value="transclude" />
                 </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: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 blockxref {
   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"
                     | string "embed"
                     | string "transclude"},
   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.

It replaces PSStandard's <blockXref> element.

Note

In PSML, most attributes names and values are in lower case.

Warning!

The types "replace" and "include" supported in PSStandard are no longer supported in PSML and should be replaced by "embed".

See also

Related element: <xref>

Created on , last edited on