Difference between revisions of "Orion/Documentation/Developer Guide/Plugging into Orion pages"

From Eclipsepedia

Jump to: navigation, search
(Service methods)
(orion.page.link.related)
(34 intermediate revisions by 4 users not shown)
Line 6: Line 6:
  
 
== Validation Properties ==
 
== Validation Properties ==
Validation properties describe the properties of a page object that should be analyzed to determine whether a particular service applies to the page. They can optionally store information from page objects into variables that can be referenced in a URI template. Linking services generally specify one or more of these properties in an array.  The general format of an individual validation property is as follows:
+
''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
 
;source
:<tt>String</tt> The name of a property to look for in the target object.  The ":" character represents nested properties, and the "|" character represents OR'ed properties. For example, the source <tt>Location</tt> specifies that the page object must have a "Location" property, such as <tt>myObject.Location</tt>. The source <tt>Git:ContentLocation</tt> specifies that the page object must have a sub-object and property such as <tt>myObject.Git.ContentLocation</tt>. The source <tt>ChildrenLocation|ContentLocation</tt> means that the page object must have either a property such as <tt>myObject.ChildrenLocation</tt> or a property such as <tt>myObject.ContentLocation</tt>. The first property found will be used.
+
:<tt>String</tt> 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 <tt>Location</tt> specifies that the page object must have a "Location" property, such as <tt>myObject.Location</tt>.
 +
::The source <tt>Git:ContentLocation</tt> specifies that the page object must have a sub-object and property such as <tt>myObject.Git.ContentLocation</tt>.
 +
::The source <tt>ChildrenLocation|ContentLocation</tt> means that the page object must have either a property such as <tt>myObject.ChildrenLocation</tt> or a property such as <tt>myObject.ContentLocation</tt>. The first property found will be used.
 +
::Elements of an array can be referred to by ":n" or "[n]". For example, the source <tt>Children[0]</tt> 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 <tt>length - n</tt>. For example, <tt>Children[-1]</tt> refers to the last element of the Children array.
 
;match
 
;match
:<tt>Object</tt> A value used to validate the source property. In general, the value of the page object's property will be compared against this value. However, if this value is a string, the string is assumed to specify a regular expression that will be passed to the RegExp constructor.
+
:<tt>String|Object</tt> ''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.<p>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 <tt>RegExp</tt> constructor, and executed against the source value.</p>
 
;variableName
 
;variableName
:<tt>String</tt> Optional. The name of a variable that represents the value of the source property. If specified, then an associated URI template may use a variable of this name, and it will contain the value of the matched source property.
+
:<tt>String</tt> ''Optional.'' The name of a variable that the value of the '''source''' property will be bound to. If provided, then an associated [[#URI Templates|URI template]] may reference a variable of this name, and it will be substituted with the value of the matched '''source''' property.
 
;variableMatchPosition
 
;variableMatchPosition
:<tt>String</tt> 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.  <tt>"all"</tt> (default) means the entire property value should be substituted for the variable.  <tt>only</tt> means only the matching part of the property value should be substituted in the URI template.  <tt>before</tt> means the part before the match is substituted in the URI template. <tt>after</tt> means the part after the match is substituted in the URI template.
+
:<tt>String</tt> ''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.   
 +
:: <tt>"all"</tt> (default) means the entire property value should be substituted for the variable.   
 +
:: <tt>"only"</tt> means only the matching part of the property value should be substituted in the URI template.   
 +
:: <tt>"before"</tt> means the part before the match is substituted in the URI template.  
 +
:: <tt>"after"</tt> means the part after the match is substituted in the URI template.
 
;replacements
 
;replacements
:<tt>Array</tt> Optional. Specifies an array of replacements (pattern and replace strings) that can be used to further modify a variable value used in a URI template.
+
:<tt>ReplacePattern[]</tt> ''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''' <code>String</code> RegExp string giving the pattern to match.
 +
* '''replacement''' <code>String</code> The string that replaces a match. JavaScript's special [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter replacement patterns] can be used here.
 +
 
 +
=== Example 1: targeting a property ===
 +
Consider a model object like a [[Orion/Server API|File]] returned by the Orion file API. A file located at the path <tt>/MyProject/src/README.md</tt> within an Orion workspace might be represented by an object like this:
 +
<source lang="javascript" enclose="div">
 +
{
 +
  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"
 +
    }
 +
  ]
 +
}
 +
</source>
 +
 
 +
We can write a Validation Property that matches a File-like object by checking for the presence of the <tt>Parents</tt> property in our '''source''':
 +
<source lang="javascript" enclose="div">
 +
validationProperties: [{
 +
    source: "Parents"
 +
}]
 +
</source>
 +
 
 +
=== 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 <tt>Parents</tt> property has a child property named <tt>0</tt>; effectively selecting only files with 1 or more parents. (A top-level folder has an empty <tt>Parents</tt> array, which has no "0" property, and hence will not match <tt>Parents:0</tt>.)
 +
<source lang="javascript" enclose="div">
 +
validationProperties: [{
 +
    source: "Parents:0"  // or equivalently "Parents[0]"
 +
}]
 +
</source>
 +
 
 +
=== 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 <tt>Name</tt> field of the parent folder. Using the '''variableName''', we assign the matched value to a URI variable named <tt>ParentFolder</tt>. 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 lang="javascript" enclose="div">
 +
validationProperties: [{
 +
    source: "Parents:0:Name",  // or equivalently "Parents[0]:Name"
 +
    variableName: "ParentFolder"
 +
}],
 +
uriTemplate: "http://www.example.org/search?q={ParentFolder}"
 +
</source>
 +
 
 +
=== 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 <tt>Parents[-1]</tt> 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 <tt>Parents.length === 0</tt>, and will not be matched by this source expression.
 +
 
 +
<source lang="javascript" enclose="div">
 +
validationProperties: [{
 +
    source: "Parents[-1]:Name",
 +
    variableName: "TopFolder"
 +
}],
 +
uriTemplate: "http://www.example.org/search?q={TopFolder}"
 +
</source>
  
 
== URI Templates ==
 
== URI Templates ==
URI templates describe the link to another page. Variables in the URI template can refer to the page object metadata, to variables named in the validation properties, or to special variables defined in Orion. Variables are referenced using curly brackets. The following variables are system wide variables (independent of the page object or variable names in the validation properties).
+
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 [[#The ValidationProperty Object|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
 
;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.
 
: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.
  
For example, the URI template <tt>{OrionHome}/content/content.html#{Location}</tt> links to a particular page (content.html) in the running Orion instance, and includes the value of the <tt>Location</tt> property in the originating page's object metadata after the hash.
+
The URI Template syntax is specified by [http://tools.ietf.org/html/rfc6570 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 <tt>Location</tt> property in the originating page's object metadata after the hash. By default, parameter values are [http://en.wikipedia.org/wiki/Percent-encoding percent-encoded] when the template is expanded. Prefixing the variable name with <code>+</code> in the template turns off percent-encoding. (This is required for any variables that we expect to contain raw URL characters like <code>'/'</code>, which would otherwise be encoded to <code>%2F</code> by the template engine.)
  
 
== Content Types ==
 
== 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 <tt>[text/html, text/css]</tt>can be used to express this.
+
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 <tt>["text/html", "text/css"]</tt> can be used to express this.
  
 
= orion.page.content =
 
= orion.page.content =
Line 46: Line 127:
 
;uriTemplate
 
;uriTemplate
 
:a [[Orion/Documentation/Developer Guide/Plugging into Orion pages#URI Templates|URI Template]] that defines the href for the iframe content.  When content is opened, it might be targeted against a particular file or folder.  In this case, the template variables can refer to file or folder metadata from the target file.  In addition to the standard variables used in Orion and the file/folder metadata, some special variables are used:
 
:a [[Orion/Documentation/Developer Guide/Plugging into Orion pages#URI Templates|URI Template]] that defines the href for the iframe content.  When content is opened, it might be targeted against a particular file or folder.  In this case, the template variables can refer to file or folder metadata from the target file.  In addition to the standard variables used in Orion and the file/folder metadata, some special variables are used:
* <tt>{SaveURL}</tt> refers to a URL that can be used to save content back to Orion.
+
:: <tt>SaveURL</tt> refers to a URL that can be used to save content back to Orion.
* <tt>{ExitURL}</tt> refers to a URL that can be used if the user chooses to exit the embedded application.   
+
:: <tt>ExitURL</tt> refers to a URL that can be used if the user chooses to exit the embedded application.   
 
;saveToken
 
;saveToken
 
:Optional.  An Array of objects describing token(s) that appear in the URL of the page that saves the content.  The saveToken is used to find the location of any content stored by the plugin.
 
:Optional.  An Array of objects describing token(s) that appear in the URL of the page that saves the content.  The saveToken is used to find the location of any content stored by the plugin.
Line 54: Line 135:
  
 
The following snippet defines an orion.page.content extension for showing the Pixlr image editor inside Orion.
 
The following snippet defines an orion.page.content extension for showing the Pixlr image editor inside Orion.
 
+
<source lang="javascript" enclose="div">
 
   provider.registerServiceProvider("orion.page.content", {}, {
 
   provider.registerServiceProvider("orion.page.content", {}, {
 
       id: "orion.pixlr.content",
 
       id: "orion.pixlr.content",
 
       name: "Pixlr",
 
       name: "Pixlr",
 
       saveToken: [{token: "imgapi?image=", terminator: "&"},
 
       saveToken: [{token: "imgapi?image=", terminator: "&"},
       uriTemplate: "http://pixlr.com/editor/?image={OrionHome}{Location}&referrer=Orion&title={Name}&locktype=true&exit={ExitURL}&target={SaveURL}imgapi&locktitle=true,contentProvider=orion.pixlr.content"});
+
       uriTemplate: "http://pixlr.com/editor/?image={+OrionHome}{+Location}&referrer=Orion&title={Name}&locktype=true&exit={+ExitURL}&target={+SaveURL}imgapi&locktitle=true,contentProvider=orion.pixlr.content"});
 
+
</source>
The URL to open this page is <tt>/content/content.html#{Location},contentProvider=orion.pixlr.content</tt>
+
The URL to open this page is <tt>/content/content.html#{+Location},contentProvider=orion.pixlr.content</tt>
  
 
If the page content requires a resource location (for example, it is an editor), then typically the page would be linked using the orion editor extension point.  This ensures that the page were opened with a specified location parameter in the URL.  The pixlr plugin contributes an editor in this way.
 
If the page content requires a resource location (for example, it is an editor), then typically the page would be linked using the orion editor extension point.  This ensures that the page were opened with a specified location parameter in the URL.  The pixlr plugin contributes an editor in this way.
 
+
<source lang="javascript" enclose="div">
 
   provider.registerServiceProvider("orion.edit.editor", {}, {
 
   provider.registerServiceProvider("orion.edit.editor", {}, {
 
       id: "orion.pixlr",
 
       id: "orion.pixlr",
 
       name: "Pixlr Image Editor",
 
       name: "Pixlr Image Editor",
       uriTemplate: "{OrionHome}/content/content.html#{Location},contentProvider=orion.pixlr.content"});
+
       uriTemplate: "{+OrionHome}/content/content.html#{+Location},contentProvider=orion.pixlr.content"});
 
+
</source>
 
The corresponding "open with" extension point is
 
The corresponding "open with" extension point is
 
+
<source lang="javascript" enclose="div">
 
   provider.registerServiceProvider("orion.navigate.openWith", {}, {
 
   provider.registerServiceProvider("orion.navigate.openWith", {}, {
 
       editor: "orion.pixlr",
 
       editor: "orion.pixlr",
 
       contentType: ["image/gif", "image/jpeg", "image/ico", "image/png","image/tiff"]});
 
       contentType: ["image/gif", "image/jpeg", "image/ico", "image/png","image/tiff"]});
 +
</source>
 +
  
 
= orion.page.link =
 
= 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 [[#orion.page.link.category | category]].
The link service provides a mechanism for plugins to add links that should appear in the main header of Orion pages. Clients supply the link name and URL. The header code will look for implementers of this service when generating page headers for Orion.
+
  
 
== Service methods ==
 
== Service methods ==
Line 84: Line 166:
  
 
== Service attributes ==
 
== Service attributes ==
Implementations of <tt>orion.page.link</tt> must define the following attributes:
+
Implementations must provide the following attributes:
  
;name
+
; id
:A human readable link name, typically used as an HTML anchor element body, or in a tooltip.
+
: <tt>String</tt>. A symbolic id for referencing this link.
;id
+
; category
:A symbolic id for referencing this link.
+
: <tt>String</tt>. The [[#orion.page.link.category | category id]] this link belongs to. The link will be placed within this category in the Orion navigation menu.
;uriTemplate
+
; name
:A [[Orion/Documentation/Developer Guide/Plugging into Orion pages#URI Templates|URI Template]]
+
: <tt>String</tt>. A human readable link name, typically used as an HTML anchor element body, or in a tooltip.
that defines the link. This template may use the standard Orion URI template variables.
+
; uriTemplate
 +
: <tt>String</tt>. A [[Orion/Documentation/Developer Guide/Plugging into Orion pages#URI Templates|URI Template]] that defines the link. This template may use the standard Orion URI template variables.
  
== Examples ==
+
The following optional attributes control the link's appearance within its category:
  
The following snippet defines the some of the main links that are shown in a default Orion installation.
+
; default
 +
: <tt>Boolean</tt>, default is <tt>false</tt>. If <tt>true</tt>, this link serves as a fallback and will be rendered when there are no other valid links in the category. This avoids having an empty category. This flag is useful for defining "top-level" page links like Orion's Search, Repositories, and Sites.
 +
; force
 +
: <tt>Boolean</tt>, default is <tt>false</tt>. Forces this link to always be shown. Normally Orion hides links when they appear to link back to the current page (as determined by <tt>window.location</tt>), and when the link provides the <tt>default</tt> flag. The <tt>force</tt> flag prevents the link from being hidden in these cases.
 +
; order
 +
: <tt>Boolean</tt>, default is <tt>100</tt>. Gives this link's ordering relative to other links in the same category. Links with lower <tt>order</tt> come first. On some platforms, Orion may present the link with the lowest <tt>order</tt> as an affordance on the category itself.
  
  var serviceImpl = {};//no service methods required
+
To enable translation, the following attributes may be provided instead of <tt>name</tt>:
  provider.registerServiceProvider("orion.page.link", serviceImpl, {
+
 
      name: "Navigator",
+
;nameKey
      id: "orion.navigator",
+
: <tt>String</tt>. The key used to look up the translated, human readable link name within the message bundle.
      uriTemplate: "{OrionHome}/navigate/table.html#"
+
;nls
  });
+
: <tt>String</tt>. Gives the message bundle path to be used for translating this link name.
   provider.registerServiceProvider("orion.page.link", serviceImpl, {
+
 
 +
== 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.
 +
<source lang="javascript" enclose="div">
 +
   provider.registerServiceProvider("orion.page.link", null, {
 +
      id: "orion.sites",
 
       name: "Sites",
 
       name: "Sites",
       id: "orion.sites",
+
       order: 10,     // Sort the
 
       uriTemplate: "{OrionHome}/sites/sites.html"
 
       uriTemplate: "{OrionHome}/sites/sites.html"
 
   });
 
   });
   provider.registerServiceProvider("orion.page.link", serviceImpl, {
+
   provider.registerServiceProvider("orion.page.link", null, {
      name: "Repositories",
+
 
       id: "orion.repositories",
 
       id: "orion.repositories",
 +
      default: true, // Use the Git Repositories link as a fallback when the 'git' category would otherwise be empty.
 +
      force: true,  // Show the Git Repositories link all the time.
 +
      order: 110,    // Sort the Git Repositories link below other links in the 'git' category.
 +
      name: "Git Repositories",
 
       uriTemplate: "{OrionHome}/git/git-repository.html#"
 
       uriTemplate: "{OrionHome}/git/git-repository.html#"
 
   });
 
   });
 +
</source>
  
= orion.page.link.related =  
+
= orion.page.link.category =
 +
The category service allows [[#orion.page.link | page links]] and [[#orion.page.link.related | related links]] to be categorized. Each category appears as an icon in Orion's navigation menu. When the user activates the category, the links within the category are shown.
  
The related link service provides a mechanism for plugins to contribute links to the "Related pages" menu in the Orion page header. Clients can specify when the link is applicable using <tt>validationProperties</tt> and <tt>contentType</tt>.
+
As of Orion 5.0, the default installation defines the following categories: "edit", "git", "search", "shell", "sites". Plugins may contribute to the default categories, or define additional categories.
 +
 
 +
== Introduced in ==
 +
Orion 5.0
  
 
== Service methods ==
 
== Service methods ==
Line 123: Line 224:
  
 
== Service attributes ==
 
== Service attributes ==
Implementations of <tt>orion.page.link.related</tt> must define the following attributes:
+
An implementation must provide the following attributes:
  
 
;id
 
;id
:A symbolic id for referencing this link.
+
: <tt>String</tt>. A symbolic id for referencing this category.
 +
;imageClass
 +
: <tt>String</tt>. A CSS class name that provides an image for this category.
 
;name
 
;name
:A human readable link name, used in the "Related pages" menu.
+
: <tt>String</tt>. The human readable name for this category.
; tooltip
+
;order
:A tooltip used to describe the link.
+
: <tt>Number</tt>, ''optional''. The sort order of this category relative to other categories. If <tt>order</tt> is not provided, the category appears after all ordered categories. The ordering of multiple categories with no <tt>order</tt> property is indeterminate.
;uriTemplate
+
 
:A [[Orion/Documentation/Developer Guide/Plugging into Orion pages#URI Templates|URI Template]]
+
To enable translation, the following attributes may be provided instead of <tt>name</tt>:
that defines the link. This template may use page object metadata, declared variable names, or standard Orion URI template variables.
+
;nameKey
 +
: <tt>String</tt>. The key used to look up the translated, human readable name of this category within the message bundle.
 +
;nls
 +
: <tt>String</tt>. Gives the message bundle path to be used for translating this category's name.
 +
 
 +
== Examples ==
 +
The following snippet defines 2 of the categories that appear in a default Orion installation: "edit" and "shell".  
 +
<source lang="javascript" enclose="div">
 +
  provider.registerServiceProvider("orion.page.link", null, {
 +
      id: "edit",
 +
      nameKey: "Editor",
 +
      nls: "orion/nls/messages",
 +
      imageClass: "core-sprite-edit",
 +
      order: 10
 +
  });
 +
  provider.registerService("orion.page.link.category", null, {
 +
      id: "git",
 +
      nameKey: "Git",
 +
      nls: "git/nls/gitmessages",
 +
      imageClass: "core-sprite-repository",
 +
      order: 20
 +
  });
 +
</source>
 +
 
 +
= orion.page.link.related =
 +
The "related link" service provides a mechanism for plugins to contribute links to the Orion navigation menu when on the active 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 is identical to a [[#orion.page.link | page link]], but with the addition of attributes <tt>validationProperties</tt> and <tt>contentType</tt>, which determine when the link applies.
 +
 
 +
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 <tt>Location</tt> field as a variable.
 +
 
 +
A related link can also be spawned from an existing [[Orion/Documentation/Developer Guide/Plugging into the navigator#orion.navigate.command | navigator command]], allowing code reuse.
 +
 
 +
== Service methods ==
 +
None. This service is purely declarative.
 +
 
 +
== Service attributes ==
 +
Implementations must provide the [[#Service_attributes_2 | attributes for a basic page link]]. The following additional attributes must also be provided:
 +
 
 
;contentType
 
;contentType
:Optional. An array of [[Orion/Documentation/Developer Guide/Plugging into the navigator#orion.core.contenttype|Content Type IDs]] for which this link is applicable.
+
: <tt>String[]</tt>, ''optional''. An array of [[Orion/Documentation/Developer Guide/Plugging into the navigator#orion.core.contenttype|Content Type IDs]] for which this link is applicable.
 
;validationProperties
 
;validationProperties
:Optional. An array of [[Orion/Documentation/Developer Guide/Plugging into Orion pages#Validation Properties|Validation Properties]] describing whether the link is applicable, and optionally declaring variables to be used in the URI template.
+
: <tt>ValidationProperty[]</tt>, ''optional''. An array of [[Orion/Documentation/Developer Guide/Plugging into Orion pages#Validation Properties|Validation Properties]] describing whether the link applies to a particular object, and optionally declaring variables and replacements to be used in the URI template.
  
== Examples ==
+
=== Using a command as a link ===
 +
A command contributed to the [[Orion/Documentation/Developer Guide/Plugging into the navigator#orion.navigate.command | 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 <tt>run()</tt> function).
  
The following related page link will determine if the current page's target has a <tt>GitUrl</tt> that conforms to the URL of git repositories hosted at github.com.  If so, then parts of the URL are assigned to variables that are used to build the associated github URL.
+
To reuse a command as a link, simply create a  
 +
with these attributes. Other attributes are obtained from the command.
  
 +
; id
 +
: <tt>String</tt>. This references the <tt>id</tt> of the orion.navigate.command extension that this link wants to use.
 +
; name
 +
: <tt>String</tt>. The name of the link. Alternatively, the <tt>nameKey</tt> and <tt>nls</tt> attributes may be provided to enable translation.
 +
 +
== Examples ==
 +
The following related page link will determine if the current page's target has a <tt>GitUrl</tt> that conforms to the URL of git repositories hosted at github.com. If so, then parts of the URL are assigned to variables that are used to build the associated github URL.
 +
<source lang="javascript" enclose="div">
 
  provider.registerServiceProvider("orion.page.link.related", null, {
 
  provider.registerServiceProvider("orion.page.link.related", null, {
 
     id: "orion.git.gotoGithub",
 
     id: "orion.git.gotoGithub",
 +
    category: "git",
 
     name: "Show in GitHub",
 
     name: "Show in GitHub",
    tooltip: "Show this repository at GitHub",
 
 
     validationProperties: [{
 
     validationProperties: [{
 
       source: "GitUrl",  
 
       source: "GitUrl",  
Line 156: Line 307:
 
     uriTemplate: "https://{GitHubLocation}"
 
     uriTemplate: "https://{GitHubLocation}"
 
  });
 
  });
+
</source>
If the service extension does not describe a name, tooltip, and uriTemplate, the implementation will look for a command extension of the same id.  In this way, commands added to the navigator that link to other pages may be considered for the Related pages menu.
+
  
 
= orion.core.linkScanner =
 
= orion.core.linkScanner =
Line 179: Line 329:
  
 
The following scanner will replace text of the form "bug 123456" with links of the form "https://bugs.eclipse.org/123456
 
The following scanner will replace text of the form "bug 123456" with links of the form "https://bugs.eclipse.org/123456
 
+
<source lang="javascript" enclose="div">
 
  var provider = new eclipse.PluginProvider();
 
  var provider = new eclipse.PluginProvider();
 
  var serviceImpl = {};
 
  var serviceImpl = {};
Line 189: Line 339:
 
  provider.registerServiceProvider("orion.core.linkScanner", serviceImpl, serviceProperties);
 
  provider.registerServiceProvider("orion.core.linkScanner", serviceImpl, serviceProperties);
 
  provider.connect();
 
  provider.connect();
 +
</source>
  
 
This scanner will replace email addresses with mailto: URLs:
 
This scanner will replace email addresses with mailto: URLs:
  
 +
<source lang="javascript" enclose="div">
 
  var provider = new eclipse.PluginProvider();
 
  var provider = new eclipse.PluginProvider();
 
  var serviceImpl = {};
 
  var serviceImpl = {};
Line 201: Line 353:
 
  provider.registerServiceProvider("orion.core.linkScanner", serviceImpl, serviceProperties);
 
  provider.registerServiceProvider("orion.core.linkScanner", serviceImpl, serviceProperties);
 
  provider.connect();
 
  provider.connect();
 +
</source>
 +
= orion.core.content =
 +
 +
The <tt>orion.core.content</tt> service is used to define files that can be imported into a user's project folder.  The service describes a <tt>contentURITemplate</tt> 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 <tt>uriTemplate</tt> can be used to specify the link instead of a <tt>contentURITemplate</tt>.
 +
 +
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 <tt>orion.core.content</tt> 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 [[Orion/Documentation/Developer Guide/Plugging into Orion pages#URI Templates|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 [[Orion/Documentation/Developer Guide/Plugging into Orion pages#URI Templates|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.
 +
<source lang="javascript" enclose="div">
 +
var provider = new orion.PluginProvider();
 +
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();
 +
</source>
 +
 +
When this plug-in is installed, the user will be offered "Another Exemplary Sample Site" as possible content for a project.
 +
 +
[[Category:Orion]]

Revision as of 16:32, 14 March 2014

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. 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/html", "text/css"] can be used to express this.

orion.page.content

Plugins can contribute page content for a page that is framed by the common Orion banner and equipped with standard Orion page services, such as the related pages menu. The page content itself is rendered in an iframe inside the page. Pages contributed in this way are opened in a URL that specifies the id of the extension.

Service methods

None. This service is purely declarative.

Service attributes

Implementations of orion.page.content must define the following attributes:

name
The name of the content, which is shown as the page title in the Orion banner.
id
A symbolic id for referencing this extension point.
uriTemplate
a URI Template that defines the href for the iframe content. When content is opened, it might be targeted against a particular file or folder. In this case, the template variables can refer to file or folder metadata from the target file. In addition to the standard variables used in Orion and the file/folder metadata, some special variables are used:
SaveURL refers to a URL that can be used to save content back to Orion.
ExitURL refers to a URL that can be used if the user chooses to exit the embedded application.
saveToken
Optional. An Array of objects describing token(s) that appear in the URL of the page that saves the content. The saveToken is used to find the location of any content stored by the plugin.

Examples

The following snippet defines an orion.page.content extension for showing the Pixlr image editor inside Orion.

   provider.registerServiceProvider("orion.page.content", {}, {
      id: "orion.pixlr.content",
      name: "Pixlr",
      saveToken: [{token: "imgapi?image=", terminator: "&"},
      uriTemplate: "http://pixlr.com/editor/?image={+OrionHome}{+Location}&referrer=Orion&title={Name}&locktype=true&exit={+ExitURL}&target={+SaveURL}imgapi&locktitle=true,contentProvider=orion.pixlr.content"});

The URL to open this page is /content/content.html#{+Location},contentProvider=orion.pixlr.content

If the page content requires a resource location (for example, it is an editor), then typically the page would be linked using the orion editor extension point. This ensures that the page were opened with a specified location parameter in the URL. The pixlr plugin contributes an editor in this way.

   provider.registerServiceProvider("orion.edit.editor", {}, {
      id: "orion.pixlr",
      name: "Pixlr Image Editor",
      uriTemplate: "{+OrionHome}/content/content.html#{+Location},contentProvider=orion.pixlr.content"});

The corresponding "open with" extension point is

   provider.registerServiceProvider("orion.navigate.openWith", {}, {
      editor: "orion.pixlr",
      contentType: ["image/gif", "image/jpeg", "image/ico", "image/png","image/tiff"]});


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 in the Orion 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:

default
Boolean, default is false. If true, this link serves as a fallback and will be rendered when there are no other valid links in the category. This avoids having an empty category. This flag is useful for defining "top-level" page links like Orion's Search, Repositories, and Sites.
force
Boolean, default is false. Forces this link to always be shown. Normally Orion hides links when they appear to link back to the current page (as determined by window.location), and when the link provides the default flag. The force flag prevents the link from being hidden in these cases.
order
Boolean, default is 100. Gives this link's ordering relative to other links in the same category. Links with lower order come first. On some platforms, Orion may present the link with the lowest order as an affordance on the category itself.

To enable translation, the following attributes may be provided instead of name:

nameKey
String. The key used to look up the translated, human readable link name within the message bundle.
nls
String. Gives the message bundle path to be used for translating this link name.

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.

   provider.registerServiceProvider("orion.page.link", null, {
      id: "orion.sites",
      name: "Sites",
      order: 10,     // Sort the
      uriTemplate: "{OrionHome}/sites/sites.html"
   });
   provider.registerServiceProvider("orion.page.link", null, {
      id: "orion.repositories",
      default: true, // Use the Git Repositories link as a fallback when the 'git' category would otherwise be empty.
      force: true,   // Show the Git Repositories link all the time.
      order: 110,    // Sort the Git Repositories link below other links in the 'git' category.
      name: "Git Repositories",
      uriTemplate: "{OrionHome}/git/git-repository.html#"
   });

orion.page.link.category

The category service allows page links and related links to be categorized. Each category appears as an icon in Orion's navigation menu. When the user activates the category, the links within the category are shown.

As of Orion 5.0, the default installation defines the following categories: "edit", "git", "search", "shell", "sites". Plugins may contribute to the default categories, or define additional categories.

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.
name
String. The human readable name for this category.
order
Number, optional. The sort order of this category relative to other categories. If order is not provided, the category appears after all ordered categories. The ordering of multiple categories with no order property is indeterminate.

To enable translation, the following attributes may be provided instead of name:

nameKey
String. The key used to look up the translated, human readable name of this category within the message bundle.
nls
String. Gives the message bundle path to be used for translating this category's name.

Examples

The following snippet defines 2 of the categories that appear in a default Orion installation: "edit" and "shell".

   provider.registerServiceProvider("orion.page.link", null, {
      id: "edit",
      nameKey: "Editor",
      nls: "orion/nls/messages",
      imageClass: "core-sprite-edit",
      order: 10
   });
   provider.registerService("orion.page.link.category", null, {
      id: "git",
      nameKey: "Git",
      nls: "git/nls/gitmessages",
      imageClass: "core-sprite-repository",
      order: 20
   });

orion.page.link.related

The "related link" service provides a mechanism for plugins to contribute links to the Orion navigation menu when on the active 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 is identical to a page link, but with the addition of attributes validationProperties and contentType, which determine when the link applies.

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, 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 must 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 a with these 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. Alternatively, the nameKey and nls attributes may be provided to enable translation.

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 parts of the URL are assigned to variables that are used to build the associated github URL.

 provider.registerServiceProvider("orion.page.link.related", null, {
    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 provider = new eclipse.PluginProvider();
 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 provider = new eclipse.PluginProvider();
 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 provider = new orion.PluginProvider();
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.