Che extension points
In addition to using API methods and events, each plug-in can bring new components into Che-Theia. These components include visual, such as panels, menus, and others. Other types of components are language servers, debuggers, and others.
The mechanism for adding additional components into Che-Theia is called extension points. An extension point is a section in a Che-Theia plug-in configuration into which the meta-information about a new component is added. This chapter contains the full list of available extension points in Che-Theia.
Syntax-highlighting grammars
This section provides syntax highlight rules for specified file types. To add syntax highlighting into Che-Theia using a plug-in, add a record that describes the new grammar into the contributes.grammars
array of the package.json
file of the plug-in.
"grammars": [
{
"language": "lang", (1)
"scopeName": "text.ext", (2)
"path": "./path/to/lang.tmLanguage.json" (3)
}
]
1 | Specifies the target language for syntax highlighting. |
2 | TextMate scope name and grammar. |
3 | Syntax-highlighting rules. |
See TextMate documentation for more details about syntax-highlighting rules. A full example: xml-language-server-plugin.
Preferences (configuration)
A plug-in can introduce new preferences. These are defined in the "configuration"
sub-object of the "contribution"
object in the package.json
file. A preference is contributed as a JSON schema that describes what is actually contributed and allows users to get support when editing settings in the Preferences Editor.
{
"contributes": {
"configuration": {
"type": "object",
"title": "A plug-in configuration",
"properties": {
"myPlugin.logLevel": {
"type": "string",
"default": "error",
"description": "Plug-in logging level"
}
}
}
}
}
Che-Theia has three scopes of preferences:
-
The default scope consists of values defined in the
"configuration"
sub-section in thepackage.json
file. These are default values of the preferences contributed by the plug-in. -
The global or application-wide scope values can be set in User Preferences. They override the default ones.
-
The workspace scope values, which are applied only when a Che-Theia workspace is opened, override default and global values. They can be set in Workspace Preferences.
A user can obtain preferences using theia.workspace.getConfiguration(section)
. If a section
is defined, only that subset of preferences is returned.
// all preferences contributed by a plug-in
theia.workspace.getConfiguration('myPlugin'); // { "logLevel": "error" }
// or
theia.workspace.getConfiguration().get('myPlugin'); // { "logLevel": "error" }
// or, `logLevel` value:
theia.workspace.getConfiguration().get('myPlugin').get('logLevel'); // "error"
The plug-in API also allows to update preferences:
const pluginPrefs = theia.workspace.getConfiguration('myPlugin');
pluginPrefs.update('logLevel', 'debug', theia.ConfigurationTarget.User);
To get all information about a configuration setting, use the inspect
method. The inspect
method returns an object that consists of default
, global
, and workspace
(if one exists) values of a preference key:
pluginPrefs.inspect('logLevel');
// {
// "key": "myPlugin.logLevel",
// "defaultValue": "error",
// "globalValue": "debug"
// }
View containers
A view container is a container that holds views. In Che-Theia, views are typically in the form of panels. All view containers are divided in three sections: left, bottom, and right. The position of a view container depends on the section to which it belongs. This defines the default position of a view container, which can be changed at runtime by dragging and dropping.
To add a view container into Che-Theia, add the appropriate record into the viewsContainers
object located under the contributes
object in the plug-in package.json
file:
"contributes": {
"viewsContainers": {
"bottom": [
{
"id": "view-container-id", (1)
"title": "The title" (2)
},
{
"id": "another-view-container-id",
"title": "Some title"
}
],
"right": [
{
"id": "view-container-on-the-right-side-id",
"title": "Panel on the right"
}
]
}
}
1 | The identifier of the view container. Used to attach to this view container. |
2 | Text displayed on the panel tab. |
Note that a view container is only useful with views in it. See a full example at tree-view-sample-plugin.
Views
A view is a visual component, designed be placed into a view container.
To add a view into Che-Theia, add an appropriate record into the contributes.views
object of a plug-in package.json
file. Each view is defined by an object with two name:value pairs. Additionally, each view description must be included in an array within the views
object, with array name matching the view-container-id
value:
"viewsContainers": {
"left": [
{
"id": "view-container-id", (1)
"title": "The title" (2)
}
],
},
"views": {
"view-container-id": [
{
"id": "tree-at-left-side",
"name": "A list"
},
{
"id": "widget-at-left-side",
"name": "A widget"
}
]
}
1 | View identifier |
2 | Name of the view, which is displayed as the widget title inside the view container |
Currently, only tree view is supported as a view widget.
For more details, see a full example at tree-view-sample-plugin.
Menus
Plug-ins can add new menu items into Che-Theia through the contributes.menus
object in a plug-in package.json
file. The menus
object consists of menu names and menu items:
"menus": {
"editor/context": [
{
"command": "my.command.id", (1)
"group": "custom.group", (2)
"when": "view == widget-at-left-side && config.namespace.property" (3)
},
{
"command": "core.about"
}
],
"explorer/context": [
{
"command": "other.command.id",
"group": "some.group"
}
]
}
1 | The identifier of the Che-Theia command that is executed when the menu item is used. The handler receives the selected resource as the first argument. |
2 | (optional) The name of the group in the menu to which the command is added. When omitted, the menu item is added to the common group in the specified menu. |
3 | (optional) The condition that defines when this menu item is visible. When omitted, the menu item is always visible. The conditions are the same as in the Visual Studio Code when clause. |
Menus that support extending:
-
explorer/context
-
editor/context
-
editor/title
-
debug/callstack/context
-
view/item/context
A plug-in example that adds menu items: menus-contribution-plugin.
Key bindings
Plug-ins can add new keyboard shortcuts or redefine existing ones. To describe a new shortcut, add a definition in the contributes.keybindings
object of a plug-in package.json
file. Each key bonding is described by three values:
"keybindings": [
{
"key": "ctrl+b", (1)
"command": "ts.compile", (2)
"when": "resourceExtname == .ts" (3)
},
{
"key": "ctrl+f alt+b",
"command": "some.command"
}
]
1 | Defines the key combination for this shortcut. Rules for defining key combinations are the same as for Visual Studio Code. |
2 | The identifier of the command invoked when the shortcut is pressed. |
3 | (optional) The condition that defines when this shortcut is available. When omitted, the shortcut is always available. The condition format is the same as in the Visual Studio Code when clause. |
Note that Ctrl+f Alt+b defines a chord: the command is invoked after pressing both Ctrl+f and Alt+b one after the other.
Debuggers
Plug-ins can add new debuggers by implementing the Debugger Adapter Protocol (DAP) for a specific debugger. The debugger can then register in the contributes.debuggers
debuggers of a plug-in package.json
file.
See the list of debuggers from the official DAP site for reference and examples.
Languages (language servers)
This is an experimental approach, which may change in the future. |
To add a language server into Che-Theia using a plug-in:
-
Describe the server in the
contributes.languages
array in the plug-inpackage.json
file:Example of a language-server definition"languages": [ { "id": "lang", (1) "aliases": [ (2) "Lang", "LANG" ], "extensions": [ (3) ".ext" ], "firstLine": "^#!/.*interpreter", (4) "configuration": "./language-configuration.json" (5) } ]
1 The ID of the language for which the language server is created. 2 Other names for the language. 3 File-name extensions for which this language server is added. 4 Hashbang
(first line) for which this language server is added.5 Path to a JSON file with the language configuration. See: Language configurationn guide. -
Register the language server using the following API call:
theia.languageServer.registerLanguageServerProvider(xLanguageServerInfo);
Where
xLanguageServerInfo
is an object oftheia.LanguageServerInfo
and has to contain the following fields:id
Language ID; it has to be the same as the
id
in the configuration JSON filename
Human-readable name of the language server
globPatterns
File pattern that specifies files for which this language server is added
command
The language server start executable
args
Arguments for the language server start executable
After the command above is invoked, the language server is started.
See a full example at xml-language-server-plugin.
Web view API
A web view API is not a contribution point by definition, but it behaves like one and allows to bring many new features to Che-Theia. Web view API plug-ins can add custom UI, graphical data, or anything that can be displayed in a web page. A web view API provides an HTML iframe
to which a plug-in has access.
To create an instance of web view:
-
Use the
createWebviewPanel
function:const webViewPanel = theia.window.createWebviewPanel('webViewId', 'Title', theia.ViewColumn.One);
-
Add content:
webViewPanel.webview.html ='<html><body><h1>Hello from web view</h1></body></html>';
Web view content is removed when hidden. To restore its state, register a serializer, or set the The current state of a web view can be read from the web view panel object. It is possible to load resources and scripts into a web view and communicate with a plug-in by posting messages. See a full sample plug-in at webview-sample-plugin for more details. |