Advanced

Advanced topics

PSML XRefs editor

This editor is used when the section contains a list of cross references.

It can be customized using the "PSMLXRefsConfig" property.

"
PSMLXRefsConfig": {
  "default" : {
    // configuration options
  }
}

The default configuration options can be customized for <xref-fragment> elements with different @type attributes by adding configurations for each type as follows:

"
PSMLXRefsConfig": {
  "default" : {
    // configuration options for <xref-fragment>
  },
  "mytype1" : {
    // configuration options for <xref-fragment type="mytype1">
  },
  "mytype2" : {
    // configuration options for <xref-fragment type="mytype2">
  }
}

Configuration options

There are two aspects of the editor that can be configured: the cross-reference's default values and the auto-suggest feature on the search field.

Cross-reference's default values

These are defined using the keyword xref and the possible pairs are listed below:

Property nameDescriptionDefault value
displayThe display of the link, possible values are document (use the document title), document+fragment (document title and section title), document+manual (document title and a manual title), manual.document
fragThe fragment referenced in the target document ("default" points to the entire document).default
labelsComma-separated list of labels to add to the cross-reference.
manualtitleThe manual title to use as the display, only used if display is manual or document+manual.
typeType of the cross-reference, possible values are None, Replace, Transclude and Embed.Replace
reverselinkBoolean flag specifying if the reference is two ways, possible values are true and false.true
reversetypeThe reverse type of the cross-reference, possible values is currently None.None

Here's the format to follow to define these value:

"xref": {
   "display" : "manual",
   "manualtitle" : "My Title Link",
   "labels" : "label1,label2",
   "reverselink" : "false"
   ...
}

Auto-suggest configuration

The auto-suggest feature is the document search that is run when the user starts typing in the omnibox. The following properties can be configured:

  • "group"  a group to search in (e.g. "acme-specs" ) - defaults to current group;
  • "fields"  a list of index fields that are searched;
  • "with a list of facets to filter the search results;
  • "display a list of index fields that will be displayed in the search results. The "pstitle" and "psid" are always displayed. To display the document path add the fields "psfolder", "psfilename" in that order.

The format is as follows:

"autosuggest" {
  "fields" : ["field1", "field2", ...]
  "with": {
    "field3" : "value3",
    "field4" : "value4",
    ...
  },
  "display" : ["field1", "field2", ...]
}

Each facet is a pair of strings made of a field name and its value. All the documents returned by the search will match these criteria. The values must be exact matches (wildcards are not allowed) except in one particular case: if the name of the facet is "psancestor":

For the psancestor facet, the wildcard character "*" is allowed as a folder name. It will then be replaced with the equivalent folder in the current document's path. This allows to search for documents only within the current context. Note that if the psancestor value does not contain a wildcard character (*) then it is used as is. If the wildcard does not match the current path, the facet is ignored.

The psancestor facet can also beginning with "." or ".." (as long as it does not contain "*"). This means the facet value will be constructed relative to the current document.

Here are a few examples when editing a document with a path of:
/ps/project/group/documents/folder/myfile.xml:

facet valuefacet value used
/ps/project/group/documents/*/ps/project/group/documents/folder
/ps/project/group/*/*/ps/project/group/documents/folder
/ps/project/group/*/ps/project/group/documents
/ps/project/group/images/*[facet is ignored]
/ps/project/group/documents/ps/project/group/documents
./assets/ps/project/group/document/folder/assets
../assets/ps/project/group/document/assets
../../assets/ps/project/group/assets

Note

If an inline label is used as a facet, only documents with an exact match (case sensitive) will be returned. This is because inline label fields are not analyzed in the index (see the Index for more information).

 

The default values for these configuration options are:

autosuggest {
  "fields" : 
["pstitle", "psfilename", "psdocid", "psid"]
  "with": {
  },
  "display": ["psfolder", "psfilename"]
}

Sample config

{
  "PSMLXRefsConfig": {
    "default" : {
      "xref": {
        "type" : "Embed",
      },
      "autosuggest" : {
        "fields": ["pstitle", "pslabel", "pscontent"],
        "with": {
          "psancestor"     : "/ps/project/group1/documents/*",
          "psdocumenttype" : "book",
          "psstatus"       : "Approved"
        },
        "display": ["psdocid", "pslabel"]
      }
    },
    "mytype" : {
      "xref": {
        "type" : "Transclude",
      }     
    }
  }
}

Created on , last edited on