Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Orion/Documentation/Developer Guide/Plugging into Orion pages
Contents
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.
If source begins with the character "!", it gives a nonexistence match, matching only when no property with the given name is defined on the source object.
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.
match may begin with a !, in which case matches when a property is not present in the target object.
- 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
StringRegExp string giving the pattern to match. - replacement
StringThe 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:
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.)
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.
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.
source: "Parents[-1]:Name",
variableName: "TopFolder"
}],
uriTemplate: "http://www.example.org/search?q={TopFolder}"
Example 5: matching property nonexistence
To create a validationProperties that excludes the workspace root, but matches any other object, we can use the ! prefix in our source expression. The workspace root has a Projects field, which every other file object (regular folders, directories, etc) does not have, so we can simply exclude Projects:
source: "!Projects" // Filter out workspace
}],
URI Templates
A URI template defines a template that can be used to generate hyperlinks. 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 URL-encoding rules, 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 is 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/html", "text/css"] can be used to express this.
orion.page.link
The link service provides a mechanism for plugins to add static links to the Orion navigation menu. Links must be associated to a category.
Service methods
None. This service is purely declarative.
Service attributes
Implementations must provide the following attributes:
- id
- String. A symbolic id for referencing this link.
- category
- String. The category id this link belongs to. The link will be placed within this category when displayed in the Orion UI (most notably in the navigation menu).
- name
- String. A human readable link name, typically used as an HTML anchor element body, or in a tooltip.
- uriTemplate
- String. A URI Template that defines the link. This template may use the standard Orion URI template variables.
The following optional attributes control the link's appearance within its category:
- order
- Boolean, default is 100. Gives this link's ordering relative to other links in the same category. Within the Orion navigation menu, the link with the lowest order is presented as an affordance on the link's category itself.
Examples
The following snippet defines the some of the main links that are shown in a default Orion installation. This snippet assumes that the categories "sites" and "git" have been defined elsewhere.
id: "orion.sites",
name: "Sites",
category: "sites"
order: 10, // Make this the first link in the 'sites' category.
uriTemplate: "{OrionHome}/sites/sites.html"
});
provider.registerServiceProvider("orion.page.link", null, {
id: "orion.repositories",
name: "Git Repositories",
category: "git",
order: 110, // Make this the last link in the 'git' category
uriTemplate: "{OrionHome}/git/git-repository.html#"
});
orion.page.link.category
For historical reasons, the category link is implemented using the page links and related links extensions: each link may be assigned to a category, referencing the category by id. The links are ranked by order property, and the lowest-order link is ultimately applied to the category icon. As of Orion 7.0, the remaining links belonging to the category are not shown in the UI.
Introduced in
Orion 5.0
Service methods
None. This service is purely declarative.
Service attributes
An implementation must provide the following attributes:
- id
- String. A symbolic id for referencing this category.
- imageClass
- String. A CSS class name that provides an image for this category.
- imageDataURI
- String. Provides an image for this category as a Data URI. This is a good alternative to imageClass for situations where the contributing plugin has no control over the page CSS. Exactly one of imageClass or imageDataURI must be provided, but not both.
- name
- String. The human readable name for this category.
- order
- Number, optional. The sort order of this category relative to other categories. This affects the rendering order of categories in the navigation menu, with lower order rendered first. If order is not provided, the category appears after all ordered categories. The ordering of multiple categories with no order property is indeterminate.
Examples
The following (simplified) snippet defines 2 of the categories that appear in a default Orion installation: "edit" and "shell".
provider.registerServiceProvider("orion.page.link.category", null, {
id: "category-edit",
name: "Editor",
imageClass: "core-sprite-edit",
order: 10 // Make the edit category appear first in the Orion navigation menu.
});
provider.registerService("orion.page.link.category", null, {
id: "category-git",
name: "Git",
imageClass: "core-sprite-repository",
order: 20 // Make the git category appear second in the Orion navigation menu.
});
// To make our category icons actually appear in the navigation menu, we must assign at least 1 link to each category.
// Here we use static links (orion.page.link) but dynamic ones (orion.page.link.related) would also work.
provider.registerServiceProvider("orion.page.link", null, {
id: "edit-link",
category: "category-edit" // !
name: "Edit",
uriTemplate: "+{OrionHome}/edit/edit.html"
});
provider.registerServiceProvider("orion.page.link", null, {
id: "git-link",
category: "category-git" // !
name: "Git Repository",
uriTemplate: "+{OrionHome}/git/git-repository.html"
});
The "related link" service provides a mechanism for plugins to contribute links to the Orion navigation menu whenever the active model object of the page (for example, the file being edited, or the folder being browsed) meets certain criteria.
The basic shape of a related link extension is identical to a page link, but with the addition of attributes validationProperties and contentType, which determine what model objects the link applies to.
A related link's URITemplate is more powerful than a normal page link's, as it can generate URIs that refer to fields of the active model object. For example, a related link for a folder could generate a "Git Log" related link specific to the folder by referencing the folder's Location field as a variable.
A related link can also be spawned from an existing navigator command extension, allowing code reuse.
Service methods
None. This service is purely declarative.
Service attributes
Implementations must provide the attributes for a basic page link. The following additional attributes can also be provided:
- contentType
- String[], optional. An array of Content Type IDs for which this link is applicable.
- validationProperties
- ValidationProperty[], optional. An array of Validation Properties describing whether the link applies to a particular object, and optionally declaring variables and replacements to be used in the URI template.
Using a command as a link
A command contributed to the orion.navigate.command extension can be reused as a related link if the command is declarative (that is, if it provides a uriTemplate rather than a run() function).
To reuse a command as a link, simply create an orion.page.link.related extension with the following attributes. Other attributes are obtained from the command.
- id
- String. This references the id of the orion.navigate.command extension that this link wants to use.
- name
- String. The name of the link.
Examples
The following related page link will determine if the current page's target has a GitUrl that conforms to the URL of git repositories hosted at github.com. If so, then the GitUrl is transformed by replacing ":" with "/", and removing the suffix ".git". The transformed URL is assigned to a variable named GitHubLocation, which is then referenced in the uriTemplate to generate the associated GitHub URL for the repository.
id: "orion.git.gotoGithub",
category: "git",
name: "Show in GitHub",
validationProperties: [{
source: "GitUrl",
match: "github\.com.*\.git",
variableName: "GitHubLocation",
variableMatchPosition: "only",
replacements: [{pattern: ":", replacement: "/"}, {pattern: ".git$", replacement: ""}]
}],
uriTemplate: "https://{GitHubLocation}"
});
orion.core.linkScanner
Link scanners are declarative services that specify patterns of text to replace with link anchors. Scanners contribute a regular expression pattern to match in the source text. They then provide a link to be inserted for each match. These scanners are used by the text link service to convert text into a DOM node with appropriate anchor and text nodes as children.
Service methods
None.
Service attributes
Implementations of orion.core.linkScanner must define the following attributes:
- pattern
- A regular expression string to locate links in the source text
- words
- A Number identifying the number of white-space delimited words in each match
- anchor
- A template of the URL for each match. The template may contain variables of the form %1, %2, etc, which are substituted by each of the words in the match.
Examples
The following scanner will replace text of the form "bug 123456" with links of the form "https://bugs.eclipse.org/123456
var serviceImpl = {};
var serviceProperties = {
pattern: "bug\\s\\d{4,7}",
words: 2,
anchor: "https://bugs.eclipse.org/%2"
};
provider.registerServiceProvider("orion.core.linkScanner", serviceImpl, serviceProperties);
provider.connect();
This scanner will replace email addresses with mailto: URLs:
var serviceImpl = {};
var serviceProperties = {
pattern: "\\b[A-Z0-9._%-]+@[A-Z0-9.-]+\\.[A-Z]{2,4}\\b",
words: 1,
anchor: "mailto:%1"
};
provider.registerServiceProvider("orion.core.linkScanner", serviceImpl, serviceProperties);
provider.connect();
orion.core.content
The orion.core.content service is used to define files that can be imported into a user's project folder. The service describes a contentURITemplate that can be imported into a folder. If the content is a zip file, it can be unzipped into the folder. If the content is to be generated by simply linking to another page, a uriTemplate can be used to specify the link instead of a contentURITemplate.
The user interface for this feature is not specified. The ability to generate content into a project may appear in multiple places.
Service methods
None. This service is purely declarative.
Service attributes
Implementations of orion.core.content may define the following attributes:
- name
- The user visible name of the content
- id
- The extension point id.
- description
- The user visible description which explains what the content contains.
- uriTemplate
- Optional. A URI Template that defines a link to another page that can generate the content. If this property is specified, then the contentURIProperty property will be ignored.
- contentURITemplate
- Optional. A URI Template that defines a link to content that should be imported into a project.
Example
Here is a sample plug-in that defines a content zip file that is colocated with the Orion plugin.
var temp = document.createElement('a');
temp.href = "testContent.zip";
provider.registerService("orion.core.content", null, {
id: "orion.content.test",
name: "Another Exemplary Sample Site",
description: "Generate a sample site from Susan's test plugin.",
contentURITemplate: temp.href
});
provider.connect();
When this plug-in is installed, the user will be offered "Another Exemplary Sample Site" as possible content for a project.