Difference between revisions of "Orion/Plugin API Changes/R0.5"

Revision as of 12:47, 11 April 2012

This page describes breaking changes occurring to the Plugin API overall, as well as API changes to service extensions that will break plugins.

Orion Plugin API Changes

We expect breaking changes in the Plugin API (plugin.js) in 0.5. However those changes are not yet implemented in 0.5M1.

Orion Service Extension Changes

Changes to individual service extensions introduced in 0.5 require modification of plugins to run on Orion 0.5. Some older Orion plugins will not function properly without modification on Orion 0.5.

Item validation and URI generation

The way that plugins validate metadata and compose URI's from metadata has changed. These changes affect the following service extensions.

• orion.navigate.command
• orion.edit.command
• orion.page.link
• orion.page.link.related
• orion.navigate.openWith

See bug 370903 for details about the problems solved by these changes.

Using validationProperties

Prior to R0.5, orion.navigate.command and orion.edit.command extensions could specify validationProperties to determine whether item metadata was valid for a particular command implementation. Validation properties were an object whose properties were key/value pairs for validation. The key describes an item property, and the value describes the expected value. The value could be either a non-string value to match against the property value, or a string wildcard pattern to match against property. The string patterns were a combination of a file wildcard format and some regular expression support. For example, these validation properties will match an object which has a property called "Git" with any value and a property called "Directory" whose value is "true".

validationProperties: {"Git":"*", "Directory":"true"}

The new format for validationProperties drops the specialized wildcard patterns and instead uses JavaScript regular expressions to match properties. To allow further evolution of the properties, the validation properties are now objects rather than key value pairs. The equivalent expression in the new format is:

validationProperties: [
  {source: "Git"},
  {source: "Directory", match: true}
]

Note that not specifying a "match" property simply means the property must be present.

Validating with content types

Prior to R0.5, validationProperties were used to match file name extensions. Regular expression patterns can still be used to match against file names, but the recommended way to specify validation against a file type is to use a content type rather than a validation property. The following validation properties were used previously to specify that a file should have a ".css" extension:

validationProperties: {"Name":"*.css"} 

The new format uses the contentType property as follows:

contentType: ["text/css"]

Previously there was no way to specify that a command was valid against either "css" OR "html". This can now be done as follows:

contentType: ["text/css", "text/html"]

Using content types

Plugins can define content types using an id of any format. The default content types registered by Orion now use the MIME type where possible. Plugins that previously specified content types that were intended to reference the platform default content types should change to the new format. For example, the old format for specifying a contentType describing all image formats was:

contentType: ["image.gif", "image.jpeg", "image.ico", "image.png","image.tiff"]});

The new format is:

contentType: ["image/gif", "image/jpeg", "image/ico", "image/png","image/tiff"]});

See bug 374991 for details.