# Overview of plugging into Orion pages

An important part of plugging into Orion pages is supplying links that connect the user to other pages inside and outside of Orion. Page-level linking services allow plugins and page authors to contribute links and other forms of connectivity between an Orion page and other web pages. The most general of these services can be used on any Orion page.

When specifying links to other pages, a service may need to use some information about the page to decide whether a link is applicable and how the link is composed. This is accomplished for many services by using the `validationProperties`, `uriTemplate`, and `contentType` properties in the service definition.

## Validation Properties

Validation properties describe the properties of a page object that should be analyzed to determine whether a particular service applies to the object. They can optionally store information from page objects into variables that can be referenced in a URI template. Contributing services generally specify one or more of these properties in an array.

## The ValidationProperty Object

A ValidationProperty has the following properties:

source
  `String` The name of a property to look for in the target object. The ":" character represents nested properties, and the "|" character represents OR'ed properties. The " n" operator may appear after a property name to treat the property as an array. The value of the property selected by source flows to the match and variableName expressions (if specified).

For example:

    The source `Location` specifies that the page object must have a "Location" property, such as `myObject.Location`.
    The source `Git:ContentLocation` specifies that the page object must have a sub-object and property such as `myObject.Git.ContentLocation`.
    The source `ChildrenLocation|ContentLocation` means that the page object must have either a property such as `myObject.ChildrenLocation` or a property such as `myObject.ContentLocation`. The first property found will be used.
    Elements of an array can be referred to by ":n" or " n". For example, the source `Children 0` specifies that the page object must have a "Children" property with at least one element in it.
    A negative array index " -n" refers to the element at index `length - n`. For example, `Children -1` refers to the last element of the Children array.
match
  `String|Object` Optional. An expression that the property selected by source will have its value validated against. If the value matches the match, then this validation property is considered to match the target object.

  If match is an object, a simple strict equality comparison is performed against the source value. If match is a string, it gives a regular expression pattern that will be passed to the `RegExp` constructor, and executed against the source value.

variableName
  `String` Optional. The name of a variable that the value of the source property will be bound to. If provided, then an associated URI template may reference a variable of this name, and it will be substituted with the value of the matched source property.
variableMatchPosition
  `String` Optional. A string that specifies what part of a matching string is used in the variable value when a regular expression was used to match the property.
    `"all"` (default) means the entire property value should be substituted for the variable.
    `"only"` means only the matching part of the property value should be substituted in the URI template.
    `"before"` means the part before the match is substituted in the URI template.
    `"after"` means the part after the match is substituted in the URI template.
replacements
  `ReplacePattern[]` Optional. Specifies an array of replacements that can be used to further modify a variable value used in a URI template. Each ReplacePattern element has the following properties:

- pattern `String` RegExp string giving the pattern to match.
- replacement `String` The string that replaces a match. JavaScript's special replacement patterns can be used here.

### Example 1: targeting a property

Consider a model object like a File returned by the Orion file API. A file located at the path `/MyProject/src/README.md` within an Orion workspace might be represented by an object like this:

    {
      Name: "README.md",
      Parents: [
        {
          ChildrenLocation: "/file/username/MyProject/src/?depth=1",
          Location: "/file/username/MyProject/src/",
          Name: "src"
        },
        {
          ChildrenLocation: "/file/username/MyProject/?depth=1",
          Location: "/file/username/MyProject/",
          Name: "MyProject"
        }
      ]
    }

We can write a Validation Property that matches a File-like object by checking for the presence of the `Parents` property in our source:

    validationProperties: [{
        source: "Parents"
    }]

### Example 2: sub-properties

But suppose we want to match only files (and folders) that are not at the top level? Building on the previous example, we match only objects whose `Parents` property has a child property named `0`; effectively selecting only files with 1 or more parents. (A top-level folder has an empty `Parents` array, which has no "0" property, and hence will not match `Parents:0`.)

    validationProperties: [{
        source: "Parents:0"  // or equivalently "Parents[0]"
    }]

### Example 3: variables

Now suppose we want to generate a link to a web search for the parent folder's name. Again using the ":" child property selector, we target the `Name` field of the parent folder. Using the variableName, we assign the matched value to a URI variable named `ParentFolder`. Finally, our URI template references that variable. At display time, when the URI template is expanded, the parent folder's name will be encoded into the search query.

    validationProperties: [{
        source: "Parents:0:Name",  // or equivalently "Parents[0]:Name"
        variableName: "ParentFolder"
    }],
    uriTemplate: "http://www.example.org/search?q={ParentFolder}"

### Example 4: array indices

Modifying the problem in Example 3, suppose we want to generate a web search for the name of the topmost containing folder of a given item. Here our source expression uses `Parents -1` to select the last element in the Parents array (which is the top-level folder, as Parents are ordered from lowest to highest). Top-level folders themselves always have `Parents.length === 0`, and will not be matched by this source expression.

    validationProperties: [{
        source: "Parents[-1]:Name",
        variableName: "TopFolder"
    }],
    uriTemplate: "http://www.example.org/search?q={TopFolder}"

## URI Templates

A URI template describes a hyperlink to another page. In Orion, URI templates are the format plugins use to provide links that the Orion UI can render. URI templates are preferred over simple strings because they correctly handle certain error-prone encoding rules of URLs, and they can contain variables, which offer an easy method to parameterize the URL.

The variables can refer to page object metadata that a command is being evaluated against, or to a variableName provided in the validation properties, or to certain system-wide variables defined in Orion. Variables are referenced by enclosing the variable name in curly brackets {VariableName} in the template expression. At display time, the Orion UI expands a URI template by substituting values in for its parameters.

The following variables are system-wide variables offered by Orion, independent of the page object or variable names in the validation properties:

OrionHome
  Specifies the hostname for the Orion server instance. This variable can be used by a plugin that is installed in another domain to reference a page location in Orion.

The URI Template syntax is specified by RFC 6570.

### Example

Here's an example of a URI template:

    {+OrionHome}/content/content.html#{+Location}

This template links to a particular page (content.html) in the running Orion instance, and puts the value of the `Location` property in the originating page's object metadata after the hash. By default, parameter values are percent-encoded when the template is expanded. Prefixing the variable name with `+` in the template turns off percent-encoding. (This is required for any variables that we expect to contain raw URL characters like `'/'`, which would otherwise be encoded to `%2F` by the template engine.)

## Content Types

Content types may be used to further validate file-based metadata. For example, if a page link should only be visible when the page is showing HTML or CSS, a content type of `"text/css"` can be used to express this.