Want to stay updated? You can also follow this RSS feed.
Want to stay updated? You can also follow this RSS feed.
\n{ new Date(post.pubDate).toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }) }
\n{ formatSummary(post.summary) }
\n Origin: { post.link }\n \n )\n })\n }\n
This section describes the overall architecture of the Theia Platform.
-Theia is designed to work as a native desktop application as well as in the -context of a browser and a remote server. To support both situations with a -single source, Theia runs in two separate processes. Those processes are called -frontend and backend respectively, and they communicate through JSON-RPC -messages over WebSockets or REST APIs over HTTP. In the case of Electron, the -backend, as well as the frontend, run locally, while in a remote context the -backend would run on a remote host.
-Both the frontend and backend processes have their dependency injection (DI) -container (see below) to which extensions can contribute.
-The frontend process represents the client and renders the UI. In the browser, -it simply runs in the rendering loop, while in Electron it runs in an Electron -Window, which basically is a browser with additional Electron and Node.js APIs. -Therefore, any frontend code may assume browser as a platform but not Node.js.
-The startup of the frontend process will first load the DI modules of all
-contributing extensions before it obtains an instance of FrontendApplication
-and call start() on it.
The backend process runs on Node.js. We use express as the HTTP server. It -may not use any code that requires a browser (DOM API) as the platform.
-The startup of the backend application will first load the DI modules of all
-contributing extensions before it obtains an instance of BackendApplication
-and calls start(portNumber) on it.
By default, the backend's express server also serves the code for the frontend.
-In an extension's top folder we have an additional layer of folders to separate -by platform:
-
common folder contains code that doesn't depend on any runtime.browser folder contains code requiring a modern browser as a platform
-(DOM API).electron-browser folder contains frontend code that requires DOM API
-as well as Electron renderer-process specific APIs.node folder contains (backend) code requiring Node.js as a platform.node-electron folder contains (backend) code specific for Electron.For a high level overview of Theia's Architecture, see this document:
-Multi-Language IDE Implemented in JS - Scope and Architecture
This guide will walk you through the process of creating Theia extensions and deploying them in your Theia-based application. Please make sure to be aware of how to create a Theia based application and the different available extension mechanisms of Theia (Plugins vs. Extensions) before you continue reading.
-As an example, we are going to add a menu item Say hello that displays a notification "Hello world!". This article is guiding you through all the necessary steps.
-Prerequisites information are available from the Theia repository.
-Please refer to the guide to create Theia applications to get familiar with the default project layout and generate a Theia project with the example 'hello world' extension using our Yeoman Generator
-Let's look at the generated code for our extension in the hello-world folder. Let’s start with the package.json. It specifies the package’s metadata, its dependencies to the Theia core package, a few scripts and dev dependencies, and the theia-extension itself. Please note that the following listing might be outdated, please always refer to the generated examples from our Yeoman Generator
The keyword theia-extension is important: It allows a Theia app to identify and install Theia extensions from npm.
{
- "name": "hello-world",
- "keywords": [
- "theia-extension"
- ],
- "version": "0.0.0",
- "files": [
- "lib",
- "src"
- ],
- "dependencies": {
- "@theia/core": "latest"
- },
- "devDependencies": {
- "rimraf": "latest",
- "typescript": "~5.4.5"
- },
- "scripts": {
- "prepare": "yarn run clean && yarn run build",
- "clean": "rimraf lib",
- "build": "tsc",
- "watch": "tsc -w"
- },
- "theiaExtensions": [
- {
- "frontend": "lib/browser/hello-world-frontend-module"
- }
- ]
-}As you can see, the extension is a dedciated package that just depends on Theia. However, as the extension contributes features to our application, it needs to be wired a runtime. To achive this in a modular way, in Theia, everything is wired up via dependency injection. An extension defines one or more dependency injection modules. This is where it binds its contribution implementations to the respective contribution interface. The modules are listed in the package.json of the extension package. An extension can contribute to the frontend, e.g. providing a UI extension, as well as to the backend, e.g. contributing a language server. When the application starts, the union of all these modules is used to configure a single, global dependency injection container on each, the frontend and the backend. The runtime will then collect all contributions of a specific kind by means of a multi-inject.
The last property theiaExtensions in the package.json above is where we list the JavaScript modules that export the DI modules defining the contribution bindings of our extension. In our case, we only provide a frontend capability (a command and a menu entry). Analogously, you could also define contributions to the backend, e.g. a language contribution with a language server.
Theia defines a plethora of contribution interfaces that allow extensions to add their behaviour to various aspects of the application. Browse the documentation section 'Platform Concepts & APIs' or search for interfaces with the name *Contribution to get an idea. An extension implements the contribution interfaces belonging to the functionality it wants to deliver. In this example, we are going to implement a CommandContribution and a MenuContribution. Other ways for extensions to interact with a Theia application are via one of the various services or managers.
In the frontend module we export a default object that is a InversifyJS ContainerModule with bindings for a command contribution and a menu contribution. Please see our dependency injection guide for more details.
export default new ContainerModule(bind => {
- // add your contribution bindings here
- bind(CommandContribution).to(HelloWorldCommandContribution);
- bind(MenuContribution).to(HelloWorldMenuContribution);
-});A command is a plain data structure defining an ID and a label. The behaviour of a command is implemented by registering a handler to its ID in a command contribution. The generator has already added a command and a handler that shows a "Hello World!" message.
-export const HelloWorldCommand = {
- id: 'HelloWorld.command',
- label: "Shows a message"
-};
-
-@injectable()
-export class HelloWorldCommandContribution implements CommandContribution {
-
- constructor(
- @inject(MessageService) private readonly messageService: MessageService,
- ) { }
-
- registerCommands(registry: CommandRegistry): void {
- registry.registerCommand(HelloWorldCommand, {
- execute: () => this.messageService.info('Hello World!')
- });
- }
-}
-...Note how we use @inject in the constructor to get the MessageService as a property, and how we use that later in the implementation of the handler. This is the elegance of dependency injection: As a client, we neither care where these dependencies come from nor what their lifecycle is.
To make it accessible by the UI, we implement a MenuContribution, adding an item to the Search/Replace section of the edit menu in the menu bar.
...
-@injectable()
-export class HelloWorldMenuContribution implements MenuContribution {
-
- registerMenus(menus: MenuModelRegistry): void {
- menus.registerMenuAction(CommonMenus.EDIT_FIND, {
- commandId: HelloWorldCommand.id,
- label: 'Say Hello'
- });
- }
-}To make sure your extension is included in your Theia application, list it as a dependency in your browser or electron app, e.g. like this:
-{
- "private": true,
- "name": "browser-app",
- "version": "0.0.0",
- "dependencies": {
- "@theia/core": "latest",
- ...
- "hello-world": "0.0.0"
- },
- "devDependencies": {
- "@theia/cli": "latest"
- },
- "scripts": {
- "bundle": "yarn rebuild && theia build --mode development",
- "rebuild": "theia rebuild:browser --cacheRoot ..",
- "start": "theia start",
- "watch": "yarn rebuild && theia build --watch --mode development"
- },
- "theia": {
- "target": "browser"
- }
-}To run the extension, you have two options:
-yarn publish and consume it from your Theia-based applicationSee Executing the Browser Application and Executing the Extension in Electron for more details* for adding extensions to the dependencies of a Theia-based application and running it.
This documentation is deprecated and needs to be updated. We currently recommend using VS Code extensions or Theia extensions instead of Theia Plugins. See the extension overview for more details.
-Alongside Theia extensions, VS Code extensions can also be used to enhance Theia applications with additional functionality, such as language support, commands, or tree views. -VS Code extensions contribute functionality through the dedicated VS Code API, which the Theia framework also supports. -This means that extensions that have been developed for VS Code are also compatible with Theia, and vice versa. -The coverage report provides more details on the extent to which the VS Code API is supported by each Theia version.
-While there are certain overlaps in which types of functionality can be contributed to a Theia application with a Theia extension or a VS Code extension, both have their unique advantages and disadvantages. -Please refer to the overview on extensions and plugins and an in-depth comparison for a more detailed discussion.
-In the remainder of this page, we guide you through the process of creating VS Code extensions and deploying them in Theia. -The steps for deploying VS Code extensions apply not only to VS Code extensions you develop yourself, but also to third-party VS Code extensions from the Theia marketplace. If you use a third-party VS Code extension, you can skip the section "Creating VS Code Extensions" and "Developing VS Code Extensions in a Theia Project".
-As VS Code extensions can be used in Theia without further modification, you can refer to the documentation on extending VS Code to learn more about creating extensions for VS Code as well as for Theia. -The easiest way to get started is to use the VS Code Extension Generator and follow the Getting Started Guide.
-As an example, let's generate the hello world extension.
-npm install -g yo generator-code # install the VS Code Extension Generator
-npm install -g vsce # install VS Code Extension CLI tooling
-
-yo code # generate an extension
-# take a look at the generated package.json defining a command "Hello World"
-# take a look at the src/extension.ts registering a command handler
-# make changes to the README and the code, if you like
-vsce package # package your VS Code extensionAs a result, a vsix file is generated, which can be used directly in VS Code and Theia (see below).
-Please note that you can also create so-called extension packs with the VS Code extension generator that defines a collection of extensions.
To enable Theia's support for VS Code extensions in order to use your own extensions or third-party VS Code extensions in your Theia application, you'll need to add @theia/plugin-ext-vscode as a dependency.
-Typically, this is done in your browser or electron application package.
{
- ...
- "name": "browser-app",
- "dependencies": {
- "@theia/core": "latest",
- ...
- "@theia/plugin-ext-vscode": "latest"
- },
- "theia": {
- "target": "browser"
- }
-}Next, you need to specify a plugins location, which is a disk location containing your VS Code extensions. -Theia will load all VS Code extensions from this location on initialization of a new user session automatically. -This location can be set either with an environment variable:
-export THEIA_DEFAULT_PLUGINS=local-dir://absolute-path-to-plugins-folderOr it can be provided in the command line option --plugins when starting Theia.
theia start --plugins=local-dir:../pluginsA common approach for Theia applications that include VS Code extensions is to add this command line parameter to the startup script in the browser or electron application package.
-{
- ...
- "name": "browser-app",
- ...
- "scripts": {
- ...
- "start": "theia start --plugins=local-dir:../plugins",
- },
- "theia": {
- "target": "browser"
- }
-}Once you've enabled VS Code extension support in your Theia application as described above and made available your or any third-party VS Code extensions that you'd like to use in your Theia application, you have two options on how to consume them:
-In the following, we'll provide more details on each of those options.
-For pre-installing a certain set of VS Code extensions in your Theia application, all you need to do is to drop them, either as a vsix file or directly as a folder into the plugins location (see prerequisites).
-On start-up of a user session, Theia will load all VS Code extensions from that location automatically.
A more systematic approach, however, is to publish VS Code extensions, to OpenVSX, GitHub Releases, or any other accessible location, and download them automatically at build time of the Theia application with the Theia CLI. -See publishing extensions to OpenVSX for more details. -This approach avoids having to manually distribute VS Code extensions or adding them in the form of a build artifact to your git repository.
-Therefore, you need to extend your package.json to
{
- ...
- "scripts": {
- "prepare": "yarn run clean && yarn build && yarn run download:plugins",
- "download:plugins": "theia download:plugins",
- ...
- },
- "theiaPluginsDir": "plugins",
- "theiaPlugins": {
- "my-hello-world-extension": "https://<url-to-your-published-extension>",
- "vscode.git": "https://open-vsx.org/api/vscode/git/1.52.1/file/vscode.git-1.52.1.vsix",
- ...
- }
-}As a result, running yarn will download any listed extensions and place them into the folder specified in theiaPluginsDir automatically.
-For more details, see also the documentation on composing Theia applications.
One of the unique advantages of VS Code extensions is that they can be installed and uninstalled by users at runtime.
-To enable the users of your Theia application to install VS Code extensions at runtime, you have to add @theia/vsx-registry as a dependency to your package.json.
{
- ...
- "name": "browser-app",
- "dependencies": {
- "@theia/core": "latest",
- ...
- "@theia/vsx-registry": "latest"
- },
- "theia": {
- "target": "browser"
- }
-}This dependency will add a view Extensions to your application, which allows searching and installing extensions from an OpenVSX registry.
-By default, the public registry at http://open-vsx.org is used, the registry URL be configured via the environment variable VSX_REGISTRY_URL.
-Please confer to the OpenVSX extension documentation for more details.
To make your VS Code extension available, you'll need to publish your extension to the configured registry.
-In certain scenarios, you may not want to develop your VS Code extension in isolation from your Theia application, but instead you may prefer to develop both your extensions and your application in project to keep update cycles short and immediate. -This is particularly useful if you develop your extensions primarily to be part a specific Theia application, thus you want to develop, test and debug them directly in the context of your Theia app, potentially alongside other Theia extensions.
-In those scenarios, you can also include VS Code extensions as part of your Theia application monorepo. -While there are several possible configuration options, probably the most straightforward approach is to follow the steps below.
-Generate your VS Code extension as usual.
-However, to make things easier and consistent, choose TypeScript as your language and yarn as a package manager for your VS Code extension to be aligned with a typical Theia application.
Put your VS Code extension package, let's say your-vs-code-extension, into your monorepo, alongside your other packages and make sure it is part of your yarn workspaces.
-Let's assume, we eventually have the following a directory structure.
monorepo
-├── apps
-│ ├── browser-app
-│ └── electron-app
-├── extensions
-│ ├── your-theia-extension
-│ └── your-vs-code-extension
-├── plugins
-└── package.jsonIn your-vs-code-extension/package.json, add symlink as a dev dependency to link your extension into the plugins location of your Theia application on each build.
{
- ...
- "scripts": {
- "compile": "tsc -p ./",
- "watch": "tsc -watch -p ./",
- "prepare": "yarn run clean && yarn run build && yarn symlink",
- "symlink": "symlink-dir . ../../plugins/your-vs-code-extension",
- ...
- },
- "devDependencies": {
- "@types/vscode": "^1.32.0",
- "symlink-dir": "latest",
- ...
- }
-}With that, your VS Code extension will be built as part of your Theia application and directly added to the plugins location for automatic installation in your Theia application. -This leads to a consistent development experience, even if you have multiple VS Code extensions and Theia extensions combined in one Theia application.
-If you aim at a consistent tsconfig.json across your VS Code extension and a typical Theia extension, you may want to change the outDir from out (default in VS Code) to lib (commonly used in Theia) and adjust the package.json accordingly.
To also enable debugging from your development IDE (VS Code), you need to setup launch.json to include the VS Code extension in the outFiles (if it is still building to the folder out and not lib) and enable source maps.
{
- "version": "0.2.0",
- "configurations": [
- {
- "type": "node",
- "request": "launch",
- "name": "Start Browser Backend",
- "program": "${workspaceRoot}/browser-app/src-gen/backend/main.js",
- "args": [
- "--loglevel=debug",
- "--port=3000",
- "--no-cluster",
- "--plugins=local-dir:${workspaceRoot}/plugins"
- ],
- "env": {
- "NODE_ENV": "development",
- "NODE_OPTIONS": "--enable-source-maps"
- },
- "sourceMaps": true,
- "outFiles": [
- "${workspaceRoot}/node_modules/@theia/*/lib/**/*.js",
- "${workspaceRoot}/extensions/*/lib/**/*.js",
- "${workspaceRoot}/extensions/*/out/**/*.js",
- "${workspaceRoot}/apps/*/src-gen/**/*.js"
- ],
- "smartStep": true,
- "internalConsoleOptions": "openOnSessionStart",
- "outputCapture": "std"
- },
- ...
- ]
-}If no plugins are available in the running Theia instance, it may be that you need to tell Theia where to find the downloaded plugins.
-The example above sets the --plugins switch in the start command which should be sufficient.
-However, if running theia start directly, you can alternatively set an environment variable to achieve the same thing:
export THEIA_DEFAULT_PLUGINS=local-dir:pluginsA backend application contribution allows Eclipse Theia extensions to hook into the lifecycle of the Theia backend. Backend application contributions are instantiated immediately after starting the backend application, which makes them a good place for initializing backend services that are required during the entire lifespan of the backend.
-To register backend application contributions, an extension needs to bind an implementation of the interface BackendApplicationContribution in the backend module.
export default new ContainerModule(bind => {
- bind(MemoryTracker).toSelf().inSingletonScope();
- bind(BackendApplicationContribution).toService(MemoryTracker);
-});The interface BackendApplicationContribution provides hooks, which are all optional so that implementations can freely choose which of those hooks they are interested in, without having to implement the others.
-For initialization of backend services, the most common hook is the initialize() method that is invoked as soon as the Theia backend is initialized.
As an example, let’s implement a backend service that shall run during the entire lifespan of the Theia backend to track its memory usage. -For the sake of simplicity it will just print the memory to the log, whenever it changes more than a certain threshold.
-Therefore, a BackendApplicationContribution named MemoryTracker is bound in the dependency injection context as shown in the code above.
-The implementation of MemoryTracker reacts to the hook initialize() and executes the method logMemory() periodically every two seconds.
-This method obtains the currently used memory, compares it to the previous memory and prints a message to the log as soon as the difference to the previous memory is above 0.1 MB.
@injectable()
-export class MemoryTracker implements BackendApplicationContribution {
-
- @inject(ILogger)
- protected readonly logger: ILogger;
- protected logTimer: NodeJS.Timer;
- protected memoryUsed = 0;
-
- initialize(): MaybePromise<void> {
- this.logTimer = setInterval(() => this.logMemory(), 2000);
- }
-
- protected logMemory(): void {
- const currentMemoryUsed = this.currentRoundedMemoryUsage();
- const diff = currentMemoryUsed - this.memoryUsed;
- if (Math.abs(diff) > 0.1) {
- const timestamp = new Date().toUTCString();
- this.logger.info(
- `[${timestamp}] PID ${process.pid} uses ${currentMemoryUsed} MB (${diff > 0 ? '+' : ''}${diff.toFixed(2)})`
- );
- this.memoryUsed = currentMemoryUsed;
- }
- }
-
- protected currentRoundedMemoryUsage() {
- return Math.round(process.memoryUsage().heapUsed / 1024 / 1024 * 100) / 100;
- }
-
- onStop(): void {
- if (this.logTimer) {
- clearInterval(this.logTimer);
- }
- }
-}Once this backend application contribution is registered and the backend is started, it starts logging an output, similar to the following:
-root INFO Theia app listening on http://localhost:3000.
-root INFO Configuration directory URI: 'file:///home/foobar/.theia'
-root INFO [Fri, 20 Aug 2021 12:20:43 GMT] PID 46590 uses 18.14 MB (+18.14)
-root INFO [Fri, 20 Aug 2021 12:20:47 GMT] PID 46590 uses 18.94 MB (+0.80)
-root INFO [Fri, 20 Aug 2021 12:20:51 GMT] PID 46590 uses 15.25 MB (-3.69)
-root INFO [Fri, 20 Aug 2021 12:21:07 GMT] PID 46590 uses 15.36 MB (+0.11)
-root INFO [Fri, 20 Aug 2021 12:21:21 GMT] PID 46590 uses 15.47 MB (+0.11)
-root INFO [Fri, 20 Aug 2021 12:21:41 GMT] PID 46590 uses 15.6 MB (+0.13)
-root INFO [Fri, 20 Aug 2021 12:21:59 GMT] PID 46590 uses 15.71 MB (+0.11)Often such backend application contributions also provide methods that can be invoked by other backend services and, for instance, start external processes that need to be available as soon as the application is started. -Examples are database connections, REST services, etc.
-In addition to initializing backend services as early as the backend is started, backend application contributions can also configure and extend the HTTP server used by the Theia backend.
-Therefore, the BackendApplicationContribution interface provides the three methods configure(app: express.Application), onStart(app: express.Application), and onStop(app: express.Application).
-Thus, the HTTP server can be configured with custom settings and even extended with additional endpoints that need to be available for the respective Theia application.
An example for configuring an additional endpoint named /myendpoint is given below.
import { injectable } from '@theia/core/shared/inversify';
-import { json } from 'body-parser';
-import { Application, Router } from '@theia/core/shared/express';
-import { BackendApplicationContribution } from '@theia/core/lib/node/backend-application';
-
-@injectable()
-export class MyCustomEndpoint implements BackendApplicationContribution {
- configure(app: Application): void {
- app.get('/myendpoint', (request, response) => {
- …
- });
- }
-}For more information on how to configure HTTP endpoints and handle events requests, please refer to the Express API.
This guide provides an overview on how to extend and customize the Theia IDE to your own custom IDE or tool. In this scenario, the Eclipse Theia IDE is an example product used as a reference on how to build desktop IDE-like products based on the Eclipse Theia framework. If you just want to use the Theia IDE, see the user guide
-Please note that adopting the Theia IDE as a basis is just one of several ways to get started with building a Theia-based application. We recommend reading the article "Build your own IDE/Tool" as a first step. Furthermore, this guide is focused on building a desktop app. We also provide an experimental Docker version of the Theia IDE as an alternative.
-The Theia IDE assembles a selected subset of existing Theia features and extensions. -We provide installers for the Theia IDE to be downloaded (see links below). -In the respective git repository you can also find the source code for the Theia IDE and its installers.
-This documentation will use these sources as a template. We will explain -how to customize this template so that you can build your own custom Theia-based product including installers and packaging for installing the desktop-based version of your custom product on all major operating systems. Please note that the technical name (e.g. in the source code) for the Theia IDE is "Theia Blueprint" to avoid confusion with the generic term "IDE".
-The Theia IDE build uses electron-builder to package the product as a desktop application.
-The product can be built and packaged with yarn. -Note that you usually can only package the product for the operating system you execute the build on. -For more information see the electron-builder documentation on multi-platform builds.
-The following commands may be run from the root directory of the repository.
-To install dependencies and build the application, simply execute yarn.
You can also directly run the unpackaged application, e.g. to test it during development with yarn electron start.
With yarn electron package, you package the application into an executable file for your current operating system.
-The packaged application will be located in applications/electron/dist.
-The folder applications/electron/dist/<OS>-unpackaged will contain the files that are bundled into the final packaged executable.
-For Linux, this is an executable .AppImage, for Windows a .exe installer, and a .dmg disk image for macOS.
You can also just create the unpackaged content by running yarn electron package:preview.
-This is useful to see the bundled files and saves time compared to a full package.
-To publish the current version, the command yarn electron deploy can be used.
-For more information on publishing also see section "Configure publish and update".
Electron-builder supports signing the packaged application on Windows and macOS.
-The current signing scripts for the Theia IDE are located in applications/electron/scripts.
-The file after-pack.js is the current entry point for the configured signing via Eclipse infrastructure.
However, as signing is highly dependent on your setup, see the electron builder’s signing documentation on how to properly set up your own signing.
-The Theia IDE is based on the Theia platform, which is a flexible and adaptable platform for build tools and IDEs. Therefore, you can adapt the feature set and general appearance of the Theia IDE to your custom requirements with almost no limits. The Theia platform provides two mechanism to add your custom extensions: VS Code extensions and Theia extensions. Please have a look at the overview about Theia extension capabilities for details. When assembling a product such as the Theia IDE, you can freely decide, which VS Code extensions and Theia extensions are part of it and thereby influence the feature set of your custom product. The following two sections describe how to modify which VS Code Extensions and which Theia extensions are part of your product. Please also note that you can allow users of a Theia-based tool to install VS Code extensions at runtime.
-All VS Code extensions that are already included in the product at start-up ("built-ins"), are defined in applications/electron/package.json.
-They are listed under the theiaPlugins property as key-value pairs.
-The keys can be freely chosen as long as they represent a valid folder name and are unique within the theiaPlugins property.
-We suggest using the extension’s unique identifier.
-The value is the download URL of the extensions.
-It will automatically be downloaded during the application’s build process.
-Any new plugin will be automatically downloaded the next time one of the following npm scripts is executed:
install (which is the same as just running yarn)preparedownload:pluginsTo remove an extension from the product, simply delete its entry.
-If plugins were not already downloaded, no further steps are required as downloaded plugins are ignored via gitignore.
-However, previously downloaded plugins are not automatically removed.
-Therefore, you need to remove its folder from the applications/electron/plugins folder.
-Alternatively, you can remove the whole applications/electron/plugins folder and execute yarn electron download:plugins to download all defined plugins.
We use the Open VSX Registry of the Eclipse Foundation to install extensions. -It is an open and community-driven VS Code extension marketplace. -More information can be found at eclipse.org.
-Eclipse Theia extensions can be added through dependencies in applications/electron/package.json.
-Like any other dependency, it will be installed via yarn.
-Similarly, removing an extension works by removing it from dependencies.
-For extensions already published on npm (or your private npm registry) this is all you need to do.
An alternative approach is developing your extension inside Theia IDE’s mono repo. -The advantage of doing this is that you don’t need to publish the extension and can build the product with the local version of the extension. -This is facilitated by the lerna build already configured in the Theia IDEs’s repository. -It links the product and all extensions in the repository together during the build.
-The easiest way to create a new extension is to use the official yeoman generator for Theia extensions.
-Assuming you have yeoman globally installed on your system, simply create a new extension in the repository root with yo theia-extension --standalone.
-The --standalone flag is used to only create an extension but not a whole Theia application frame because it is already provided by the Theia IDE.
-After successfully generating the extension, add its folder name to the Theia IDEs’s root package.json in the workspaces property.
-After adding the extension to the dependencies in applications/electron/package.json as described above, the new extension will be part of the built product.
You can also add your own branding to the product by customizing the application icons and title, the welcome page and the About dialog. -In addition, some parts of the installer can be customized.
-The window title is the application’s name if no workspace is opened and <workspace name> — <application name> if a workspace is opened.
-The application name can be adapted in applications/electron/package.json by navigating through the nested properties.
To change the application name, open the file and locate the following nested structure:
- "theia": {
- "frontend": {
- "config": {
- "applicationName": "Theia IDE",
- },
- },
- },Change the value of applicationName to the desired name.
-Also see the structure in the original file.
Application icons are located in applications/electron/resources/.
-Simply replace them with your own icons.
-Because each operating system handles icons differently, they should all be replaced to ensure proper use.
-They map as follows:
The Eclipse Theia welcome page can be customized by binding a custom WidgetFactory for Theia’s GettingStartedWidget.
-This is done with the Theia IDE in the theia-blueprint-product extension.
-The easiest way to customize the welcome page is to adapt the class TheiaBlueprintGettingStartedWidget in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-getting-started-widget.tsx.
The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:
bind(TheiaBlueprintGettingStartedWidget).toSelf();
- bind(WidgetFactory).toDynamicValue(context => ({
- id: GettingStartedWidget.ID,
- createWidget: () => context.container.get<TheiaBlueprintGettingStartedWidget>(TheiaBlueprintGettingStartedWidget),
- })).inSingletonScope();To use another custom widget, remove this code and bind your widget correspondingly.
-The Eclipse Theia about dialog can be customized by binding a custom subclass of Theia’s AboutDialog class to AboutDialog.
-This is done with Theia IDE in the theia-blueprint-product extension.
-The easiest way to customize the about dialog is to adapt the class TheiaBlueprintAboutDialog in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-about-dialog.tsx.
The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:
isBound(AboutDialog) ? rebind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope() : bind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope();To use another custom dialog widget, remove this code, extend Theia’s AboutDialog class, and (re)bind it as above.
-The default preferences directory in Eclipse Theia IDE is .theia-blueprint and is located as described in the Preferences documentation. You can customize this location by modifying theia-blueprint-variables-server.ts.
Since Theia 1.49.0 Theia Electron applications support displaying a splash screen before showing the main window.
The splash screen can be enabled within the application package.json's Theia options by providing an object at theia.frontend.config.electron.splashScreenOptions with the following properties:
{
- content: string // <mandatory> path to the content to render within the splash screen, resolved from application root
- width: number // default 640
- height: number // default 480
- minDuration: number // minimum amount of time in milliseconds to show the splash screen before main window is shown. default 0
- maxDuration: number // maximum amount of time in milliseconds before splash screen is removed and main window is shown. default 30000
-}If not configured otherwise via minDuration, the splash screen will be shown until the frontend is ready, i.e. when the loading spinner is gone.
-Then the splash screen will be closed and the main window is shown.
The main window / splash screen can be configured to be shown "early", i.e. the window will be shown before it's ready to render content.
-By default this is true to give the user visual feedback as early as possible.
If you prefer only showing the main window / splash screen once they are ready to render content, then you can configure theia.frontend.config.electron.showWindowEarly: false in your application's package.json.
The installers are created using electron-builder.
-The corresponding configuration file is located at applications/electron/electron-builder.yml.
The installer files’ base names are defined by the productName property in applications/electron/electron-builder.yml.
As is typical for Windows applications, there is an installation wizard for the Windows version of the Theia IDE. -The installer is configured in the nsis section of the configuration file. -Available customizations include settings such as:
-More details on available options and how they can be customized can be found in the official electron builder documentation. -This documentation also includes information about more advanced features such as custom NSIS scripts.
-The Theia IDE uses electron-builder to create and publish installers. -It also uses electron-updater, developed by the electron-builder organization, to provide automatic updates of the installed application.
-There are various deployment targets which can be configured in the applications/electron/package.json and applications/electron/electron-builder.yml as documented here in the Electron Builder documentation.
-Multiple publish configurations can be configured.
-Thereby, the first one is automatically used by the updater to look for available updates.
-The currently used generic publishing method does not automatically publish to the specified server, but is just used as the lookup location for the updater.
Eclipse Theia Blueprint has been rebranded to "Theia IDE" and has moved to this page.
If enabled via the preferences, Theia can show a navigation bar, often referred to as breadcrumbs, above the content of widgets that are located in the main area of the workbench. -This interactive navigation bar indicates the location of the widget's content in the context of an overall structure, such as the filesystem. -By default, Theia shows breadcrumbs for the location of files in the filesystem when a file is opened in the text editors.
-
-However, Theia's breadcrumbs mechanism can also be used for any custom widget, too. -Moreover, Theia allows showing a widget's content location in an arbitrary custom logical structure, such as a custom project structure. -On this page, we describe how custom breadcrumbs work and how widgets declare their location within an overall structure.
-What is being shown in the breadcrumbs of a widget is defined by breadcrumbs contributions.
-Such contributions must implement the BreadcrumbsContribution interface and return an array of Breadcrumbs for a specific URI, which are then shown for any widget that specifies this URI as their content's location.
-A widget declares the location of its content in the form of a URI by implementing the interface NavigatableWidget.
So let's look at an example widget that declares an arbitrary URI.
-@injectable()
-export class CustomWidget extends ReactWidget implements NavigatableWidget {
- // ...
- getResourceUri(): URI | undefined {
- return new URI('resource://project-a/component-b/config-c');
- }
-}When this CustomWidget is opened, Theia will look for breadcrumbs contributions that return breadcrumbs for this URI.
-By default, it won't find any and thus won't show any breadcrumbs.
-So let's add a breadcrumbs contribution that reacts to URIs with the scheme resource as used by our widget above.
export default new ContainerModule(bind => {
- bind(CustomBreadcrumbsContribution).toSelf().inSingletonScope();
- bind(BreadcrumbsContribution).toService(CustomBreadcrumbsContribution);
-});
-
-@injectable()
-export class CustomBreadcrumbsContribution implements BreadcrumbsContribution {
- type: symbol = CustomBreadcrumbType;
- priority: number = 100;
-
- protected readonly onDidChangeBreadcrumbsEmitter = new Emitter<URI>();
- get onDidChangeBreadcrumbs(): Event<URI> {
- return this.onDidChangeBreadcrumbsEmitter.event;
- }
-
- computeBreadcrumbs(uri: URI): MaybePromise<Breadcrumb[]> {
- if (uri.scheme !== 'resource') {
- return [];
- }
- // uri is 'resources://project-a/component-b/config-c' for our widget above
- // but let's just hard code breadcrumbs as an example for the sake of simplicity
- return [
- {
- id: 'project',
- label: 'Project A',
- longLabel: 'The project',
- iconClass: 'codicon codicon-folder default-folder-icon file-icon',
- type: CustomBreadcrumbType
- },
- {
- id: 'component',
- label: 'Component B',
- longLabel: 'A component within a project',
- iconClass: 'codicon codicon-file default-file-icon file-icon',
- type: CustomBreadcrumbType
- },
- {
- id: 'config',
- label: 'Configuration C',
- longLabel: 'A configuration within a component',
- iconClass: 'markdown-icon medium-blue theia-file-icons-js file-icon',
- type: CustomBreadcrumbType
- }
- ];
- }
-
- // ...
-}Once the breadcrumbs contribution is registered, Theia will show the following for our custom widget.
-
-Breadcrumbs contributions also must implement the method attachPopupContent.
-Theia invokes this method as soon as a user clicks on one of the breadcrumbs and passes a parent HTML element into which the breadcrumbs contribution can now add arbitrary HTML content, including trees, buttons, etc.
-This content is consequently being shown as a popup below the clicked breadcrumbs element.
-If this method returns a Disposable, Theia will call it, once the popup is closed, allowing to dispose resources that may have been allocated for the rendered content.
As an example, let's just return add some simple HTML to the popup, as shown below.
-@injectable()
-export class CustomBreadcrumbsContribution implements BreadcrumbsContribution {
- // ...
- attachPopupContent(breadcrumb: Breadcrumb, parent: HTMLElement): Promise<Disposable | undefined> {
- parent.innerHTML = '<div style="margin-left: 10px"><h3>'
- + breadcrumb.label
- + '</h3><p>We can show arbitrary content here and react to clicks.</p></div>';
- return Promise.resolve(undefined);
- }
-}
-As defined by the BreadcrumbsContribution interface, a contribution must define a priority.
-The property is used by Theia to properly order the breadcrumbs returned by all breadcrumbs contributions.
-Thus, if you have for instance three breadcrumbs contributions that return a non-empty array of breadcrumbs for a particular URI, we'll end up with a final breadcrumbs list that contains all breadcrumbs of all three contributions ordered from lowest to highest priority.
-The Theia text editor uses this mechanism to append logical structures of code to a source file, for instance.
-Contributions that return an empty array for a specific URI are obviously ignored.
Contribution A with a priority of 10 returns [a, b]
-Contribution B with a priority of 20 returns [c, d]
-Contribution C with a priority of 30 returns [e, f]
-=> [a, b, c, d, e, f]Theia's filesystem extension registers a breadcrumbs contribution that returns breadcrumbs according to the directory hierarchy for any file URI, such as file://home/user/a/b/c.txt.
-The breadcrumbs returned by that contribution are also interactive by showing a file tree on click for navigating to adjacent files.
You can also make use of the filesystem breadcrumbs in custom widgets by just returning file URIs in your implementation of NavigatableWidget#getResourceUri().
-If needed, you can also register additional breadcrumbs contributions with a high number as priority to append to the file URI shown in the breadcrumbs, such as for navigating to specific sections in your custom widget.
Accordingly, however, if you want to avoid showing filesystem breadcrumbs altogether and only use custom breadcrumbs, your widget must return a URI that isn't a file URI, for instance resource://a/b/c.
Commands are runnable actions defined by an ID and the function to be executed (plus some optional parameters like a name or an icon). Commands can be triggered via the command palette, they can be bound to keybindings or menu items, and they can be called programmatically. The action that commands trigger can be context-sensitive, so that they can only be called under certain conditions (window focus, current selection etc.).
-The following sections provide details about how to contribute commands, keybindings and menu items. The sections will describe how to connect the different contributions and how to use the corresponding services for managing these items.
-If you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
-All the following code examples are from the Theia extension generator. You can get the same code set-up by installing the generator, selecting the “Hello World” example (see here) and choosing “helloworld” as the name.
-By contributing a command, you can add a custom action to Theia. A command can be triggered by the user via the command palette, a keybinding or a menu entry. It can also be called programmatically.
-All commands of a Theia application are managed in the CommandRegistry. To contribute commands to the command registry, modules must implement the CommandContribution interface (see code example below).
A command is an object with an id and an optional, potentially user visible label (see HelloworldCommand in the example below). The command contribution receives the CommandRegistry in the registerCommands function as a parameter. The command can then be registered by calling registerCommand on this registry. Along with the command a callback needs to be provided which is executed whenever the command is triggered (CommandHandler). In the example, the command uses the MessageService to “say hello”.
helloworld-contribution.ts
-export const HelloworldCommand: Command = {
- id: 'Helloworld.command',
- label: "Say Hello"
-};
-
-@injectable()
-export class HelloworldCommandContribution implements CommandContribution {
-
- constructor(
- @inject(MessageService) private readonly messageService: MessageService,
- ) { }
-
- registerCommands(registry: CommandRegistry): void {
- registry.registerCommand(HelloworldCommand, {
- execute: () => this.messageService.info('Hello World!')
- });
- }
-}
-To make the command execution context-sensitive, the CommandHandler can optionally implement isEnabled and isVisible. You can optionally register more than one CommandHandler and let the command execute one of them based on the current context. To register additional handlers for a command use the registerHandler function on the CommandRegistry
-When a command is executed, the command registry checks all registered handlers. The first handler that returns true on isEnabled will be considered to be active, and it will be executed. Only one handler should be active (isEnabled === true) at the same time, though. isVisible controls the visibility of menu items and tool items that are connected to a command, as well as whether the command is shown in the command palette. If the active handler returns true, the menu item will be visible and vice versa.
-Finally, by implementing isToggle a handler can optionally specify, whether menu items connected to the commands should be toggled on or off.
To make our CommandContribution accessible to Theia, we need to bind the custom HelloworldCommandContribution to the respective contribution symbol CommandContribution. This is done in the helloworld-frontend-module, for more details see Services and Contributions.
helloworld-frontend-module.ts
-export default new ContainerModule(bind => {
- // add your contribution bindings here
- bind(CommandContribution).to(HelloworldCommandContribution);
-...
-});The CommandRegistry used to register our contributed command above, also provides an API to interact with commands. As an example, you can programmatically execute commands, you can browse through all registered commands or you can access a list of recently executed commands. Please refer to the TypeDoc for the CommandRegistry for more details. To use the CommandRegistry outside of a contribution, you can access it via dependency injection.
In the following sections, we describe how to bind commands to menu items and keybindings.
-Theia allows you to contribute menu items that will be displayed in specific menus within your Theia application. Menu items are bound to commands and therefore allow the user to trigger actions (please see the section about commands above).
-All the following code examples are from the Theia extension generator. You can get the same code set-up by installing the generator, selecting the “Hello World” example (see here) and choosing “helloworld” as the name.
-All menu items of a Theia application are managed in the MenuModelRegistry. To contribute menu items to the registry, modules must implement the ´MenuContribution´ interface (see code example below).
The registration of the command can be done in the function registerMenus, which will be called by the Theia framework. The function provides the MenuModelRegistry as a parameter. On this registry we can call registerMenuAction. It expects a MenuPath and a MenuAction. The MenuPath specifies the menu (and submenu) to place the menu item into. Please see here for the paths of some common menus.
The MenuAction consists of a command id, specifying which command to trigger, and an optional label, specifying the label of the menu item.
helloworld-contribution.ts
-@injectable()
-export class HelloworldMenuContribution implements MenuContribution {
-
- registerMenus(menus: MenuModelRegistry): void {
- menus.registerMenuAction(CommonMenus.EDIT_FIND, {
- commandId: HelloworldCommand.id,
- label: HelloworldCommand.label
- });
- }
-}To make our MenuContribution accessible to Theia, we need to bind the custom HelloWorldMenuContribution to the respective contribution symbol MenuContribution. This is done in the helloworld-frontend-module, for more details see Services and Contributions.
helloworld-contribution.ts
-export default new ContainerModule(bind => {
- bind(MenuContribution).to(HelloworldMenuContribution);
- ...
-});
-Please note that you also contribute menu items without a command which allows you to create custom top level menus and sub menus. To achieve this, contribute a menu item without a command and then reference the id of this menu item as a MenuPath in other contributes. This will add menu items to your custom menu.
Keybindings allow the user to trigger commands using specific key combinations. Keybindings can define conditions, specifying when they are active. As an example, there can be keybindings that are only active when the text editor is focused.
-Please note that the following code examples are not part of the generated template, so you will need to manually add them (see previous sections).
-To contribute a keybinding, implement a KeybindingContribution (see code example below) with which you can access the KeybindingRegistry, allowing you to register a keybinding. Keybindings consist of:
keybinding: The key combinationcommand: The id of the command to be triggeredwhen(optional): The condition when the keybinding should be activehelloworld-keybinding-contribution.ts
-export class HelloworldKeybindingContribution implements KeybindingContribution {
- registerKeybindings(keybindings: KeybindingRegistry): void {
- keybindings.registerKeybinding({
- keybinding: "alt+enter",
- command: 'Helloworld.command',
- when: 'editorFocus && editorIsOpen'
- });
- }
-}The syntax for the “when” clause follows the VS Code terminology. Modifiers are platform independent, so Modifier.M1 is Command on OS X and CTRL on Windows/Linux. Key string constants can be viewed in Key documentation.
Just as you needed to bind the contributions before, keybinding contributions also need to be bound to the symbol KeybindingContribution to make them accessible for Theia.
editor-frontend-module.ts
-export default new ContainerModule(bind => {
- bind(KeybindingContribution).to(HelloworldKeybindingContribution);
- ...
-});
-This guide will teach you how to create your own Theia-based application. The guide will demonstrate how to configure your own application composed of existing or new Theia extensions, and any VS Code extensions you want bundled in your application by default. Please get familiar with the extension mechanisms of Theia in case you are not already. -We provide two entry points for creating your own Theia-based application.
-If you are new to Theia, we recommend starting with the first option, as it is quicker and simpler to get started with. If you want to create a full product based on Theia, you can later on switch to using the Theia IDE without loosing your existing work by integrating your extensions into your custom version of the Theia IDE. In this guide, we will demonstrate how to get started with the Yeoman Generator.
-The detailed list of prerequisites is located at the main Theia repository:
- -A Theia app is composed of so-called Theia extensions. Each extension resides in its own npm package. -An extension provides a set of features, e.g. widgets, commands, handlers, etc. for a specific functionality. The Theia project itself ships a number of extensions for common features, e.g. for editors, terminals, the project view etc. You can resue these existing extensions by just adding them to you custom Theia application. Additionally, you can add arbitrary VS Code extensions to your application, again for reusing existing features already available, such as Git support. Finally, you can then extend and customize your Theia application with your own features, which you can implement as Theia extensions or VS Code extensions. -In this guide, we will create a Theia application with a number of existing Theia extensions and one (generated) custom Theia extension. Please also refer to our documentation on how to create custom Theia extensions to learn more on how to create your own Theia extensions. Finally, also see our guide on how to add VS Code extensions to your custom Theia application.
-We are going to create a monorepo (a repository containing multiple npm packages) named my-theia-app containing three packages: browser-app, electron-app and hello-world-extension. The first two contain the custom Theia applications to run in browser and electron mode. The 'hello-world' package contains a generated example extension, that adds a feature to our custom Theia application. This extension can serve as a starting point for you to add your own custom features via Theia extensions.
We are going to use yarn instead of npm (Theia default). We are also going to use lerna to run scripts across workspaces.
To ease the setup of such a repository we have created a Yeoman generator to scaffold the project. It will also generate the hello-world example extension. Run it using
npm install -g yo generator-theia-extension
-mkdir my-theia-app
-cd my-theia-app
-yo theia-extension # select the 'Hello World' option and complete the promptsAfter creating the project structure, the Yeoman generator will also install the required dependencies, so it might take a minute to complete.
-Let's have look at the generated code now. The root package.json defines the workspaces, the dependency to lerna and some scripts to build, start and watch the project for browser or electron. Please note that the excerpt on this page might be outdated, please use the Yeoman generator to generate the files listed below to get the latest version.
{
- "private": true,
- "engines": {
- "yarn": ">=1.7.0 <2",
- "node": ">=18"
- },
- "scripts": {
- "build:browser": "yarn --cwd browser-app bundle",
- "build:electron": "yarn --cwd electron-app bundle",
- "prepare": "lerna run prepare",
- "postinstall": "theia check:theia-version",
- "start:browser": "yarn --cwd browser-app start",
- "start:electron": "yarn --cwd electron-app start",
- "watch:browser": "lerna run --parallel watch --ignore electron-app",
- "watch:electron": "lerna run --parallel watch --ignore browser-app"
- },
- "devDependencies": {
- "lerna": "2.4.0"
- },
- "workspaces": [
- "hello-world", "browser-app", "electron-app"
- ]
-}Besides the root level artifacts, you will have three directories in your project:
-Now we want to see our Theia application in action. For this purpose, the generator has created a package.json in the folder browser-app, which defines your Theia app. It defines a Theia browser application with a couple of statically included extensions, including our hello-world. These extensions are the features, that will be part of our Theia application. The generated project contains a minimalistic set-up, you can add additional features by adding more existing (or custom) extensions to this list. The example also does not contain any VS Code extensions, see here on how to add them.
{
- "private": true,
- "name": "browser-app",
- "version": "0.0.0",
- "dependencies": {
- "@theia/core": "latest",
- "@theia/editor": "latest",
- "@theia/filesystem": "latest",
- "@theia/markers": "latest",
- "@theia/messages": "latest",
- "@theia/monaco": "latest",
- "@theia/navigator": "latest",
- "@theia/preferences": "latest",
- "@theia/process": "latest",
- "@theia/terminal": "latest",
- "@theia/workspace": "latest",
- "hello-world": "0.0.0"
- },
- "devDependencies": {
- "@theia/cli": "latest"
- },
- "scripts": {
- "bundle": "yarn rebuild && theia build --mode development",
- "rebuild": "theia rebuild:browser --cacheRoot ..",
- "start": "theia start",
- "watch": "yarn rebuild && theia build --watch --mode development"
- },
- "theia": {
- "target": "browser"
- }
-}Now we have all pieces together to build and run the application. -To run the browser app, enter:
-yarn build:browser
-yarn start:browserPoint your browser to http://localhost:3000, you will see a minimalistic custom Theia App. -As this Theia app contains the generated 'hello world' extension, you can try out the custom feature. Open the quick access bar by pressing 'F1' and enter 'say hello' and 'ENTER': A message "Hello World!" should pop up. This command is contributed by the 'hello-world' extension, see this guide to learn more.
-The package.json for the Electron app looks almost the same, except for the name and the target property.
{
- "name": "electron-app",
- ...
- "theia": {
- "target": "electron"
- }
-}Before running the electron app, you have to rebuild some native modules:
-yarn build:electron
-yarn start:electronIn this guide, we have demonstrated how to set-up your own custom Theia application. The next typical steps are:
-If you run the yarn command behind a proxy you may encounter issues in building native dependencies (like oniguruma), in the last part of the build, with the following error stack:
[4/4] Building fresh packages...
-[1/9] XXXXX
-[2/9] XXXXX
-[3/9] XXXXX
-[4/9] XXXXX
-error /theiaide/node_modules/XXXXX: Command failed.
-Exit code: 1
-Command: node-gyp rebuild
-Arguments:
-Directory: /theiaide/node_modules/XXXXX
-Output:
-gyp info it worked if it ends with ok
-gyp info using node-gyp@3.8.0
-gyp info using node@8.15.0 | linux | x64
-gyp http GET https://nodejs.org/download/release/v8.15.0/node-v8.15.0-headers.tar.gz
-gyp WARN install got an error, rolling back install
-gyp ERR! configure error
-gyp ERR! stack Error: read ECONNRESET
-gyp ERR! stack at TLSWrap.onread (net.js:622:25)
-gyp ERR! System Linux 3.10.0-862.11.6.el7.x86_64
-gyp ERR! command "/usr/bin/node" "/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
-gyp ERR! cwd /theiaide/node_modules/XXXXX
-gyp ERR! node -v v8.15.0This happens because node-gyp does not rely on system/NPM proxy settings. In that case, download the node-headers file using the link provided in the error stack
-(in the example above https://nodejs.org/download/release/v8.15.0/node-v8.15.0-headers.tar.gz) and run the build with the following command:
npm_config_tarball=/path/to/node-v8.15.0-headers.tar.gz yarn installThis guide outlines how to incorporate specific bug fixes or features from Theia's master branch into your project without needing to fully upgrade to a new version of Theia.
-Imagine you are developing a Theia application using version 1.43.0. You encounter a bug in Theia, report it, and the community fixes it. However, there is no immediate Theia release including this fix. This guide describes how to use this fix in your local development, e.g. to validate it or to just already consume it before the next Theia release is published.
-We also assume that:
-Note: In the following, we assume you are adopting the Theia version 1.43 which you want to hotfix(backport). Please replace "1.43" with the correct version of Theia that you currently build your project against.
-Clone and Branch Theia Codebase
-
-Clone the Theia codebase and checkout the version you are adopting in your project. Create a new branch from this version to apply the fix.
For convenience, make sure to clone it next to where your Theia application repo is cloned. E.g., if your Theia app is in ~/git/myapp , make sure you clone the Theia repo such that it ends up at ~/git/theia . This isn't absolutely necessary, but will make things easier in a subsequent step. We'll be assuming you've done it that way.
-git clone -b v1.43.0 https://github.com/eclipse-theia/theia.git
-cd theia
-git checkout -b v1.43.0_with_fixNow you have a local clone of the same exact Theia version your application is currently using. It doesn't have the backported fix, but the next steps will take care of that.
-Identify the commit to backport on master
-
-Browse the commit history of the Theia project in the master branch to identify the commit you want to backport. It will typically be linked on the corresponding ticket on Github. Identify the commit SHA that has the fix in the master branch. In the following, we assume it is 0a615512.
Cherry-Pick the Fix
-
-Use the commit SHA of the fix to cherry-pick it onto your local Theia branch.
git cherry-pick 0a615512Given the assumptions for this scenario, the cherry-pick should occur without any merge conflicts. If there are conflicts, you will need to address them. Now you have a local clone of Theia that includes the fix you want to backport.
-Check Modified Files
-
-Use the following command to see what files were altered by the fix.
git show --name-only --pretty="" 0a615512Adjust Package.json Files
-
-If the list of changes shows that any package.json files were modified, ensure that Theia package versions are not newer than 1.43. Open each one in an editor and replace any instances where a Theia package is referenced using a version newer than 1.43.0. E.g., if you find
"dependencies": {
- "@theia/core": "1.44.0",
- ...
-}change 1.44.0 to 1.43.0 . -If you overlook or forget to adjust any such forward version references, you will probably encounter errors when you try to build your local Theia version.
-Note Modified Packages
-
-Identify which packages in packages/ and dev-packages/ were affected.
Build Theia
-
-Run yarn to build Theia in the modified branch.
-
-We assume here that everything builds without errors. If there are errors, double check your steps above (particular #5). If you didn't make any mistakes, then it's likely that the fix has dependencies on other changes that have happened in the codebase since Theia 1.43.0. That is not necessarily a deal breaker. You may be able to adjust the fix to make it work on top of the 1.43.0 codebase. It may require that you cherry-pick another small change or two (but hopefully not more than that).
Use Modified Theia in Your App
-
-In your application's package.json, add resolutions for each modified package.
"resolutions": {
- "**/@theia/core": "file:../theia/packages/core",
- "**/@theia/terminal": "file:../theia/packages/terminal",
- // more resolutions as needed
-}Update Node Modules
-
-Use yarn install with appropriate flags to update your node_modules.
yarn install --check-files --ignore-scripts--check-files tells yarn to skip the optimization it normally does and to ensure node_modules has what it should have.
---ignore-scripts lets us skip subsequent yarn lifecycle activity that isn't necessary in this particular step. We just want the node_modules to get updated.
-Please Note: You will have to re-run this step if you later make any additional changes to the Theia codebase that affect the packages you specified in the resolutions section above (e.g., if you cherry-pick another commit). Keep in mind that the yarn install cmdline above does not create symlinks. It makes copies of directories in your Theia workspace and puts them in your apps's node_modules . Any subsequent changes in those Theia directories need to be copied over again.
Build Your Application
-
-Finally, run yarn in your application directory to build it with the new fixes.
By following these steps, you can backport Theia fixes or features into your application without waiting for an official release. This process is particularly useful for minor changes that don't depend on other recent codebase updates.
The Contribution Filter feature in Theia enables developers to remove specific contributions from a Theia-based application. This capability is typically used to eliminate existing features already present in Theia core, such as specific commands or menu entries.
-For a general understanding of contributions and contribution points, please refer to the Services and Contributions documentation.
-The Contribution Filter feature provides a way to selectively disable certain contributions within a Theia application. This is handeled by the ContributionFilterRegistry and FilterContributions which allow you to register and apply filters to contributions.
The FilterContribution interface allows you to register your contribution filters. These filters will be used by the ContributionFilterRegistry to remove or modify contributions.
ContributionFilterRegistry.Here's an example of how to use the Contribution Filter to remove specific commands from a Theia application. In this example, we will first define some commands and the filter them. If you want to filter some existing contributions, you would of course skip the first step and just provide a FilterContribution.
First, we define an example command that we want to filter out (more information about commands).
-import { Command } from '@theia/core/lib/common';
-
-export namespace SampleFilteredCommand {
-
- const EXAMPLE_CATEGORY = 'Examples';
-
- export const TO_BE_FILTERED: Command = {
- id: 'example_command.filtered',
- category: EXAMPLE_CATEGORY,
- label: 'This command should be filtered out'
- };
-}We register the example command with a command contribution.
-import { CommandContribution, CommandRegistry } from '@theia/core/lib/common';
-import { injectable } from 'inversify';
-
-@injectable()
-export class SampleFilteredCommandContribution implements CommandContribution {
-
- registerCommands(commands: CommandRegistry): void {
- commands.registerCommand(SampleFilteredCommand.TO_BE_FILTERED, { execute: () => { } });
- }
-}Now, we register the filters to remove specific contributions, in our case the example command we just registered. The filter below is scoped to be only applied to CommandContribution, you can use '*' to filter any type of contribution. In the filter implementation, we additionally check for the specific type SampleFilteredCommandContribution in the example.
import { FilterContribution, ContributionFilterRegistry, CommandContribution } from '@theia/core/lib/common';
-import { injectable } from 'inversify';
-
-@injectable()
-export class SampleFilterContribution implements FilterContribution {
-
- registerContributionFilters(registry: ContributionFilterRegistry): void {
- registry.addFilters([CommandContribution], [
- contrib => !(contrib instanceof SampleFilteredCommandContribution)
- ]);
- }
-}Ensure that your contributions are properly bound in the dependency injection container.
-import { interfaces } from 'inversify';
-import { CommandContribution, bindContribution } from '@theia/core/lib/common';
-
-export function bindSampleFilteredCommandContribution(bind: interfaces.Bind): void {
- bind(CommandContribution).to(SampleFilteredCommandContribution).inSingletonScope();
- bind(FilterContribution).to(SampleFilterContribution).inSingletonScope();
-}The Contribution Filter feature in Theia is a powerful tool for developers to manage and customize the contributions in their applications. By leveraging FilterContributions , developers can easily define and apply filters to remove or modify specific contributions, thereby tailoring the functionality of their Theia-based applications to their specific needs.
By default, Theia shows the value of a widget's caption property when users hover above a widget's tab (see also widgets).
-In certain use cases, especially with custom editors, this information may however not be sufficient to give users sufficient overview about a widget's content before activating the tab.
Therefore, Theia optionally provides an enhanced tab bar preview for widgets of the main or bottom area of Theia; that is, for horizontal tab bars. -This enhanced preview offers more room for information for widgets to show when hovering above a widget's tab. -Moreover, it can easily be styled according to the needs of a tool provider adopting Theia.
-The enhanced tab bar preview is disabled by default and needs to be explicitly enabled with a via the preference window.tabbar.enhancedPreview.
-After enabling the enhanced tab bar preview, users will see the following on hovering over a widget's tab:
-
-The values shown in the tab bar preview are taken from the widget's title and caption properties.
-These values can thus be easily provided by the widget implementation:
@postConstruct()
- protected async init(): Promise<void> {
- this.id = GettingStartedWidget.ID;
- this.title.label = GettingStartedWidget.LABEL;
- this.title.caption = 'Home > Theia > Getting Started';
- this.title.closable = true;For custom products, the enhanced tab bar preview can be customized and styled according to the requirements of the respective product. -Below we discuss the most relevant customization options.
-The styling of the hover box can easily be done with CSS.
-If all hovers should be styled (including ones that are unaffected by the window.tabbar.enhancedPreview setting) the .theia-hover CSS class can be adjusted.
-To only change the styling of the enhanced tab bar previews, use the CSS selector .theia-hover.extended-tab-preview instead.
-By default, the enhanced tab bar preview for horizontal tab bars has rounded corners. This is defined by adding a border-radius to the .theia-hover.extended-tab-preview CSS class:
.theia-hover.extended-tab-preview {
- border-radius: 10px;
-}To style the elements inside of the preview, class names are assigned to the different components of the preview. -Those are:
-.theia-horizontal-tabBar-hover-div (for the outer box).theia-horizontal-tabBar-hover-title (for the title).theia-horizontal-tabBar-hover-caption (for the caption).If, for example, the preview should have a fixed size, this can be achieved by specifying a width for the .theia-horizontal-tabBar-hover-div and a max-width to the other two rules.
-To also ensure the text is not going over the boxes boundaries, the property word-wrap: break-word can be added to the latter two rules.
.theia-horizontal-tabBar-hover-div {
- margin: 0px 4px;
- width: 100px;
-}
-
-.theia-horizontal-tabBar-hover-title {
- font-weight: bolder;
- font-size: medium;
- margin: 0px 0px;
- max-width: 100px;
- word-wrap: break-word
-}
-
-.theia-horizontal-tabBar-hover-caption {
- font-size: small;
- margin: 0px 0px;
- margin-top: 4px;
- max-width: 100px;
- word-wrap: break-word
-}After those rules are applied the preview will look as shown below:
-
-To change the actual content that is being rendered inside of the preview, the TabBarRenderer can be extended to overwrite the renderExtendedTabBarPreview method.
-If, for example, the preview should only render the caption, the following CustomTabBarRenderer could be created:
export class CustomTabBarRenderer extends TabBarRenderer {
- protected override renderExtendedTabBarPreview = (title: Title<Widget>) => {
- const hoverBox = document.createElement('div');
- hoverBox.classList.add('theia-horizontal-tabBar-hover-div');
- const labelElement = document.createElement('p');
- labelElement.classList.add('theia-horizontal-tabBar-hover-title');
- labelElement.textContent = title.label;
- hoverBox.append(labelElement);
- return hoverBox;
- };
-}Now, we need to bind our custom TabBarRendererFactory to activate our customization and ensure the preview renders the information as defined in the implementation of CustomTabBarRenderer.renderExtendedTabBarPreview() above.
bind(TabBarRendererFactory).toFactory(({ container }) => () => {
- const contextMenuRenderer = container.get(ContextMenuRenderer);
- const tabBarDecoratorService = container.get(TabBarDecoratorService);
- const iconThemeService = container.get(IconThemeService);
- const selectionService = container.get(SelectionService);
- const commandService = container.get<CommandService>(CommandService);
- const corePreferences = container.get<CorePreferences>(CorePreferences);
- const hoverService = container.get(HoverService);
- return new CustomTabBarRenderer(contextMenuRenderer, tabBarDecoratorService, iconThemeService, selectionService, commandService, corePreferences, hoverService);
- });Events in Theia can be confusing, hopefully we can clarify things.
-Let's consider this code:
-(From logger-watcher.ts)
-@injectable()
-export class LoggerWatcher {
-
- getLoggerClient(): ILoggerClient {
- const emitter = this.onLogLevelChangedEmitter
- return {
- onLogLevelChanged(event: ILogLevelChangedEvent) {
- emitter.fire(event)
- }
- }
- }
-
- private onLogLevelChangedEmitter = new Emitter<ILogLevelChangedEvent>();
-
- get onLogLevelChanged(): Event<ILogLevelChangedEvent> {
- return this.onLogLevelChangedEmitter.event;
- }
-}Let's start with:
- private onLogLevelChangedEmitter = new Emitter<ILogLevelChangedEvent>();So first what is an Emitter?
An Emitter is an event handler container, -it allows for event handlers to be registered on it and triggered with an -event of type X in this case an ILogLevelChangedEvent.
-So here we just create an Emitter that will have events of type ILogLevelChangedEvent;
Next we want to be able to register an event handler on this Emitter to
-do so we do this:
get onLogLevelChanged(): Event<ILogLevelChangedEvent> {
- return this.onLogLevelChangedEmitter.event;
- }What this actually returns is a function that will register an event -handler. Passing it your event handler function will -register it so that it's called when the event fires.
-So you can call:
-(From logger.ts)
- /* Update the root logger log level if it changes in the backend. */
- loggerWatcher.onLogLevelChanged(event => {
- this.id.then(id => {
- if (id === this.rootLoggerId) {
- this._logLevel = Promise.resolve(event.newLogLevel);
- }
- });
- });This registers the anonymous function passed as param on this emitter.
-Next we will need to trigger this event handler by firing an event:
- onLogLevelChanged(event: ILogLevelChangedEvent) {
- emitter.fire(event)
- }When calling this function, the emitter fires and all the event handlers -are called.
-So if you need to trigger events in theia:
-Eclipse Theia is designed in a very modular and extensible way. It supports four ways of being extended/adapted to your specific requirements. These are complementary and are targeted at different use cases. You can pick the best option and even mix them within the same project. -In the following, we will give you a quick overview of the available extension mechanisms and provide more details in the sections below.
-These are not scoped to frontend connections and have no access (directly) to frontend services.
-The following diagram shows the high level architecture for all four options. VS Code extensions and Theia plugins run in a dedicated process per frontend connection, can be installed at runtime, and work against a defined API. Headless plugins similarly run in a dedicated process, but only one that is not associated with any frontend connection. Theia extensions are added during compile time and become a core part of your Theia application. They can access the full API of Theia.
-
-If you would like more guidance on which mechanism to use, please also refer to this detailed comparison between VS Code extensions and Theia extensions.
-VS Code extensions are the popular mechanism to extend VS Code with new language support and other features. VS Code extensions are simple to develop and they have access to a defined and restricted API. VS Code extensions can be pre-installed (built in), but also installed at runtime (e.g. by the user). Eclipse Theia provides the same extension API as VS Code, so extensions are compatible. Therefore, to develop your own extension, please refer to the VS Code extension documentation. Please also refer to this coverage report, highlighting which API of VS Code is covered by Theia. -Please also note that you can use existing VS Code extensions in Theia, too. A good source for installing or downloading extensions is the Open VSX registry.
-A Theia extension is a module that resides inside a Theia application and directly communicates with other modules (Theia extensions). The Theia project itself is composed of Theia extensions too. To create a Theia application, you can select a number of Theia extensions provided by the Theia project (core extensions), add your own custom Theia extensions and then compile and run the result. Your custom Theia extension will have access to the same API as the core extensions. This modularity allows you to extend, adapt or remove almost anything in Theia according to your requirements. Also, specific use cases, such as complex views are easier to develop with Theia extensions compared to VS Code extensions.
-Technically, an extension is an npm package that exposes any number of DI modules (ContainerModule) that contribute to the creation of the DI container.
-Extensions are consumed by declaring them as a dependency in the package.json of the application/extension, and are installed at compile time.
-See this section for more detail on how to author a Theia extension.
Theia plugins are a special type of VS Code extensions that only run in Eclipse Theia. They share the architecture and other attributes of VS Code extensions, but they also have access to additional API that is only available in Theia, not in VS Code. Most noticeable, Theia plugins can also directly contribute to the frontend while VS Code extensions are restricted to the backend. As a consequence Theia plugins can directly manipulate the UI without going through a webview abstraction, easing the development process. Please be aware that the support for Theia Plugins is currently under discussion. We therefore recommend using VS Code extensions or Theia extensions instead of Theia Plugins.
-Headless plugins are a special type of plugin that only runs in Eclipse Theia. They are very similar architecturally and otherwise to VS Code extensions, except that they run in the Node backend outside of the scope of any frontend connection. Therefore, they are suitable for extensibility use cases involving CLI interactions where there is no browser frontend and extension of common backend services defined for application-specific purposes. Accordingly, they are not provided with a default API for access to the backend Theia services but have access only to custom APIs published explicitly to them by the application to support the extensibility of its own backend services.
Frontend application contributions can react to lifecycle events of the Theia frontend application to execute behavior before the frontend is started or stopped, or once the frontend’s layout is initialized.
-Besides providing a generally useful startup hook, frontend application contributions are also typically used to open and arrange views, register listeners, add status bar items, or customize the layout of the application shell when the application is started.
-Another use case is to react to shutdown, for instance, to persist certain application data on shutdown, e.g. using the StorageService.
As any other frontend contribution, frontend application contributions are also registered in a frontend module by binding an implementation of the FrontendApplicationContribution interface.
-A typical pattern is a view that shall always be initially opened on startup.
-Therefore, the view implementation does not only extend the AbstractViewContribution<MyWidget>, but is also registered as FrontendApplicationContribution to open the contributed view after the application shell layout is initialized.
export default new ContainerModule(bind => {
- …
- bindViewContribution(bind, MyViewContribution);
- bind(FrontendApplicationContribution).toService(MyViewContribution);
-}Besides the view implementation itself, the view can now implement the method initializeLayout(app: FrontendApplication) from the FrontendApplicationContribution interface to open itself after the layout has been initialized.
-Note that this method is only called if there is no previously stored workbench layout available, which makes it ideal to implement initial workbench layouts, as it won’t override layout changes that users already applied manually in a previous session.
@injectable()
-export class MyViewContribution extends AbstractViewContribution<MyViewWidget>
- implements FrontendApplicationContribution {
- …
- async initializeLayout(app: FrontendApplication): Promise<void> {
- await this.openView();
- }
- …
-}If a frontend application contribution needs to be invoked every time the application is started -- and not only after initial layout when there is no previously stored layout state -- the methods configure(app: FrontendApplication) and onStart(app: FrontendApplication) can be used instead.
-As these methods are invoked even before the application shell is attached or menus are initialized, you may want to use those in combination with the frontend application state service, depending on your use case.
@injectable()
-export class MyViewContribution extends AbstractViewContribution<MyViewWidget>
- implements FrontendApplicationContribution {
- …
- @inject(FrontendApplicationStateService)
- protected readonly stateService: FrontendApplicationStateService;
- …
- async onStart(app: FrontendApplication): Promise<void> {
- this.stateService.reachedState('ready').then(
- () => this.openView({ reveal: true })
- );
- }
-}Another typical use for frontend application contributions is to install listeners, e.g. to react to changes of preferences, or to add custom widgets to the application shell in the configure(app: FrontendApplication) and onStart(app: FrontendApplication) respectively.
This page has been merged into the documentation overview
Theia can be localized by installing Visual Studio Code language packs. Using the Configure Display Language command, users of Theia can change their currently used locale.
-The framework provides additional features to enable extension developers to localize their own extensions.
Let's say you have a simple string you want to present in the frontend of your application, like a custom widget that displays a goodbye message:
-render() {
- return <span>Bye</span>
-}To display this message using different locales, you can use the nls.localize function, imported from the @theia/core package:
render() {
- return <span>{nls.localize('bye', 'Bye')}</span>
-}The first argument is a key to identify the translated value. The second argument is the default value that will be used if the user didn't change their locale. When using template expressions in the frontend, keep in mind that the nls.localize function allows you to format strings using the additional args parameter. When the localize function identifies placeholders in the format {n} where n represents any number, it will try to replace the placeholder with the input parameter at the appropriate position, e.g. {0} will be replaced by the first additional parameter, {1} by the second and so forth:
nls.localize('bye-format', 'Bye {0} and {1}!', first, second);The Command namespace provides an additional utility function to help you localize your extension. The toLocalizedCommand function accepts a Command and localization keys as its arguments. The first additional key will be used to localize the label and the second for the category. If none are provided, the id of the command will be used as the label localization key:
command = Command.toLocalizedCommand({
- id: 'hello-command',
- label: 'Hello'
- category: 'Greetings'
-}, 'hello', 'greetings');After replacing the all user-facing strings with nls.localize calls, you can use the theia nls-extract command of the @theia/cli package to extract all used localization keys into a single JSON file. For the two examples above, it will result in the following JSON output:
{
- "bye": "Bye",
- "hello": "Hello",
- "greetings": "Greetings"
-}You can also group these keys by using forward-slashes. For example, a call like nls.localize('group/bye', 'Bye') will be transformed into this JSON file:
{
- "group": {
- "bye": "Bye"
- }
-}These files will have to be translated into your target languages. Afterwards, you can continue with registering these new localizations for your strings using a custom LocalizationContribution:
// creating your own localization contribution for German, Italian and simplified Chinese
-export class CustomLocalizationContribution implements LocalizationContribution {
- async registerLocalizations(registry: LocalizationRegistry): Promise<void> {
- // Theia uses language codes, e.g. "de" for German
- registry.registerLocalizationFromRequire('de', require('../data/i18n/nls.de.json'));
- registry.registerLocalizationFromRequire('it', require('../data/i18n/nls.it.json'));
- registry.registerLocalizationFromRequire('zh-cn', require('../data/i18n/nls.zh-cn.json'));
- }
-}Lastly, this LocalizationContribution will have to be bound within your backend injection module:
bind(CustomLocalizationContribution).toSelf().inSingletonScope();
-bind(LocalizationContribution).toService(CustomLocalizationContribution);Be aware that the Configure Display Language command only shows a locale once its language pack has been installed. This assures that no parts of the Theia base framework remain untranslated after a user changes the display language.
If you want to deploy your Theia app to a specific region, you may want to change the default locale.
-To do this you simply add a defaultLocale entry to the frontend configuration of your Theia app in your package.json file:
"theia": {
- "frontend": {
- "config": {
- "defaultLocale": "zh-cn"
- }
- }
-}The first time a user starts your Theia app, the locale will be automatically set to the selected default locale.
-They are still free to change the selected locale using the Configure Display Language command.
In this section, we provide a high level overview on how to get started with Eclipse Theia and link to respective sections to read. -Eclipse Theia is a platform for building custom Cloud & Desktop IDEs and tools with modern web technologies. The Eclipse Theia Platform is not a tool itself, but there are many tools which are built upon Theia. The Theia project provides a tool called Eclipse Theia IDE that can be directly used. The Theia IDE can also be used as a template to get started with building your own tool. Please have a look at the project goals for more details!
-You cannot directly launch/use Theia as it is a platform. The project provides one tool called Eclipse IDE that you can directly download and use. Further, it is very easy to create your own product based on Theia. Please also refer to this article highlighting the various options available to launch/try Eclipse Theia and Theia-based products.
-The first step is to define a custom product based on Theia. Please check out the guide on how to build your own IDE or tool based on Theia. Subsequently, you might want to extend this product with your own feature for which you can use the available extension mechanisms of Theia.
-If you are unsure what Theia is, how it compares to other technologies or how to migrate Eclipse-based tools to it, please have a look at resource section.
-Theia is an open community, and we are glad to help you. You can ask questions using our public community forum, you can report bugs and feature requests, and you can get professional support, consulting and implementation services for building products based on Theia.
-Also follow Theia on Twitter to stay up-to-date!
-Read below to learn how to take part in improving Theia:
-In this section, we provide a high level overview on how to get started with Eclipse Theia and link to respective sections to read. -Eclipse Theia is a platform for building custom Cloud & Desktop IDEs and tools with modern web technologies. The Eclipse Theia Platform is not a tool itself, but there are many tools which are built upon Theia. The Theia project provides a tool called Eclipse Theia IDE that can be directly used. The Theia IDE can also be used as a template to get started with building your own tool. Please have a look at the project goals for more details!
-You cannot directly launch/use Theia as it is a platform. The project provides one tool called Eclipse IDE that you can directly download and use. Further, it is very easy to create your own product based on Theia. Please also refer to this article highlighting the various options available to launch/try Eclipse Theia and Theia-based products.
-The first step is to define a custom product based on Theia. Please check out the guide on how to build your own IDE or tool based on Theia. Subsequently, you might want to extend this product with your own feature for which you can use the available extension mechanisms of Theia.
-If you are unsure what Theia is, how it compares to other technologies or how to migrate Eclipse-based tools to it, please have a look at resource section.
-Theia is an open community, and we are glad to help you. You can ask questions using our public community forum, you can report bugs and feature requests, and you can get professional support, consulting and implementation services for building products based on Theia.
-Also follow Theia on Twitter to stay up-to-date!
-Read below to learn how to take part in improving Theia:
-In this section we will explain how you can create a backend service and -then connect to it over RPC.
-We will use the task execution system as a small example of that.
-This works by creating a service exposed by the express framework and -then connecting to that over a websocket connection.
-So the first thing you will want to do is expose your service so that the -frontend can connect to it.
-You will need to create backend server module file similar to this (task-backend-module.ts):
-import { ContainerModule } from '@theia/core/shared/inversify'';
-import { ConnectionHandler, RpcConnectionHandler } from '@theia/core/lib/common/messaging';
-import { TaskClient, TaskServer, taskPath } from '../common/task-protocol';
-
- bind(ConnectionHandler).toDynamicValue(ctx =>
- new RpcConnectionHandler<TaskClient>(taskPath, client => {
- const taskServer = ctx.container.get<TaskServer>(TaskServer);
- taskServer.setClient(client);
- return taskServer;
- })
- ).inSingletonScope();Let's go over that in detail:
-import { ConnectionHandler, RpcConnectionHandler } from '@theia/core/lib/common/messaging';This imports the RpcConnectionHandler, this factory enables you to create
-a connection handler that onConnection creates a proxy object to the remote object that
-is called in the backend over RPC and optionally exposes a local object to RPC.
We'll see more on how this is done as we go.
-The ConnectionHandler is a simple interface that specifies the path of the
-connection and what happens on connection creation.
It looks like this:
-import { Channel } from '../message-rpc/channel';
-
-export const ConnectionHandler = Symbol('ConnectionHandler');
-
-export interface ConnectionHandler {
- readonly path: string;
- onConnection(connection: Channel): void;
-}import { TaskClient, TaskServer, taskPath } from '../common/task-protocol';The task-protocol.ts file contains the interfaces that the server and the
-client need to implement.
The server here means the backend object that will be called over RPC -and the client is a client object that can receive notifications from the -backend object.
-We will get more into that later.
- bind<ConnectionHandler>(ConnectionHandler).toDynamicValue(ctx => {Here a bit of magic happens, at first glance we're just saying here is an
-implementation of a ConnectionHandler.
The magic here is that this ConnectionHandler type is bound to a
-ContributionProvider. A central MessagingContribution picks up all registered connection handlers
-an when this contribution is initialized it creates a websocket channel for all bound ConnectionHandlers.
-To save resources the hood all MessagingContributions are routed over one
-websocket connection (multiplexing).
To dig more into ContributionProvider see this section.
-So now:
- new RpcConnectionHandler<TaskClient>(taskPath, client => {This does a few things if we look at this class implementation:
-export class RpcConnectionHandler<T extends object> implements ConnectionHandler {
- constructor(
- readonly path: string,
- readonly targetFactory: (proxy: RpcProxy<T>) => any,
- readonly factoryConstructor: new () => RpcProxyFactory<T> = RpcProxyFactory
- ) { }
-
- onConnection(connection: Channel): void {
- const factory = new this.factoryConstructor();
- const proxy = factory.createProxy();
- factory.target = this.targetFactory(proxy);
- factory.listen(connection);
- }
-}We see that a websocket channel is created on the taskPath ("/services/task") by the extension of the ConnectionHandler.
And let's look at what it does onConnection :
onConnection(connection: Channel): void {
- const factory = new this.factoryConstructor();
- const proxy = factory.createProxy();
- factory.target = this.targetFactory(proxy);
- factory.listen(connection);
- }Let's go over this line by line:
- const factory = new this.factoryConstructor();This creates a ProxyFactory on path "services/task".
const proxy = factory.createProxy();Here we create a proxy object from the factory, this will be used to call
-the other end of the RPC channel using the TaskClient interface.
factory.target = this.targetFactory(proxy);This will call the function we've passed in parameter so:
- client => {
- const taskServer = ctx.container.get<TaskServer>(TaskServer);
- taskServer.setClient(client);
- return taskServer;
- }This sets the client on the taskServer, in this case this is used to
-run asynchronous tasks (e.g. a terminal command) in the backend.
And it returns the taskServer as the object that will be exposed over RPC.
factory.listen(channel);This connects the factory to the channel and establishes the RPC protocol.
-So now that we have a backend service let's see how to connect to it from -the frontend.
-To do that you will need something like this:
-(From task-frontend-module)
import { ContainerModule } from '@theia/core/shared/inversify';
-import { WebSocketConnectionProvider } from '@theia/core/lib/browser/messaging';
-import { TaskServer, taskPath } from '../common/task-protocol';
-import { TaskWatcher } from '../common/task-watcher';
-
-export default new ContainerModule(bind => {
- bind(TaskServer).toDynamicValue(ctx => {
- const connection = ctx.container.get(WebSocketConnectionProvider);
- const taskWatcher = ctx.container.get(TaskWatcher);
- return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());
- }).inSingletonScope();
-});The important bit here are those lines:
- bind(TaskServer).toDynamicValue(ctx => {
- const connection = ctx.container.get(WebSocketConnectionProvider);
- const taskWatcher = ctx.container.get(TaskWatcher);
- return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());
- }).inSingletonScope();
-Let's go line by line:
- const connection = ctx.container.get(WebSocketConnectionProvider);Here we're getting the websocket connection, this will be used to create a proxy from.
- const taskWatcher = ctx.container.get(TaskWatcher);Here we're creating a watcher, this is used to get notified about events
-from the backend by using the taskWatcher's client
-(taskWatcher.getTaskClient())
See more information about how events work in theia here.
- return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());As the second argument, we pass a local object to handle RPC messages from the remote object.
-Sometimes the local object depends on the proxy and cannot be instantiated before the proxy is instantiated.
-In such cases, the proxy interface should implement RpcServer and the local object should be provided as a client.
export type RpcServer<Client> = Disposable & {
- /**
- * If this server is a proxy to a remote server then
- * a client is used as a local object
- * to handle RPC messages from the remote server.
- */
- setClient(client: Client | undefined): void;
- getClient?(): Client | undefined;
-};
-
-export interface TaskServer extends RpcServer<TaskClient> {
- // ...
-}
-
-const serverProxy = connection.createProxy<TaskServer>("/services/task");
-const client = taskWatcher.getTaskClient();
-serverProxy.setClient(client);So here at the last line we're binding the TaskServer interface to a
-RPC proxy.
Note that his under the hood calls:
- createProxy<T extends object>(path: string, arg?: object): RpcProxy<T> {
- const factory = arg instanceof RpcProxyFactory ? arg : new RpcProxyFactory<T>(arg);
- this.listen({
- path,
- onConnection: c => factory.listen(c)
- });
- return factory.createProxy();
- }So it's very similar to the backend example.
-Maybe you've noticed too but as far as the connection is concerned the frontend -is the server and the backend is the client. But that doesn't really -matter in our logic.
-So again there's multiple things going on here what this does is that:
-taskWatcher.getTaskClient() object.TaskServer.So now instances of TaskServer are proxied over RPC to the
-backend's TaskServer object.
If you wish to see the complete implementation of what I referred too in -this documentation see this commit.
A label provider in Eclipse Theia is responsible for the way elements/nodes are presented in the UI. The label provider determines the icon and the text for elements displayed in trees, lists or other locations such as view headers. A good example is the file explorer: file and directory nodes retrieve their icon and text from the label provider. Another example for the usage of a label provider is the header of an open editor. Please also see the LabelProvider TypeDoc.
-The default label provider in Theia browses registered label provider contributions to determine the best fitting one for an element/node. The label provider will delegate the calls for a specific node to the contribution which can best handle the element. Eclipse Theia provides default label provider contributions for common types, e.g. for files. By providing your own label provider contributions, you can extend or adapt the look of specific nodes, based on specific criteria.
-In this article we will describe how to customize the label and icon of a custom file type (.my) in Eclipse Theia, as seen in the screenshot below.
-
-If you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
-All the following code examples are from the Theia extension generator. You can get the same code set-up by installing the generator, selecting the “Label Provider” example (see here) and choosing “labelProvider” as the name.
-To contribute a custom label provider contribution you provide a LabelProviderContribution, i.e. a class implementing this interface. In this example, instead of directly implementing the interface, we extend the default implementation for files: FileTreeLabelProvider. This allows us to only override the behavior we want to customize.
labelprovider-contribution.ts
-@injectable()
-export class LabelproviderLabelProviderContribution extends FileTreeLabelProviderThe function canHandle determines whether the label provider contribution is responsible for a specific node (in our example for ".my" files). Therefore, it can check any condition on the respective file, e.g. the file extension. The return value of the function is an integer representing the priority of the label provider contribution, the label provider contribution with the highest priority will be used by the label provider. This way, you can override the default label provider contributions to custom files by returning a higher priority.
The canHandle function receives an object representing the file handed in as a parameter (for the file tree a FileStatNode). Please see an example implementation for canHandle below, which will register a label provider contribution for the file extension “.my”:
labelprovider-contribution.ts
-canHandle(element: object): number {
- if (FileStatNode.is(element)) {
- let uri = element.uri;
- if (uri.path.ext === '.my') {
- return super.canHandle(element)+1;
- }
- }
- return 0;
-}Once the label provider contribution is registered for your custom file extension, you can optionally implement getName, getIcon and getLongName. These receive a URI as a parameter and return a custom icon and a custom name for the respective file. Icon and name are used in the file view of Theia. The long name (not customized in the example) is shown as a tooltip when you hover over the file in an opened editor tab. For more details, see the LabelProviderContribution TypeDoc
labelprovider-contribution.ts
-getIcon(): string {
- return 'fa fa-star-o';
-}
-
-getName(fileStatNode: FileStatNode): string {
- return super.getName(fileStatNode) + ' (with my label)';
-}To make our LabelProviderContribution accessible to Theia, we need to bind the custom LabelProviderLabelProviderContribution to the respective contribution symbol LabelProviderContribution. This is done in the labelprovider-frontend-module, for more details see Services and Contributions.
labelprovider-frontend-module.ts
-export default new ContainerModule(bind => {
- // label binding
- bind(LabelProviderContribution).to(LabelProviderLabelProviderContribution);
-});The getIcon function returns a CSS string identifying an icon for the custom file type. In the example above, we use a Font Awesome icon. If you want to use a custom icon, you need to add this icon to the CSS as well. Usually, there will be multiple versions of an icon depending on the style (dark vs. light). The following example shows how to add a custom icon. To use this in the example, replace the returned string in getIcon above with ‘my-icon’
example.css
-.my-icon {
- background-repeat: no-repeat;
- background-size: 12px;
- width: 13px;
- height: 13px;
-}
-.light-plus .my-icon{
- background-image: url('./custom_icon_black_18dp.png');
-}
-.dark-plus .my-icon{
- background-image: url('./custom_icon_white_18dp.png');
-}Theia uses standard technologies for adding language support to custom Theia-based products. By integrating the Monaco Code Editor, Theia supports the language server protocol (LSP) as well as TextMate.
-We recommend you use VS Code Extensions which the Theia Framework supports in order to add support for an existing or a custom language. Please refer to the VS Code Language Support documentation for additional details.
The message service allows you to show messages, interactive dialogues and progress information to the user. You can get the MessageService injected and call either info, warn or error on it to report your message (see code example below):
@inject(MessageService) private readonly messageService: MessageService
-this.messageService.info('Hello World!')By default, Theia will display messages as toast notifications in the bottom right corner. Below you can see screenshots of the different message types (info, warn and error). Please note that you can easily adopt Theia to implement a different behavior for displaying messages by providing a custom MessageClient.
Info
-
-Warn
-
-Error
-
-By default, notifications will be displayed until the user closes them. You can optionally define a time-out after which messages will be closed automatically:
-this.messageService.info('Say Hello with timeout',{timeout: 3000})Optionally, you can also add actions that the user can execute. In case the user executes an action, the message service call will resolve to the action string which was handed over.
-In the following code example, we provide the two actions “Say Hello again!” and “Cancel”. We react to the action “Say hello again!” by posting yet another message, “Cancel” will be ignored.
-@inject(MessageService) private readonly messageService: MessageService
-
-this.messageService
- .error("Hello World!", "Say Hello again!", "Cancel")
- .then((action) => {
- if (action === "Say Hello again!")
- this.messageService.info("Hello again!");
- })The corresponding toast notification will look like this:
-
-When the user selects “Say Hello again”, another toast notification will be shown:
-
-The message service also allows you to report progress on an ongoing operation. You can incrementally update a progress bar and the message while the toast notification remains visible until the operation is done. The following example opens a progress bar and updates the status three times before it is completed. Please see the TypeDoc of MessageService for more detailed information.
this.messageService
- .showProgress({
- text: `Doing something`,
- })
- .then((progress) => {
- // Do something
- progress.report({
- message: "First step completed",
- work: { done: 10, total: 100 },
- });
- // Do something
- progress.report({
- message: "Next step completed",
- work: { done: 80, total: 100 },
- });
- // Do something
- progress.report({
- message: "Complete",
- work: { done: 100, total: 100 },
- });
- progress.cancel();
- })Note that progress.cancel is also used to signal that progress is complete.
-The code example above will be displayed like this:
Theia has a preference service which allows modules to get preference values, contribute default preferences and listen for preference changes.
-Preferences can be saved in the root of the workspace under .theia/settings.json or under $HOME/.theia/settings.json on Linux systems. For Windows systems, the user settings will by default be in the %USERPROFILE%/.theia/settings.json (something like C:\Users\epatpol\.theia/settings.json)
As of right now the files must contain a valid a JSON containing the names and values of preferences (note that the following preference names are not official and only used as an example). You can also add comments to the settings.json file if needed i.e.
-{
- // Enable/Disable the line numbers in the monaco editor
- "monaco.lineNumbers": "off",
- // Tab width in the editor
- "monaco.tabWidth": 4,
- "fs.watcherExcludes": "path/to/file"
-}Let's take the filesystem as an example of a module using the preference service
-To contribute some preference values. A module must contribute a valid json schema that will be used to validate the preferences. A module must bind the following PreferenceContribution to a value like this:
-export interface PreferenceSchema {
- [name: string]: Object,
- properties: {
- [name: string]: object
- }
-}
-
-export interface PreferenceContribution {
- readonly schema: PreferenceSchema;
-}For instance, the filesystem binds it like so:
-export const filesystemPreferenceSchema: PreferenceSchema = {
- "type": "object",
- "properties": {
- "files.watcherExclude": {
- "description": "List of paths to exclude from the filesystem watcher",
- "additionalProperties": {
- "type": "boolean"
- }
- }
- }
-};
-
-bind(PreferenceContribution).toConstantValue(
-{
- schema: filesystemPreferenceSchema
-});Here are some useful links for contributing a validation schema:
- -To use the value of a preference, simply get the injected PreferenceService from the container
-const preferences = ctx.container.get(PreferenceService);In the case of the filesystem, the service is fetched at the beginning for the bindings. There, you can use the onPreferenceChanged method to register a pref changed callback.
-
-constructor(@inject(PreferenceService) protected readonly prefService: PreferenceService
- prefService.onPreferenceChanged(e => { callback }Where the event received e is like this:
export interface PreferenceChangedEvent {
- readonly preferenceName: string;
- readonly newValue?: any;
- readonly oldValue?: any;
-}Although this can be used directly in the needed class, the filesystem provides a proxy preference service specific to the filesystem preferences (which uses the preference service in the background). This allows for faster and more efficient searching for the preference (as it searches for the preference in the filesystem preference service, and not on all preferences via the more generic preference service). It's also more efficient in the sense that only the modules watching for specific preferences related to a module will be notified. To do so, there is a proxy interface for the filesystem configuration that is bound like so using the preference proxy interface:
-export type PreferenceProxy<T> = Readonly<T> & Disposable & PreferenceEventEmitter<T>;
-export function createPreferenceProxy<T extends Configuration>(preferences: PreferenceService, configuration: T): PreferenceProxy<T> {
- /* Register a client to the preference server
- When a preference is received, it is validated against the schema and then fired if valid, otherwise the default value is provided.
-
- This proxy is also in charge of calling the configured preference service when the proxy object is called i.e editorPrefs['preferenceName']
-
- It basically forwards methods to the real object, i.e dispose/ready etc.
-}To use that proxy, simply bind it to a new type X = PreferenceProxy<CONFIGURATION_INTERFACE> and then bind(X) to a proxy using the method above.
-export interface FileSystemConfiguration {
- 'files.watcherExclude': { [globPattern: string]: boolean }
-}
-
-export const FileSystemPreferences = Symbol('FileSystemPreferences');
-export type FileSystemPreferences = PreferenceProxy<FileSystemConfiguration>;
-
-export function createFileSystemPreferences(preferences: PreferenceService): FileSystemPreferences {
- return createPreferenceProxy(preferences, defaultFileSystemConfiguration, filesystemPreferenceSchema);
-}
-
-export function bindFileSystemPreferences(bind: interfaces.Bind): void {
-
- bind(FileSystemPreferences).toDynamicValue(ctx => {
- const preferences = ctx.container.get(PreferenceService);
- return createFileSystemPreferences(preferences);
- });
-
- bind(PreferenceContribution).toConstantValue({ schema: filesystemPreferenceSchema });
-
-}Finally, to use the filesystem configuration in your module. Simply inject it where you need it. You can then access the preference like so (filesystem example) :
-const patterns = this.preferences['files.watcherExclude'];and you can also register for preference change like so:
-this.toDispose.push(preferences.onPreferenceChanged(e => {
- if (e.preferenceName === 'files.watcherExclude') {
- this.toRestartAll.dispose();
- }
-}));constructor(...,
- @inject(FileSystemPreferences) protected readonly preferences: FileSystemPreferences) {
- ...
- this.toDispose.push(preferences.onPreferenceChanged(e => {
- if (e.preferenceName === 'files.watcherExclude') {
- this.toRestartAll.dispose();
- }
- }));
- ...
-}As of right now, when a settings.json is modified either in the ${workspace}/.theia/ or in the os.homedir()/.theia/, this will trigger an event from the JSON preference server. Currently, there's a CompoundPreferenceServer that manages the different servers (scopes) like workspace/user/defaults (provided via the contributions above). Next, the PreferenceService manages this server and adds a more convenient API on top of it (i.e. getBoolean, getString etc.). It also allows clients to registers for preference changes. This PreferenceService can then be used either directly via injection in the modules, or via a more specific proxy (like the filesystem configuration from above).
In the case of the preference file being modified, the flow would then be:
-.theia/settings.json -> JsonPreferenceServer -> CompoundPreferenceServer -> PreferenceService -> PreferenceProxy<FileSystemConfiguration> -> FileSystemWatcherIn the case of the filesystem, one would use the same proxied config as above to access the preferences.
- if (this.prefService['preferenceName']) {
- ...
- }
-
- if (this.prefService['preferenceName2']) {
- ...
- }
-})This works because, as we have seen it above, the proxy will simply call prefService.get('preferenceName').
-This section describes the overall goals of the Eclipse Theia project.
-Eclipse Theia mission statement: A framework for building tools and IDEs based on web technologies.
-The goal of the Eclipse Theia project is to provide a platform for efficiently developing tools and IDEs based on a modern web technology stack. The primary target group for Theia is developers implementing a custom tool for end users. As Theia-based products are typically customized, branded and labeled by its adopters, the actual end users may not even be aware of the Theia project they are using under the hood. Therefore, end users are only an indirect secondary target group of Theia.
-Tools and IDEs built on Theia can run as desktop applications or in the browser. The backend of Theia can run locally (for the desktop case) or as a remote service in the cloud. Both variants currently have an equal priority.
-Theia is targeted at building a variety of custom tools. Prominent examples of Theia-based products include IDE's, but Theia also explicitly targets tools that do not focus on textual input/editors or software development. Thus, Theia's scope also included diagram editors or form-based UI. The Theia platform hence covers the typical application scenarios of the Eclipse rich-client platform (Eclipse RCP). As a consequence, the platform aims at making as few assumptions as possible about what adopters might want to build with Theia. It explicitly allows deviation from the standard workbench layout and the removal of all default features.
-Theia provides a workbench frame, i.e., a window management system permitting the display of views, editors, and menus and makes available tools and interactions allowing the user to modify of the window layout, trigger commands, and use key bindings and other concepts known from a desktop tool such as drag and drop.
-Theia optionally provides common tool features as components to be reused by adopters. Common features are generic, so that they may be reused in several tools. Examples for these common tool features include a file explorer, Git support and a code editor.
-Theia is an extensible and adaptable framework. Extensibility in this context means that you can easily add new features to a product built on the Theia platform (including UI and backend functionality). These new features can either be provided by the Theia project itself (common features), by other projects (e.g. Eclipse GLSP) or be custom features that are developed by an adopter. Adaptable in this context means that the workbench and all common features that are provided by the Theia project can be customized and adapted to project-specific needs. This includes changing or removing existing features and adjusting the look and feel.
-Theia provides the ability to host VS Code extensions. This allows adopters to benefit from features that are provided as VS Code extensions and make them part of their tool offering. It also allows end users of Theia-based tools to install additional features, if the adopter providing a tool allows users to do so. When applicable, the default Theia UX aligns with the VS Code UI, although adopters can deviate from this.
-Theia uses/reuses industrial standard technologies and practices whenever applicable. This keeps the scope of the project minimal and decreases the maintenance cost. This applies to the use of frameworks and development tools as well as to general concepts such as UX.
-The Eclipse Theia project does not primarily aim to provide products for end users but focuses on offering a platform for building products. However, the project provides product templates, a.k.a. “Blueprints”. These blueprints serve two purposes. First, they allow adopters to consume example Theia-based products from the view point of an end user, which enables them to evaluate the underlying platform without first creating a product based on it. Second, the blueprints serve as templates to create custom products. Therefore, the template products contain documentation on how to customize them.
-Eclipse Theia is an open and vendor-neutral project with a diverse community of contributors from large corporations down to small companies and even individual developers. This diverse and steadily growing community is a stable base for the ongoing development of additional features and maintenance of existing functionality based on a broad and balanced view of the requirements put forward by the Theia adopters. The commercial-friendly licensing and the rigorous underlying IP management ensures that adopters can safely build commercial and internal products based on Theia. Project communication is open and transparent and welcomes new adopters by keeping the barriers of contribution as low as possible. Decisions in the project are based on the principle of meritocracy meaning that the weight of contributors in decisions is solely based on their achievements for the project as recognized by their peers. This provides an important incentive for contributors to make contributions. The open governance and diverse community of Theia is one of its strongest assets for its mid- to long-term evolution and viability.
Many IDEs, such as the traditional Eclipse IDE, have the notion of a global, extensible property view, -which shows additional information about the current selection within the IDE. -Property views are heavily used in those IDEs for showing details of elements in e.g. diagram editors, -complex tree editors, or the file explorer selection. -Therefore, the main idea is to have a global, generic property view in the IDE, -but allow specific implementations to extend the contents of the global property view -with specific additional information for some type of selection.
-The @theia/property-view extension contributes a generic, global property view based on Theia's global selection.
-The property view widget can be opened/toggled either via menu View->Properties or via shortcut Shift+Alt+P.
-It is located in the bottom dock area by default.
-The following two default content widgets are implemented in this extension:
EmptyPropertyViewWidget: If no other widget can be provided, a simple message (No properties available) is shown.ResourcePropertyViewWidget: Displays additional information about a file (e.g. location, name, last modified) that is selected in the file explorer or in the active monaco editor.To contribute a specific property view, it is necessary to implement a PropertyViewDataService which gathers the property data for a selection
-as well as a PropertyViewWidgetProvider which provides a suitable content widget to display the property data for a specific selection inside the property view widget.
Here is a short example of how to implement an additional property view, which displays the name and whether it is a file or directory
-in a simple React widget based on the selection from the file explorer (assuming there would be no ResourcePropertyViewWidget of course):
The FileInfoPropertyDataService gathers the file information and delivers a custom object:
custom-data-service.ts:
export interface FileInfoPropertyObject {
- name: string;
- isDirectory: boolean;
-}
-
-@injectable()
-export class FileInfoPropertyDataService implements PropertyDataService {
-
- readonly id = 'fileinfo';
- readonly label = 'FileInfoPropertyDataService';
-
- @inject(LabelProvider) protected readonly labelProvider: LabelProvider;
-
- canHandleSelection(selection: Object | undefined): number {
- return this.isFileSelection(selection) ? 1 : 0;
- }
-
- private isFileSelection(selection: Object | undefined): boolean {
- return !!selection && Array.isArray(selection) && FileSelection.is(selection[0]);
- }
-
- async providePropertyData(selection: Object | undefined): Promise<FileInfoPropertyObject | undefined> {
- if (this.isFileSelection(selection) && Array.isArray(selection)) {
- return {
- name: this.labelProvider.getName(selection[0].fileStat.resource),
- isDirectory: (selection[0].fileStat as FileStat).isDirectory
- };
- }
- return Promise.reject();
- }
-}The FileInfoPropertyWidget is a simple ReactWidget and displays the selected node and whether it is a file or directory:
custom-content-widget.tsx:
export class FileInfoPropertyViewWidget extends ReactWidget implements PropertyViewContentWidget {
-
- static readonly ID = 'file-info-property-view';
- static readonly LABEL = 'File Information';
-
- protected currentFileInfo: FileInfoPropertyObject;
-
- constructor() {
- super();
- this.id = FileInfoPropertyViewWidget.ID;
- this.title.label = FileInfoPropertyViewWidget.LABEL;
- this.title.caption = FileInfoPropertyViewWidget.LABEL;
- this.title.closable = false;
- this.node.tabIndex = 0;
- }
-
- updatePropertyViewContent(propertyDataService?: PropertyDataService, selection?: Object | undefined): void {
- if (propertyDataService) {
- propertyDataService.providePropertyData(selection).then((fileInfo: FileInfoPropertyObject) => this.currentFileInfo = fileInfo);
- }
- this.update();
- }
-
- protected render(): React.ReactNode {
- return (<div>
- {`Selected node in explorer: ${this.currentFileInfo.name} ${this.currentFileInfo.isDirectory ? '(Directory)' : '(File)'}`
- }
- </div>);
- }
-}The FileInfoPropertyViewWidgetProvider is responsible to provide the correct PropertyViewContentWidget based on the selection:
custom-widget-provider.ts:
@injectable()
-export class FileInfoPropertyViewWidgetProvider extends DefaultPropertyViewWidgetProvider {
-
- override readonly id = 'fileinfo';
- override readonly label = 'FileInfoPropertyViewWidgetProvider';
-
- private fileInfoWidget: FileInfoPropertyViewWidget;
-
- constructor() {
- super();
- this.fileInfoWidget = new FileInfoPropertyViewWidget();
- }
-
- override canHandle(selection: Object | undefined): number {
- return this.isFileSelection(selection) ? 1 : 0;
- }
-
- private isFileSelection(selection: Object | undefined): boolean {
- return !!selection && Array.isArray(selection) && FileSelection.is(selection[0]);
- }
-
- override provideWidget(selection: Object | undefined): Promise<FileInfoPropertyViewWidget> {
- return Promise.resolve(this.fileInfoWidget);
- }
-
- override updateContentWidget(selection: Object | undefined): void {
- this.getPropertyDataService(selection).then(service => this.fileInfoWidget.updatePropertyViewContent(service, selection));
- }
-}In the frontend module of the application the FileInfoPropertyDataService as well as the FileInfoPropertyViewWidgetProvider are registered as follows:
bind(PropertyDataService).to(FileInfoPropertyDataService).inSingletonScope();
-bind(PropertyViewWidgetProvider).to(FileInfoPropertyViewWidgetProvider).inSingletonScope();Following these few steps should give the reader an idea on how to implement an own property view, consisting of a specific PropertyViewWidgetProvider and PropertyViewDataService.
The resulting property view will be displayed like this:
-
In this section we describe how Theia extensions can use services provided by the platform and by other extensions. Furthermore, we describe how extensions can contribute to the Theia workbench via contribution points.
-A service is an object that provides functionality to its consumers. The contract between a service and its consumers is described by an interface. Any implementation of a service must implement that interface according to the interface documentation. Any extension in Theia can provide and/or consume services. The extensions provided by the Theia platform provide a set of default services, e.g. the MessageService. However, you can provide and consume your own custom services, too.
Contribution points define hooks, which allow extending something. Contribution points are defined by an interface that the contributor is expected to implement, e.g. a CommandContribution. The extension defining the contribution point will then pick up the contribution, e.g. adding the contributed command to the Theia workbench.
Contribution points, like services, can be contributed to and defined by any extension. The Theia platform defines a set of default contribution points, e.g. to add commands or menus to the Theia workbench. However, you can also define your own ones.
-The usage of services and contribution points requires communication between extensions. To avoid direct dependencies on the implementation classes, Theia uses dependency injection.
-
-In the following sections, we provide a quick overview of dependency injection, services, contributions and how to define contribution points.
-Theia uses the DI framework InversifyJS to wire ups the difference services and contributions points.
-Dependency injection decouples the consumers of services -- i.e. the dependencies of those consumers -- from the actual creation and retrieval of those services. As an example, if you want to use a service, you neither have to instantiate it, nor do you need to manually retrieve it from somewhere. Instead, the dependency injection container injects the services on creation of your component. The dependency injection container resolves the dependency for you and, if necessary, even instantiates it on the fly. With that, the consumer of services doesn’t need to worry where they come from. You can easily exchange the actual implementations of services later on without having to change the consumers. The dependency injection container works based on some configuration you provide on startup through so-called container modules.
-We will provide examples on how to use dependency injection in the sections “Services” and “Contributing to contribution points” below.
-Dependency injection is an integral part of Theia. Therefore, we highly recommend learning at -least the basics of InversifyJS. For more details, please also refer to this article on how dependency injection works in Theia
-To use a service in Theia, you can get it injected as a dependency using DI. Dependencies are usually specified via the interface of the service you want to retrieve. This way, you even avoid a dependency on any specific implementation, the caller just knows the interface. This allows the component providing the implementation to seamlessly replace the implementation of a service. You can even override the existing default implementation of a service without breaking any service consumers.
-To get a parameter injected from the dependency injection container, you need to annotate it with an identifier (a string). Service providers on the other hand will publish the available services using an identifier, too. When a parameter with a specific identifier is requested via dependency injection, the dependency injection context will look it up and return an instance of the respective service. For convenience service providers usually use a Symbol as an identifier that has exactly the same name as the respective service interface itself. The following examples the '@inject(MessageService)' is the symbol (service identifier), while 'private readonly messageService: MessageService' is referring the interface of the service.
-Services, or more generically, dependencies can be injected as fields, in the constructor or in initialization functions (see following code example).
-// Injection in the constructor.
-constructor(@inject(MessageService) private readonly messageService: MessageService) { }
-
-// Injection as a field.
-@inject(MessageService)
-protected readonly messageService!: MessageService;
-
-// Injection in an initialization function (will be called after the constructor and after injecting fields.
-@postConstruct()
-protected async init(@inject(MessageService) private readonly messageService: MessageService) { }Please note that injection will only work in components that are created by the DI container. Therefore, they must be marked with @injectable (see code example below). Furthermore, they must be registered in the DI context (for an example see next section).
@injectable()
-export class MyContribution implements SomeContributionInterfaceContribution Points in Theia define an interface to be implemented, e.g. CommandContribution. A contributing extension must provide an implementation of this interface and mark it with @injectable, e.g.:
mycommand-contribution.ts
-@injectable()
-export class MyCommandContribution implements CommandContributionAdditionally, the contribution must be bound in the DI container, so that the contribution point provider can pick up our contribution, more precisely get it injected. The binding is done in the container module of an extension. It binds the implementation to the contribution interface, or to be technically correct, to the Symbol representing the interface (see example below).
-helloworld-frontend-module.ts
-export default new ContainerModule(bind => {
- // add your contribution bindings here
- bind(CommandContribution).to(HelloworldCommandContribution);
-...
-});Please see Commands/Menus/Keybindings for a simple example for the usage of services and contribution points.
-If an extension wants to provide a hook for others to contribute to, they -should define a contribution-point. A contribution-point is just an -interface that many others can implement. The extension will delegate to them -when needed.
-The OpenerService, for instance, defines a contribution point to allow others
-registering OpenHandlers. You can have a look at the code
-here.
Theia comes with an extensive list of contribution points already. A good way
-to see what contribution points exist is to do a find references on
-bindContributionProvider.
A contribution provider is basically a container for contributions where -contributions are instances of a bound type.
-It is very generic.
-To bind a type to a contribution provider you can do like this:
-(From messaging-module.ts)
-export const messagingModule = new ContainerModule(bind => {
- bind<BackendApplicationContribution>(BackendApplicationContribution).to(MessagingContribution);
- bindContributionProvider(bind, ConnectionHandler)
-});The last line will bind a ContributionProvider to one that contains all -ConnectionHandler bound instances.
-It is used as such:
-(From messaging-module.ts)
- constructor( @inject(ContributionProvider) @named(ConnectionHandler) protected readonly handlers: ContributionProvider<ConnectionHandler>) {
- }
-So here we're injecting a ContributionProvider with the named
-ConnectionHandler value that was bound before by bindContributionProvider.
This enables anyone to bind a ConnectionHandler and now when the -messagingModule is started all the ConnectionHandlers will be initiated.
Eclipse Theia users can execute tasks to automate certain steps in their workflow.
-Tasks can be invoked via the main menu Terminal or via the command palette.
-Every task is defined by a task configuration, which specifies among other properties the task type, a label, optionally a description, whether it is a background task or not, whether it is a build or test task, its dependencies to other tasks, etc.
-Tasks in Eclipse Theia are structurally compatible with Visual Studio Code tasks.
-Similar to Visual Studio Code, users can define tasks in a file named tasks.json file in the workspace or on user level.
In Eclipse Theia, tasks can also be provided from and executed by custom Theia extensions.
-In particular, Theia offers the three main contribution points for tasks: TaskProvider, TaskResolver and TaskRunner.
-To better understand the purpose of those, let’s look at the flow, through the involved components, when a user selects and executes a task in the following figure.
-Besides the user-defined task configurations, Eclipse Theia will also offer its users all task configurations collected from the registered task providers. -When a user selects one of the provided task configurations and executes it, the configuration will be handed over to the task service, which will first resolve the selected task configuration using a resolver that is registered for the selected task configuration’s type. -A task resolver can manipulate the task configuration before it is actually executed. -This is useful for, e.g., filling in default values and resolving custom variables in a task configuration. -Once the configuration is resolved, the task service requests the execution of the resolved task configuration on the task server, which runs on the backend. -To actually perform the resolved task configuration, the task server looks up the task runner registered for the configuration’s type. -Finally, the task runner is responsible for actually performing the task according to the specified task configuration.
-Theia provides dedicated contribution points for task providers, task resolvers, and task runners. -Thus, Theia extensions can extend the list of available tasks with custom task types, handle the resolution of task configurations of custom task types, as well as implement their execution.
-In the following example, we will contribute a custom task provider, which provides a custom task. -Further, we will add a custom task resolver that will enhance the task configuration before execution. -Finally, we will contribute a custom task runner that executes our provided task.
-Task providers and task resolvers are contributed via an implementation of TaskContribution.
-Like all contributions, it must be bound in the respective front end module as shown below.
-If you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
export default new ContainerModule(bind => {
- bind(TaskContribution).to(MyTaskContribution);
-});Our TaskContribution contributes a task provider and a task resolver (see following listing). Their implementation is shown below. By specifying a task type along with the registration, Theia will pick the right resolver and runner for our custom task type (myTaskType).
@injectable()
-export class MyTaskContribution implements TaskContribution {
-
- registerProviders(providers: TaskProviderRegistry): void {
- providers.register('myTaskType', new MyTaskProvider())
- }
-
- registerResolvers(resolvers: TaskResolverRegistry): void {
- resolvers.registerTaskResolver('myTaskType', new MyTaskResolver())
- }
-}Our example task provider contributes exactly one task:
-class MyTaskProvider implements TaskProvider {
- async provideTasks(): Promise<TaskConfiguration[]> {
- return [{
- label: 'My Custom Task',
- type: 'myTaskType',
- _scope: 'MyTaskProvider'
- }];
- }
-}Our example task resolver always sets property myCustomValue to the static value 42.
-In a real scenario, it would check whether it is set in the specified taskConfig and only add it if it is not set. Or it would resolve variables specified in the taskConfig.
class MyTaskResolver implements TaskResolver {
- async resolveTask(taskConfig: TaskConfiguration):Promise<TaskConfiguration> {
- return {...taskConfig, myCustomValue: 42 }
- }
-}Task runners are contributed via a TaskRunnerContribution. As we use dependency injection to create the actual task runner, we bind the contribution and the task runner itself in our module:
export default new ContainerModule(bind => {
- bind(MyTaskRunner).toSelf().inSingletonScope();
- bind(TaskRunnerContribution).to(MyTaskRunnerContribution);
-});In our TaskRunnerContribution, we register an instance of our custom task runner at the TaskRunnerRegistry along with the task type our runner is responsible for.
@injectable()
-export class MyTaskRunnerContribution implements TaskRunnerContribution {
-
- @inject(MyTaskRunner)
- protected readonly myTaskRunner: MyTaskRunner;
-
- registerRunner(runners: TaskRunnerRegistry): void {
- runners.registerRunner('myTaskType', this.myTaskRunner);
- }
-}Task runners need to implement the interface TaskRunner.
-The function run receives the TaskConfiguration when a task is triggered and is responsible for actually running the operation.
-In our example, we instantiate a custom implementation of Task called MyTask and execute it with the current configuration.
-Using the existing interface Task allows us to connect the task to the TaskManager which will show visual feedback in the workbench during tasks execution (see screenshot below).
@injectable()
-export class MyTaskRunner implements TaskRunner {
-
- @inject(TaskManager)
- protected readonly taskManager: TaskManager;
-
- @inject(ILogger)
- protected readonly logger: ILogger;
-
- async run(config: TaskConfiguration, ctx?: string): Promise<Task> {
- const myTask = new MyTask(this.taskManager, this.logger,
- { config, label: 'My Custom Task' });
- myTask.execute(config.myCustomValue);
- return myTask;
- }
-}Finally, our custom task configuration will wait for 5000 ms and then print out the custom value we have added in our task resolver before:
-class MyTask extends Task {
- execute(myCustomValue: number) {
- this.logger.info(`Start running custom task: ${myCustomValue}`);
- setTimeout(() => {
- this.logger.info(`Finished running custom task: ${myCustomValue}`);
- this.fireTaskExited({ taskId: this.taskId, code: 0 });
- }, 5000);
- }
- …
-}As you can see in the screenshot below, our custom task is running for 5000 ms (as we set a timeout in MyTask) and then it stops.
-As can be seen in the console output, the task starts and finishes 5000 ms later, and prints the custom variable that has been added by the custom resolver.
-root INFO Start running custom task: 42
-root INFO Finished running custom task: 42Extensions can also omit contributing a task provider, but only contribute a runner (and optionally a resolver).
-As a consequence, those custom tasks are not provided automatically to users, but users can still configure tasks based on these custom task types in their tasks.json file.
-To support users in the creation of such user-defined task configurations for custom task types, Theia provides a dedicated contribution point for task definitions.
-A task definition essentially specifies a JSON schema defining the properties that can or need to be specified for a task of a certain custom type.
This section explains how to build custom AI assistants and integrate AI support into custom tools and IDEs using Theia AI. Theia AI, part of the Theia Platform, is a powerful framework designed to help tool builders integrate tailored AI capabilities into their tools and IDEs with ease (see also this Theia AI introduction). It provides reusable components, prompt management, LLM integration, and flexible user interfaces, allowing you to focus on delivering domain-specific AI features. This section is targeted at tool builders using Theia and Theia AI as a platform to build custom tools and IDEs. -For detailed information on how to use the experimental AI features in the Theia IDE as an end user, refer to the user documentation. -To learn how to generally extend Theia by creating Theia extensions, including AI ones, visit the extension authoring guide.
-
-High Level Architecture of Theia AI
-In this section, we will introduce the concept of agents and demonstrate how to create your own custom agents. An Agent in Theia AI is a self-contained component mediating between the user interface that triggers the agent, and the LLM. Thus, it is typically invoked with a user input or a UI event, collects relevant context, produces one or more prompts, handles the communication with a language model (LLM),, and invokes actions in the tool and/or returns outputs to the UI as a result. Each agent can have unique behavior based on its design.
-Agents can generally be integrated into any part of the tool (e.g., terminals, editors, custom widgets) and also interact with any available and exposed API of Theia to collect context, trigger actions, or show results. A special type of agent in Theia AI is ‘Chat Agent’, which is automatically integrated into Theia AI’s default chat UI. A chat agent handles conversational interactions, making them suitable for tasks like answering questions in a chat interface.
-An important design decision is how you split your AI feature set among agents. Please note that Theia AI enables any kind of modularity from one agent capable of handling many types of user requests or events to an agent delegating sub-tasks to other agents, or even several agents operating on one request. Agents can communicate with each other, so you can chain agents for one user request. This decision really depends on the specific use cases and project. Theia AI makes it easy to iteratively refine the modularity of agents while developing it. A good start is typically to start with one agent per use case.
-This guide will walk you through creating agents and chat agents using Theia AI, providing a deeper understanding of the framework and how to leverage it for custom use cases.
-In general, an agent is essentially an injectable Theia service offering a specific API for its clients, such as custom widgets, editors, or menu items. Clients can obtain the instance of the agent from the agent registry or get it injected via DI, and call its methods. Usually those methods are very use case specific, often taking parameters for context that are relevant and already available to the clients calling the agents. The agent will then construct one or more prompts, obtain one or more language models, process its output, invoke actions in Theia and/or return a result to the client, e.g. to show a result message, offer follow-up questions or buttons to perform actions.
-As you see, an agent is rather generic — and this is on purpose. It is designed to cater many different use cases integrated in a variety of UI components, widgets, or editors. An example of such an agent in the Theia IDE is the code completion agent integrated in the code editor.
-A Chat Agent is integrated into the default chat UI provided by Theia AI and thus needs to implement a more specific interface, so it can be invoked from the chat UI generically. It’s designed for conversational interaction with users.
-Let’s create a new agent for the Theia IDE as an example! This new agent will assist users in identifying (and later executing) arbitrary commands in the Theia IDE, such as opening the settings or showing the toolbar. You can review the full code of this agent as a reference.
-The first step in creating a chat agent is defining the system prompt template, which acts as the foundation for guiding how the agent interacts with the LLM.
-export const commandPromptTemplate: PromptTemplate = {
- id = 'command-chat-agent-system-prompt-template';
- template = `Always respond with: “I am the command agent`;
-}This template sets the behavior of the agent, in the example above, it will always respond with a test String for now.
-Next, we will create the chat agent, which allows you to customize the agent’s behavior, specify its language model requirements, which prompt templates it uses, and define its interaction with users. In our case, we want to create a simple Chat Agent for which we extend the reusable base implementation provided by Theia AI (see code example below).
-AbstractChatAgent takes care of a basic conversation flow and streaming, so we literally only need to define a name, an id, a description and which system prompt our agent uses. This agent will be available in the default chat UI and can be referenced via @Command. The agent will respond based on the behavior defined in the prompt.
export class CommandChatAgent extends AbstractChatAgent {
- id: string = 'Command';
- name: string = 'Command';
- description: string = `Helps users find and execute commands in the IDE`;
- variables: string[] = []; // Optional: define variables for dynamic data insertion.
- promptTemplates: PromptTemplate[] = [commandPromptTemplate];
-
- protected async getSystemMessage(): Promise<SystemMessage | undefined> {
- const systemPrompt = await this.promptService.getPrompt('command-system');
- return SystemMessage.fromResolvedPromptTemplate(systemPrompt);
- }
-}In the example above, we retrieve the prompt from Theia AIs Prompt Service. This provides features such as automatic variable resolvement. The usage of the Prompt Service is of course optional, as an agent implemented you can also simply define your own data structure if you prefer. -In the example above, we also register our prompt template with Theia AI. With this, Theia AI can provide generic features such as the prompt editor, but of course this is again up to the agent implementer whether to register prompts or not.
-To integrate our agent with Theia AI, we need to register it. Theia as a platform is modular, so we can just register the agent along with the existing agents via dependency injection, no forking or customization of Theia framework code is required. See also the section on services and contributions and specifically the section on contribution points. -In the following code example, we register our agent as an ‘Agent’ and as a ‘ChatAgent’. With this, the simple agent above will already be available in the default chat, you can directly “talk” to it via typing “@Command”. In the current state, it will of course only respond with “I am the command agent”.
-bind(Agent).toService(CommandChatAgent);
-bind(ChatAgent).toService(CommandChatAgent);The next step is typically the most effort and it is actually unrelated to Theia AI: You need to develop the behavior of the agent, including one or more prompts that reliably return the expected output.
-In our example, we want to return an executable Theia command that the user is looking for with their question. For this, we need to augment our prompt with variables (see section “Variables and Tool Functions”) to give the LLM the necessary context information on what Theia commands are available. Moreover, we want this response in a parsable format, so that we can easily detect the command selected by the LLM in its response and provide the user with the option to directly execute the command. See the section “Response Renderers” for more details.
-Getting such agent implementations right typically requires a bit of prompt evaluation with a set of expected user queries. A huge help in Theia AI is that you can modify the prompt templates at runtime to test different scenarios and tweak the prompt until you are satisfied, instead of changing the prompt templates in the code and need to rebuild after every change.
-Also, if the underlying LLM supports it, structured output is a huge time saver, as this usually guarantees that the output follows a specific format and avoids coping with variations in your agent’s parsing logic. -This guide is focussed on Theia AI and not about developing specific agents per se. If you need support building your own custom AI assistance, please get in contact with a service provider and browse our resource section.
-Agents often need to interact with the tool to fetch dynamic data, such as a text selection, project-data or any tool-specific data. Theia AI allows you to encapsulate this data access in Variables, which can then be used in prompts or user requests and will be resolved with the actual data from the tool at runtime. Furthermore, agents can use so-called Tool Functions that allow the underlying LLM to proactively call an action, either to retrieve more information or to trigger any kind of action including the modification of data.
-Theia AI by default supports two types of variables:
-Agent-specific variables are controlled by a specific agent. To fill a variable with data, you can literally use any internal Theia API or other external APIs or methods you like. As an example, let’s again look at the chat agent that assists users in identifying (and later executing) arbitrary commands in the Theia IDE, such as opening the settings or showing the toolbar. You can review the full code of this agent as a reference.
-To allow the underlying LLM to identify the right command, we want to send it a list with all available commands. To achieve this, we first retrieve a list of all available commands using the CommandRegistry (see code example below). This step is independent of Theia AI and you could retrieve any sort of data here instead. -Second, we resolve the variable ‘command-ids’ when receiving the system prompt’ (also see code example below).
-// Retrieve all available commands
-const knownCommands: string[] = [];
-for (const command of this.commandRegistry.getAllCommands()) {
- knownCommands.push(`${command.id}: ${command.label}`);
-}
-
-// Resolve the variable when retrieving the system prompt
-const systemPrompt = await this.promptService.getPrompt('command-chat-agent-system-prompt-template', {
- 'command-ids': knownCommands.join('\n')
-});Please note that the manual resolvement of variables is not necessary when using global variables. -Now we can simply use our agent-specific variable in our prompt templates, e.g. like this:
-You are a service that helps users find commands to execute in an IDE.
-
-These are the available commands:
-Begin List:
-{{command-ids}}
-End ListIf an agent uses agent-specific variables, it can decide to explicitly declare them. This enables one to keep track of used variables and optionally even show this information to the user (see example screenshot below).
-
-To declare an agent-specific variable, simply add it like this in the constructor of your agents, along with an optional description and whether it is used in the prompt template or not.
-this.agentSpecificVariables = [{
- name: 'command-ids',
- description: 'The list of available commands in Theia.',
- usedInPrompt: true
-}];Global variables are available to all agents. Therefore, they are provided as a dedicated contribution. In the following, we will define a simple global variable that resolves to the current date, i.e. to the time when the variable get resolved in a request. You can review the full code of this variable for a complete description. -A Global variable basically consists of four parts.
-First, we define the variable, as it can be used in requests. In the following example, we define two optional arguments to influence the format.
-export const TODAY_VARIABLE: AIVariable = {
- id: 'today-provider',
- description: 'Does something for today',
- name: 'today',
- args: [
- { name: TodayVariableArgs.IN_ISO_8601, description: 'Returns the current date in ISO 8601 format' },
- { name: TodayVariableArgs.IN_UNIX_SECONDS, description: 'Returns the current date in unix seconds format' }
- ]
-};Second, we register the variable using an ‘AIVariableContribution’ (see code example below). Third, we resolve the variable (also see code example below). Please note that for resolving a variable, you can access all necessary APIs, including tool-specific API or custom services.
-export class TodayVariableContribution implements AIVariableContribution, AIVariableResolver {
- // Register the variable resolver
- registerVariables(service: AIVariableService): void {
- service.registerResolver(TODAY_VARIABLE, this);
- }
-
- async resolve(request: AIVariableResolutionRequest, context: AIVariableContext): Promise<ResolvedAIVariable | undefined> {
- if (request.variable.name === TODAY_VARIABLE.name) {
- return this.resolveTodayVariable(request);
- }
- return undefined;
- }
-
- private resolveTodayVariable(request: AIVariableResolutionRequest): ResolvedTodayVariable {
- const date = new Date();
- if (request.arg === TodayVariableArgs.IN_ISO_8601) {
- return { variable: request.variable, value: date.toISOString(), date };
- }
- if (request.arg === TodayVariableArgs.IN_UNIX_SECONDS) {
- return { variable: request.variable, value: Math.round(date.getTime() / 1000).toString(), date };
- }
- return { variable: request.variable, value: date.toDateString(), date };
- }
-}
-
-...
-
-bind(AIVariableContribution).to(TodayVariableContribution).inSingletonScope();It can now be used in any prompt template, as well as in user requests.
-Tool functions allow an agent to provide capabilities to the underlying LLM. Compared to variables, it is up to the LLM to decide whether to use an available function or not. Functions can be used to allow the LLM to retrieve additional information or to trigger actions in the tool. Actions can be literally anything you want the LLM to be able to trigger, including modifications of data. Tool Functions can be used in requests, similarly to variables as shown in the following prompt example:
-Use the following functions to access the workspace:
-- ~{getWorkspaceFileList}
-- ~{getFileContent}.To implement your own tool functions, provide an implementation of interface ‘ToolProvider’, in which you specify the ID, optionally parameters and a handler that represented the function to be called, e.g. like this:
-@injectable()
-export class FileContentFunction implements ToolProvider {
- static ID = FILE_CONTENT_FUNCTION_ID;
-
- getTool(): ToolRequest {
- return {
- id: FileContentFunction.ID,
- name: FileContentFunction.ID,
- description: 'Get the content of the file',
- parameters: {
- type: 'object',
- properties: {
- file: {
- type: 'string',
- description: 'The path of the file to retrieve content for',
- }
- }
- },
- handler: (arg_string: string) => {
- const file = this.parseArg(arg_string);
- return this.getFileContent(file);
- }
- };
- }
-}
-See here for the full example listed above. In the handler, you can call literally any available API to execute arbitrary actions or retrieve arbitrary content, including tool-specific things.
-Finally, register your ‘ToolProvider’ like this:
-bind(ToolProvider).to(FileContentFunction);This section explains the process of converting an LLM (Large Language Model) response into custom UI controls within the Theia AI default chat (or any custom chat implementation). Custom UI control can be specially highlighted text, clickable buttons or literally anything that you want to display to your users. -As an example, we will use the command chat agent used in this documentation before, which is capable of identifying a command in the Theia IDE based on the user's request. We will augment this agent to render commands that the agent returns as buttons. By clicking the button, users can then directly invoke a command.
-Let’s look at the basic control flow of a chat request in Theia AI (see diagram below). The flow starts with a user request in the default Chat UI (1), which is sent to the underlying LLM (2) to return an answer (3). By default, the agent can forward the response to the Chat UI as-is. However, in our scenario, the agent will parse the response and augment it with a structured response content (4). Based on this, the chat UI can select a corresponding response part renderer to be shown in the UI (5).
-
-In the following, we will dive into the details on how to implement this flow.
-The first step to enable structured response parsing is developing a prompt that reliably returns the expected output. In this case, the output should include an executable Theia command related to the user's question in JSON format. The response needs to be in a parsable format, allowing the system to detect the command and provide the user with the option to execute it.
-An simplified example of such a prompt might look like the following (you can review the full prompt template here)
-You are a service that helps users find commands to execute in an IDE.
-You reply with stringified JSON Objects that tell the user which command to execute and its arguments, if any.
-
-Example:
-
-\`\`\`json
-{
- "type": "theia-command",
- "commandId": "workbench.action.selectIconTheme"
-}
-\`\`\`
-
-Here are the known Theia commands:
-
-Begin List:
-{{command-ids}}
-End ListAs described in the previous section the variable {{command-ids}} is dynamically populated with the list of available commands.
After receiving the LLM response, the next step is to parse it in the agent implementation and transform it into a response content that can then be processed by the Chat UI. In the following code example:
-CommandChatResponseContentImpl object is created to wrap the command.You can review the parsing code, including error handling here)
-Example code:
-const parsedCommand = JSON.parse(jsonString) as ParsedCommand;
-const theiaCommand = this.commandRegistry.getCommand(parsedCommand.commandId);
-return new CommandChatResponseContentImpl(theiaCommand);Please note that a chat response can contain a list of response parts, allowing various UI components to be mixed with actionable response components.
-The final step is to display a button in the Chat UI to allow users to execute the command. This is done by creating a new Response Part Renderer. The renderer is registered to handle CommandChatResponseContent, ensuring that the Chat UI calls it whenever a corresponding content type is part of the response.
The following example code shows the corresponding response renderer, you can review the full code here.
-canHandle Method: Determines whether the renderer can handle the response part. If the response is of type CommandChatResponseContent, it returns a positive value, indicating it can process the content.render Method: Displays a button if the command is enabled. If the command is not executable globally, a message is shown.onCommand Method: Executes the command when the button is clicked.canHandle(response: ChatResponseContent): number {
- if (isCommandChatResponseContent(response)) {
- return 10;
- }
- return -1;
-}
-
-render(response: CommandChatResponseContent): ReactNode {
- const isCommandEnabled = this.commandRegistry.isEnabled(response.command.id);
- return (
- isCommandEnabled ? (
- <button className='theia-button main' onClick={this.onCommand.bind(this)}>{response.command.label}</button>
- ) : (
- <div>The command has the id "{response.command.id}" but it is not executable globally from the Chat window.</div>
- )
- );
-}
-
-private onCommand(arg: AIChatCommandArguments): void {
- this.commandService.executeCommand(arg.command.id);
-}Finally, the custom response renderer needs to be registered:
-bind(ChatResponsePartRenderer).to(CommandPartRenderer).inSingletonScope();By following the steps outlined, you can transform an LLM response into custom and optionally actionable UI controls within Theia AI. See the Theia IDE documentation on how the example looks integrated in a tool. -This approach enables users to interact with the AI-powered Chat UI more efficiently, e.g. allowing executing commands directly from the suggestions provided.
-Theia AI currently provides out-of-the-box support for any OpenAI-compatible LLM services (including the OpenAI models hosted by OpenAI or self-hosted compatible LLMs) and Ollama LLMs. We are also working on integrating support for LLamaFile. As a tool provider, you can easily add support for other LLM APIs too. Please consider contributing any further LLM providers to the open source project, so that the community can benefit from increased compatibility and share the maintenance cost.
-To support a specific LLM, you basically need to provide an implementation of the interface ‘LanguageModel’, which provides an abstraction between agents and the underlying LLM. This Language Model is then registered at the ‘LanguageModelRegistry’, to make it retrievable for agents, e.g. like this:
-this.languageModelRegistry.addLanguageModels([new OllamaModel());If you want to allow the user to configure the LLM provider, e.g. change the URL or the available models, consider integrating your LLM provider with Theias preference system.
-For further details, we recommend reviewing the available LLM provider in Theia AI:
- -Please note that Theia AI currently does not provide a fixed contribution point for Language Models, yet. This is due to the fact that we are working on supporting more models and also capabilities of new LLMs are emerging at the moment, such as function calling and structured output. We plan to consolidate the LLM Provider interfaces within the next months while adding more LLM Providers to the core framework. We are happy for feedback and contributions in this area.
-If want to learn more about the AI support in the Theia AI, please see this Theia AI introduction, our article on the vision of Theia AI and the demonstrations in Sneak Preview Series about Theia AI
In this section we'll outline some advanced hints and tips to get the most out of developing tools based on Eclipse Theia.
-Theia allows running VS Code extension by providing a compatible API (see this overview for details). -It is possible to extend this API to allow VS Code extensions running in Theia to access additional functionality compared to when they run within VS Code. -This allows you to provide a feature as a VS Code extension targeting VS Code and Theia. However, when running in Theia, the feature can be enhanced by using custom API only available in Theia.
-The following code example shows the usage custom API which is invoked only when running in a Theia-based application. This is determined via the application name. -The API is imported asynchronously to avoid runtime errors in VS Code.
-if (vscode.env.appName === MY_THEIA_APP_NAME) {
- // Implement Theia API
- const api = await import('@mytheiaextension/mycustomapi');
- // After importing the custom API, it can be used as any other API. The following lines are using an example API.
- api.host.getMessageHandler(() => getMessage());
- api.host.onRequestMessage((actor: string) => {
- const message = getMessage(actor);
- api.host.showMessage(message);
- });
-}An alternative to providing a custom API is to define custom commands. Again, these commands would only be available if the VS Code extension is running in Theia (see following code example).
-if (vscode.env.appName === MY_THEIA_APP_NAME) {
- // Execute Theia custom command
- const commands = await vscode.commands.getCommands();
- if (commands.indexOf(MY_THEIA_CUSTOM_COMMAND) > -1) {
- vscode.commands.executeCommand(MY_THEIA_CUSTOM_COMMAND);
- }
-}An example of this technique can be seen here:
-Eclipse Theia provides an optional and fully dynamic toolbar to be included in your custom IDE or tool. Please also see the documentation of the toolbar from a user point of view.
-To enable the toolbar, simply include the Theia extension "@theia/toolbar" into your Theia-based product (also see the documentation on composing Theia applications).
-The Theia toolbar defines some default commands that are displayed even before the user can configure the toolbar to their preferences. These defaults are defined in a ToolbarDefaultsFactory. See here for the default ToolbarDefaultsFactory that is shipped within the toolbar extension.
-To define your own default commands to the toolbar, create a custom implementation of ToolbarDefaultsFactory and rebind you own factory in your extension module (see following code example).
if (isBound(ToolbarDefaultsFactory)) {
- rebind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);
-} else {
- bind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);
-}This section documents how to use AI features in the Theia IDE (available since version 1.54, see also this introduction). These features are based on Theia AI, a framework for building AI assistance in tools and IDEs. Theia AI is part of the Theia platform. If you're interested in building your own custom tool or IDE with Theia AI, please refer to the corresponding documentation.
-Please note that these features are in early access and experimental. This means they may be unstable, behave unexpectedly, or undergo significant changes. In particular, using your own LLM might incur costs that you need to monitor closely. We have not yet optimized the AI assistants in the Theia IDE for token usage. Use these features at your own risk, and we welcome any feedback, suggestions, and contributions!
-Theia AI features within the Theia IDE are currently disabled by default. See the next section on how to enable them.
-To activate AI support in the Theia IDE, go to Preferences and enable the setting “AI-features => AI Enable.”
-To use Theia AI within the Theia IDE, you need to provide access to at least one LLM. Theia IDE comes with preinstalled support for OpenAI API-compatible models, either hosted by OpenAI or self-hosted via VLLM. Additionally, Theia IDE supports connecting to models via Ollama. See the corresponding sections below on how to configure these providers.
-Other LLM providers, including local models, can be added easily. We are also working on enabling LLamaFile support in the near future. If you would like to see support for a specific LLM, please provide feedback or consider contributing.
-Each LLM provider offers a configurable list of available models (see the screenshot below for OpenAI models). To use a model in your IDE, configure it on a per-agent basis in the AI Configuration view.
-To enable the use of OpenAI, you need to create an API key in your OpenAI account and enter it in the settings dialog (see the screenshot below). Please note that creating an API key requires a paid subscription, and using these models may incur additional costs. Be sure to monitor your usage carefully to avoid unexpected charges. We have not yet optimized the AI assistants in the Theia IDE for token usage.
-
-The OpenAI provider is preconfigured with a list of available models. You can easily add new models to this list, for example, if new options are released.
-As an alternative to using an official OpenAI account, Theia IDE also supports arbitrary models compatible with the OpenAI API (e.g., hosted via VLLM). This enables you to connect to self-hosted models with ease. To add a custom model, click on the link in the settings section and add your configuration like this:
-{
- "ai-features.openAiCustom.customOpenAiModels": [
- {
- "model": "your-model-name",
- "url": "your-URL",
- "id": "your-unique-id", // Optional: if not provided, the model name will be used as the ID
- "apiKey": "your-api-key" // Optional: use 'true' to apply the global OpenAI API key
- }
- ]
-}To configure a LlamaFile LLM in the Theia IDE, add the necessary settings to your configuration (see example below)
-{
- "ai-features.llamafile.llamafiles": [
- {
- "name": "modelname", //you can choose a name for your model
- "uri": "file:///home/.../YourModel.llamafile",
- "port": 30000 //you can choose a port to be used by llamafile
- }
- ]
-}Replace "name", "uri", and "port" with your specific LlamaFile details.
-The Theia IDE also offers convenience commands to start and stop your LlamaFiles:
-Please make sure that your LlamaFiles are executable. -For more details on LlamaFiles, including a quickstart, see the official Mozilla LlamaFile documentation.
-To connect to models hosted via Ollama, enter the corresponding URL, along with the available models, in the settings (as shown below).
-
-This section provides an overview of the currently available agents in the Theia IDE. Agents marked as “Chat Agents” are available in the global chat, while others are directly integrated into UI elements, such as code completion. You can configure and deactivate agents in the AI Configuration view.
-This agent helps developers by providing concise and accurate answers to general programming and software development questions. It also serves as a fallback for generic user questions. By default, this agent does not have access to the current user context or workspace. However, you can add variables, such as #selectedText, to your requests to provide additional context.
This agent analyzes user requests against the descriptions of all available chat agents and selects the best-fitting agent to respond (using AI). The user's request is delegated to the selected agent without further confirmation. The Orchestrator is currently the default agent in the Theia IDE for all chat requests. You can deactivate it in the AI Configuration View.
-This agent is aware of all commands available in the Theia IDE and the current tool the user is working with. Based on the user request, it can find the appropriate command and let the user execute it.
-This agent can access the user's workspace, retrieve a list of all available files, and view their content. It can answer questions about the current project, including project files and source code in the workspace, such as how to build the project, where to place source code, or where to find specific files or configurations.
-This agent provides inline code completion within the Theia IDE's code editor. It continuously shows suggestions while writing, and users can press TAB to insert the current suggestion. Note that this agent makes continuous requests to the underlying LLM while coding.
-This agent assists with writing and executing terminal commands. Based on the user's request, it suggests commands and allows them to be directly pasted and executed in the terminal. It can access the current directory, environment, and recent terminal output to provide context-aware assistance. You can open the terminal assistance agent via Ctrl+I in the terminal view.
-The Theia IDE provides a global chat interface where users can interact with all chat agents. The Orchestrator automatically delegates user requests to the most appropriate agent. To send a request directly to a specific agent, mention the agent's name using '@', for example, '@Command'. Press '@' in the chat to see a list of available chat agents.
-
-Some agents produce special results, such as buttons (shown in the screenshot above) or code that can be directly inserted. You can augment your requests in the chat with context by using variables. For example, to refer to the currently selected text, use #selectedText in your request. Pressing '#' in the chat will show a list of available variables.
The AI Configuration View allows you to review and adapt agent-specific settings. Select an agent on the left side and review its properties on the right:
-
-In the Theia IDE, you can open and edit prompts for all agents from the AI Configuration View. Prompts are shown in a text editor (see the screenshot below). Changes saved in the prompt editor will take effect with the next request made to the corresponding agent. You can reset a prompt to its default using the "Reset" button in the AI configuration view or the "Revert" toolbar item in the prompt editor (top-right corner).
-
-Variables and functions can be used in prompts. Variables are replaced with context-specific information at the time of the request (e.g., the currently selected text), while functions can trigger actions or retrieve additional information. You can find an overview of all global variables in the "Variables" tab of the AI Configuration View and agent-specific variables in the agent's configuration.
-Variables are used with the following syntax:
-{{variableName}}Tool functions are used with the following syntax:
-~{functionName}Custom agents enable users to define new chat agents with custom prompts on the fly, allowing the creation of custom workflows and extending the Theia IDE with new capabilities. These agents are immediately available in the default chat.
-To define a new custom agent, navigate to the AI Configuration View and click on "Add Custom Agent".
-
-This action opens a YAML file where all available custom agents are defined. Below is an example configuration:
-- id: obfuscator
- name: Obfuscator
- description: This is an example agent. Please adapt the properties to fit your needs.
- prompt: Obfuscate the following code so that no human can understand it anymore. Preserve the functionality.
- defaultLLM: openai/gpt-4oCustom agents can be configured in the AI Configuration View just like other chat agents. You can enable/disable them, modify their prompt templates, and integrate variables and functions within these templates to enhance functionality.
-The AI History view allows you to review all communications between agents and underlying LLMs. Select the corresponding agent at the top to see all its requests in the section below.
-
-If want to learn more about the AI support in the Theia AI, please see this introduction, our article on the vision of Theia AI and the demonstrations in Sneak Preview Series about Theia AI
The Theia IDE is a modern and open IDE for cloud and desktop. The Theia IDE is based on the Theia platform.
-
-This section is about using the Theia IDE from an end user point of view. Please note that the Theia IDE is based on the Theia Platform, a technology to build tools and IDEs. As an end user, you are not using “Theia”, but always a product based on Theia, in this case the Theia IDE. If you are using another product based on Theia, please consider the specific end user documentation of the product you are using over this section.
-The Theia IDE features and usability concept is heavily influences by VS Code. Therefore, for many use cases, we refer to the VS Code documentation. We still provide some selected documentation about use cases which are differing or not supported in VS Code:
- -Please note that you can also use the Theia IDE as a basis to create your own custom product.
You can install VS Code extensions into Theia-based products via the Open VSX Registry, aka “Theia Marketplace” or “Theia Extension Registry”.
-Note: To be able to install extensions, the creator of your Theia-based tool needs to have enabled this option. The following documentation is based on the Theia IDE, a standard product based on Theia. This might slightly differ from the Theia-based product you are using, please contact the provider of your tool if there are uncertainties and also see here. For tool creators, please see the end of this document.
-To install new extensions into the Theia IDE, please open the Extensions View via the Menu "View => Extensions" or via the command “Toggle Extensions View”.
-In the opened Extension View you can browse for available VS Code extensions using the search field on top (see screenshot below). In the list of matching extensions, you can review the details about an extension and directly install it by clicking on the “Install” button.
-The Extension View also presents recommendations to be installed, if any, as well as extensions that are already installed. Here, you can uninstall extensions by clicking “Uninstall”.
-
-The last section, “Built-In” shows VS Code extensions that are a fix part of your Theia-based product. This means the creator of your tool has installed them already for you and you can also not uninstall them.
-Every Theia version supports a specific VS Code extension API version, i.e. the extension API is fully provided by Theia until and including this VS Code version. In the Theia IDE, you can find the supported version in the about dialog (Menu "Help" => "About"). The Open VSX Registry will automatically show compatible VS Code extensions only.
-Extensions not listed as compatible might still work in Theia, as newer API versions are usually already partially implemented. In this case, you can manually install the extension via a VSIX file and test if it works (Use the command "Extensions: Install from VSIX...").
-Please note that a few parts of the VS Code extension API are only stubbed in Theia. Extensions will be installable, but some features might not work as expected.
-For details about the compatibility of Theia for VS Code extensions can be found in this report. This includes unsupported as well as stubbed parts of the API for all recent Theia versions.
-If you are missing a specific VS Code extension or if you have issues with using a VS Code extension in Theia, please report this to the creator of your Theia-based Tool. If you are using the Theia IDE or a variant of it, please report your issues here.
-For adopters: If you are building a Theia-based product, please have a look at our overview about extensions and plugins as well as at the documentation on authoring VS Code extensions in Theia.
Eclipse Theia provides a dynamic toolbar allowing easy access to commonly used commands. The toolbar contains default commands and can be dynamically adapted by users based on their personal preference.
-Note: To use the toolbar in Theia, the creator of your Theia-based tool needs to have enabled this option. The following documentation is based on the Theia IDE, a standard product based on Theia. This might slightly differ from the Theia-based product you are using, please contact the provider of your tool if there are uncertainties and also see here. For tool creators, please see the toolbar adopter documentation.
-As a user, you can control the default visibility of the Theia toolbar using the setting "Show Toolbar" (see screenshot below). Additionally, you can toggle the toolbar using "ALT+T" or via right-click on the toolbar => "Toggle Toolbar".
-
-The toolbar will show some default commands, which are configured by the provider of your Theia-based tool. As a user, you can add and remove commands. Further, you can change their position in the toolbar. To remove an existing command, right-click the icon in the toolbar and select "Remove Command From Toolbar". To change the position of an existing command, simply drag it around. The toolbar supports three columns to visually structure commands ("Left", "Center" and "Right"). -To add a new command to the toolbar, right click and select "Add Command to Toolbar" (see screenshot below). This will open a wizard that first allows you to select the command you want to add. In the second step, you can specify and icon that is used to display the new command in the toolbar. Finally, you select the column the new command will be placed in (you can still move it around later).
-
-To restore the default commands on the toolbar, right click and select "Restore Toolbar Defaults". Please note that this will delete all custom commands you might have added.
A widget is a part displaying content within the Theia workbench, e.g. a view or an editor. Examples for existing widgets in Theia are the file explorer, the code editor or the problems view. By contributing custom widgets, you can place your own custom UI in a Theia-based application. Your custom UI will behave the same as other widgets in terms of window layouts including the title tab, resizing, dragging and opening/closing (see screenshot below).
-
-Furthermore, a widget will receive events from the surrounding workbench, e.g. on application start, on resize or on detach. The implementation of the actual content of a widget, which is rendered in the provided frame is completely up to you, though. As an example, you can implement some custom UI using React within a widget.
-In a nutshell, a widget is a frame to embed some custom (HTML-based) UI into the Theia workbench (see diagram below)
-
-In this article we will describe how to contribute a custom widget to the Theia workbench. We will focus on a simple view (in contrast to an editor) and use React to implement the UI.
-If you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
-If you would like to have a look at the example code, please use the Theia extension generator. Install the generator, select the “Widget” example and enter “MyWidget” as a name for the extension.
-Contributing a widget, in our example a view consists of three components:
-For the implementation of custom widgets, Theia provides several base classes to inherit from. This enables you to focus on creating your custom UI only, as the base classes already implement most required functions. Theia does not depend on a specific UI technology, like React, Vue.js or Angular. However, it provides convenience support by providing respective base classes, e.g. for React. If in doubt, using React is the most common choice for implementing custom widgets at the moment. Below you find an excerpt of the class hierarchy. In case you want to implement a widget using react, choose ReactWidget as a base class. If you want to implement a widget that mainly displays a tree, use TreeWidget. If you do not want to use React, use BaseWidget. Browse the type hierarchy of BaseWidget to see other available options.
In the following code examples, we use ReactWidget as a base class. As shown below, we first initialize the widget with some base parameters:
id: To uniquely identify the widget, e.g. to open it via the WidgetManager.label: Shown in the tab when the widget is open.caption: Shown when hovering over the tab when the widget is open.closable: Whether the user can close the widget (via the “x” in the tab or via right click menu).iconClass: The icon shown in the tab when the widget is opened.mywidget-widget.tsx
-@injectable()
-export class MyWidget extends ReactWidget {
-
-static readonly ID = 'my:widget';
-static readonly LABEL = 'My Widget';
-
-@postConstruct()
-protected async init(): Promise < void> {
- this.id = MyWidget.ID;
- this.title.label = MyWidget.LABEL;
- this.title.caption = MyWidget.LABEL;
- this.title.closable = true;
- this.title.iconClass = 'fa fa-window-maximize'; // example widget icon.
- this.update();
-}When using the respective base class, the implementation of a widget can be really minimal and focused on the custom UI part. In our example, we just implement the render function that will create our actual custom UI (using JSX/React). The example UI contains a button that will trigger the displayMessage function below.
mywidget-widget.tsx (continued)
-protected render(): React.ReactNode {
- const header = `This is a sample widget which simply calls the messageService in order to display an info message to end users.`;
- return <div id='widget-container'>
- <AlertMessage type='INFO' header={header} />
- <button className='theia-button secondary' title='Display Message' onClick={_a => this.displayMessage()}>Display Message</button>
- </div>
-}
-
-@inject(MessageService)
-protected readonly messageService!: MessageService;
-
-protected displayMessage(): void {
- this.messageService.info('Congratulations: My Widget Successfully Created!');
-}Please note, that you can override functions of BaseWidget or ReactWidget to hook into specific life cycle events of a widget, e.g. onUpdateRequest or onResize. These events are defined by Phosphor.js, the underlying window management framework, see this documentation about the Widget class.
Besides implementing the actual widget, you need to wire it with the Eclipse Theia workbench, which is described in the next two sections.
-Widgets in Theia are instantiated and managed by a central service, the WidgetManager. This allows the application to keep track of all created widgets. As an example, the WidgetManager supports the function getOrCreate, which will either return an existing widget, if it was already created, or create a new one if not.
To make a custom widget instantiatable by the widget manager, you need to register a WidgetFactory. A widget factory consists of an ID and a function that creates the actual widget. The widget manager will collect all contributed widget factories and pick the correct one for a respective widget by ID.
In our example (see code below), we first bind our widget MyWidget to itself so that we can instantiate it in our factory using dependency injection. This is not necessarily required for all widgets if they do not use dependency injection inside. We are using dependency injection in our example above to retrieve the message service and for the @postConstruct event. Second, we bind a WidgetFactory defining the ID of the widget and the createWidget function. This function allows you to control the widget creation, e.g. to pass specific parameters to a custom widget if required. In our simple example, we just use the dependency injection context to instantiate our widget.
mywidget-frontend-module.ts
-bind(MyWidget).toSelf();
-bind(WidgetFactory).toDynamicValue(ctx => ({
- id: MyWidget.ID,
- createWidget: () => ctx.container.get<MyWidget>(MyWidget)
-})).inSingletonScope();Now you could already open a widget manually via using the widget manager API. However, for most use cases, you want to add a view to the view menu and also provide a respective command. This can be conveniently done using a widget contribution as described in the next section.
-Widget contributions allow you to wire a widget into the Theia workbench, more precisely to add them to the view menu and the quick command bar. Theia provides a convenient base class AbstractViewContribution to inherit from, which already implements the most common feature set (see example code below). For the initialization, you only need to specify the following parameters:
widgetID: The ID of the widget, used to open it via the widget managerwidgetName: The name which is displayed in the view menu. Usually the same name as used for the widget tab.defaultWidgetOptions: Option to influence where the widget will be displayed on opening, e.g. in the left area of the workbench. See the typedoc for more information.toggleCommandId: The command that opens the view. You can use the pre implemented openView function provided by the super class.Besides specifying these base parameters, you need to register the command to open the view. The base class implements the respective command contribution interface, so you just need to implement registerCommands to do so (see below).
mywidget-contribution.ts
-export const MyWidgetCommand: Command = { id: 'widget:command' };
-export class MyWidgetContribution extends AbstractViewContribution<MyWidget> {
- constructor() {
- super({
- widgetId: MyWidget.ID,
- widgetName: MyWidget.LABEL,
- defaultWidgetOptions: { area: 'left' },
- toggleCommandId: MyWidgetCommand.id
- });
- }
-
- registerCommands(commands: CommandRegistry): void {
- commands.registerCommand(MyWidgetCommand, {
- execute: () => super.openView({ activate: false, reveal: true })
- });
- }
-}With the contribution above, the view will now be shown in the standard “view” menu of Theia and you can also use the respective “open view” command to open it.
Not sure whether you need a web or desktop version or both?
With Theia you can develop one IDE and run it in a browser or as a native desktop application from a single source.
Theia is designed in a modular way to allow extenders and adopters to customize and extend every aspect.
This goes way beyond “just adding extensions”, because Eclipse Theia lets you build fully customized or white-labeled products!
Theia is truly vendor-neutral and developed by a diverse community. Unlike other “open source” projects, Theia is actually hosted at an Open-Source Foundation, protecting it against single-vendor decisions that are against the interest of the community. Learn more here.
Theia is based on a state-of-the-art web-based technology stack. It provides language support via LSP and DAP. Further, it can host VS Code extensions and provides full terminal access.
Eclipse Theia is a framework for building tools and IDEs. You can try it by building your own IDE/tools based on Theia within minutes. Alternatively, you can download and use the Theia IDE, a template tool based on Eclipse Theia or try it online.
Learn more about Eclipse Theia, how to get started with it, how to build your own tool/IDE and about the project's goals. Browse the documentation and resource section. Also, checkout the available introduction video below!
Checkout the available releases including changelogs, migration guides and news and noteworthy articles. Browse the project's sources and consume/download Theia packages from the npm registry.
Eclipse Theia is an open source project governed by the Eclipse Foundation. We are happy for any contributions! Please check out the contribution guide, our code of conduct and consider starting with good first issues.
Jonas Helming, Theia project lead and Principal Software Architect at EclipseSource
Jonas Helming, Theia project lead and Principal Software Architect at EclipseSource
Thomas Mäder, Theia project lead and Principal Software Developer at Red Hat
Unlock limitless possibilities with Theia IDE's seamless compatibility with the VS Code extension ecosystem. From robust linting tools to interactive notebook editors, customize your development experience like never before. Explore more than 3000 available extensions for the Theia IDE at open-vsx.org!
Experience world-class code editing support in Theia IDE, integrated with the Language Server Protocol (LSP). Develop in almost any programming language, including Python, Java, JavaScript, C++, and more—all within one environment.
Experience the future of development with Theia IDE's AI support. Built on Theia AI, the AI assistance offers unmatched transparency and control, allowing you to customize AI interactions, choose your preferred models—whether cloud-based, self-hosted, or local—tailor prompts to your workflow, and even create your own custom agents to automate individual workflows, all while maintaining full ownership of your data.
The Theia IDE is backed by a diverse and healthy open source ecosystem. Enjoy the added confidence of a fully open-source platform governed by a vendor-neutral community. Deploy and enrich your toolset on your own terms.
Elevate your development workflow with Theia IDE's flexible workbench layout and user experience. Featuring theming support, a dynamic toolbar, detachable views, and efficient tab management, our web-based interface is designed to adapt to your needs, streamlining your projects for optimal productivity.
The Theia IDE is built upon the highly modular Theia platform, enabling the integration of custom extensions and the creation of fully tailored tools (see examples below). Explore the Theia Platform and learn how to create custom tool offerings with ease!
This section describes the overall architecture of the Theia Platform.
\nTheia is designed to work as a native desktop application as well as in the\ncontext of a browser and a remote server. To support both situations with a\nsingle source, Theia runs in two separate processes. Those processes are called\nfrontend and backend respectively, and they communicate through JSON-RPC\nmessages over WebSockets or REST APIs over HTTP. In the case of Electron, the\nbackend, as well as the frontend, run locally, while in a remote context the\nbackend would run on a remote host.
\nBoth the frontend and backend processes have their dependency injection (DI)\ncontainer (see below) to which extensions can contribute.
\nThe frontend process represents the client and renders the UI. In the browser,\nit simply runs in the rendering loop, while in Electron it runs in an Electron\nWindow, which basically is a browser with additional Electron and Node.js APIs.\nTherefore, any frontend code may assume browser as a platform but not Node.js.
\nThe startup of the frontend process will first load the DI modules of all\ncontributing extensions before it obtains an instance of FrontendApplication\nand call start() on it.
The backend process runs on Node.js. We use express as the HTTP server. It\nmay not use any code that requires a browser (DOM API) as the platform.
\nThe startup of the backend application will first load the DI modules of all\ncontributing extensions before it obtains an instance of BackendApplication\nand calls start(portNumber) on it.
By default, the backend's express server also serves the code for the frontend.
\nIn an extension's top folder we have an additional layer of folders to separate\nby platform:
\n
common folder contains code that doesn't depend on any runtime.browser folder contains code requiring a modern browser as a platform\n(DOM API).electron-browser folder contains frontend code that requires DOM API\nas well as Electron renderer-process specific APIs.node folder contains (backend) code requiring Node.js as a platform.node-electron folder contains (backend) code specific for Electron.For a high level overview of Theia's Architecture, see this document:
\nMulti-Language IDE Implemented in JS - Scope and Architecture
","fields":{"slug":"architecture"}}},"pageContext":{"slug":"architecture"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/authoring_extensions/page-data.json b/pr-previews/pr-663/page-data/docs/authoring_extensions/page-data.json deleted file mode 100644 index d5bdab05..00000000 --- a/pr-previews/pr-663/page-data/docs/authoring_extensions/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/authoring_extensions/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Authoring an Extension"},"html":"This guide will walk you through the process of creating Theia extensions and deploying them in your Theia-based application. Please make sure to be aware of how to create a Theia based application and the different available extension mechanisms of Theia (Plugins vs. Extensions) before you continue reading.
\nAs an example, we are going to add a menu item Say hello that displays a notification \"Hello world!\". This article is guiding you through all the necessary steps.
\nPrerequisites information are available from the Theia repository.
\nPlease refer to the guide to create Theia applications to get familiar with the default project layout and generate a Theia project with the example 'hello world' extension using our Yeoman Generator
\nLet's look at the generated code for our extension in the hello-world folder. Let’s start with the package.json. It specifies the package’s metadata, its dependencies to the Theia core package, a few scripts and dev dependencies, and the theia-extension itself. Please note that the following listing might be outdated, please always refer to the generated examples from our Yeoman Generator
The keyword theia-extension is important: It allows a Theia app to identify and install Theia extensions from npm.
{\n \"name\": \"hello-world\",\n \"keywords\": [\n \"theia-extension\"\n ],\n \"version\": \"0.0.0\",\n \"files\": [\n \"lib\",\n \"src\"\n ],\n \"dependencies\": {\n \"@theia/core\": \"latest\"\n },\n \"devDependencies\": {\n \"rimraf\": \"latest\",\n \"typescript\": \"~5.4.5\"\n },\n \"scripts\": {\n \"prepare\": \"yarn run clean && yarn run build\",\n \"clean\": \"rimraf lib\",\n \"build\": \"tsc\",\n \"watch\": \"tsc -w\"\n },\n \"theiaExtensions\": [\n {\n \"frontend\": \"lib/browser/hello-world-frontend-module\"\n }\n ]\n}As you can see, the extension is a dedciated package that just depends on Theia. However, as the extension contributes features to our application, it needs to be wired a runtime. To achive this in a modular way, in Theia, everything is wired up via dependency injection. An extension defines one or more dependency injection modules. This is where it binds its contribution implementations to the respective contribution interface. The modules are listed in the package.json of the extension package. An extension can contribute to the frontend, e.g. providing a UI extension, as well as to the backend, e.g. contributing a language server. When the application starts, the union of all these modules is used to configure a single, global dependency injection container on each, the frontend and the backend. The runtime will then collect all contributions of a specific kind by means of a multi-inject.
The last property theiaExtensions in the package.json above is where we list the JavaScript modules that export the DI modules defining the contribution bindings of our extension. In our case, we only provide a frontend capability (a command and a menu entry). Analogously, you could also define contributions to the backend, e.g. a language contribution with a language server.
Theia defines a plethora of contribution interfaces that allow extensions to add their behaviour to various aspects of the application. Browse the documentation section 'Platform Concepts & APIs' or search for interfaces with the name *Contribution to get an idea. An extension implements the contribution interfaces belonging to the functionality it wants to deliver. In this example, we are going to implement a CommandContribution and a MenuContribution. Other ways for extensions to interact with a Theia application are via one of the various services or managers.
In the frontend module we export a default object that is a InversifyJS ContainerModule with bindings for a command contribution and a menu contribution. Please see our dependency injection guide for more details.
export default new ContainerModule(bind => {\n // add your contribution bindings here\n bind(CommandContribution).to(HelloWorldCommandContribution);\n bind(MenuContribution).to(HelloWorldMenuContribution);\n});A command is a plain data structure defining an ID and a label. The behaviour of a command is implemented by registering a handler to its ID in a command contribution. The generator has already added a command and a handler that shows a \"Hello World!\" message.
\nexport const HelloWorldCommand = {\n id: 'HelloWorld.command',\n label: \"Shows a message\"\n};\n\n@injectable()\nexport class HelloWorldCommandContribution implements CommandContribution {\n\n constructor(\n @inject(MessageService) private readonly messageService: MessageService,\n ) { }\n\n registerCommands(registry: CommandRegistry): void {\n registry.registerCommand(HelloWorldCommand, {\n execute: () => this.messageService.info('Hello World!')\n });\n }\n}\n...Note how we use @inject in the constructor to get the MessageService as a property, and how we use that later in the implementation of the handler. This is the elegance of dependency injection: As a client, we neither care where these dependencies come from nor what their lifecycle is.
To make it accessible by the UI, we implement a MenuContribution, adding an item to the Search/Replace section of the edit menu in the menu bar.
...\n@injectable()\nexport class HelloWorldMenuContribution implements MenuContribution {\n\n registerMenus(menus: MenuModelRegistry): void {\n menus.registerMenuAction(CommonMenus.EDIT_FIND, {\n commandId: HelloWorldCommand.id,\n label: 'Say Hello'\n });\n }\n}To make sure your extension is included in your Theia application, list it as a dependency in your browser or electron app, e.g. like this:
\n{\n \"private\": true,\n \"name\": \"browser-app\",\n \"version\": \"0.0.0\",\n \"dependencies\": {\n \"@theia/core\": \"latest\",\n ...\n \"hello-world\": \"0.0.0\"\n },\n \"devDependencies\": {\n \"@theia/cli\": \"latest\"\n },\n \"scripts\": {\n \"bundle\": \"yarn rebuild && theia build --mode development\",\n \"rebuild\": \"theia rebuild:browser --cacheRoot ..\",\n \"start\": \"theia start\",\n \"watch\": \"yarn rebuild && theia build --watch --mode development\"\n },\n \"theia\": {\n \"target\": \"browser\"\n }\n}To run the extension, you have two options:
\nyarn publish and consume it from your Theia-based applicationSee Executing the Browser Application and Executing the Extension in Electron for more details* for adding extensions to the dependencies of a Theia-based application and running it.
","fields":{"slug":"authoring_extensions"}}},"pageContext":{"slug":"authoring_extensions"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/authoring_plugins/page-data.json b/pr-previews/pr-663/page-data/docs/authoring_plugins/page-data.json deleted file mode 100644 index af984f37..00000000 --- a/pr-previews/pr-663/page-data/docs/authoring_plugins/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/authoring_plugins/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Authoring Plug-ins"},"html":"This documentation is deprecated and needs to be updated. We currently recommend using VS Code extensions or Theia extensions instead of Theia Plugins. See the extension overview for more details.
\n","fields":{"slug":"authoring_plugins"}}},"pageContext":{"slug":"authoring_plugins"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/authoring_vscode_extensions/page-data.json b/pr-previews/pr-663/page-data/docs/authoring_vscode_extensions/page-data.json deleted file mode 100644 index d0852be1..00000000 --- a/pr-previews/pr-663/page-data/docs/authoring_vscode_extensions/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/authoring_vscode_extensions/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Authoring VS Code Extensions"},"html":"Alongside Theia extensions, VS Code extensions can also be used to enhance Theia applications with additional functionality, such as language support, commands, or tree views.\nVS Code extensions contribute functionality through the dedicated VS Code API, which the Theia framework also supports.\nThis means that extensions that have been developed for VS Code are also compatible with Theia, and vice versa.\nThe coverage report provides more details on the extent to which the VS Code API is supported by each Theia version.
\nWhile there are certain overlaps in which types of functionality can be contributed to a Theia application with a Theia extension or a VS Code extension, both have their unique advantages and disadvantages.\nPlease refer to the overview on extensions and plugins and an in-depth comparison for a more detailed discussion.
\nIn the remainder of this page, we guide you through the process of creating VS Code extensions and deploying them in Theia.\nThe steps for deploying VS Code extensions apply not only to VS Code extensions you develop yourself, but also to third-party VS Code extensions from the Theia marketplace. If you use a third-party VS Code extension, you can skip the section \"Creating VS Code Extensions\" and \"Developing VS Code Extensions in a Theia Project\".
\nAs VS Code extensions can be used in Theia without further modification, you can refer to the documentation on extending VS Code to learn more about creating extensions for VS Code as well as for Theia.\nThe easiest way to get started is to use the VS Code Extension Generator and follow the Getting Started Guide.
\nAs an example, let's generate the hello world extension.
\nnpm install -g yo generator-code # install the VS Code Extension Generator\nnpm install -g vsce # install VS Code Extension CLI tooling\n\nyo code # generate an extension\n# take a look at the generated package.json defining a command \"Hello World\"\n# take a look at the src/extension.ts registering a command handler\n# make changes to the README and the code, if you like\nvsce package # package your VS Code extensionAs a result, a vsix file is generated, which can be used directly in VS Code and Theia (see below).\nPlease note that you can also create so-called extension packs with the VS Code extension generator that defines a collection of extensions.
To enable Theia's support for VS Code extensions in order to use your own extensions or third-party VS Code extensions in your Theia application, you'll need to add @theia/plugin-ext-vscode as a dependency.\nTypically, this is done in your browser or electron application package.
{\n ...\n \"name\": \"browser-app\",\n \"dependencies\": {\n \"@theia/core\": \"latest\",\n ...\n \"@theia/plugin-ext-vscode\": \"latest\"\n },\n \"theia\": {\n \"target\": \"browser\"\n }\n}Next, you need to specify a plugins location, which is a disk location containing your VS Code extensions.\nTheia will load all VS Code extensions from this location on initialization of a new user session automatically.\nThis location can be set either with an environment variable:
\nexport THEIA_DEFAULT_PLUGINS=local-dir://absolute-path-to-plugins-folderOr it can be provided in the command line option --plugins when starting Theia.
theia start --plugins=local-dir:../pluginsA common approach for Theia applications that include VS Code extensions is to add this command line parameter to the startup script in the browser or electron application package.
\n{\n ...\n \"name\": \"browser-app\",\n ...\n \"scripts\": {\n ...\n \"start\": \"theia start --plugins=local-dir:../plugins\",\n },\n \"theia\": {\n \"target\": \"browser\"\n }\n}Once you've enabled VS Code extension support in your Theia application as described above and made available your or any third-party VS Code extensions that you'd like to use in your Theia application, you have two options on how to consume them:
\nIn the following, we'll provide more details on each of those options.
\nFor pre-installing a certain set of VS Code extensions in your Theia application, all you need to do is to drop them, either as a vsix file or directly as a folder into the plugins location (see prerequisites).\nOn start-up of a user session, Theia will load all VS Code extensions from that location automatically.
A more systematic approach, however, is to publish VS Code extensions, to OpenVSX, GitHub Releases, or any other accessible location, and download them automatically at build time of the Theia application with the Theia CLI.\nSee publishing extensions to OpenVSX for more details.\nThis approach avoids having to manually distribute VS Code extensions or adding them in the form of a build artifact to your git repository.
\nTherefore, you need to extend your package.json to
{\n ...\n \"scripts\": {\n \"prepare\": \"yarn run clean && yarn build && yarn run download:plugins\",\n \"download:plugins\": \"theia download:plugins\",\n ...\n },\n \"theiaPluginsDir\": \"plugins\",\n \"theiaPlugins\": {\n \"my-hello-world-extension\": \"https://<url-to-your-published-extension>\",\n \"vscode.git\": \"https://open-vsx.org/api/vscode/git/1.52.1/file/vscode.git-1.52.1.vsix\",\n ...\n }\n}As a result, running yarn will download any listed extensions and place them into the folder specified in theiaPluginsDir automatically.\nFor more details, see also the documentation on composing Theia applications.
One of the unique advantages of VS Code extensions is that they can be installed and uninstalled by users at runtime.\nTo enable the users of your Theia application to install VS Code extensions at runtime, you have to add @theia/vsx-registry as a dependency to your package.json.
{\n ...\n \"name\": \"browser-app\",\n \"dependencies\": {\n \"@theia/core\": \"latest\",\n ...\n \"@theia/vsx-registry\": \"latest\"\n },\n \"theia\": {\n \"target\": \"browser\"\n }\n}This dependency will add a view Extensions to your application, which allows searching and installing extensions from an OpenVSX registry.\nBy default, the public registry at http://open-vsx.org is used, the registry URL be configured via the environment variable VSX_REGISTRY_URL.\nPlease confer to the OpenVSX extension documentation for more details.
To make your VS Code extension available, you'll need to publish your extension to the configured registry.
\nIn certain scenarios, you may not want to develop your VS Code extension in isolation from your Theia application, but instead you may prefer to develop both your extensions and your application in project to keep update cycles short and immediate.\nThis is particularly useful if you develop your extensions primarily to be part a specific Theia application, thus you want to develop, test and debug them directly in the context of your Theia app, potentially alongside other Theia extensions.
\nIn those scenarios, you can also include VS Code extensions as part of your Theia application monorepo.\nWhile there are several possible configuration options, probably the most straightforward approach is to follow the steps below.
\nGenerate your VS Code extension as usual.\nHowever, to make things easier and consistent, choose TypeScript as your language and yarn as a package manager for your VS Code extension to be aligned with a typical Theia application.
Put your VS Code extension package, let's say your-vs-code-extension, into your monorepo, alongside your other packages and make sure it is part of your yarn workspaces.\nLet's assume, we eventually have the following a directory structure.
monorepo\n├── apps\n│ ├── browser-app\n│ └── electron-app\n├── extensions\n│ ├── your-theia-extension\n│ └── your-vs-code-extension\n├── plugins\n└── package.jsonIn your-vs-code-extension/package.json, add symlink as a dev dependency to link your extension into the plugins location of your Theia application on each build.
{\n ...\n \"scripts\": {\n \"compile\": \"tsc -p ./\",\n \"watch\": \"tsc -watch -p ./\",\n \"prepare\": \"yarn run clean && yarn run build && yarn symlink\",\n \"symlink\": \"symlink-dir . ../../plugins/your-vs-code-extension\",\n ...\n },\n \"devDependencies\": {\n \"@types/vscode\": \"^1.32.0\",\n \"symlink-dir\": \"latest\",\n ...\n }\n}With that, your VS Code extension will be built as part of your Theia application and directly added to the plugins location for automatic installation in your Theia application.\nThis leads to a consistent development experience, even if you have multiple VS Code extensions and Theia extensions combined in one Theia application.
\nIf you aim at a consistent tsconfig.json across your VS Code extension and a typical Theia extension, you may want to change the outDir from out (default in VS Code) to lib (commonly used in Theia) and adjust the package.json accordingly.
To also enable debugging from your development IDE (VS Code), you need to setup launch.json to include the VS Code extension in the outFiles (if it is still building to the folder out and not lib) and enable source maps.
{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"type\": \"node\",\n \"request\": \"launch\",\n \"name\": \"Start Browser Backend\",\n \"program\": \"${workspaceRoot}/browser-app/src-gen/backend/main.js\",\n \"args\": [\n \"--loglevel=debug\",\n \"--port=3000\",\n \"--no-cluster\",\n \"--plugins=local-dir:${workspaceRoot}/plugins\"\n ],\n \"env\": {\n \"NODE_ENV\": \"development\",\n \"NODE_OPTIONS\": \"--enable-source-maps\"\n },\n \"sourceMaps\": true,\n \"outFiles\": [\n \"${workspaceRoot}/node_modules/@theia/*/lib/**/*.js\",\n \"${workspaceRoot}/extensions/*/lib/**/*.js\",\n \"${workspaceRoot}/extensions/*/out/**/*.js\",\n \"${workspaceRoot}/apps/*/src-gen/**/*.js\"\n ],\n \"smartStep\": true,\n \"internalConsoleOptions\": \"openOnSessionStart\",\n \"outputCapture\": \"std\"\n },\n ...\n ]\n}If no plugins are available in the running Theia instance, it may be that you need to tell Theia where to find the downloaded plugins.\nThe example above sets the --plugins switch in the start command which should be sufficient.\nHowever, if running theia start directly, you can alternatively set an environment variable to achieve the same thing:
export THEIA_DEFAULT_PLUGINS=local-dir:pluginsA backend application contribution allows Eclipse Theia extensions to hook into the lifecycle of the Theia backend. Backend application contributions are instantiated immediately after starting the backend application, which makes them a good place for initializing backend services that are required during the entire lifespan of the backend.
\nTo register backend application contributions, an extension needs to bind an implementation of the interface BackendApplicationContribution in the backend module.
export default new ContainerModule(bind => {\n bind(MemoryTracker).toSelf().inSingletonScope();\n bind(BackendApplicationContribution).toService(MemoryTracker);\n});The interface BackendApplicationContribution provides hooks, which are all optional so that implementations can freely choose which of those hooks they are interested in, without having to implement the others.\nFor initialization of backend services, the most common hook is the initialize() method that is invoked as soon as the Theia backend is initialized.
As an example, let’s implement a backend service that shall run during the entire lifespan of the Theia backend to track its memory usage.\nFor the sake of simplicity it will just print the memory to the log, whenever it changes more than a certain threshold.
\nTherefore, a BackendApplicationContribution named MemoryTracker is bound in the dependency injection context as shown in the code above.\nThe implementation of MemoryTracker reacts to the hook initialize() and executes the method logMemory() periodically every two seconds.\nThis method obtains the currently used memory, compares it to the previous memory and prints a message to the log as soon as the difference to the previous memory is above 0.1 MB.
@injectable()\nexport class MemoryTracker implements BackendApplicationContribution {\n\n @inject(ILogger)\n protected readonly logger: ILogger;\n protected logTimer: NodeJS.Timer;\n protected memoryUsed = 0;\n\n initialize(): MaybePromise<void> {\n this.logTimer = setInterval(() => this.logMemory(), 2000);\n }\n\n protected logMemory(): void {\n const currentMemoryUsed = this.currentRoundedMemoryUsage();\n const diff = currentMemoryUsed - this.memoryUsed;\n if (Math.abs(diff) > 0.1) {\n const timestamp = new Date().toUTCString();\n this.logger.info(\n `[${timestamp}] PID ${process.pid} uses ${currentMemoryUsed} MB (${diff > 0 ? '+' : ''}${diff.toFixed(2)})`\n );\n this.memoryUsed = currentMemoryUsed;\n }\n }\n\n protected currentRoundedMemoryUsage() {\n return Math.round(process.memoryUsage().heapUsed / 1024 / 1024 * 100) / 100;\n }\n\n onStop(): void {\n if (this.logTimer) {\n clearInterval(this.logTimer);\n }\n }\n}Once this backend application contribution is registered and the backend is started, it starts logging an output, similar to the following:
\nroot INFO Theia app listening on http://localhost:3000.\nroot INFO Configuration directory URI: 'file:///home/foobar/.theia'\nroot INFO [Fri, 20 Aug 2021 12:20:43 GMT] PID 46590 uses 18.14 MB (+18.14)\nroot INFO [Fri, 20 Aug 2021 12:20:47 GMT] PID 46590 uses 18.94 MB (+0.80)\nroot INFO [Fri, 20 Aug 2021 12:20:51 GMT] PID 46590 uses 15.25 MB (-3.69)\nroot INFO [Fri, 20 Aug 2021 12:21:07 GMT] PID 46590 uses 15.36 MB (+0.11)\nroot INFO [Fri, 20 Aug 2021 12:21:21 GMT] PID 46590 uses 15.47 MB (+0.11)\nroot INFO [Fri, 20 Aug 2021 12:21:41 GMT] PID 46590 uses 15.6 MB (+0.13)\nroot INFO [Fri, 20 Aug 2021 12:21:59 GMT] PID 46590 uses 15.71 MB (+0.11)Often such backend application contributions also provide methods that can be invoked by other backend services and, for instance, start external processes that need to be available as soon as the application is started.\nExamples are database connections, REST services, etc.
\nIn addition to initializing backend services as early as the backend is started, backend application contributions can also configure and extend the HTTP server used by the Theia backend.\nTherefore, the BackendApplicationContribution interface provides the three methods configure(app: express.Application), onStart(app: express.Application), and onStop(app: express.Application).\nThus, the HTTP server can be configured with custom settings and even extended with additional endpoints that need to be available for the respective Theia application.
An example for configuring an additional endpoint named /myendpoint is given below.
import { injectable } from '@theia/core/shared/inversify';\nimport { json } from 'body-parser';\nimport { Application, Router } from '@theia/core/shared/express';\nimport { BackendApplicationContribution } from '@theia/core/lib/node/backend-application';\n\n@injectable()\nexport class MyCustomEndpoint implements BackendApplicationContribution {\n configure(app: Application): void {\n app.get('/myendpoint', (request, response) => {\n …\n });\n }\n}For more information on how to configure HTTP endpoints and handle events requests, please refer to the Express API.
","fields":{"slug":"backend_application_contribution"}}},"pageContext":{"slug":"backend_application_contribution"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/blueprint_documentation/page-data.json b/pr-previews/pr-663/page-data/docs/blueprint_documentation/page-data.json deleted file mode 100644 index f0c6e2d8..00000000 --- a/pr-previews/pr-663/page-data/docs/blueprint_documentation/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/blueprint_documentation/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Extending/Adopting the Theia IDE"},"html":"This guide provides an overview on how to extend and customize the Theia IDE to your own custom IDE or tool. In this scenario, the Eclipse Theia IDE is an example product used as a reference on how to build desktop IDE-like products based on the Eclipse Theia framework. If you just want to use the Theia IDE, see the user guide
\nPlease note that adopting the Theia IDE as a basis is just one of several ways to get started with building a Theia-based application. We recommend reading the article \"Build your own IDE/Tool\" as a first step. Furthermore, this guide is focused on building a desktop app. We also provide an experimental Docker version of the Theia IDE as an alternative.
\nThe Theia IDE assembles a selected subset of existing Theia features and extensions.\nWe provide installers for the Theia IDE to be downloaded (see links below).\nIn the respective git repository you can also find the source code for the Theia IDE and its installers.
\nThis documentation will use these sources as a template. We will explain\nhow to customize this template so that you can build your own custom Theia-based product including installers and packaging for installing the desktop-based version of your custom product on all major operating systems. Please note that the technical name (e.g. in the source code) for the Theia IDE is \"Theia Blueprint\" to avoid confusion with the generic term \"IDE\".
\nThe Theia IDE build uses electron-builder to package the product as a desktop application.
\nThe product can be built and packaged with yarn.\nNote that you usually can only package the product for the operating system you execute the build on.\nFor more information see the electron-builder documentation on multi-platform builds.
\nThe following commands may be run from the root directory of the repository.
\nTo install dependencies and build the application, simply execute yarn.
You can also directly run the unpackaged application, e.g. to test it during development with yarn electron start.
With yarn electron package, you package the application into an executable file for your current operating system.\nThe packaged application will be located in applications/electron/dist.\nThe folder applications/electron/dist/<OS>-unpackaged will contain the files that are bundled into the final packaged executable.\nFor Linux, this is an executable .AppImage, for Windows a .exe installer, and a .dmg disk image for macOS.
You can also just create the unpackaged content by running yarn electron package:preview.\nThis is useful to see the bundled files and saves time compared to a full package.\nTo publish the current version, the command yarn electron deploy can be used.\nFor more information on publishing also see section \"Configure publish and update\".
Electron-builder supports signing the packaged application on Windows and macOS.\nThe current signing scripts for the Theia IDE are located in applications/electron/scripts.\nThe file after-pack.js is the current entry point for the configured signing via Eclipse infrastructure.
However, as signing is highly dependent on your setup, see the electron builder’s signing documentation on how to properly set up your own signing.
\nThe Theia IDE is based on the Theia platform, which is a flexible and adaptable platform for build tools and IDEs. Therefore, you can adapt the feature set and general appearance of the Theia IDE to your custom requirements with almost no limits. The Theia platform provides two mechanism to add your custom extensions: VS Code extensions and Theia extensions. Please have a look at the overview about Theia extension capabilities for details. When assembling a product such as the Theia IDE, you can freely decide, which VS Code extensions and Theia extensions are part of it and thereby influence the feature set of your custom product. The following two sections describe how to modify which VS Code Extensions and which Theia extensions are part of your product. Please also note that you can allow users of a Theia-based tool to install VS Code extensions at runtime.
\nAll VS Code extensions that are already included in the product at start-up (\"built-ins\"), are defined in applications/electron/package.json.\nThey are listed under the theiaPlugins property as key-value pairs.\nThe keys can be freely chosen as long as they represent a valid folder name and are unique within the theiaPlugins property.\nWe suggest using the extension’s unique identifier.\nThe value is the download URL of the extensions.\nIt will automatically be downloaded during the application’s build process.\nAny new plugin will be automatically downloaded the next time one of the following npm scripts is executed:
install (which is the same as just running yarn)preparedownload:pluginsTo remove an extension from the product, simply delete its entry.\nIf plugins were not already downloaded, no further steps are required as downloaded plugins are ignored via gitignore.\nHowever, previously downloaded plugins are not automatically removed.\nTherefore, you need to remove its folder from the applications/electron/plugins folder.\nAlternatively, you can remove the whole applications/electron/plugins folder and execute yarn electron download:plugins to download all defined plugins.
We use the Open VSX Registry of the Eclipse Foundation to install extensions.\nIt is an open and community-driven VS Code extension marketplace.\nMore information can be found at eclipse.org.
\nEclipse Theia extensions can be added through dependencies in applications/electron/package.json.\nLike any other dependency, it will be installed via yarn.\nSimilarly, removing an extension works by removing it from dependencies.\nFor extensions already published on npm (or your private npm registry) this is all you need to do.
An alternative approach is developing your extension inside Theia IDE’s mono repo.\nThe advantage of doing this is that you don’t need to publish the extension and can build the product with the local version of the extension.\nThis is facilitated by the lerna build already configured in the Theia IDEs’s repository.\nIt links the product and all extensions in the repository together during the build.
\nThe easiest way to create a new extension is to use the official yeoman generator for Theia extensions.\nAssuming you have yeoman globally installed on your system, simply create a new extension in the repository root with yo theia-extension --standalone.\nThe --standalone flag is used to only create an extension but not a whole Theia application frame because it is already provided by the Theia IDE.\nAfter successfully generating the extension, add its folder name to the Theia IDEs’s root package.json in the workspaces property.\nAfter adding the extension to the dependencies in applications/electron/package.json as described above, the new extension will be part of the built product.
You can also add your own branding to the product by customizing the application icons and title, the welcome page and the About dialog.\nIn addition, some parts of the installer can be customized.
\nThe window title is the application’s name if no workspace is opened and <workspace name> — <application name> if a workspace is opened.\nThe application name can be adapted in applications/electron/package.json by navigating through the nested properties.
To change the application name, open the file and locate the following nested structure:
\n \"theia\": {\n \"frontend\": {\n \"config\": {\n \"applicationName\": \"Theia IDE\",\n },\n },\n },Change the value of applicationName to the desired name.\nAlso see the structure in the original file.
Application icons are located in applications/electron/resources/.\nSimply replace them with your own icons.\nBecause each operating system handles icons differently, they should all be replaced to ensure proper use.\nThey map as follows:
The Eclipse Theia welcome page can be customized by binding a custom WidgetFactory for Theia’s GettingStartedWidget.\nThis is done with the Theia IDE in the theia-blueprint-product extension.\nThe easiest way to customize the welcome page is to adapt the class TheiaBlueprintGettingStartedWidget in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-getting-started-widget.tsx.
The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:
bind(TheiaBlueprintGettingStartedWidget).toSelf();\n bind(WidgetFactory).toDynamicValue(context => ({\n id: GettingStartedWidget.ID,\n createWidget: () => context.container.get<TheiaBlueprintGettingStartedWidget>(TheiaBlueprintGettingStartedWidget),\n })).inSingletonScope();To use another custom widget, remove this code and bind your widget correspondingly.
\nThe Eclipse Theia about dialog can be customized by binding a custom subclass of Theia’s AboutDialog class to AboutDialog.\nThis is done with Theia IDE in the theia-blueprint-product extension.\nThe easiest way to customize the about dialog is to adapt the class TheiaBlueprintAboutDialog in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-about-dialog.tsx.
The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:
isBound(AboutDialog) ? rebind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope() : bind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope();To use another custom dialog widget, remove this code, extend Theia’s AboutDialog class, and (re)bind it as above.
\nThe default preferences directory in Eclipse Theia IDE is .theia-blueprint and is located as described in the Preferences documentation. You can customize this location by modifying theia-blueprint-variables-server.ts.
Since Theia 1.49.0 Theia Electron applications support displaying a splash screen before showing the main window.
The splash screen can be enabled within the application package.json's Theia options by providing an object at theia.frontend.config.electron.splashScreenOptions with the following properties:
{\n content: string // <mandatory> path to the content to render within the splash screen, resolved from application root\n width: number // default 640\n height: number // default 480\n minDuration: number // minimum amount of time in milliseconds to show the splash screen before main window is shown. default 0\n maxDuration: number // maximum amount of time in milliseconds before splash screen is removed and main window is shown. default 30000\n}If not configured otherwise via minDuration, the splash screen will be shown until the frontend is ready, i.e. when the loading spinner is gone.\nThen the splash screen will be closed and the main window is shown.
The main window / splash screen can be configured to be shown \"early\", i.e. the window will be shown before it's ready to render content.\nBy default this is true to give the user visual feedback as early as possible.
If you prefer only showing the main window / splash screen once they are ready to render content, then you can configure theia.frontend.config.electron.showWindowEarly: false in your application's package.json.
The installers are created using electron-builder.\nThe corresponding configuration file is located at applications/electron/electron-builder.yml.
The installer files’ base names are defined by the productName property in applications/electron/electron-builder.yml.
As is typical for Windows applications, there is an installation wizard for the Windows version of the Theia IDE.\nThe installer is configured in the nsis section of the configuration file.\nAvailable customizations include settings such as:
\nMore details on available options and how they can be customized can be found in the official electron builder documentation.\nThis documentation also includes information about more advanced features such as custom NSIS scripts.
\nThe Theia IDE uses electron-builder to create and publish installers.\nIt also uses electron-updater, developed by the electron-builder organization, to provide automatic updates of the installed application.
\nThere are various deployment targets which can be configured in the applications/electron/package.json and applications/electron/electron-builder.yml as documented here in the Electron Builder documentation.\nMultiple publish configurations can be configured.\nThereby, the first one is automatically used by the updater to look for available updates.\nThe currently used generic publishing method does not automatically publish to the specified server, but is just used as the lookup location for the updater.
Eclipse Theia Blueprint has been rebranded to \"Theia IDE\" and has moved to this page.
","fields":{"slug":"blueprint_download"}}},"pageContext":{"slug":"blueprint_download"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/breadcrumbs/page-data.json b/pr-previews/pr-663/page-data/docs/breadcrumbs/page-data.json deleted file mode 100644 index f49d6651..00000000 --- a/pr-previews/pr-663/page-data/docs/breadcrumbs/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/breadcrumbs/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Breadcrumbs"},"html":"If enabled via the preferences, Theia can show a navigation bar, often referred to as breadcrumbs, above the content of widgets that are located in the main area of the workbench.\nThis interactive navigation bar indicates the location of the widget's content in the context of an overall structure, such as the filesystem.\nBy default, Theia shows breadcrumbs for the location of files in the filesystem when a file is opened in the text editors.
\n![\"A](\"../../breadcrumbs.png\")
\nHowever, Theia's breadcrumbs mechanism can also be used for any custom widget, too.\nMoreover, Theia allows showing a widget's content location in an arbitrary custom logical structure, such as a custom project structure.\nOn this page, we describe how custom breadcrumbs work and how widgets declare their location within an overall structure.
\nWhat is being shown in the breadcrumbs of a widget is defined by breadcrumbs contributions.\nSuch contributions must implement the BreadcrumbsContribution interface and return an array of Breadcrumbs for a specific URI, which are then shown for any widget that specifies this URI as their content's location.\nA widget declares the location of its content in the form of a URI by implementing the interface NavigatableWidget.
So let's look at an example widget that declares an arbitrary URI.
\n@injectable()\nexport class CustomWidget extends ReactWidget implements NavigatableWidget {\n // ...\n getResourceUri(): URI | undefined {\n return new URI('resource://project-a/component-b/config-c');\n }\n}When this CustomWidget is opened, Theia will look for breadcrumbs contributions that return breadcrumbs for this URI.\nBy default, it won't find any and thus won't show any breadcrumbs.\nSo let's add a breadcrumbs contribution that reacts to URIs with the scheme resource as used by our widget above.
export default new ContainerModule(bind => {\n bind(CustomBreadcrumbsContribution).toSelf().inSingletonScope();\n bind(BreadcrumbsContribution).toService(CustomBreadcrumbsContribution);\n});\n\n@injectable()\nexport class CustomBreadcrumbsContribution implements BreadcrumbsContribution {\n type: symbol = CustomBreadcrumbType;\n priority: number = 100;\n\n protected readonly onDidChangeBreadcrumbsEmitter = new Emitter<URI>();\n get onDidChangeBreadcrumbs(): Event<URI> {\n return this.onDidChangeBreadcrumbsEmitter.event;\n }\n\n computeBreadcrumbs(uri: URI): MaybePromise<Breadcrumb[]> {\n if (uri.scheme !== 'resource') {\n return [];\n }\n // uri is 'resources://project-a/component-b/config-c' for our widget above\n // but let's just hard code breadcrumbs as an example for the sake of simplicity\n return [\n {\n id: 'project',\n label: 'Project A',\n longLabel: 'The project',\n iconClass: 'codicon codicon-folder default-folder-icon file-icon',\n type: CustomBreadcrumbType\n },\n {\n id: 'component',\n label: 'Component B',\n longLabel: 'A component within a project',\n iconClass: 'codicon codicon-file default-file-icon file-icon',\n type: CustomBreadcrumbType\n },\n {\n id: 'config',\n label: 'Configuration C',\n longLabel: 'A configuration within a component',\n iconClass: 'markdown-icon medium-blue theia-file-icons-js file-icon',\n type: CustomBreadcrumbType\n }\n ];\n }\n\n // ...\n}Once the breadcrumbs contribution is registered, Theia will show the following for our custom widget.
\n![\"A](\"../../breadcrumbs-custom.png\")
\nBreadcrumbs contributions also must implement the method attachPopupContent.\nTheia invokes this method as soon as a user clicks on one of the breadcrumbs and passes a parent HTML element into which the breadcrumbs contribution can now add arbitrary HTML content, including trees, buttons, etc.\nThis content is consequently being shown as a popup below the clicked breadcrumbs element.\nIf this method returns a Disposable, Theia will call it, once the popup is closed, allowing to dispose resources that may have been allocated for the rendered content.
As an example, let's just return add some simple HTML to the popup, as shown below.
\n@injectable()\nexport class CustomBreadcrumbsContribution implements BreadcrumbsContribution {\n // ...\n attachPopupContent(breadcrumb: Breadcrumb, parent: HTMLElement): Promise<Disposable | undefined> {\n parent.innerHTML = '<div style=\"margin-left: 10px\"><h3>'\n + breadcrumb.label\n + '</h3><p>We can show arbitrary content here and react to clicks.</p></div>';\n return Promise.resolve(undefined);\n }\n}![\"A](\"../../breadcrumbs-popup.png\")
\nAs defined by the BreadcrumbsContribution interface, a contribution must define a priority.\nThe property is used by Theia to properly order the breadcrumbs returned by all breadcrumbs contributions.\nThus, if you have for instance three breadcrumbs contributions that return a non-empty array of breadcrumbs for a particular URI, we'll end up with a final breadcrumbs list that contains all breadcrumbs of all three contributions ordered from lowest to highest priority.\nThe Theia text editor uses this mechanism to append logical structures of code to a source file, for instance.\nContributions that return an empty array for a specific URI are obviously ignored.
Contribution A with a priority of 10 returns [a, b]\nContribution B with a priority of 20 returns [c, d]\nContribution C with a priority of 30 returns [e, f]\n=> [a, b, c, d, e, f]Theia's filesystem extension registers a breadcrumbs contribution that returns breadcrumbs according to the directory hierarchy for any file URI, such as file://home/user/a/b/c.txt.\nThe breadcrumbs returned by that contribution are also interactive by showing a file tree on click for navigating to adjacent files.
You can also make use of the filesystem breadcrumbs in custom widgets by just returning file URIs in your implementation of NavigatableWidget#getResourceUri().\nIf needed, you can also register additional breadcrumbs contributions with a high number as priority to append to the file URI shown in the breadcrumbs, such as for navigating to specific sections in your custom widget.
Accordingly, however, if you want to avoid showing filesystem breadcrumbs altogether and only use custom breadcrumbs, your widget must return a URI that isn't a file URI, for instance resource://a/b/c.
Commands are runnable actions defined by an ID and the function to be executed (plus some optional parameters like a name or an icon). Commands can be triggered via the command palette, they can be bound to keybindings or menu items, and they can be called programmatically. The action that commands trigger can be context-sensitive, so that they can only be called under certain conditions (window focus, current selection etc.).
\nThe following sections provide details about how to contribute commands, keybindings and menu items. The sections will describe how to connect the different contributions and how to use the corresponding services for managing these items.
\nIf you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
\nAll the following code examples are from the Theia extension generator. You can get the same code set-up by installing the generator, selecting the “Hello World” example (see here) and choosing “helloworld” as the name.
\nBy contributing a command, you can add a custom action to Theia. A command can be triggered by the user via the command palette, a keybinding or a menu entry. It can also be called programmatically.
\nAll commands of a Theia application are managed in the CommandRegistry. To contribute commands to the command registry, modules must implement the CommandContribution interface (see code example below).
A command is an object with an id and an optional, potentially user visible label (see HelloworldCommand in the example below). The command contribution receives the CommandRegistry in the registerCommands function as a parameter. The command can then be registered by calling registerCommand on this registry. Along with the command a callback needs to be provided which is executed whenever the command is triggered (CommandHandler). In the example, the command uses the MessageService to “say hello”.
helloworld-contribution.ts
\nexport const HelloworldCommand: Command = {\n id: 'Helloworld.command',\n label: \"Say Hello\"\n};\n\n@injectable()\nexport class HelloworldCommandContribution implements CommandContribution {\n\n constructor(\n @inject(MessageService) private readonly messageService: MessageService,\n ) { }\n\n registerCommands(registry: CommandRegistry): void {\n registry.registerCommand(HelloworldCommand, {\n execute: () => this.messageService.info('Hello World!')\n });\n }\n}\nTo make the command execution context-sensitive, the CommandHandler can optionally implement isEnabled and isVisible. You can optionally register more than one CommandHandler and let the command execute one of them based on the current context. To register additional handlers for a command use the registerHandler function on the CommandRegistry\nWhen a command is executed, the command registry checks all registered handlers. The first handler that returns true on isEnabled will be considered to be active, and it will be executed. Only one handler should be active (isEnabled === true) at the same time, though. isVisible controls the visibility of menu items and tool items that are connected to a command, as well as whether the command is shown in the command palette. If the active handler returns true, the menu item will be visible and vice versa.\nFinally, by implementing isToggle a handler can optionally specify, whether menu items connected to the commands should be toggled on or off.
To make our CommandContribution accessible to Theia, we need to bind the custom HelloworldCommandContribution to the respective contribution symbol CommandContribution. This is done in the helloworld-frontend-module, for more details see Services and Contributions.
helloworld-frontend-module.ts
\nexport default new ContainerModule(bind => {\n // add your contribution bindings here\n bind(CommandContribution).to(HelloworldCommandContribution);\n...\n});The CommandRegistry used to register our contributed command above, also provides an API to interact with commands. As an example, you can programmatically execute commands, you can browse through all registered commands or you can access a list of recently executed commands. Please refer to the TypeDoc for the CommandRegistry for more details. To use the CommandRegistry outside of a contribution, you can access it via dependency injection.
In the following sections, we describe how to bind commands to menu items and keybindings.
\nTheia allows you to contribute menu items that will be displayed in specific menus within your Theia application. Menu items are bound to commands and therefore allow the user to trigger actions (please see the section about commands above).
\nAll the following code examples are from the Theia extension generator. You can get the same code set-up by installing the generator, selecting the “Hello World” example (see here) and choosing “helloworld” as the name.
\nAll menu items of a Theia application are managed in the MenuModelRegistry. To contribute menu items to the registry, modules must implement the ´MenuContribution´ interface (see code example below).
The registration of the command can be done in the function registerMenus, which will be called by the Theia framework. The function provides the MenuModelRegistry as a parameter. On this registry we can call registerMenuAction. It expects a MenuPath and a MenuAction. The MenuPath specifies the menu (and submenu) to place the menu item into. Please see here for the paths of some common menus.
The MenuAction consists of a command id, specifying which command to trigger, and an optional label, specifying the label of the menu item.
helloworld-contribution.ts
\n@injectable()\nexport class HelloworldMenuContribution implements MenuContribution {\n\n registerMenus(menus: MenuModelRegistry): void {\n menus.registerMenuAction(CommonMenus.EDIT_FIND, {\n commandId: HelloworldCommand.id,\n label: HelloworldCommand.label\n });\n }\n}To make our MenuContribution accessible to Theia, we need to bind the custom HelloWorldMenuContribution to the respective contribution symbol MenuContribution. This is done in the helloworld-frontend-module, for more details see Services and Contributions.
helloworld-contribution.ts
\nexport default new ContainerModule(bind => {\n bind(MenuContribution).to(HelloworldMenuContribution);\n ...\n});\nPlease note that you also contribute menu items without a command which allows you to create custom top level menus and sub menus. To achieve this, contribute a menu item without a command and then reference the id of this menu item as a MenuPath in other contributes. This will add menu items to your custom menu.
Keybindings allow the user to trigger commands using specific key combinations. Keybindings can define conditions, specifying when they are active. As an example, there can be keybindings that are only active when the text editor is focused.
\nPlease note that the following code examples are not part of the generated template, so you will need to manually add them (see previous sections).
\nTo contribute a keybinding, implement a KeybindingContribution (see code example below) with which you can access the KeybindingRegistry, allowing you to register a keybinding. Keybindings consist of:
keybinding: The key combinationcommand: The id of the command to be triggeredwhen(optional): The condition when the keybinding should be activehelloworld-keybinding-contribution.ts
\nexport class HelloworldKeybindingContribution implements KeybindingContribution {\n registerKeybindings(keybindings: KeybindingRegistry): void {\n keybindings.registerKeybinding({\n keybinding: \"alt+enter\",\n command: 'Helloworld.command',\n when: 'editorFocus && editorIsOpen'\n });\n }\n}The syntax for the “when” clause follows the VS Code terminology. Modifiers are platform independent, so Modifier.M1 is Command on OS X and CTRL on Windows/Linux. Key string constants can be viewed in Key documentation.
Just as you needed to bind the contributions before, keybinding contributions also need to be bound to the symbol KeybindingContribution to make them accessible for Theia.
editor-frontend-module.ts
\nexport default new ContainerModule(bind => {\n bind(KeybindingContribution).to(HelloworldKeybindingContribution);\n ...\n});\nThis guide will teach you how to create your own Theia-based application. The guide will demonstrate how to configure your own application composed of existing or new Theia extensions, and any VS Code extensions you want bundled in your application by default. Please get familiar with the extension mechanisms of Theia in case you are not already.\nWe provide two entry points for creating your own Theia-based application.
\nIf you are new to Theia, we recommend starting with the first option, as it is quicker and simpler to get started with. If you want to create a full product based on Theia, you can later on switch to using the Theia IDE without loosing your existing work by integrating your extensions into your custom version of the Theia IDE. In this guide, we will demonstrate how to get started with the Yeoman Generator.
\nThe detailed list of prerequisites is located at the main Theia repository:
\nA Theia app is composed of so-called Theia extensions. Each extension resides in its own npm package.\nAn extension provides a set of features, e.g. widgets, commands, handlers, etc. for a specific functionality. The Theia project itself ships a number of extensions for common features, e.g. for editors, terminals, the project view etc. You can resue these existing extensions by just adding them to you custom Theia application. Additionally, you can add arbitrary VS Code extensions to your application, again for reusing existing features already available, such as Git support. Finally, you can then extend and customize your Theia application with your own features, which you can implement as Theia extensions or VS Code extensions.\nIn this guide, we will create a Theia application with a number of existing Theia extensions and one (generated) custom Theia extension. Please also refer to our documentation on how to create custom Theia extensions to learn more on how to create your own Theia extensions. Finally, also see our guide on how to add VS Code extensions to your custom Theia application.
\nWe are going to create a monorepo (a repository containing multiple npm packages) named my-theia-app containing three packages: browser-app, electron-app and hello-world-extension. The first two contain the custom Theia applications to run in browser and electron mode. The 'hello-world' package contains a generated example extension, that adds a feature to our custom Theia application. This extension can serve as a starting point for you to add your own custom features via Theia extensions.
We are going to use yarn instead of npm (Theia default). We are also going to use lerna to run scripts across workspaces.
To ease the setup of such a repository we have created a Yeoman generator to scaffold the project. It will also generate the hello-world example extension. Run it using
npm install -g yo generator-theia-extension\nmkdir my-theia-app\ncd my-theia-app\nyo theia-extension # select the 'Hello World' option and complete the promptsAfter creating the project structure, the Yeoman generator will also install the required dependencies, so it might take a minute to complete.\nLet's have look at the generated code now. The root package.json defines the workspaces, the dependency to lerna and some scripts to build, start and watch the project for browser or electron. Please note that the excerpt on this page might be outdated, please use the Yeoman generator to generate the files listed below to get the latest version.
{\n \"private\": true,\n \"engines\": {\n \"yarn\": \">=1.7.0 <2\",\n \"node\": \">=18\"\n },\n \"scripts\": {\n \"build:browser\": \"yarn --cwd browser-app bundle\",\n \"build:electron\": \"yarn --cwd electron-app bundle\",\n \"prepare\": \"lerna run prepare\",\n \"postinstall\": \"theia check:theia-version\",\n \"start:browser\": \"yarn --cwd browser-app start\",\n \"start:electron\": \"yarn --cwd electron-app start\",\n \"watch:browser\": \"lerna run --parallel watch --ignore electron-app\",\n \"watch:electron\": \"lerna run --parallel watch --ignore browser-app\"\n },\n \"devDependencies\": {\n \"lerna\": \"2.4.0\"\n },\n \"workspaces\": [\n \"hello-world\", \"browser-app\", \"electron-app\"\n ]\n}Besides the root level artifacts, you will have three directories in your project:
\nNow we want to see our Theia application in action. For this purpose, the generator has created a package.json in the folder browser-app, which defines your Theia app. It defines a Theia browser application with a couple of statically included extensions, including our hello-world. These extensions are the features, that will be part of our Theia application. The generated project contains a minimalistic set-up, you can add additional features by adding more existing (or custom) extensions to this list. The example also does not contain any VS Code extensions, see here on how to add them.
{\n \"private\": true,\n \"name\": \"browser-app\",\n \"version\": \"0.0.0\",\n \"dependencies\": {\n \"@theia/core\": \"latest\",\n \"@theia/editor\": \"latest\",\n \"@theia/filesystem\": \"latest\",\n \"@theia/markers\": \"latest\",\n \"@theia/messages\": \"latest\",\n \"@theia/monaco\": \"latest\",\n \"@theia/navigator\": \"latest\",\n \"@theia/preferences\": \"latest\",\n \"@theia/process\": \"latest\",\n \"@theia/terminal\": \"latest\",\n \"@theia/workspace\": \"latest\",\n \"hello-world\": \"0.0.0\"\n },\n \"devDependencies\": {\n \"@theia/cli\": \"latest\"\n },\n \"scripts\": {\n \"bundle\": \"yarn rebuild && theia build --mode development\",\n \"rebuild\": \"theia rebuild:browser --cacheRoot ..\",\n \"start\": \"theia start\",\n \"watch\": \"yarn rebuild && theia build --watch --mode development\"\n },\n \"theia\": {\n \"target\": \"browser\"\n }\n}Now we have all pieces together to build and run the application.\nTo run the browser app, enter:
\nyarn build:browser\nyarn start:browserPoint your browser to http://localhost:3000, you will see a minimalistic custom Theia App.\nAs this Theia app contains the generated 'hello world' extension, you can try out the custom feature. Open the quick access bar by pressing 'F1' and enter 'say hello' and 'ENTER': A message \"Hello World!\" should pop up. This command is contributed by the 'hello-world' extension, see this guide to learn more.
\nThe package.json for the Electron app looks almost the same, except for the name and the target property.
{\n \"name\": \"electron-app\",\n ...\n \"theia\": {\n \"target\": \"electron\"\n }\n}Before running the electron app, you have to rebuild some native modules:
\nyarn build:electron\nyarn start:electronIn this guide, we have demonstrated how to set-up your own custom Theia application. The next typical steps are:
\nIf you run the yarn command behind a proxy you may encounter issues in building native dependencies (like oniguruma), in the last part of the build, with the following error stack:
[4/4] Building fresh packages...\n[1/9] XXXXX\n[2/9] XXXXX\n[3/9] XXXXX\n[4/9] XXXXX\nerror /theiaide/node_modules/XXXXX: Command failed.\nExit code: 1\nCommand: node-gyp rebuild\nArguments:\nDirectory: /theiaide/node_modules/XXXXX\nOutput:\ngyp info it worked if it ends with ok\ngyp info using node-gyp@3.8.0\ngyp info using node@8.15.0 | linux | x64\ngyp http GET https://nodejs.org/download/release/v8.15.0/node-v8.15.0-headers.tar.gz\ngyp WARN install got an error, rolling back install\ngyp ERR! configure error\ngyp ERR! stack Error: read ECONNRESET\ngyp ERR! stack at TLSWrap.onread (net.js:622:25)\ngyp ERR! System Linux 3.10.0-862.11.6.el7.x86_64\ngyp ERR! command \"/usr/bin/node\" \"/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js\" \"rebuild\"\ngyp ERR! cwd /theiaide/node_modules/XXXXX\ngyp ERR! node -v v8.15.0This happens because node-gyp does not rely on system/NPM proxy settings. In that case, download the node-headers file using the link provided in the error stack\n(in the example above https://nodejs.org/download/release/v8.15.0/node-v8.15.0-headers.tar.gz) and run the build with the following command:
npm_config_tarball=/path/to/node-v8.15.0-headers.tar.gz yarn installThis guide outlines how to incorporate specific bug fixes or features from Theia's master branch into your project without needing to fully upgrade to a new version of Theia.
\nImagine you are developing a Theia application using version 1.43.0. You encounter a bug in Theia, report it, and the community fixes it. However, there is no immediate Theia release including this fix. This guide describes how to use this fix in your local development, e.g. to validate it or to just already consume it before the next Theia release is published.
\nWe also assume that:
\nNote: In the following, we assume you are adopting the Theia version 1.43 which you want to hotfix(backport). Please replace \"1.43\" with the correct version of Theia that you currently build your project against.
\nClone and Branch Theia Codebase\n
\nClone the Theia codebase and checkout the version you are adopting in your project. Create a new branch from this version to apply the fix.
For convenience, make sure to clone it next to where your Theia application repo is cloned. E.g., if your Theia app is in ~/git/myapp , make sure you clone the Theia repo such that it ends up at ~/git/theia . This isn't absolutely necessary, but will make things easier in a subsequent step. We'll be assuming you've done it that way.
\ngit clone -b v1.43.0 https://github.com/eclipse-theia/theia.git\ncd theia\ngit checkout -b v1.43.0_with_fixNow you have a local clone of the same exact Theia version your application is currently using. It doesn't have the backported fix, but the next steps will take care of that.
\nIdentify the commit to backport on master\n
\nBrowse the commit history of the Theia project in the master branch to identify the commit you want to backport. It will typically be linked on the corresponding ticket on Github. Identify the commit SHA that has the fix in the master branch. In the following, we assume it is 0a615512.
Cherry-Pick the Fix\n
\nUse the commit SHA of the fix to cherry-pick it onto your local Theia branch.
git cherry-pick 0a615512Given the assumptions for this scenario, the cherry-pick should occur without any merge conflicts. If there are conflicts, you will need to address them. Now you have a local clone of Theia that includes the fix you want to backport.
\nCheck Modified Files\n
\nUse the following command to see what files were altered by the fix.
git show --name-only --pretty=\"\" 0a615512Adjust Package.json Files\n
\nIf the list of changes shows that any package.json files were modified, ensure that Theia package versions are not newer than 1.43. Open each one in an editor and replace any instances where a Theia package is referenced using a version newer than 1.43.0. E.g., if you find
\"dependencies\": {\n \"@theia/core\": \"1.44.0\",\n ...\n}change 1.44.0 to 1.43.0 .\nIf you overlook or forget to adjust any such forward version references, you will probably encounter errors when you try to build your local Theia version.
\nNote Modified Packages\n
\nIdentify which packages in packages/ and dev-packages/ were affected.
Build Theia\n
\nRun yarn to build Theia in the modified branch.\n
\nWe assume here that everything builds without errors. If there are errors, double check your steps above (particular #5). If you didn't make any mistakes, then it's likely that the fix has dependencies on other changes that have happened in the codebase since Theia 1.43.0. That is not necessarily a deal breaker. You may be able to adjust the fix to make it work on top of the 1.43.0 codebase. It may require that you cherry-pick another small change or two (but hopefully not more than that).
Use Modified Theia in Your App\n
\nIn your application's package.json, add resolutions for each modified package.
\"resolutions\": {\n \"**/@theia/core\": \"file:../theia/packages/core\",\n \"**/@theia/terminal\": \"file:../theia/packages/terminal\",\n // more resolutions as needed\n}Update Node Modules\n
\nUse yarn install with appropriate flags to update your node_modules.
yarn install --check-files --ignore-scripts--check-files tells yarn to skip the optimization it normally does and to ensure node_modules has what it should have.
\n--ignore-scripts lets us skip subsequent yarn lifecycle activity that isn't necessary in this particular step. We just want the node_modules to get updated.
\nPlease Note: You will have to re-run this step if you later make any additional changes to the Theia codebase that affect the packages you specified in the resolutions section above (e.g., if you cherry-pick another commit). Keep in mind that the yarn install cmdline above does not create symlinks. It makes copies of directories in your Theia workspace and puts them in your apps's node_modules . Any subsequent changes in those Theia directories need to be copied over again.
Build Your Application\n
\nFinally, run yarn in your application directory to build it with the new fixes.
By following these steps, you can backport Theia fixes or features into your application without waiting for an official release. This process is particularly useful for minor changes that don't depend on other recent codebase updates.
","fields":{"slug":"consume_theia_fixes_master"}}},"pageContext":{"slug":"consume_theia_fixes_master"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/contribution_filter/page-data.json b/pr-previews/pr-663/page-data/docs/contribution_filter/page-data.json deleted file mode 100644 index 9f6f0434..00000000 --- a/pr-previews/pr-663/page-data/docs/contribution_filter/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/contribution_filter/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Contribution Filter"},"html":"The Contribution Filter feature in Theia enables developers to remove specific contributions from a Theia-based application. This capability is typically used to eliminate existing features already present in Theia core, such as specific commands or menu entries.
\nFor a general understanding of contributions and contribution points, please refer to the Services and Contributions documentation.
\nThe Contribution Filter feature provides a way to selectively disable certain contributions within a Theia application. This is handeled by the ContributionFilterRegistry and FilterContributions which allow you to register and apply filters to contributions.
The FilterContribution interface allows you to register your contribution filters. These filters will be used by the ContributionFilterRegistry to remove or modify contributions.
ContributionFilterRegistry.Here's an example of how to use the Contribution Filter to remove specific commands from a Theia application. In this example, we will first define some commands and the filter them. If you want to filter some existing contributions, you would of course skip the first step and just provide a FilterContribution.
First, we define an example command that we want to filter out (more information about commands).
\nimport { Command } from '@theia/core/lib/common';\n\nexport namespace SampleFilteredCommand {\n\n const EXAMPLE_CATEGORY = 'Examples';\n\n export const TO_BE_FILTERED: Command = {\n id: 'example_command.filtered',\n category: EXAMPLE_CATEGORY,\n label: 'This command should be filtered out'\n };\n}We register the example command with a command contribution.
\nimport { CommandContribution, CommandRegistry } from '@theia/core/lib/common';\nimport { injectable } from 'inversify';\n\n@injectable()\nexport class SampleFilteredCommandContribution implements CommandContribution {\n\n registerCommands(commands: CommandRegistry): void {\n commands.registerCommand(SampleFilteredCommand.TO_BE_FILTERED, { execute: () => { } });\n }\n}Now, we register the filters to remove specific contributions, in our case the example command we just registered. The filter below is scoped to be only applied to CommandContribution, you can use '*' to filter any type of contribution. In the filter implementation, we additionally check for the specific type SampleFilteredCommandContribution in the example.
import { FilterContribution, ContributionFilterRegistry, CommandContribution } from '@theia/core/lib/common';\nimport { injectable } from 'inversify';\n\n@injectable()\nexport class SampleFilterContribution implements FilterContribution {\n\n registerContributionFilters(registry: ContributionFilterRegistry): void {\n registry.addFilters([CommandContribution], [\n contrib => !(contrib instanceof SampleFilteredCommandContribution)\n ]);\n }\n}Ensure that your contributions are properly bound in the dependency injection container.
\nimport { interfaces } from 'inversify';\nimport { CommandContribution, bindContribution } from '@theia/core/lib/common';\n\nexport function bindSampleFilteredCommandContribution(bind: interfaces.Bind): void {\n bind(CommandContribution).to(SampleFilteredCommandContribution).inSingletonScope();\n bind(FilterContribution).to(SampleFilterContribution).inSingletonScope();\n}The Contribution Filter feature in Theia is a powerful tool for developers to manage and customize the contributions in their applications. By leveraging FilterContributions , developers can easily define and apply filters to remove or modify specific contributions, thereby tailoring the functionality of their Theia-based applications to their specific needs.
By default, Theia shows the value of a widget's caption property when users hover above a widget's tab (see also widgets).\nIn certain use cases, especially with custom editors, this information may however not be sufficient to give users sufficient overview about a widget's content before activating the tab.
Therefore, Theia optionally provides an enhanced tab bar preview for widgets of the main or bottom area of Theia; that is, for horizontal tab bars.\nThis enhanced preview offers more room for information for widgets to show when hovering above a widget's tab.\nMoreover, it can easily be styled according to the needs of a tool provider adopting Theia.
\nThe enhanced tab bar preview is disabled by default and needs to be explicitly enabled with a via the preference window.tabbar.enhancedPreview.
![\"A](\"../../enhanced-preview-setting.png\")
\nAfter enabling the enhanced tab bar preview, users will see the following on hovering over a widget's tab:
\n![\"A](\"../../enhanced-preview.png\")
\nThe values shown in the tab bar preview are taken from the widget's title and caption properties.\nThese values can thus be easily provided by the widget implementation:
@postConstruct()\n protected async init(): Promise<void> {\n this.id = GettingStartedWidget.ID;\n this.title.label = GettingStartedWidget.LABEL;\n this.title.caption = 'Home > Theia > Getting Started';\n this.title.closable = true;For custom products, the enhanced tab bar preview can be customized and styled according to the requirements of the respective product.\nBelow we discuss the most relevant customization options.
\nThe styling of the hover box can easily be done with CSS.\nIf all hovers should be styled (including ones that are unaffected by the window.tabbar.enhancedPreview setting) the .theia-hover CSS class can be adjusted.\nTo only change the styling of the enhanced tab bar previews, use the CSS selector .theia-hover.extended-tab-preview instead.\nBy default, the enhanced tab bar preview for horizontal tab bars has rounded corners. This is defined by adding a border-radius to the .theia-hover.extended-tab-preview CSS class:
.theia-hover.extended-tab-preview {\n border-radius: 10px;\n}To style the elements inside of the preview, class names are assigned to the different components of the preview.\nThose are:
\n.theia-horizontal-tabBar-hover-div (for the outer box).theia-horizontal-tabBar-hover-title (for the title).theia-horizontal-tabBar-hover-caption (for the caption).If, for example, the preview should have a fixed size, this can be achieved by specifying a width for the .theia-horizontal-tabBar-hover-div and a max-width to the other two rules.\nTo also ensure the text is not going over the boxes boundaries, the property word-wrap: break-word can be added to the latter two rules.
.theia-horizontal-tabBar-hover-div {\n margin: 0px 4px;\n width: 100px;\n}\n\n.theia-horizontal-tabBar-hover-title {\n font-weight: bolder;\n font-size: medium;\n margin: 0px 0px;\n max-width: 100px;\n word-wrap: break-word\n}\n\n.theia-horizontal-tabBar-hover-caption {\n font-size: small;\n margin: 0px 0px;\n margin-top: 4px;\n max-width: 100px;\n word-wrap: break-word\n}After those rules are applied the preview will look as shown below:
\n![\"A](\"../../enhanced-preview-custom.png\")
\nTo change the actual content that is being rendered inside of the preview, the TabBarRenderer can be extended to overwrite the renderExtendedTabBarPreview method.\nIf, for example, the preview should only render the caption, the following CustomTabBarRenderer could be created:
export class CustomTabBarRenderer extends TabBarRenderer {\n protected override renderExtendedTabBarPreview = (title: Title<Widget>) => {\n const hoverBox = document.createElement('div');\n hoverBox.classList.add('theia-horizontal-tabBar-hover-div');\n const labelElement = document.createElement('p');\n labelElement.classList.add('theia-horizontal-tabBar-hover-title');\n labelElement.textContent = title.label;\n hoverBox.append(labelElement);\n return hoverBox;\n };\n}Now, we need to bind our custom TabBarRendererFactory to activate our customization and ensure the preview renders the information as defined in the implementation of CustomTabBarRenderer.renderExtendedTabBarPreview() above.
bind(TabBarRendererFactory).toFactory(({ container }) => () => {\n const contextMenuRenderer = container.get(ContextMenuRenderer);\n const tabBarDecoratorService = container.get(TabBarDecoratorService);\n const iconThemeService = container.get(IconThemeService);\n const selectionService = container.get(SelectionService);\n const commandService = container.get<CommandService>(CommandService);\n const corePreferences = container.get<CorePreferences>(CorePreferences);\n const hoverService = container.get(HoverService);\n return new CustomTabBarRenderer(contextMenuRenderer, tabBarDecoratorService, iconThemeService, selectionService, commandService, corePreferences, hoverService);\n });Events in Theia can be confusing, hopefully we can clarify things.
\nLet's consider this code:
\n(From logger-watcher.ts)
\n@injectable()\nexport class LoggerWatcher {\n\n getLoggerClient(): ILoggerClient {\n const emitter = this.onLogLevelChangedEmitter\n return {\n onLogLevelChanged(event: ILogLevelChangedEvent) {\n emitter.fire(event)\n }\n }\n }\n\n private onLogLevelChangedEmitter = new Emitter<ILogLevelChangedEvent>();\n\n get onLogLevelChanged(): Event<ILogLevelChangedEvent> {\n return this.onLogLevelChangedEmitter.event;\n }\n}Let's start with:
\n private onLogLevelChangedEmitter = new Emitter<ILogLevelChangedEvent>();So first what is an Emitter?
An Emitter is an event handler container,\nit allows for event handlers to be registered on it and triggered with an\nevent of type X in this case an ILogLevelChangedEvent.
\nSo here we just create an Emitter that will have events of type ILogLevelChangedEvent;
Next we want to be able to register an event handler on this Emitter to\ndo so we do this:
get onLogLevelChanged(): Event<ILogLevelChangedEvent> {\n return this.onLogLevelChangedEmitter.event;\n }What this actually returns is a function that will register an event\nhandler. Passing it your event handler function will\nregister it so that it's called when the event fires.
\nSo you can call:
\n(From logger.ts)
\n /* Update the root logger log level if it changes in the backend. */\n loggerWatcher.onLogLevelChanged(event => {\n this.id.then(id => {\n if (id === this.rootLoggerId) {\n this._logLevel = Promise.resolve(event.newLogLevel);\n }\n });\n });This registers the anonymous function passed as param on this emitter.
\nNext we will need to trigger this event handler by firing an event:
\n onLogLevelChanged(event: ILogLevelChangedEvent) {\n emitter.fire(event)\n }When calling this function, the emitter fires and all the event handlers\nare called.
\nSo if you need to trigger events in theia:
\nEclipse Theia is designed in a very modular and extensible way. It supports four ways of being extended/adapted to your specific requirements. These are complementary and are targeted at different use cases. You can pick the best option and even mix them within the same project.\nIn the following, we will give you a quick overview of the available extension mechanisms and provide more details in the sections below.
\nThese are not scoped to frontend connections and have no access (directly) to frontend services.
\nThe following diagram shows the high level architecture for all four options. VS Code extensions and Theia plugins run in a dedicated process per frontend connection, can be installed at runtime, and work against a defined API. Headless plugins similarly run in a dedicated process, but only one that is not associated with any frontend connection. Theia extensions are added during compile time and become a core part of your Theia application. They can access the full API of Theia.
\n![\"Block](\"../../extensiontypes.svg\")
\nIf you would like more guidance on which mechanism to use, please also refer to this detailed comparison between VS Code extensions and Theia extensions.
\nVS Code extensions are the popular mechanism to extend VS Code with new language support and other features. VS Code extensions are simple to develop and they have access to a defined and restricted API. VS Code extensions can be pre-installed (built in), but also installed at runtime (e.g. by the user). Eclipse Theia provides the same extension API as VS Code, so extensions are compatible. Therefore, to develop your own extension, please refer to the VS Code extension documentation. Please also refer to this coverage report, highlighting which API of VS Code is covered by Theia.\nPlease also note that you can use existing VS Code extensions in Theia, too. A good source for installing or downloading extensions is the Open VSX registry.
\nA Theia extension is a module that resides inside a Theia application and directly communicates with other modules (Theia extensions). The Theia project itself is composed of Theia extensions too. To create a Theia application, you can select a number of Theia extensions provided by the Theia project (core extensions), add your own custom Theia extensions and then compile and run the result. Your custom Theia extension will have access to the same API as the core extensions. This modularity allows you to extend, adapt or remove almost anything in Theia according to your requirements. Also, specific use cases, such as complex views are easier to develop with Theia extensions compared to VS Code extensions.\nTechnically, an extension is an npm package that exposes any number of DI modules (ContainerModule) that contribute to the creation of the DI container.\nExtensions are consumed by declaring them as a dependency in the package.json of the application/extension, and are installed at compile time.\nSee this section for more detail on how to author a Theia extension.
Theia plugins are a special type of VS Code extensions that only run in Eclipse Theia. They share the architecture and other attributes of VS Code extensions, but they also have access to additional API that is only available in Theia, not in VS Code. Most noticeable, Theia plugins can also directly contribute to the frontend while VS Code extensions are restricted to the backend. As a consequence Theia plugins can directly manipulate the UI without going through a webview abstraction, easing the development process. Please be aware that the support for Theia Plugins is currently under discussion. We therefore recommend using VS Code extensions or Theia extensions instead of Theia Plugins.
\nHeadless plugins are a special type of plugin that only runs in Eclipse Theia. They are very similar architecturally and otherwise to VS Code extensions, except that they run in the Node backend outside of the scope of any frontend connection. Therefore, they are suitable for extensibility use cases involving CLI interactions where there is no browser frontend and extension of common backend services defined for application-specific purposes. Accordingly, they are not provided with a default API for access to the backend Theia services but have access only to custom APIs published explicitly to them by the application to support the extensibility of its own backend services.
","fields":{"slug":"extensions"}}},"pageContext":{"slug":"extensions"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/frontend_application_contribution/page-data.json b/pr-previews/pr-663/page-data/docs/frontend_application_contribution/page-data.json deleted file mode 100644 index de9025c0..00000000 --- a/pr-previews/pr-663/page-data/docs/frontend_application_contribution/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/frontend_application_contribution/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Frontend Application Contributions"},"html":"Frontend application contributions can react to lifecycle events of the Theia frontend application to execute behavior before the frontend is started or stopped, or once the frontend’s layout is initialized.\nBesides providing a generally useful startup hook, frontend application contributions are also typically used to open and arrange views, register listeners, add status bar items, or customize the layout of the application shell when the application is started.\nAnother use case is to react to shutdown, for instance, to persist certain application data on shutdown, e.g. using the StorageService.
As any other frontend contribution, frontend application contributions are also registered in a frontend module by binding an implementation of the FrontendApplicationContribution interface.\nA typical pattern is a view that shall always be initially opened on startup.\nTherefore, the view implementation does not only extend the AbstractViewContribution<MyWidget>, but is also registered as FrontendApplicationContribution to open the contributed view after the application shell layout is initialized.
export default new ContainerModule(bind => {\n …\n bindViewContribution(bind, MyViewContribution);\n bind(FrontendApplicationContribution).toService(MyViewContribution);\n}Besides the view implementation itself, the view can now implement the method initializeLayout(app: FrontendApplication) from the FrontendApplicationContribution interface to open itself after the layout has been initialized.\nNote that this method is only called if there is no previously stored workbench layout available, which makes it ideal to implement initial workbench layouts, as it won’t override layout changes that users already applied manually in a previous session.
@injectable()\nexport class MyViewContribution extends AbstractViewContribution<MyViewWidget>\n implements FrontendApplicationContribution {\n …\n async initializeLayout(app: FrontendApplication): Promise<void> {\n await this.openView();\n }\n …\n}If a frontend application contribution needs to be invoked every time the application is started -- and not only after initial layout when there is no previously stored layout state -- the methods configure(app: FrontendApplication) and onStart(app: FrontendApplication) can be used instead.\nAs these methods are invoked even before the application shell is attached or menus are initialized, you may want to use those in combination with the frontend application state service, depending on your use case.
@injectable()\nexport class MyViewContribution extends AbstractViewContribution<MyViewWidget>\n implements FrontendApplicationContribution {\n …\n @inject(FrontendApplicationStateService)\n protected readonly stateService: FrontendApplicationStateService;\n …\n async onStart(app: FrontendApplication): Promise<void> {\n this.stateService.reachedState('ready').then(\n () => this.openView({ reveal: true })\n );\n }\n}Another typical use for frontend application contributions is to install listeners, e.g. to react to changes of preferences, or to add custom widgets to the application shell in the configure(app: FrontendApplication) and onStart(app: FrontendApplication) respectively.
This page has been merged into the documentation overview
","fields":{"slug":"getting_started"}}},"pageContext":{"slug":"getting_started"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/i18n/page-data.json b/pr-previews/pr-663/page-data/docs/i18n/page-data.json deleted file mode 100644 index bbaaa561..00000000 --- a/pr-previews/pr-663/page-data/docs/i18n/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/i18n/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Internationalization"},"html":"Theia can be localized by installing Visual Studio Code language packs. Using the Configure Display Language command, users of Theia can change their currently used locale.\nThe framework provides additional features to enable extension developers to localize their own extensions.
Let's say you have a simple string you want to present in the frontend of your application, like a custom widget that displays a goodbye message:
\nrender() {\n return <span>Bye</span>\n}To display this message using different locales, you can use the nls.localize function, imported from the @theia/core package:
render() {\n return <span>{nls.localize('bye', 'Bye')}</span>\n}The first argument is a key to identify the translated value. The second argument is the default value that will be used if the user didn't change their locale. When using template expressions in the frontend, keep in mind that the nls.localize function allows you to format strings using the additional args parameter. When the localize function identifies placeholders in the format {n} where n represents any number, it will try to replace the placeholder with the input parameter at the appropriate position, e.g. {0} will be replaced by the first additional parameter, {1} by the second and so forth:
nls.localize('bye-format', 'Bye {0} and {1}!', first, second);The Command namespace provides an additional utility function to help you localize your extension. The toLocalizedCommand function accepts a Command and localization keys as its arguments. The first additional key will be used to localize the label and the second for the category. If none are provided, the id of the command will be used as the label localization key:
command = Command.toLocalizedCommand({\n id: 'hello-command',\n label: 'Hello'\n category: 'Greetings'\n}, 'hello', 'greetings');After replacing the all user-facing strings with nls.localize calls, you can use the theia nls-extract command of the @theia/cli package to extract all used localization keys into a single JSON file. For the two examples above, it will result in the following JSON output:
{\n \"bye\": \"Bye\",\n \"hello\": \"Hello\",\n \"greetings\": \"Greetings\"\n}You can also group these keys by using forward-slashes. For example, a call like nls.localize('group/bye', 'Bye') will be transformed into this JSON file:
{\n \"group\": {\n \"bye\": \"Bye\"\n }\n}These files will have to be translated into your target languages. Afterwards, you can continue with registering these new localizations for your strings using a custom LocalizationContribution:
// creating your own localization contribution for German, Italian and simplified Chinese\nexport class CustomLocalizationContribution implements LocalizationContribution {\n async registerLocalizations(registry: LocalizationRegistry): Promise<void> {\n // Theia uses language codes, e.g. \"de\" for German\n registry.registerLocalizationFromRequire('de', require('../data/i18n/nls.de.json'));\n registry.registerLocalizationFromRequire('it', require('../data/i18n/nls.it.json'));\n registry.registerLocalizationFromRequire('zh-cn', require('../data/i18n/nls.zh-cn.json'));\n }\n}Lastly, this LocalizationContribution will have to be bound within your backend injection module:
bind(CustomLocalizationContribution).toSelf().inSingletonScope();\nbind(LocalizationContribution).toService(CustomLocalizationContribution);Be aware that the Configure Display Language command only shows a locale once its language pack has been installed. This assures that no parts of the Theia base framework remain untranslated after a user changes the display language.
If you want to deploy your Theia app to a specific region, you may want to change the default locale.\nTo do this you simply add a defaultLocale entry to the frontend configuration of your Theia app in your package.json file:
\"theia\": {\n \"frontend\": {\n \"config\": {\n \"defaultLocale\": \"zh-cn\"\n }\n }\n}The first time a user starts your Theia app, the locale will be automatically set to the selected default locale.\nThey are still free to change the selected locale using the Configure Display Language command.
In this section, we provide a high level overview on how to get started with Eclipse Theia and link to respective sections to read.\nEclipse Theia is a platform for building custom Cloud & Desktop IDEs and tools with modern web technologies. The Eclipse Theia Platform is not a tool itself, but there are many tools which are built upon Theia. The Theia project provides a tool called Eclipse Theia IDE that can be directly used. The Theia IDE can also be used as a template to get started with building your own tool. Please have a look at the project goals for more details!
\nYou cannot directly launch/use Theia as it is a platform. The project provides one tool called Eclipse IDE that you can directly download and use. Further, it is very easy to create your own product based on Theia. Please also refer to this article highlighting the various options available to launch/try Eclipse Theia and Theia-based products.
\nThe first step is to define a custom product based on Theia. Please check out the guide on how to build your own IDE or tool based on Theia. Subsequently, you might want to extend this product with your own feature for which you can use the available extension mechanisms of Theia.
\nIf you are unsure what Theia is, how it compares to other technologies or how to migrate Eclipse-based tools to it, please have a look at resource section.
\nTheia is an open community, and we are glad to help you. You can ask questions using our public community forum, you can report bugs and feature requests, and you can get professional support, consulting and implementation services for building products based on Theia.
\nAlso follow Theia on Twitter to stay up-to-date!
\nRead below to learn how to take part in improving Theia:
\nEPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
","fields":{"slug":"index"}}},"pageContext":{"slug":"index"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/json_rpc/page-data.json b/pr-previews/pr-663/page-data/docs/json_rpc/page-data.json deleted file mode 100644 index d5852ef3..00000000 --- a/pr-previews/pr-663/page-data/docs/json_rpc/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/json_rpc/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Communication via RPC"},"html":"In this section we will explain how you can create a backend service and\nthen connect to it over RPC.
\nWe will use the task execution system as a small example of that.
\nThis works by creating a service exposed by the express framework and\nthen connecting to that over a websocket connection.
\nSo the first thing you will want to do is expose your service so that the\nfrontend can connect to it.
\nYou will need to create backend server module file similar to this (task-backend-module.ts):
\nimport { ContainerModule } from '@theia/core/shared/inversify'';\nimport { ConnectionHandler, RpcConnectionHandler } from '@theia/core/lib/common/messaging';\nimport { TaskClient, TaskServer, taskPath } from '../common/task-protocol';\n\n bind(ConnectionHandler).toDynamicValue(ctx =>\n new RpcConnectionHandler<TaskClient>(taskPath, client => {\n const taskServer = ctx.container.get<TaskServer>(TaskServer);\n taskServer.setClient(client);\n return taskServer;\n })\n ).inSingletonScope();Let's go over that in detail:
\nimport { ConnectionHandler, RpcConnectionHandler } from '@theia/core/lib/common/messaging';This imports the RpcConnectionHandler, this factory enables you to create\na connection handler that onConnection creates a proxy object to the remote object that\nis called in the backend over RPC and optionally exposes a local object to RPC.
We'll see more on how this is done as we go.
\nThe ConnectionHandler is a simple interface that specifies the path of the\nconnection and what happens on connection creation.
It looks like this:
\nimport { Channel } from '../message-rpc/channel';\n\nexport const ConnectionHandler = Symbol('ConnectionHandler');\n\nexport interface ConnectionHandler {\n readonly path: string;\n onConnection(connection: Channel): void;\n}import { TaskClient, TaskServer, taskPath } from '../common/task-protocol';The task-protocol.ts file contains the interfaces that the server and the\nclient need to implement.
The server here means the backend object that will be called over RPC\nand the client is a client object that can receive notifications from the\nbackend object.
\nWe will get more into that later.
\n bind<ConnectionHandler>(ConnectionHandler).toDynamicValue(ctx => {Here a bit of magic happens, at first glance we're just saying here is an\nimplementation of a ConnectionHandler.
The magic here is that this ConnectionHandler type is bound to a\nContributionProvider. A central MessagingContribution picks up all registered connection handlers\nan when this contribution is initialized it creates a websocket channel for all bound ConnectionHandlers.\nTo save resources the hood all MessagingContributions are routed over one\nwebsocket connection (multiplexing).
To dig more into ContributionProvider see this section.
\nSo now:
\n new RpcConnectionHandler<TaskClient>(taskPath, client => {This does a few things if we look at this class implementation:
\nexport class RpcConnectionHandler<T extends object> implements ConnectionHandler {\n constructor(\n readonly path: string,\n readonly targetFactory: (proxy: RpcProxy<T>) => any,\n readonly factoryConstructor: new () => RpcProxyFactory<T> = RpcProxyFactory\n ) { }\n\n onConnection(connection: Channel): void {\n const factory = new this.factoryConstructor();\n const proxy = factory.createProxy();\n factory.target = this.targetFactory(proxy);\n factory.listen(connection);\n }\n}We see that a websocket channel is created on the taskPath (\"/services/task\") by the extension of the ConnectionHandler.
And let's look at what it does onConnection :
onConnection(connection: Channel): void {\n const factory = new this.factoryConstructor();\n const proxy = factory.createProxy();\n factory.target = this.targetFactory(proxy);\n factory.listen(connection);\n }Let's go over this line by line:
\n const factory = new this.factoryConstructor();This creates a ProxyFactory on path \"services/task\".
const proxy = factory.createProxy();Here we create a proxy object from the factory, this will be used to call\nthe other end of the RPC channel using the TaskClient interface.
factory.target = this.targetFactory(proxy);This will call the function we've passed in parameter so:
\n client => {\n const taskServer = ctx.container.get<TaskServer>(TaskServer);\n taskServer.setClient(client);\n return taskServer;\n }This sets the client on the taskServer, in this case this is used to\nrun asynchronous tasks (e.g. a terminal command) in the backend.
And it returns the taskServer as the object that will be exposed over RPC.
factory.listen(channel);This connects the factory to the channel and establishes the RPC protocol.
\nSo now that we have a backend service let's see how to connect to it from\nthe frontend.
\nTo do that you will need something like this:
\n(From task-frontend-module)
import { ContainerModule } from '@theia/core/shared/inversify';\nimport { WebSocketConnectionProvider } from '@theia/core/lib/browser/messaging';\nimport { TaskServer, taskPath } from '../common/task-protocol';\nimport { TaskWatcher } from '../common/task-watcher';\n\nexport default new ContainerModule(bind => {\n bind(TaskServer).toDynamicValue(ctx => {\n const connection = ctx.container.get(WebSocketConnectionProvider);\n const taskWatcher = ctx.container.get(TaskWatcher);\n return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());\n }).inSingletonScope();\n});The important bit here are those lines:
\n bind(TaskServer).toDynamicValue(ctx => {\n const connection = ctx.container.get(WebSocketConnectionProvider);\n const taskWatcher = ctx.container.get(TaskWatcher);\n return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());\n }).inSingletonScope();\nLet's go line by line:
\n const connection = ctx.container.get(WebSocketConnectionProvider);Here we're getting the websocket connection, this will be used to create a proxy from.
\n const taskWatcher = ctx.container.get(TaskWatcher);Here we're creating a watcher, this is used to get notified about events\nfrom the backend by using the taskWatcher's client\n(taskWatcher.getTaskClient())
See more information about how events work in theia here.
\n return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());As the second argument, we pass a local object to handle RPC messages from the remote object.\nSometimes the local object depends on the proxy and cannot be instantiated before the proxy is instantiated.\nIn such cases, the proxy interface should implement RpcServer and the local object should be provided as a client.
export type RpcServer<Client> = Disposable & {\n /**\n * If this server is a proxy to a remote server then\n * a client is used as a local object\n * to handle RPC messages from the remote server.\n */\n setClient(client: Client | undefined): void;\n getClient?(): Client | undefined;\n};\n\nexport interface TaskServer extends RpcServer<TaskClient> {\n // ...\n}\n\nconst serverProxy = connection.createProxy<TaskServer>(\"/services/task\");\nconst client = taskWatcher.getTaskClient();\nserverProxy.setClient(client);So here at the last line we're binding the TaskServer interface to a\nRPC proxy.
Note that his under the hood calls:
\n createProxy<T extends object>(path: string, arg?: object): RpcProxy<T> {\n const factory = arg instanceof RpcProxyFactory ? arg : new RpcProxyFactory<T>(arg);\n this.listen({\n path,\n onConnection: c => factory.listen(c)\n });\n return factory.createProxy();\n }So it's very similar to the backend example.
\nMaybe you've noticed too but as far as the connection is concerned the frontend\nis the server and the backend is the client. But that doesn't really\nmatter in our logic.
\nSo again there's multiple things going on here what this does is that:
\ntaskWatcher.getTaskClient() object.TaskServer.So now instances of TaskServer are proxied over RPC to the\nbackend's TaskServer object.
If you wish to see the complete implementation of what I referred too in\nthis documentation see this commit.
","fields":{"slug":"json_rpc"}}},"pageContext":{"slug":"json_rpc"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/label_provider/page-data.json b/pr-previews/pr-663/page-data/docs/label_provider/page-data.json deleted file mode 100644 index ac77ac10..00000000 --- a/pr-previews/pr-663/page-data/docs/label_provider/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/label_provider/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Label Provider"},"html":"A label provider in Eclipse Theia is responsible for the way elements/nodes are presented in the UI. The label provider determines the icon and the text for elements displayed in trees, lists or other locations such as view headers. A good example is the file explorer: file and directory nodes retrieve their icon and text from the label provider. Another example for the usage of a label provider is the header of an open editor. Please also see the LabelProvider TypeDoc.
\nThe default label provider in Theia browses registered label provider contributions to determine the best fitting one for an element/node. The label provider will delegate the calls for a specific node to the contribution which can best handle the element. Eclipse Theia provides default label provider contributions for common types, e.g. for files. By providing your own label provider contributions, you can extend or adapt the look of specific nodes, based on specific criteria.
\nIn this article we will describe how to customize the label and icon of a custom file type (.my) in Eclipse Theia, as seen in the screenshot below.
\n![\"A](\"../../custom-label-provider.png\")
\nIf you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
\nAll the following code examples are from the Theia extension generator. You can get the same code set-up by installing the generator, selecting the “Label Provider” example (see here) and choosing “labelProvider” as the name.
\nTo contribute a custom label provider contribution you provide a LabelProviderContribution, i.e. a class implementing this interface. In this example, instead of directly implementing the interface, we extend the default implementation for files: FileTreeLabelProvider. This allows us to only override the behavior we want to customize.
labelprovider-contribution.ts
\n@injectable()\nexport class LabelproviderLabelProviderContribution extends FileTreeLabelProviderThe function canHandle determines whether the label provider contribution is responsible for a specific node (in our example for \".my\" files). Therefore, it can check any condition on the respective file, e.g. the file extension. The return value of the function is an integer representing the priority of the label provider contribution, the label provider contribution with the highest priority will be used by the label provider. This way, you can override the default label provider contributions to custom files by returning a higher priority.
The canHandle function receives an object representing the file handed in as a parameter (for the file tree a FileStatNode). Please see an example implementation for canHandle below, which will register a label provider contribution for the file extension “.my”:
labelprovider-contribution.ts
\ncanHandle(element: object): number {\n if (FileStatNode.is(element)) {\n let uri = element.uri;\n if (uri.path.ext === '.my') {\n return super.canHandle(element)+1;\n }\n }\n return 0;\n}Once the label provider contribution is registered for your custom file extension, you can optionally implement getName, getIcon and getLongName. These receive a URI as a parameter and return a custom icon and a custom name for the respective file. Icon and name are used in the file view of Theia. The long name (not customized in the example) is shown as a tooltip when you hover over the file in an opened editor tab. For more details, see the LabelProviderContribution TypeDoc
labelprovider-contribution.ts
\ngetIcon(): string {\n return 'fa fa-star-o';\n}\n\ngetName(fileStatNode: FileStatNode): string {\n return super.getName(fileStatNode) + ' (with my label)';\n}To make our LabelProviderContribution accessible to Theia, we need to bind the custom LabelProviderLabelProviderContribution to the respective contribution symbol LabelProviderContribution. This is done in the labelprovider-frontend-module, for more details see Services and Contributions.
labelprovider-frontend-module.ts
\nexport default new ContainerModule(bind => {\n // label binding\n bind(LabelProviderContribution).to(LabelProviderLabelProviderContribution);\n});The getIcon function returns a CSS string identifying an icon for the custom file type. In the example above, we use a Font Awesome icon. If you want to use a custom icon, you need to add this icon to the CSS as well. Usually, there will be multiple versions of an icon depending on the style (dark vs. light). The following example shows how to add a custom icon. To use this in the example, replace the returned string in getIcon above with ‘my-icon’
example.css
\n.my-icon {\n background-repeat: no-repeat;\n background-size: 12px;\n width: 13px;\n height: 13px;\n}\n.light-plus .my-icon{\n background-image: url('./custom_icon_black_18dp.png');\n}\n.dark-plus .my-icon{\n background-image: url('./custom_icon_white_18dp.png');\n}Theia uses standard technologies for adding language support to custom Theia-based products. By integrating the Monaco Code Editor, Theia supports the language server protocol (LSP) as well as TextMate.
\nWe recommend you use VS Code Extensions which the Theia Framework supports in order to add support for an existing or a custom language. Please refer to the VS Code Language Support documentation for additional details.
","fields":{"slug":"language_support"}}},"pageContext":{"slug":"language_support"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/message_service/page-data.json b/pr-previews/pr-663/page-data/docs/message_service/page-data.json deleted file mode 100644 index dff6eb09..00000000 --- a/pr-previews/pr-663/page-data/docs/message_service/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/message_service/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Message Service"},"html":"The message service allows you to show messages, interactive dialogues and progress information to the user. You can get the MessageService injected and call either info, warn or error on it to report your message (see code example below):
@inject(MessageService) private readonly messageService: MessageService\nthis.messageService.info('Hello World!')By default, Theia will display messages as toast notifications in the bottom right corner. Below you can see screenshots of the different message types (info, warn and error). Please note that you can easily adopt Theia to implement a different behavior for displaying messages by providing a custom MessageClient.
Info
\n![\"Message](\"../../message-service-info.png\")
\nWarn
\n![\"Message](\"../../message-service-warn.png\")
\nError
\n![\"Message](\"../../message-service-error.png\")
\nBy default, notifications will be displayed until the user closes them. You can optionally define a time-out after which messages will be closed automatically:
\nthis.messageService.info('Say Hello with timeout',{timeout: 3000})Optionally, you can also add actions that the user can execute. In case the user executes an action, the message service call will resolve to the action string which was handed over.
\nIn the following code example, we provide the two actions “Say Hello again!” and “Cancel”. We react to the action “Say hello again!” by posting yet another message, “Cancel” will be ignored.
\n@inject(MessageService) private readonly messageService: MessageService\n\nthis.messageService\n .error(\"Hello World!\", \"Say Hello again!\", \"Cancel\")\n .then((action) => {\n if (action === \"Say Hello again!\")\n this.messageService.info(\"Hello again!\");\n })The corresponding toast notification will look like this:
\n![\"Message](\"../../message-service-user-action.png\")
\nWhen the user selects “Say Hello again”, another toast notification will be shown:
\n![\"Message](\"../../message-service-hello-again.png\")
\nThe message service also allows you to report progress on an ongoing operation. You can incrementally update a progress bar and the message while the toast notification remains visible until the operation is done. The following example opens a progress bar and updates the status three times before it is completed. Please see the TypeDoc of MessageService for more detailed information.
this.messageService\n .showProgress({\n text: `Doing something`,\n })\n .then((progress) => {\n // Do something\n progress.report({\n message: \"First step completed\",\n work: { done: 10, total: 100 },\n });\n // Do something\n progress.report({\n message: \"Next step completed\",\n work: { done: 80, total: 100 },\n });\n // Do something\n progress.report({\n message: \"Complete\",\n work: { done: 100, total: 100 },\n });\n progress.cancel();\n })Note that progress.cancel is also used to signal that progress is complete.\nThe code example above will be displayed like this:
![\"Message](\"../../message-service-progress-reporting.gif\")
","fields":{"slug":"message_service"}}},"pageContext":{"slug":"message_service"}},"staticQueryHashes":["2468095761"],"slicesMap":{}}
\ No newline at end of file
diff --git a/pr-previews/pr-663/page-data/docs/page-data.json b/pr-previews/pr-663/page-data/docs/page-data.json
deleted file mode 100644
index 5f67e650..00000000
--- a/pr-previews/pr-663/page-data/docs/page-data.json
+++ /dev/null
@@ -1 +0,0 @@
-{"componentChunkName":"component---src-pages-docs-js","path":"/docs/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Getting Started"},"html":"In this section, we provide a high level overview on how to get started with Eclipse Theia and link to respective sections to read.\nEclipse Theia is a platform for building custom Cloud & Desktop IDEs and tools with modern web technologies. The Eclipse Theia Platform is not a tool itself, but there are many tools which are built upon Theia. The Theia project provides a tool called Eclipse Theia IDE that can be directly used. The Theia IDE can also be used as a template to get started with building your own tool. Please have a look at the project goals for more details!
\nYou cannot directly launch/use Theia as it is a platform. The project provides one tool called Eclipse IDE that you can directly download and use. Further, it is very easy to create your own product based on Theia. Please also refer to this article highlighting the various options available to launch/try Eclipse Theia and Theia-based products.
\nThe first step is to define a custom product based on Theia. Please check out the guide on how to build your own IDE or tool based on Theia. Subsequently, you might want to extend this product with your own feature for which you can use the available extension mechanisms of Theia.
\nIf you are unsure what Theia is, how it compares to other technologies or how to migrate Eclipse-based tools to it, please have a look at resource section.
\nTheia is an open community, and we are glad to help you. You can ask questions using our public community forum, you can report bugs and feature requests, and you can get professional support, consulting and implementation services for building products based on Theia.
\nAlso follow Theia on Twitter to stay up-to-date!
\nRead below to learn how to take part in improving Theia:
\nEPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
","fields":{"slug":"index"}}},"pageContext":{}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/preferences/page-data.json b/pr-previews/pr-663/page-data/docs/preferences/page-data.json deleted file mode 100644 index 33da2deb..00000000 --- a/pr-previews/pr-663/page-data/docs/preferences/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/preferences/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Preferences"},"html":"Theia has a preference service which allows modules to get preference values, contribute default preferences and listen for preference changes.
\nPreferences can be saved in the root of the workspace under .theia/settings.json or under $HOME/.theia/settings.json on Linux systems. For Windows systems, the user settings will by default be in the %USERPROFILE%/.theia/settings.json (something like C:\\Users\\epatpol\\.theia/settings.json)
As of right now the files must contain a valid a JSON containing the names and values of preferences (note that the following preference names are not official and only used as an example). You can also add comments to the settings.json file if needed i.e.
\n{\n // Enable/Disable the line numbers in the monaco editor\n\t\"monaco.lineNumbers\": \"off\",\n // Tab width in the editor\n\t\"monaco.tabWidth\": 4,\n\t\"fs.watcherExcludes\": \"path/to/file\"\n}Let's take the filesystem as an example of a module using the preference service
\nTo contribute some preference values. A module must contribute a valid json schema that will be used to validate the preferences. A module must bind the following PreferenceContribution to a value like this:
\nexport interface PreferenceSchema {\n [name: string]: Object,\n properties: {\n [name: string]: object\n }\n}\n\nexport interface PreferenceContribution {\n readonly schema: PreferenceSchema;\n}For instance, the filesystem binds it like so:
\nexport const filesystemPreferenceSchema: PreferenceSchema = {\n \"type\": \"object\",\n \"properties\": {\n \"files.watcherExclude\": {\n \"description\": \"List of paths to exclude from the filesystem watcher\",\n \"additionalProperties\": {\n \"type\": \"boolean\"\n }\n }\n }\n};\n\nbind(PreferenceContribution).toConstantValue(\n{\n schema: filesystemPreferenceSchema\n});Here are some useful links for contributing a validation schema:
\n\nTo use the value of a preference, simply get the injected PreferenceService from the container
\nconst preferences = ctx.container.get(PreferenceService);In the case of the filesystem, the service is fetched at the beginning for the bindings. There, you can use the onPreferenceChanged method to register a pref changed callback.
\n\nconstructor(@inject(PreferenceService) protected readonly prefService: PreferenceService\n\tprefService.onPreferenceChanged(e => { callback }Where the event received e is like this:
export interface PreferenceChangedEvent {\n readonly preferenceName: string;\n readonly newValue?: any;\n readonly oldValue?: any;\n}Although this can be used directly in the needed class, the filesystem provides a proxy preference service specific to the filesystem preferences (which uses the preference service in the background). This allows for faster and more efficient searching for the preference (as it searches for the preference in the filesystem preference service, and not on all preferences via the more generic preference service). It's also more efficient in the sense that only the modules watching for specific preferences related to a module will be notified. To do so, there is a proxy interface for the filesystem configuration that is bound like so using the preference proxy interface:
\nexport type PreferenceProxy<T> = Readonly<T> & Disposable & PreferenceEventEmitter<T>;\nexport function createPreferenceProxy<T extends Configuration>(preferences: PreferenceService, configuration: T): PreferenceProxy<T> {\n /* Register a client to the preference server\n When a preference is received, it is validated against the schema and then fired if valid, otherwise the default value is provided.\n\n This proxy is also in charge of calling the configured preference service when the proxy object is called i.e editorPrefs['preferenceName']\n\n It basically forwards methods to the real object, i.e dispose/ready etc.\n}To use that proxy, simply bind it to a new type X = PreferenceProxy<CONFIGURATION_INTERFACE> and then bind(X) to a proxy using the method above.
\nexport interface FileSystemConfiguration {\n 'files.watcherExclude': { [globPattern: string]: boolean }\n}\n\nexport const FileSystemPreferences = Symbol('FileSystemPreferences');\nexport type FileSystemPreferences = PreferenceProxy<FileSystemConfiguration>;\n\nexport function createFileSystemPreferences(preferences: PreferenceService): FileSystemPreferences {\n return createPreferenceProxy(preferences, defaultFileSystemConfiguration, filesystemPreferenceSchema);\n}\n\nexport function bindFileSystemPreferences(bind: interfaces.Bind): void {\n\n bind(FileSystemPreferences).toDynamicValue(ctx => {\n const preferences = ctx.container.get(PreferenceService);\n return createFileSystemPreferences(preferences);\n });\n\n bind(PreferenceContribution).toConstantValue({ schema: filesystemPreferenceSchema });\n\n}Finally, to use the filesystem configuration in your module. Simply inject it where you need it. You can then access the preference like so (filesystem example) :
\nconst patterns = this.preferences['files.watcherExclude'];and you can also register for preference change like so:
\nthis.toDispose.push(preferences.onPreferenceChanged(e => {\n if (e.preferenceName === 'files.watcherExclude') {\n this.toRestartAll.dispose();\n }\n}));constructor(...,\n @inject(FileSystemPreferences) protected readonly preferences: FileSystemPreferences) {\n\t...\n this.toDispose.push(preferences.onPreferenceChanged(e => {\n if (e.preferenceName === 'files.watcherExclude') {\n this.toRestartAll.dispose();\n }\n }));\n\t...\n}As of right now, when a settings.json is modified either in the ${workspace}/.theia/ or in the os.homedir()/.theia/, this will trigger an event from the JSON preference server. Currently, there's a CompoundPreferenceServer that manages the different servers (scopes) like workspace/user/defaults (provided via the contributions above). Next, the PreferenceService manages this server and adds a more convenient API on top of it (i.e. getBoolean, getString etc.). It also allows clients to registers for preference changes. This PreferenceService can then be used either directly via injection in the modules, or via a more specific proxy (like the filesystem configuration from above).
In the case of the preference file being modified, the flow would then be:
\n.theia/settings.json -> JsonPreferenceServer -> CompoundPreferenceServer -> PreferenceService -> PreferenceProxy<FileSystemConfiguration> -> FileSystemWatcherIn the case of the filesystem, one would use the same proxied config as above to access the preferences.
\n if (this.prefService['preferenceName']) {\n ...\n }\n\n if (this.prefService['preferenceName2']) {\n ...\n }\n})This works because, as we have seen it above, the proxy will simply call prefService.get('preferenceName').
\nThis section describes the overall goals of the Eclipse Theia project.
\nEclipse Theia mission statement: A framework for building tools and IDEs based on web technologies.
\nThe goal of the Eclipse Theia project is to provide a platform for efficiently developing tools and IDEs based on a modern web technology stack. The primary target group for Theia is developers implementing a custom tool for end users. As Theia-based products are typically customized, branded and labeled by its adopters, the actual end users may not even be aware of the Theia project they are using under the hood. Therefore, end users are only an indirect secondary target group of Theia.
\nTools and IDEs built on Theia can run as desktop applications or in the browser. The backend of Theia can run locally (for the desktop case) or as a remote service in the cloud. Both variants currently have an equal priority.
\nTheia is targeted at building a variety of custom tools. Prominent examples of Theia-based products include IDE's, but Theia also explicitly targets tools that do not focus on textual input/editors or software development. Thus, Theia's scope also included diagram editors or form-based UI. The Theia platform hence covers the typical application scenarios of the Eclipse rich-client platform (Eclipse RCP). As a consequence, the platform aims at making as few assumptions as possible about what adopters might want to build with Theia. It explicitly allows deviation from the standard workbench layout and the removal of all default features.
\nTheia provides a workbench frame, i.e., a window management system permitting the display of views, editors, and menus and makes available tools and interactions allowing the user to modify of the window layout, trigger commands, and use key bindings and other concepts known from a desktop tool such as drag and drop.
\nTheia optionally provides common tool features as components to be reused by adopters. Common features are generic, so that they may be reused in several tools. Examples for these common tool features include a file explorer, Git support and a code editor.
\nTheia is an extensible and adaptable framework. Extensibility in this context means that you can easily add new features to a product built on the Theia platform (including UI and backend functionality). These new features can either be provided by the Theia project itself (common features), by other projects (e.g. Eclipse GLSP) or be custom features that are developed by an adopter. Adaptable in this context means that the workbench and all common features that are provided by the Theia project can be customized and adapted to project-specific needs. This includes changing or removing existing features and adjusting the look and feel.
\nTheia provides the ability to host VS Code extensions. This allows adopters to benefit from features that are provided as VS Code extensions and make them part of their tool offering. It also allows end users of Theia-based tools to install additional features, if the adopter providing a tool allows users to do so. When applicable, the default Theia UX aligns with the VS Code UI, although adopters can deviate from this.
\nTheia uses/reuses industrial standard technologies and practices whenever applicable. This keeps the scope of the project minimal and decreases the maintenance cost. This applies to the use of frameworks and development tools as well as to general concepts such as UX.
\nThe Eclipse Theia project does not primarily aim to provide products for end users but focuses on offering a platform for building products. However, the project provides product templates, a.k.a. “Blueprints”. These blueprints serve two purposes. First, they allow adopters to consume example Theia-based products from the view point of an end user, which enables them to evaluate the underlying platform without first creating a product based on it. Second, the blueprints serve as templates to create custom products. Therefore, the template products contain documentation on how to customize them.
\nEclipse Theia is an open and vendor-neutral project with a diverse community of contributors from large corporations down to small companies and even individual developers. This diverse and steadily growing community is a stable base for the ongoing development of additional features and maintenance of existing functionality based on a broad and balanced view of the requirements put forward by the Theia adopters. The commercial-friendly licensing and the rigorous underlying IP management ensures that adopters can safely build commercial and internal products based on Theia. Project communication is open and transparent and welcomes new adopters by keeping the barriers of contribution as low as possible. Decisions in the project are based on the principle of meritocracy meaning that the weight of contributors in decisions is solely based on their achievements for the project as recognized by their peers. This provides an important incentive for contributors to make contributions. The open governance and diverse community of Theia is one of its strongest assets for its mid- to long-term evolution and viability.
","fields":{"slug":"project_goals"}}},"pageContext":{"slug":"project_goals"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/property_view/page-data.json b/pr-previews/pr-663/page-data/docs/property_view/page-data.json deleted file mode 100644 index 03a14b62..00000000 --- a/pr-previews/pr-663/page-data/docs/property_view/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/property_view/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Property View"},"html":"Many IDEs, such as the traditional Eclipse IDE, have the notion of a global, extensible property view,\nwhich shows additional information about the current selection within the IDE.\nProperty views are heavily used in those IDEs for showing details of elements in e.g. diagram editors,\ncomplex tree editors, or the file explorer selection.\nTherefore, the main idea is to have a global, generic property view in the IDE,\nbut allow specific implementations to extend the contents of the global property view\nwith specific additional information for some type of selection.
\nThe @theia/property-view extension contributes a generic, global property view based on Theia's global selection.\nThe property view widget can be opened/toggled either via menu View->Properties or via shortcut Shift+Alt+P.\nIt is located in the bottom dock area by default.\nThe following two default content widgets are implemented in this extension:
EmptyPropertyViewWidget: If no other widget can be provided, a simple message (No properties available) is shown.ResourcePropertyViewWidget: Displays additional information about a file (e.g. location, name, last modified) that is selected in the file explorer or in the active monaco editor.To contribute a specific property view, it is necessary to implement a PropertyViewDataService which gathers the property data for a selection\nas well as a PropertyViewWidgetProvider which provides a suitable content widget to display the property data for a specific selection inside the property view widget.
Here is a short example of how to implement an additional property view, which displays the name and whether it is a file or directory\nin a simple React widget based on the selection from the file explorer (assuming there would be no ResourcePropertyViewWidget of course):
The FileInfoPropertyDataService gathers the file information and delivers a custom object:
custom-data-service.ts:
export interface FileInfoPropertyObject {\n name: string;\n isDirectory: boolean;\n}\n\n@injectable()\nexport class FileInfoPropertyDataService implements PropertyDataService {\n\n readonly id = 'fileinfo';\n readonly label = 'FileInfoPropertyDataService';\n\n @inject(LabelProvider) protected readonly labelProvider: LabelProvider;\n\n canHandleSelection(selection: Object | undefined): number {\n return this.isFileSelection(selection) ? 1 : 0;\n }\n\n private isFileSelection(selection: Object | undefined): boolean {\n return !!selection && Array.isArray(selection) && FileSelection.is(selection[0]);\n }\n\n async providePropertyData(selection: Object | undefined): Promise<FileInfoPropertyObject | undefined> {\n if (this.isFileSelection(selection) && Array.isArray(selection)) {\n return {\n name: this.labelProvider.getName(selection[0].fileStat.resource),\n isDirectory: (selection[0].fileStat as FileStat).isDirectory\n };\n }\n return Promise.reject();\n }\n}The FileInfoPropertyWidget is a simple ReactWidget and displays the selected node and whether it is a file or directory:
custom-content-widget.tsx:
export class FileInfoPropertyViewWidget extends ReactWidget implements PropertyViewContentWidget {\n\n static readonly ID = 'file-info-property-view';\n static readonly LABEL = 'File Information';\n\n protected currentFileInfo: FileInfoPropertyObject;\n\n constructor() {\n super();\n this.id = FileInfoPropertyViewWidget.ID;\n this.title.label = FileInfoPropertyViewWidget.LABEL;\n this.title.caption = FileInfoPropertyViewWidget.LABEL;\n this.title.closable = false;\n this.node.tabIndex = 0;\n }\n\n updatePropertyViewContent(propertyDataService?: PropertyDataService, selection?: Object | undefined): void {\n if (propertyDataService) {\n propertyDataService.providePropertyData(selection).then((fileInfo: FileInfoPropertyObject) => this.currentFileInfo = fileInfo);\n }\n this.update();\n }\n\n protected render(): React.ReactNode {\n return (<div>\n {`Selected node in explorer: ${this.currentFileInfo.name} ${this.currentFileInfo.isDirectory ? '(Directory)' : '(File)'}`\n }\n </div>);\n }\n}The FileInfoPropertyViewWidgetProvider is responsible to provide the correct PropertyViewContentWidget based on the selection:
custom-widget-provider.ts:
@injectable()\nexport class FileInfoPropertyViewWidgetProvider extends DefaultPropertyViewWidgetProvider {\n\n override readonly id = 'fileinfo';\n override readonly label = 'FileInfoPropertyViewWidgetProvider';\n\n private fileInfoWidget: FileInfoPropertyViewWidget;\n\n constructor() {\n super();\n this.fileInfoWidget = new FileInfoPropertyViewWidget();\n }\n\n override canHandle(selection: Object | undefined): number {\n return this.isFileSelection(selection) ? 1 : 0;\n }\n\n private isFileSelection(selection: Object | undefined): boolean {\n return !!selection && Array.isArray(selection) && FileSelection.is(selection[0]);\n }\n\n override provideWidget(selection: Object | undefined): Promise<FileInfoPropertyViewWidget> {\n return Promise.resolve(this.fileInfoWidget);\n }\n\n override updateContentWidget(selection: Object | undefined): void {\n this.getPropertyDataService(selection).then(service => this.fileInfoWidget.updatePropertyViewContent(service, selection));\n }\n}In the frontend module of the application the FileInfoPropertyDataService as well as the FileInfoPropertyViewWidgetProvider are registered as follows:
bind(PropertyDataService).to(FileInfoPropertyDataService).inSingletonScope();\nbind(PropertyViewWidgetProvider).to(FileInfoPropertyViewWidgetProvider).inSingletonScope();Following these few steps should give the reader an idea on how to implement an own property view, consisting of a specific PropertyViewWidgetProvider and PropertyViewDataService.
The resulting property view will be displayed like this:
\n![\"Property](\"../../custom-property-view.gif\")
","fields":{"slug":"property_view"}}},"pageContext":{"slug":"property_view"}},"staticQueryHashes":["2468095761"],"slicesMap":{}}
\ No newline at end of file
diff --git a/pr-previews/pr-663/page-data/docs/services_and_contributions/page-data.json b/pr-previews/pr-663/page-data/docs/services_and_contributions/page-data.json
deleted file mode 100644
index 5f6ddfb5..00000000
--- a/pr-previews/pr-663/page-data/docs/services_and_contributions/page-data.json
+++ /dev/null
@@ -1 +0,0 @@
-{"componentChunkName":"component---src-templates-doc-js","path":"/docs/services_and_contributions/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Services and Contributions"},"html":"In this section we describe how Theia extensions can use services provided by the platform and by other extensions. Furthermore, we describe how extensions can contribute to the Theia workbench via contribution points.
\nA service is an object that provides functionality to its consumers. The contract between a service and its consumers is described by an interface. Any implementation of a service must implement that interface according to the interface documentation. Any extension in Theia can provide and/or consume services. The extensions provided by the Theia platform provide a set of default services, e.g. the MessageService. However, you can provide and consume your own custom services, too.
Contribution points define hooks, which allow extending something. Contribution points are defined by an interface that the contributor is expected to implement, e.g. a CommandContribution. The extension defining the contribution point will then pick up the contribution, e.g. adding the contributed command to the Theia workbench.
Contribution points, like services, can be contributed to and defined by any extension. The Theia platform defines a set of default contribution points, e.g. to add commands or menus to the Theia workbench. However, you can also define your own ones.
\nThe usage of services and contribution points requires communication between extensions. To avoid direct dependencies on the implementation classes, Theia uses dependency injection.
\n![\"Dependency](\"../../dependency-injection.png\")
\nIn the following sections, we provide a quick overview of dependency injection, services, contributions and how to define contribution points.
\nTheia uses the DI framework InversifyJS to wire ups the difference services and contributions points.
\nDependency injection decouples the consumers of services -- i.e. the dependencies of those consumers -- from the actual creation and retrieval of those services. As an example, if you want to use a service, you neither have to instantiate it, nor do you need to manually retrieve it from somewhere. Instead, the dependency injection container injects the services on creation of your component. The dependency injection container resolves the dependency for you and, if necessary, even instantiates it on the fly. With that, the consumer of services doesn’t need to worry where they come from. You can easily exchange the actual implementations of services later on without having to change the consumers. The dependency injection container works based on some configuration you provide on startup through so-called container modules.
\nWe will provide examples on how to use dependency injection in the sections “Services” and “Contributing to contribution points” below.
\nDependency injection is an integral part of Theia. Therefore, we highly recommend learning at\nleast the basics of InversifyJS. For more details, please also refer to this article on how dependency injection works in Theia
\nTo use a service in Theia, you can get it injected as a dependency using DI. Dependencies are usually specified via the interface of the service you want to retrieve. This way, you even avoid a dependency on any specific implementation, the caller just knows the interface. This allows the component providing the implementation to seamlessly replace the implementation of a service. You can even override the existing default implementation of a service without breaking any service consumers.
\nTo get a parameter injected from the dependency injection container, you need to annotate it with an identifier (a string). Service providers on the other hand will publish the available services using an identifier, too. When a parameter with a specific identifier is requested via dependency injection, the dependency injection context will look it up and return an instance of the respective service. For convenience service providers usually use a Symbol as an identifier that has exactly the same name as the respective service interface itself. The following examples the '@inject(MessageService)' is the symbol (service identifier), while 'private readonly messageService: MessageService' is referring the interface of the service.
\nServices, or more generically, dependencies can be injected as fields, in the constructor or in initialization functions (see following code example).
\n// Injection in the constructor.\nconstructor(@inject(MessageService) private readonly messageService: MessageService) { }\n\n// Injection as a field.\n@inject(MessageService)\nprotected readonly messageService!: MessageService;\n\n// Injection in an initialization function (will be called after the constructor and after injecting fields.\n@postConstruct()\nprotected async init(@inject(MessageService) private readonly messageService: MessageService) { }Please note that injection will only work in components that are created by the DI container. Therefore, they must be marked with @injectable (see code example below). Furthermore, they must be registered in the DI context (for an example see next section).
@injectable()\nexport class MyContribution implements SomeContributionInterfaceContribution Points in Theia define an interface to be implemented, e.g. CommandContribution. A contributing extension must provide an implementation of this interface and mark it with @injectable, e.g.:
mycommand-contribution.ts
\n@injectable()\nexport class MyCommandContribution implements CommandContributionAdditionally, the contribution must be bound in the DI container, so that the contribution point provider can pick up our contribution, more precisely get it injected. The binding is done in the container module of an extension. It binds the implementation to the contribution interface, or to be technically correct, to the Symbol representing the interface (see example below).
\nhelloworld-frontend-module.ts
\nexport default new ContainerModule(bind => {\n // add your contribution bindings here\n bind(CommandContribution).to(HelloworldCommandContribution);\n...\n});Please see Commands/Menus/Keybindings for a simple example for the usage of services and contribution points.
\nIf an extension wants to provide a hook for others to contribute to, they\nshould define a contribution-point. A contribution-point is just an\ninterface that many others can implement. The extension will delegate to them\nwhen needed.
\nThe OpenerService, for instance, defines a contribution point to allow others\nregistering OpenHandlers. You can have a look at the code\nhere.
Theia comes with an extensive list of contribution points already. A good way\nto see what contribution points exist is to do a find references on\nbindContributionProvider.
A contribution provider is basically a container for contributions where\ncontributions are instances of a bound type.
\nIt is very generic.
\nTo bind a type to a contribution provider you can do like this:
\n(From messaging-module.ts)
\nexport const messagingModule = new ContainerModule(bind => {\n bind<BackendApplicationContribution>(BackendApplicationContribution).to(MessagingContribution);\n bindContributionProvider(bind, ConnectionHandler)\n});The last line will bind a ContributionProvider to one that contains all\nConnectionHandler bound instances.
\nIt is used as such:
\n(From messaging-module.ts)
\n constructor( @inject(ContributionProvider) @named(ConnectionHandler) protected readonly handlers: ContributionProvider<ConnectionHandler>) {\n }\nSo here we're injecting a ContributionProvider with the named\nConnectionHandler value that was bound before by bindContributionProvider.
This enables anyone to bind a ConnectionHandler and now when the\nmessagingModule is started all the ConnectionHandlers will be initiated.
","fields":{"slug":"services_and_contributions"}}},"pageContext":{"slug":"services_and_contributions"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/tasks/page-data.json b/pr-previews/pr-663/page-data/docs/tasks/page-data.json deleted file mode 100644 index 8dc2ff40..00000000 --- a/pr-previews/pr-663/page-data/docs/tasks/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/tasks/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Tasks"},"html":"Eclipse Theia users can execute tasks to automate certain steps in their workflow.\nTasks can be invoked via the main menu Terminal or via the command palette.\nEvery task is defined by a task configuration, which specifies among other properties the task type, a label, optionally a description, whether it is a background task or not, whether it is a build or test task, its dependencies to other tasks, etc.\nTasks in Eclipse Theia are structurally compatible with Visual Studio Code tasks.\nSimilar to Visual Studio Code, users can define tasks in a file named tasks.json file in the workspace or on user level.
In Eclipse Theia, tasks can also be provided from and executed by custom Theia extensions.\nIn particular, Theia offers the three main contribution points for tasks: TaskProvider, TaskResolver and TaskRunner.\nTo better understand the purpose of those, let’s look at the flow, through the involved components, when a user selects and executes a task in the following figure.
![\"Task](\"../../tasks.png\")
\nBesides the user-defined task configurations, Eclipse Theia will also offer its users all task configurations collected from the registered task providers.\nWhen a user selects one of the provided task configurations and executes it, the configuration will be handed over to the task service, which will first resolve the selected task configuration using a resolver that is registered for the selected task configuration’s type.\nA task resolver can manipulate the task configuration before it is actually executed.\nThis is useful for, e.g., filling in default values and resolving custom variables in a task configuration.\nOnce the configuration is resolved, the task service requests the execution of the resolved task configuration on the task server, which runs on the backend.\nTo actually perform the resolved task configuration, the task server looks up the task runner registered for the configuration’s type.\nFinally, the task runner is responsible for actually performing the task according to the specified task configuration.
\nTheia provides dedicated contribution points for task providers, task resolvers, and task runners.\nThus, Theia extensions can extend the list of available tasks with custom task types, handle the resolution of task configurations of custom task types, as well as implement their execution.
\nIn the following example, we will contribute a custom task provider, which provides a custom task.\nFurther, we will add a custom task resolver that will enhance the task configuration before execution.\nFinally, we will contribute a custom task runner that executes our provided task.
\nTask providers and task resolvers are contributed via an implementation of TaskContribution.\nLike all contributions, it must be bound in the respective front end module as shown below.\nIf you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
export default new ContainerModule(bind => {\n bind(TaskContribution).to(MyTaskContribution);\n});Our TaskContribution contributes a task provider and a task resolver (see following listing). Their implementation is shown below. By specifying a task type along with the registration, Theia will pick the right resolver and runner for our custom task type (myTaskType).
@injectable()\nexport class MyTaskContribution implements TaskContribution {\n\n registerProviders(providers: TaskProviderRegistry): void {\n providers.register('myTaskType', new MyTaskProvider())\n }\n\n registerResolvers(resolvers: TaskResolverRegistry): void {\n resolvers.registerTaskResolver('myTaskType', new MyTaskResolver())\n }\n}Our example task provider contributes exactly one task:
\nclass MyTaskProvider implements TaskProvider {\n async provideTasks(): Promise<TaskConfiguration[]> {\n return [{\n label: 'My Custom Task',\n type: 'myTaskType',\n _scope: 'MyTaskProvider'\n }];\n }\n}Our example task resolver always sets property myCustomValue to the static value 42.\nIn a real scenario, it would check whether it is set in the specified taskConfig and only add it if it is not set. Or it would resolve variables specified in the taskConfig.
class MyTaskResolver implements TaskResolver {\n async resolveTask(taskConfig: TaskConfiguration):Promise<TaskConfiguration> {\n return {...taskConfig, myCustomValue: 42 }\n }\n}Task runners are contributed via a TaskRunnerContribution. As we use dependency injection to create the actual task runner, we bind the contribution and the task runner itself in our module:
export default new ContainerModule(bind => {\n bind(MyTaskRunner).toSelf().inSingletonScope();\n bind(TaskRunnerContribution).to(MyTaskRunnerContribution);\n});In our TaskRunnerContribution, we register an instance of our custom task runner at the TaskRunnerRegistry along with the task type our runner is responsible for.
@injectable()\nexport class MyTaskRunnerContribution implements TaskRunnerContribution {\n\n @inject(MyTaskRunner)\n protected readonly myTaskRunner: MyTaskRunner;\n\n registerRunner(runners: TaskRunnerRegistry): void {\n runners.registerRunner('myTaskType', this.myTaskRunner);\n }\n}Task runners need to implement the interface TaskRunner.\nThe function run receives the TaskConfiguration when a task is triggered and is responsible for actually running the operation.\nIn our example, we instantiate a custom implementation of Task called MyTask and execute it with the current configuration.\nUsing the existing interface Task allows us to connect the task to the TaskManager which will show visual feedback in the workbench during tasks execution (see screenshot below).
@injectable()\nexport class MyTaskRunner implements TaskRunner {\n\n @inject(TaskManager)\n protected readonly taskManager: TaskManager;\n\n @inject(ILogger)\n protected readonly logger: ILogger;\n\n async run(config: TaskConfiguration, ctx?: string): Promise<Task> {\n const myTask = new MyTask(this.taskManager, this.logger,\n { config, label: 'My Custom Task' });\n myTask.execute(config.myCustomValue);\n return myTask;\n }\n}Finally, our custom task configuration will wait for 5000 ms and then print out the custom value we have added in our task resolver before:
\nclass MyTask extends Task {\n execute(myCustomValue: number) {\n this.logger.info(`Start running custom task: ${myCustomValue}`);\n setTimeout(() => {\n this.logger.info(`Finished running custom task: ${myCustomValue}`);\n this.fireTaskExited({ taskId: this.taskId, code: 0 });\n }, 5000);\n }\n …\n}As you can see in the screenshot below, our custom task is running for 5000 ms (as we set a timeout in MyTask) and then it stops.
![\"Running](\"../../running-custom-task.gif\")
\nAs can be seen in the console output, the task starts and finishes 5000 ms later, and prints the custom variable that has been added by the custom resolver.
\nroot INFO Start running custom task: 42\nroot INFO Finished running custom task: 42Extensions can also omit contributing a task provider, but only contribute a runner (and optionally a resolver).\nAs a consequence, those custom tasks are not provided automatically to users, but users can still configure tasks based on these custom task types in their tasks.json file.\nTo support users in the creation of such user-defined task configurations for custom task types, Theia provides a dedicated contribution point for task definitions.\nA task definition essentially specifies a JSON schema defining the properties that can or need to be specified for a task of a certain custom type.
This section explains how to build custom AI assistants and integrate AI support into custom tools and IDEs using Theia AI. Theia AI, part of the Theia Platform, is a powerful framework designed to help tool builders integrate tailored AI capabilities into their tools and IDEs with ease (see also this Theia AI introduction). It provides reusable components, prompt management, LLM integration, and flexible user interfaces, allowing you to focus on delivering domain-specific AI features. This section is targeted at tool builders using Theia and Theia AI as a platform to build custom tools and IDEs.\nFor detailed information on how to use the experimental AI features in the Theia IDE as an end user, refer to the user documentation.\nTo learn how to generally extend Theia by creating Theia extensions, including AI ones, visit the extension authoring guide.
\n![\"High](\"../../theia-ai-architecture.png\")
\nHigh Level Architecture of Theia AI
\nIn this section, we will introduce the concept of agents and demonstrate how to create your own custom agents. An Agent in Theia AI is a self-contained component mediating between the user interface that triggers the agent, and the LLM. Thus, it is typically invoked with a user input or a UI event, collects relevant context, produces one or more prompts, handles the communication with a language model (LLM),, and invokes actions in the tool and/or returns outputs to the UI as a result. Each agent can have unique behavior based on its design.
\nAgents can generally be integrated into any part of the tool (e.g., terminals, editors, custom widgets) and also interact with any available and exposed API of Theia to collect context, trigger actions, or show results. A special type of agent in Theia AI is ‘Chat Agent’, which is automatically integrated into Theia AI’s default chat UI. A chat agent handles conversational interactions, making them suitable for tasks like answering questions in a chat interface.
\nAn important design decision is how you split your AI feature set among agents. Please note that Theia AI enables any kind of modularity from one agent capable of handling many types of user requests or events to an agent delegating sub-tasks to other agents, or even several agents operating on one request. Agents can communicate with each other, so you can chain agents for one user request. This decision really depends on the specific use cases and project. Theia AI makes it easy to iteratively refine the modularity of agents while developing it. A good start is typically to start with one agent per use case.
\nThis guide will walk you through creating agents and chat agents using Theia AI, providing a deeper understanding of the framework and how to leverage it for custom use cases.
\nIn general, an agent is essentially an injectable Theia service offering a specific API for its clients, such as custom widgets, editors, or menu items. Clients can obtain the instance of the agent from the agent registry or get it injected via DI, and call its methods. Usually those methods are very use case specific, often taking parameters for context that are relevant and already available to the clients calling the agents. The agent will then construct one or more prompts, obtain one or more language models, process its output, invoke actions in Theia and/or return a result to the client, e.g. to show a result message, offer follow-up questions or buttons to perform actions.
\nAs you see, an agent is rather generic — and this is on purpose. It is designed to cater many different use cases integrated in a variety of UI components, widgets, or editors. An example of such an agent in the Theia IDE is the code completion agent integrated in the code editor.
\nA Chat Agent is integrated into the default chat UI provided by Theia AI and thus needs to implement a more specific interface, so it can be invoked from the chat UI generically. It’s designed for conversational interaction with users.
\nLet’s create a new agent for the Theia IDE as an example! This new agent will assist users in identifying (and later executing) arbitrary commands in the Theia IDE, such as opening the settings or showing the toolbar. You can review the full code of this agent as a reference.
\nThe first step in creating a chat agent is defining the system prompt template, which acts as the foundation for guiding how the agent interacts with the LLM.
\nexport const commandPromptTemplate: PromptTemplate = {\n id = 'command-chat-agent-system-prompt-template';\n template = `Always respond with: “I am the command agent`;\n}This template sets the behavior of the agent, in the example above, it will always respond with a test String for now.
\nNext, we will create the chat agent, which allows you to customize the agent’s behavior, specify its language model requirements, which prompt templates it uses, and define its interaction with users. In our case, we want to create a simple Chat Agent for which we extend the reusable base implementation provided by Theia AI (see code example below).\nAbstractChatAgent takes care of a basic conversation flow and streaming, so we literally only need to define a name, an id, a description and which system prompt our agent uses. This agent will be available in the default chat UI and can be referenced via @Command. The agent will respond based on the behavior defined in the prompt.
export class CommandChatAgent extends AbstractChatAgent {\n id: string = 'Command';\n name: string = 'Command';\n description: string = `Helps users find and execute commands in the IDE`;\n variables: string[] = []; // Optional: define variables for dynamic data insertion.\n promptTemplates: PromptTemplate[] = [commandPromptTemplate];\n\n protected async getSystemMessage(): Promise<SystemMessage | undefined> {\n const systemPrompt = await this.promptService.getPrompt('command-system');\n return SystemMessage.fromResolvedPromptTemplate(systemPrompt);\n }\n}In the example above, we retrieve the prompt from Theia AIs Prompt Service. This provides features such as automatic variable resolvement. The usage of the Prompt Service is of course optional, as an agent implemented you can also simply define your own data structure if you prefer.\nIn the example above, we also register our prompt template with Theia AI. With this, Theia AI can provide generic features such as the prompt editor, but of course this is again up to the agent implementer whether to register prompts or not.
\nTo integrate our agent with Theia AI, we need to register it. Theia as a platform is modular, so we can just register the agent along with the existing agents via dependency injection, no forking or customization of Theia framework code is required. See also the section on services and contributions and specifically the section on contribution points.\nIn the following code example, we register our agent as an ‘Agent’ and as a ‘ChatAgent’. With this, the simple agent above will already be available in the default chat, you can directly “talk” to it via typing “@Command”. In the current state, it will of course only respond with “I am the command agent”.
\nbind(Agent).toService(CommandChatAgent);\nbind(ChatAgent).toService(CommandChatAgent);The next step is typically the most effort and it is actually unrelated to Theia AI: You need to develop the behavior of the agent, including one or more prompts that reliably return the expected output.
\nIn our example, we want to return an executable Theia command that the user is looking for with their question. For this, we need to augment our prompt with variables (see section “Variables and Tool Functions”) to give the LLM the necessary context information on what Theia commands are available. Moreover, we want this response in a parsable format, so that we can easily detect the command selected by the LLM in its response and provide the user with the option to directly execute the command. See the section “Response Renderers” for more details.
\nGetting such agent implementations right typically requires a bit of prompt evaluation with a set of expected user queries. A huge help in Theia AI is that you can modify the prompt templates at runtime to test different scenarios and tweak the prompt until you are satisfied, instead of changing the prompt templates in the code and need to rebuild after every change.
\nAlso, if the underlying LLM supports it, structured output is a huge time saver, as this usually guarantees that the output follows a specific format and avoids coping with variations in your agent’s parsing logic.\nThis guide is focussed on Theia AI and not about developing specific agents per se. If you need support building your own custom AI assistance, please get in contact with a service provider and browse our resource section.
\nAgents often need to interact with the tool to fetch dynamic data, such as a text selection, project-data or any tool-specific data. Theia AI allows you to encapsulate this data access in Variables, which can then be used in prompts or user requests and will be resolved with the actual data from the tool at runtime. Furthermore, agents can use so-called Tool Functions that allow the underlying LLM to proactively call an action, either to retrieve more information or to trigger any kind of action including the modification of data.
\nTheia AI by default supports two types of variables:
\nAgent-specific variables are controlled by a specific agent. To fill a variable with data, you can literally use any internal Theia API or other external APIs or methods you like. As an example, let’s again look at the chat agent that assists users in identifying (and later executing) arbitrary commands in the Theia IDE, such as opening the settings or showing the toolbar. You can review the full code of this agent as a reference.
\nTo allow the underlying LLM to identify the right command, we want to send it a list with all available commands. To achieve this, we first retrieve a list of all available commands using the CommandRegistry (see code example below). This step is independent of Theia AI and you could retrieve any sort of data here instead.\nSecond, we resolve the variable ‘command-ids’ when receiving the system prompt’ (also see code example below).
\n// Retrieve all available commands\nconst knownCommands: string[] = [];\nfor (const command of this.commandRegistry.getAllCommands()) {\n knownCommands.push(`${command.id}: ${command.label}`);\n}\n\n// Resolve the variable when retrieving the system prompt\nconst systemPrompt = await this.promptService.getPrompt('command-chat-agent-system-prompt-template', {\n 'command-ids': knownCommands.join('\\n')\n});Please note that the manual resolvement of variables is not necessary when using global variables.\nNow we can simply use our agent-specific variable in our prompt templates, e.g. like this:
\nYou are a service that helps users find commands to execute in an IDE.\n\nThese are the available commands:\nBegin List:\n{{command-ids}}\nEnd ListIf an agent uses agent-specific variables, it can decide to explicitly declare them. This enables one to keep track of used variables and optionally even show this information to the user (see example screenshot below).
\n![\"Used](\"../../used-variables-command-agent.png\")
\nTo declare an agent-specific variable, simply add it like this in the constructor of your agents, along with an optional description and whether it is used in the prompt template or not.
\nthis.agentSpecificVariables = [{\n name: 'command-ids',\n description: 'The list of available commands in Theia.',\n usedInPrompt: true\n}];Global variables are available to all agents. Therefore, they are provided as a dedicated contribution. In the following, we will define a simple global variable that resolves to the current date, i.e. to the time when the variable get resolved in a request. You can review the full code of this variable for a complete description.\nA Global variable basically consists of four parts.
\nFirst, we define the variable, as it can be used in requests. In the following example, we define two optional arguments to influence the format.
\nexport const TODAY_VARIABLE: AIVariable = {\n id: 'today-provider',\n description: 'Does something for today',\n name: 'today',\n args: [\n { name: TodayVariableArgs.IN_ISO_8601, description: 'Returns the current date in ISO 8601 format' },\n { name: TodayVariableArgs.IN_UNIX_SECONDS, description: 'Returns the current date in unix seconds format' }\n ]\n};Second, we register the variable using an ‘AIVariableContribution’ (see code example below). Third, we resolve the variable (also see code example below). Please note that for resolving a variable, you can access all necessary APIs, including tool-specific API or custom services.
\nexport class TodayVariableContribution implements AIVariableContribution, AIVariableResolver {\n // Register the variable resolver\n registerVariables(service: AIVariableService): void {\n service.registerResolver(TODAY_VARIABLE, this);\n }\n\n async resolve(request: AIVariableResolutionRequest, context: AIVariableContext): Promise<ResolvedAIVariable | undefined> {\n if (request.variable.name === TODAY_VARIABLE.name) {\n return this.resolveTodayVariable(request);\n }\n return undefined;\n }\n\n private resolveTodayVariable(request: AIVariableResolutionRequest): ResolvedTodayVariable {\n const date = new Date();\n if (request.arg === TodayVariableArgs.IN_ISO_8601) {\n return { variable: request.variable, value: date.toISOString(), date };\n }\n if (request.arg === TodayVariableArgs.IN_UNIX_SECONDS) {\n return { variable: request.variable, value: Math.round(date.getTime() / 1000).toString(), date };\n }\n return { variable: request.variable, value: date.toDateString(), date };\n }\n}\n\n...\n\nbind(AIVariableContribution).to(TodayVariableContribution).inSingletonScope();It can now be used in any prompt template, as well as in user requests.
\nTool functions allow an agent to provide capabilities to the underlying LLM. Compared to variables, it is up to the LLM to decide whether to use an available function or not. Functions can be used to allow the LLM to retrieve additional information or to trigger actions in the tool. Actions can be literally anything you want the LLM to be able to trigger, including modifications of data. Tool Functions can be used in requests, similarly to variables as shown in the following prompt example:
\nUse the following functions to access the workspace:\n- ~{getWorkspaceFileList}\n- ~{getFileContent}.To implement your own tool functions, provide an implementation of interface ‘ToolProvider’, in which you specify the ID, optionally parameters and a handler that represented the function to be called, e.g. like this:
\n@injectable()\nexport class FileContentFunction implements ToolProvider {\n static ID = FILE_CONTENT_FUNCTION_ID;\n\n getTool(): ToolRequest {\n return {\n id: FileContentFunction.ID,\n name: FileContentFunction.ID,\n description: 'Get the content of the file',\n parameters: {\n type: 'object',\n properties: {\n file: {\n type: 'string',\n description: 'The path of the file to retrieve content for',\n }\n }\n },\n handler: (arg_string: string) => {\n const file = this.parseArg(arg_string);\n return this.getFileContent(file);\n }\n };\n }\n}\nSee here for the full example listed above. In the handler, you can call literally any available API to execute arbitrary actions or retrieve arbitrary content, including tool-specific things.
\nFinally, register your ‘ToolProvider’ like this:
\nbind(ToolProvider).to(FileContentFunction);This section explains the process of converting an LLM (Large Language Model) response into custom UI controls within the Theia AI default chat (or any custom chat implementation). Custom UI control can be specially highlighted text, clickable buttons or literally anything that you want to display to your users.\nAs an example, we will use the command chat agent used in this documentation before, which is capable of identifying a command in the Theia IDE based on the user's request. We will augment this agent to render commands that the agent returns as buttons. By clicking the button, users can then directly invoke a command.
\nLet’s look at the basic control flow of a chat request in Theia AI (see diagram below). The flow starts with a user request in the default Chat UI (1), which is sent to the underlying LLM (2) to return an answer (3). By default, the agent can forward the response to the Chat UI as-is. However, in our scenario, the agent will parse the response and augment it with a structured response content (4). Based on this, the chat UI can select a corresponding response part renderer to be shown in the UI (5).
\n![\"Request](\"../../architecture-renderers.png\")
\nIn the following, we will dive into the details on how to implement this flow.
\nThe first step to enable structured response parsing is developing a prompt that reliably returns the expected output. In this case, the output should include an executable Theia command related to the user's question in JSON format. The response needs to be in a parsable format, allowing the system to detect the command and provide the user with the option to execute it.
\nAn simplified example of such a prompt might look like the following (you can review the full prompt template here)
\nYou are a service that helps users find commands to execute in an IDE. \nYou reply with stringified JSON Objects that tell the user which command to execute and its arguments, if any.\n\nExample:\n\n\\`\\`\\`json\n{\n \"type\": \"theia-command\",\n \"commandId\": \"workbench.action.selectIconTheme\"\n}\n\\`\\`\\`\n\nHere are the known Theia commands:\n\nBegin List: \n{{command-ids}}\nEnd ListAs described in the previous section the variable {{command-ids}} is dynamically populated with the list of available commands.
After receiving the LLM response, the next step is to parse it in the agent implementation and transform it into a response content that can then be processed by the Chat UI. In the following code example:
\nCommandChatResponseContentImpl object is created to wrap the command.You can review the parsing code, including error handling here)
\nExample code:
\nconst parsedCommand = JSON.parse(jsonString) as ParsedCommand;\nconst theiaCommand = this.commandRegistry.getCommand(parsedCommand.commandId);\nreturn new CommandChatResponseContentImpl(theiaCommand);Please note that a chat response can contain a list of response parts, allowing various UI components to be mixed with actionable response components.
\nThe final step is to display a button in the Chat UI to allow users to execute the command. This is done by creating a new Response Part Renderer. The renderer is registered to handle CommandChatResponseContent, ensuring that the Chat UI calls it whenever a corresponding content type is part of the response.
The following example code shows the corresponding response renderer, you can review the full code here.
\ncanHandle Method: Determines whether the renderer can handle the response part. If the response is of type CommandChatResponseContent, it returns a positive value, indicating it can process the content.render Method: Displays a button if the command is enabled. If the command is not executable globally, a message is shown.onCommand Method: Executes the command when the button is clicked.canHandle(response: ChatResponseContent): number {\n if (isCommandChatResponseContent(response)) {\n return 10;\n }\n return -1;\n}\n\nrender(response: CommandChatResponseContent): ReactNode {\n const isCommandEnabled = this.commandRegistry.isEnabled(response.command.id);\n return (\n isCommandEnabled ? (\n <button className='theia-button main' onClick={this.onCommand.bind(this)}>{response.command.label}</button>\n ) : (\n <div>The command has the id \"{response.command.id}\" but it is not executable globally from the Chat window.</div>\n )\n );\n}\n\nprivate onCommand(arg: AIChatCommandArguments): void {\n this.commandService.executeCommand(arg.command.id);\n}Finally, the custom response renderer needs to be registered:
\nbind(ChatResponsePartRenderer).to(CommandPartRenderer).inSingletonScope();By following the steps outlined, you can transform an LLM response into custom and optionally actionable UI controls within Theia AI. See the Theia IDE documentation on how the example looks integrated in a tool.\nThis approach enables users to interact with the AI-powered Chat UI more efficiently, e.g. allowing executing commands directly from the suggestions provided.
\nTheia AI currently provides out-of-the-box support for any OpenAI-compatible LLM services (including the OpenAI models hosted by OpenAI or self-hosted compatible LLMs) and Ollama LLMs. We are also working on integrating support for LLamaFile. As a tool provider, you can easily add support for other LLM APIs too. Please consider contributing any further LLM providers to the open source project, so that the community can benefit from increased compatibility and share the maintenance cost.
\nTo support a specific LLM, you basically need to provide an implementation of the interface ‘LanguageModel’, which provides an abstraction between agents and the underlying LLM. This Language Model is then registered at the ‘LanguageModelRegistry’, to make it retrievable for agents, e.g. like this:
\nthis.languageModelRegistry.addLanguageModels([new OllamaModel());If you want to allow the user to configure the LLM provider, e.g. change the URL or the available models, consider integrating your LLM provider with Theias preference system.
\nFor further details, we recommend reviewing the available LLM provider in Theia AI:
\n\nPlease note that Theia AI currently does not provide a fixed contribution point for Language Models, yet. This is due to the fact that we are working on supporting more models and also capabilities of new LLMs are emerging at the moment, such as function calling and structured output. We plan to consolidate the LLM Provider interfaces within the next months while adding more LLM Providers to the core framework. We are happy for feedback and contributions in this area.
\nIf want to learn more about the AI support in the Theia AI, please see this Theia AI introduction, our article on the vision of Theia AI and the demonstrations in Sneak Preview Series about Theia AI
","fields":{"slug":"theia_ai"}}},"pageContext":{"slug":"theia_ai"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/tips/page-data.json b/pr-previews/pr-663/page-data/docs/tips/page-data.json deleted file mode 100644 index ed5ceae9..00000000 --- a/pr-previews/pr-663/page-data/docs/tips/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/tips/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Advanced Tips"},"html":"In this section we'll outline some advanced hints and tips to get the most out of developing tools based on Eclipse Theia.
\nTheia allows running VS Code extension by providing a compatible API (see this overview for details).\nIt is possible to extend this API to allow VS Code extensions running in Theia to access additional functionality compared to when they run within VS Code.\nThis allows you to provide a feature as a VS Code extension targeting VS Code and Theia. However, when running in Theia, the feature can be enhanced by using custom API only available in Theia.
\nThe following code example shows the usage custom API which is invoked only when running in a Theia-based application. This is determined via the application name.\nThe API is imported asynchronously to avoid runtime errors in VS Code.
\nif (vscode.env.appName === MY_THEIA_APP_NAME) {\n // Implement Theia API\n const api = await import('@mytheiaextension/mycustomapi');\n // After importing the custom API, it can be used as any other API. The following lines are using an example API.\n api.host.getMessageHandler(() => getMessage());\n api.host.onRequestMessage((actor: string) => {\n const message = getMessage(actor);\n api.host.showMessage(message);\n });\n}An alternative to providing a custom API is to define custom commands. Again, these commands would only be available if the VS Code extension is running in Theia (see following code example).
\nif (vscode.env.appName === MY_THEIA_APP_NAME) {\n // Execute Theia custom command\n const commands = await vscode.commands.getCommands();\n if (commands.indexOf(MY_THEIA_CUSTOM_COMMAND) > -1) {\n vscode.commands.executeCommand(MY_THEIA_CUSTOM_COMMAND);\n }\n}An example of this technique can be seen here:
\nhttps://github.com/thegecko/vscode-theia-extension
","fields":{"slug":"tips"}}},"pageContext":{"slug":"tips"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/toolbar/page-data.json b/pr-previews/pr-663/page-data/docs/toolbar/page-data.json deleted file mode 100644 index 201d6fec..00000000 --- a/pr-previews/pr-663/page-data/docs/toolbar/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/toolbar/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Dynamic Toolbar"},"html":"Eclipse Theia provides an optional and fully dynamic toolbar to be included in your custom IDE or tool. Please also see the documentation of the toolbar from a user point of view.
\nTo enable the toolbar, simply include the Theia extension \"@theia/toolbar\" into your Theia-based product (also see the documentation on composing Theia applications).
\nThe Theia toolbar defines some default commands that are displayed even before the user can configure the toolbar to their preferences. These defaults are defined in a ToolbarDefaultsFactory. See here for the default ToolbarDefaultsFactory that is shipped within the toolbar extension.\nTo define your own default commands to the toolbar, create a custom implementation of ToolbarDefaultsFactory and rebind you own factory in your extension module (see following code example).
if (isBound(ToolbarDefaultsFactory)) {\n rebind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);\n} else {\n bind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);\n}This section documents how to use AI features in the Theia IDE (available since version 1.54, see also this introduction). These features are based on Theia AI, a framework for building AI assistance in tools and IDEs. Theia AI is part of the Theia platform. If you're interested in building your own custom tool or IDE with Theia AI, please refer to the corresponding documentation.
\nPlease note that these features are in early access and experimental. This means they may be unstable, behave unexpectedly, or undergo significant changes. In particular, using your own LLM might incur costs that you need to monitor closely. We have not yet optimized the AI assistants in the Theia IDE for token usage. Use these features at your own risk, and we welcome any feedback, suggestions, and contributions!
\nTheia AI features within the Theia IDE are currently disabled by default. See the next section on how to enable them.
\nTo activate AI support in the Theia IDE, go to Preferences and enable the setting “AI-features => AI Enable.”
\nTo use Theia AI within the Theia IDE, you need to provide access to at least one LLM. Theia IDE comes with preinstalled support for OpenAI API-compatible models, either hosted by OpenAI or self-hosted via VLLM. Additionally, Theia IDE supports connecting to models via Ollama. See the corresponding sections below on how to configure these providers.
\nOther LLM providers, including local models, can be added easily. We are also working on enabling LLamaFile support in the near future. If you would like to see support for a specific LLM, please provide feedback or consider contributing.
\nEach LLM provider offers a configurable list of available models (see the screenshot below for OpenAI models). To use a model in your IDE, configure it on a per-agent basis in the AI Configuration view.
\nTo enable the use of OpenAI, you need to create an API key in your OpenAI account and enter it in the settings dialog (see the screenshot below). Please note that creating an API key requires a paid subscription, and using these models may incur additional costs. Be sure to monitor your usage carefully to avoid unexpected charges. We have not yet optimized the AI assistants in the Theia IDE for token usage.
\n![\"Open](\"../../enter-openai-key.png\")
\nThe OpenAI provider is preconfigured with a list of available models. You can easily add new models to this list, for example, if new options are released.
\nAs an alternative to using an official OpenAI account, Theia IDE also supports arbitrary models compatible with the OpenAI API (e.g., hosted via VLLM). This enables you to connect to self-hosted models with ease. To add a custom model, click on the link in the settings section and add your configuration like this:
\n{\n \"ai-features.openAiCustom.customOpenAiModels\": [\n {\n \"model\": \"your-model-name\",\n \"url\": \"your-URL\",\n \"id\": \"your-unique-id\", // Optional: if not provided, the model name will be used as the ID\n \"apiKey\": \"your-api-key\" // Optional: use 'true' to apply the global OpenAI API key\n }\n ]\n}To configure a LlamaFile LLM in the Theia IDE, add the necessary settings to your configuration (see example below)
\n{\n \"ai-features.llamafile.llamafiles\": [\n {\n \"name\": \"modelname\", //you can choose a name for your model\n \"uri\": \"file:///home/.../YourModel.llamafile\",\n \"port\": 30000 //you can choose a port to be used by llamafile\n }\n ]\n}Replace \"name\", \"uri\", and \"port\" with your specific LlamaFile details.
\nThe Theia IDE also offers convenience commands to start and stop your LlamaFiles:
\nPlease make sure that your LlamaFiles are executable.\nFor more details on LlamaFiles, including a quickstart, see the official Mozilla LlamaFile documentation.
\nTo connect to models hosted via Ollama, enter the corresponding URL, along with the available models, in the settings (as shown below).
\n![\"Ollama](\"../../ollama-setting.png\")
\nThis section provides an overview of the currently available agents in the Theia IDE. Agents marked as “Chat Agents” are available in the global chat, while others are directly integrated into UI elements, such as code completion. You can configure and deactivate agents in the AI Configuration view.
\nThis agent helps developers by providing concise and accurate answers to general programming and software development questions. It also serves as a fallback for generic user questions. By default, this agent does not have access to the current user context or workspace. However, you can add variables, such as #selectedText, to your requests to provide additional context.
This agent analyzes user requests against the descriptions of all available chat agents and selects the best-fitting agent to respond (using AI). The user's request is delegated to the selected agent without further confirmation. The Orchestrator is currently the default agent in the Theia IDE for all chat requests. You can deactivate it in the AI Configuration View.
\nThis agent is aware of all commands available in the Theia IDE and the current tool the user is working with. Based on the user request, it can find the appropriate command and let the user execute it.
\nThis agent can access the user's workspace, retrieve a list of all available files, and view their content. It can answer questions about the current project, including project files and source code in the workspace, such as how to build the project, where to place source code, or where to find specific files or configurations.
\nThis agent provides inline code completion within the Theia IDE's code editor. It continuously shows suggestions while writing, and users can press TAB to insert the current suggestion. Note that this agent makes continuous requests to the underlying LLM while coding.
\nThis agent assists with writing and executing terminal commands. Based on the user's request, it suggests commands and allows them to be directly pasted and executed in the terminal. It can access the current directory, environment, and recent terminal output to provide context-aware assistance. You can open the terminal assistance agent via Ctrl+I in the terminal view.
\nThe Theia IDE provides a global chat interface where users can interact with all chat agents. The Orchestrator automatically delegates user requests to the most appropriate agent. To send a request directly to a specific agent, mention the agent's name using '@', for example, '@Command'. Press '@' in the chat to see a list of available chat agents.
\n![\"General](\"../../general-chat.png\")
\nSome agents produce special results, such as buttons (shown in the screenshot above) or code that can be directly inserted. You can augment your requests in the chat with context by using variables. For example, to refer to the currently selected text, use #selectedText in your request. Pressing '#' in the chat will show a list of available variables.
The AI Configuration View allows you to review and adapt agent-specific settings. Select an agent on the left side and review its properties on the right:
\n![\"AI](\"../../ai-configuration-view.png\")
\nIn the Theia IDE, you can open and edit prompts for all agents from the AI Configuration View. Prompts are shown in a text editor (see the screenshot below). Changes saved in the prompt editor will take effect with the next request made to the corresponding agent. You can reset a prompt to its default using the \"Reset\" button in the AI configuration view or the \"Revert\" toolbar item in the prompt editor (top-right corner).
\n![\"Prompt](\"../../prompt-editor.png\")
\nVariables and functions can be used in prompts. Variables are replaced with context-specific information at the time of the request (e.g., the currently selected text), while functions can trigger actions or retrieve additional information. You can find an overview of all global variables in the \"Variables\" tab of the AI Configuration View and agent-specific variables in the agent's configuration.
\nVariables are used with the following syntax:
\n{{variableName}}Tool functions are used with the following syntax:
\n~{functionName}Custom agents enable users to define new chat agents with custom prompts on the fly, allowing the creation of custom workflows and extending the Theia IDE with new capabilities. These agents are immediately available in the default chat.
\nTo define a new custom agent, navigate to the AI Configuration View and click on \"Add Custom Agent\".
\n![\"Add](\"../../add-custom-agents.png\")
\nThis action opens a YAML file where all available custom agents are defined. Below is an example configuration:
\n- id: obfuscator\n name: Obfuscator\n description: This is an example agent. Please adapt the properties to fit your needs.\n prompt: Obfuscate the following code so that no human can understand it anymore. Preserve the functionality.\n defaultLLM: openai/gpt-4oCustom agents can be configured in the AI Configuration View just like other chat agents. You can enable/disable them, modify their prompt templates, and integrate variables and functions within these templates to enhance functionality.
\nThe AI History view allows you to review all communications between agents and underlying LLMs. Select the corresponding agent at the top to see all its requests in the section below.
\n![\"AI](\"../../history-view.png\")
\nIf want to learn more about the AI support in the Theia AI, please see this introduction, our article on the vision of Theia AI and the demonstrations in Sneak Preview Series about Theia AI
","fields":{"slug":"user_ai"}}},"pageContext":{"slug":"user_ai"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/user_getting_started/page-data.json b/pr-previews/pr-663/page-data/docs/user_getting_started/page-data.json deleted file mode 100644 index 25ffb96b..00000000 --- a/pr-previews/pr-663/page-data/docs/user_getting_started/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_getting_started/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Using Theia As An End User"},"html":"The Theia IDE is a modern and open IDE for cloud and desktop. The Theia IDE is based on the Theia platform.
\n![\"Theia](\"../../theia-screenshot.jpg\")
\nThis section is about using the Theia IDE from an end user point of view. Please note that the Theia IDE is based on the Theia Platform, a technology to build tools and IDEs. As an end user, you are not using “Theia”, but always a product based on Theia, in this case the Theia IDE. If you are using another product based on Theia, please consider the specific end user documentation of the product you are using over this section.
\nThe Theia IDE features and usability concept is heavily influences by VS Code. Therefore, for many use cases, we refer to the VS Code documentation. We still provide some selected documentation about use cases which are differing or not supported in VS Code:
\n\nPlease note that you can also use the Theia IDE as a basis to create your own custom product.
","fields":{"slug":"user_getting_started"}}},"pageContext":{"slug":"user_getting_started"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/user_install_vscode_extensions/page-data.json b/pr-previews/pr-663/page-data/docs/user_install_vscode_extensions/page-data.json deleted file mode 100644 index f86dea30..00000000 --- a/pr-previews/pr-663/page-data/docs/user_install_vscode_extensions/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_install_vscode_extensions/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Installing VS Code Extensions in Theia"},"html":"You can install VS Code extensions into Theia-based products via the Open VSX Registry, aka “Theia Marketplace” or “Theia Extension Registry”.
\nNote: To be able to install extensions, the creator of your Theia-based tool needs to have enabled this option. The following documentation is based on the Theia IDE, a standard product based on Theia. This might slightly differ from the Theia-based product you are using, please contact the provider of your tool if there are uncertainties and also see here. For tool creators, please see the end of this document.
\nTo install new extensions into the Theia IDE, please open the Extensions View via the Menu \"View => Extensions\" or via the command “Toggle Extensions View”.
\nIn the opened Extension View you can browse for available VS Code extensions using the search field on top (see screenshot below). In the list of matching extensions, you can review the details about an extension and directly install it by clicking on the “Install” button.
\nThe Extension View also presents recommendations to be installed, if any, as well as extensions that are already installed. Here, you can uninstall extensions by clicking “Uninstall”.
\n![\"Theia](\"../../theia-marketplace.gif\")
\nThe last section, “Built-In” shows VS Code extensions that are a fix part of your Theia-based product. This means the creator of your tool has installed them already for you and you can also not uninstall them.
\nEvery Theia version supports a specific VS Code extension API version, i.e. the extension API is fully provided by Theia until and including this VS Code version. In the Theia IDE, you can find the supported version in the about dialog (Menu \"Help\" => \"About\"). The Open VSX Registry will automatically show compatible VS Code extensions only.
\nExtensions not listed as compatible might still work in Theia, as newer API versions are usually already partially implemented. In this case, you can manually install the extension via a VSIX file and test if it works (Use the command \"Extensions: Install from VSIX...\").
\nPlease note that a few parts of the VS Code extension API are only stubbed in Theia. Extensions will be installable, but some features might not work as expected.
\nFor details about the compatibility of Theia for VS Code extensions can be found in this report. This includes unsupported as well as stubbed parts of the API for all recent Theia versions.
\nIf you are missing a specific VS Code extension or if you have issues with using a VS Code extension in Theia, please report this to the creator of your Theia-based Tool. If you are using the Theia IDE or a variant of it, please report your issues here.
\nFor adopters: If you are building a Theia-based product, please have a look at our overview about extensions and plugins as well as at the documentation on authoring VS Code extensions in Theia.
","fields":{"slug":"user_install_vscode_extensions"}}},"pageContext":{"slug":"user_install_vscode_extensions"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/user_toolbar/page-data.json b/pr-previews/pr-663/page-data/docs/user_toolbar/page-data.json deleted file mode 100644 index 9d74effe..00000000 --- a/pr-previews/pr-663/page-data/docs/user_toolbar/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_toolbar/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Using the dynamic Toolbar in Theia"},"html":"Eclipse Theia provides a dynamic toolbar allowing easy access to commonly used commands. The toolbar contains default commands and can be dynamically adapted by users based on their personal preference.
\nNote: To use the toolbar in Theia, the creator of your Theia-based tool needs to have enabled this option. The following documentation is based on the Theia IDE, a standard product based on Theia. This might slightly differ from the Theia-based product you are using, please contact the provider of your tool if there are uncertainties and also see here. For tool creators, please see the toolbar adopter documentation.
\nAs a user, you can control the default visibility of the Theia toolbar using the setting \"Show Toolbar\" (see screenshot below). Additionally, you can toggle the toolbar using \"ALT+T\" or via right-click on the toolbar => \"Toggle Toolbar\".
\n![\"Theia](\"../../theia-toolbar-visibility.gif\")
\nThe toolbar will show some default commands, which are configured by the provider of your Theia-based tool. As a user, you can add and remove commands. Further, you can change their position in the toolbar. To remove an existing command, right-click the icon in the toolbar and select \"Remove Command From Toolbar\". To change the position of an existing command, simply drag it around. The toolbar supports three columns to visually structure commands (\"Left\", \"Center\" and \"Right\").\nTo add a new command to the toolbar, right click and select \"Add Command to Toolbar\" (see screenshot below). This will open a wizard that first allows you to select the command you want to add. In the second step, you can specify and icon that is used to display the new command in the toolbar. Finally, you select the column the new command will be placed in (you can still move it around later).
\n![\"Theia](\"../../theia-toolbar.gif\")
\nTo restore the default commands on the toolbar, right click and select \"Restore Toolbar Defaults\". Please note that this will delete all custom commands you might have added.
","fields":{"slug":"user_toolbar"}}},"pageContext":{"slug":"user_toolbar"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/docs/widgets/page-data.json b/pr-previews/pr-663/page-data/docs/widgets/page-data.json deleted file mode 100644 index 37d52d9a..00000000 --- a/pr-previews/pr-663/page-data/docs/widgets/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/widgets/","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Widgets"},"html":"A widget is a part displaying content within the Theia workbench, e.g. a view or an editor. Examples for existing widgets in Theia are the file explorer, the code editor or the problems view. By contributing custom widgets, you can place your own custom UI in a Theia-based application. Your custom UI will behave the same as other widgets in terms of window layouts including the title tab, resizing, dragging and opening/closing (see screenshot below).
\n![\"Widget](\"../../widget-example.gif\")
\nFurthermore, a widget will receive events from the surrounding workbench, e.g. on application start, on resize or on detach. The implementation of the actual content of a widget, which is rendered in the provided frame is completely up to you, though. As an example, you can implement some custom UI using React within a widget.
\nIn a nutshell, a widget is a frame to embed some custom (HTML-based) UI into the Theia workbench (see diagram below)
\n![\"Widget](\"../../widget-architecture.png\")
\nIn this article we will describe how to contribute a custom widget to the Theia workbench. We will focus on a simple view (in contrast to an editor) and use React to implement the UI.
\nIf you are not yet familiar with contribution points in Theia or the use of dependency injection, please consider this guide on Services and Contributions.
\nIf you would like to have a look at the example code, please use the Theia extension generator. Install the generator, select the “Widget” example and enter “MyWidget” as a name for the extension.
\nContributing a widget, in our example a view consists of three components:
\nFor the implementation of custom widgets, Theia provides several base classes to inherit from. This enables you to focus on creating your custom UI only, as the base classes already implement most required functions. Theia does not depend on a specific UI technology, like React, Vue.js or Angular. However, it provides convenience support by providing respective base classes, e.g. for React. If in doubt, using React is the most common choice for implementing custom widgets at the moment. Below you find an excerpt of the class hierarchy. In case you want to implement a widget using react, choose ReactWidget as a base class. If you want to implement a widget that mainly displays a tree, use TreeWidget. If you do not want to use React, use BaseWidget. Browse the type hierarchy of BaseWidget to see other available options.
In the following code examples, we use ReactWidget as a base class. As shown below, we first initialize the widget with some base parameters:
id: To uniquely identify the widget, e.g. to open it via the WidgetManager.label: Shown in the tab when the widget is open.caption: Shown when hovering over the tab when the widget is open.closable: Whether the user can close the widget (via the “x” in the tab or via right click menu).iconClass: The icon shown in the tab when the widget is opened.mywidget-widget.tsx
\n@injectable()\nexport class MyWidget extends ReactWidget {\n\nstatic readonly ID = 'my:widget';\nstatic readonly LABEL = 'My Widget';\n\n@postConstruct()\nprotected async init(): Promise < void> {\n this.id = MyWidget.ID;\n this.title.label = MyWidget.LABEL;\n this.title.caption = MyWidget.LABEL;\n this.title.closable = true;\n this.title.iconClass = 'fa fa-window-maximize'; // example widget icon.\n this.update();\n}When using the respective base class, the implementation of a widget can be really minimal and focused on the custom UI part. In our example, we just implement the render function that will create our actual custom UI (using JSX/React). The example UI contains a button that will trigger the displayMessage function below.
mywidget-widget.tsx (continued)
\nprotected render(): React.ReactNode {\n const header = `This is a sample widget which simply calls the messageService in order to display an info message to end users.`;\n return <div id='widget-container'>\n <AlertMessage type='INFO' header={header} />\n <button className='theia-button secondary' title='Display Message' onClick={_a => this.displayMessage()}>Display Message</button>\n </div>\n}\n\n@inject(MessageService)\nprotected readonly messageService!: MessageService;\n\nprotected displayMessage(): void {\n this.messageService.info('Congratulations: My Widget Successfully Created!');\n}Please note, that you can override functions of BaseWidget or ReactWidget to hook into specific life cycle events of a widget, e.g. onUpdateRequest or onResize. These events are defined by Phosphor.js, the underlying window management framework, see this documentation about the Widget class.
Besides implementing the actual widget, you need to wire it with the Eclipse Theia workbench, which is described in the next two sections.
\nWidgets in Theia are instantiated and managed by a central service, the WidgetManager. This allows the application to keep track of all created widgets. As an example, the WidgetManager supports the function getOrCreate, which will either return an existing widget, if it was already created, or create a new one if not.
To make a custom widget instantiatable by the widget manager, you need to register a WidgetFactory. A widget factory consists of an ID and a function that creates the actual widget. The widget manager will collect all contributed widget factories and pick the correct one for a respective widget by ID.
In our example (see code below), we first bind our widget MyWidget to itself so that we can instantiate it in our factory using dependency injection. This is not necessarily required for all widgets if they do not use dependency injection inside. We are using dependency injection in our example above to retrieve the message service and for the @postConstruct event. Second, we bind a WidgetFactory defining the ID of the widget and the createWidget function. This function allows you to control the widget creation, e.g. to pass specific parameters to a custom widget if required. In our simple example, we just use the dependency injection context to instantiate our widget.
mywidget-frontend-module.ts
\nbind(MyWidget).toSelf();\nbind(WidgetFactory).toDynamicValue(ctx => ({\n id: MyWidget.ID,\n createWidget: () => ctx.container.get<MyWidget>(MyWidget)\n})).inSingletonScope();Now you could already open a widget manually via using the widget manager API. However, for most use cases, you want to add a view to the view menu and also provide a respective command. This can be conveniently done using a widget contribution as described in the next section.
\nWidget contributions allow you to wire a widget into the Theia workbench, more precisely to add them to the view menu and the quick command bar. Theia provides a convenient base class AbstractViewContribution to inherit from, which already implements the most common feature set (see example code below). For the initialization, you only need to specify the following parameters:
widgetID: The ID of the widget, used to open it via the widget managerwidgetName: The name which is displayed in the view menu. Usually the same name as used for the widget tab.defaultWidgetOptions: Option to influence where the widget will be displayed on opening, e.g. in the left area of the workbench. See the typedoc for more information.toggleCommandId: The command that opens the view. You can use the pre implemented openView function provided by the super class.Besides specifying these base parameters, you need to register the command to open the view. The base class implements the respective command contribution interface, so you just need to implement registerCommands to do so (see below).
mywidget-contribution.ts
\nexport const MyWidgetCommand: Command = { id: 'widget:command' };\nexport class MyWidgetContribution extends AbstractViewContribution<MyWidget> {\n constructor() {\n super({\n widgetId: MyWidget.ID,\n widgetName: MyWidget.LABEL,\n defaultWidgetOptions: { area: 'left' },\n toggleCommandId: MyWidgetCommand.id\n });\n }\n\n registerCommands(commands: CommandRegistry): void {\n commands.registerCommand(MyWidgetCommand, {\n execute: () => super.openView({ activate: false, reveal: true })\n });\n }\n}With the contribution above, the view will now be shown in the standard “view” menu of Theia and you can also use the respective “open view” command to open it.
","fields":{"slug":"widgets"}}},"pageContext":{"slug":"widgets"}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/index/page-data.json b/pr-previews/pr-663/page-data/index/page-data.json deleted file mode 100644 index b0001ce5..00000000 --- a/pr-previews/pr-663/page-data/index/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-pages-index-js","path":"/","result":{"pageContext":{"adopters":[{"name":"Acquia","logo":"logo-acquia.png","projects":["ecd.theia"],"homepage_url":"https://www.acquia.com/","logo_white":"logo-acquia-white.png"},{"name":"Arduino","logo":"logo-arduino.svg","projects":["ecd.theia"],"homepage_url":"https://www.arduino.cc/en/software#future-version-of-the-arduino-ide","logo_white":"logo-arduino-white.svg"},{"name":"Arm","logo":"logo-arm.svg","projects":["adoptium.temurin","iot.cyclonedds","ecd.theia"],"homepage_url":"https://www.arm.com/","logo_white":"logo-arm-white.svg"},{"name":"Broadcom Inc.","logo":"logo-broadcom.png","projects":["ecd.che","ecd.theia","ecd.openvsx"],"homepage_url":"https://www.broadcom.com/solutions/mainframe","logo_white":"logo-broadcom-white.png"},{"name":"CS GROUP - France","logo":"logo-cs_group.svg","projects":["ecd.theia","ecd.emfcloud"],"homepage_url":"https://www.csgroup.eu","logo_white":"logo-cs_group-white.svg"},{"name":"EclipseSource","logo":"logo-es.svg","projects":["iot.cyclonedds","ecd.che","ecd.theia","ecd.emfcloud","ecd.glsp","ecd.sprotty"],"homepage_url":"https://eclipsesource.com/","logo_white":"logo-es-white.svg"},{"name":"Ericsson","logo":"logo-ericsson.svg","projects":["ecd.openvsx","ecd.sprotty","ecd.theia","iot.leshan"],"homepage_url":"https://www.ericsson.com/en/networks/offerings/cellular-iot","logo_white":"logo-ericsson-white.svg"},{"name":"Gitpod","logo":"logo-gitpod.svg","projects":["ecd.openvsx","ecd.theia"],"homepage_url":"https://www.gitpod.io/","logo_white":"logo-gitpod-white.svg"},{"name":"IBM","logo":"logo-ibm.png","projects":["ecd.che","ecd.theia","ecd.openvsx"],"homepage_url":"https://www.ibm.com/products/wazi-developer","logo_white":"logo-ibm-white.png"},{"name":"K2View","logo":"logo-k2view.svg","projects":["ecd.theia"],"homepage_url":"https://www.k2view.com","logo_white":"logo-k2view-white.svg"},{"name":"Killercoda","logo":"logo-killercoda.svg","projects":["ecd.theia"],"homepage_url":"https://killercoda.com","logo_white":"logo-killercoda.svg"},{"name":"Logi.cals","logo":"logo-logicals.svg","projects":["ecd.che","ecd.glsp","ecd.theia"],"homepage_url":"https://logicals.com/en/","logo_white":"logo-logicals-white.svg"},{"name":"Record Evolution","logo":"logo-record-evolution.png","projects":["ecd.theia"],"homepage_url":"https://www.record-evolution.de/en/home-en/","logo_white":"logo-record-evolution-white.png"},{"name":"Red Hat","logo":"Logo-RedHat-A-Color-RGB.svg","projects":["iot.hono","iot.paho","ecd.che","ecd.theia","ecd.jkube","adoptium.temurin"],"homepage_url":"https://developers.redhat.com","logo_white":"Logo-RedHat-A-White-RGB.svg"},{"name":"Renesas","logo":"logo-renesas.svg","projects":["ecd.theia","ecd.emfcloud","ecd.glsp"],"homepage_url":"https://renesas.com/","logo_white":"logo-renesas-white.svg"},{"name":"Samsung","logo":"logo-samsung.png","projects":["ecd.theia"],"homepage_url":"https://semiconductor.samsung.com/us/","logo_white":""},{"name":"SAP","logo":"logo-sap.png","projects":["ecd.dirigible","ecd.che","ecd.theia","ecd.openvsx","ecd.orion","technology.jgit","technology.egit","technology.steady","tools.mat"],"homepage_url":"https://www.sap.com","logo_white":"logo-sap-white.png"},{"name":"Smartface","logo":"logo-smartface.svg","projects":["ecd.theia"],"homepage_url":"https://smartface.io/","logo_white":"logo-smartface-white.svg"},{"name":"STMicroelectronics","logo":"logo-stmicroelectronics.svg","projects":["ecd.theia","ecd.glsp","ecd.emfcloud"],"homepage_url":"https://www.st.com","logo_white":"logo-stmicroelectronics-white.svg"},{"name":"Terapines","logo":"logo-terapines.svg","projects":["ecd.theia"],"homepage_url":"https://www.terapines.com/","logo_white":"logo-terapines-white.svg"},{"name":"TypeFox","logo":"logo-typefox.svg","projects":["ecd.openvsx","ecd.sprotty","ecd.theia"],"homepage_url":"https://www.typefox.io/","logo_white":"logo-typefox-white.svg"},{"name":"VUEngine","logo":"logo-vuengine.png","projects":["ecd.theia"],"homepage_url":"https://www.vuengine.dev","logo_white":"logo-vuengine-white.png"}]}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/releases/page-data.json b/pr-previews/pr-663/page-data/releases/page-data.json deleted file mode 100644 index 174c2637..00000000 --- a/pr-previews/pr-663/page-data/releases/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-pages-releases-js","path":"/releases/","result":{"pageContext":{}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/resources/page-data.json b/pr-previews/pr-663/page-data/resources/page-data.json deleted file mode 100644 index a3d089cc..00000000 --- a/pr-previews/pr-663/page-data/resources/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-pages-resources-js","path":"/resources/","result":{"pageContext":{}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/sq/d/2468095761.json b/pr-previews/pr-663/page-data/sq/d/2468095761.json deleted file mode 100644 index 693303e9..00000000 --- a/pr-previews/pr-663/page-data/sq/d/2468095761.json +++ /dev/null @@ -1 +0,0 @@ -{"data":{"site":{"siteMetadata":{"title":"Theia - Cloud and Desktop IDE Platform","description":"Theia is an open-source cloud desktop IDE framework implemented in TypeScript."}}}} \ No newline at end of file diff --git a/pr-previews/pr-663/page-data/support/page-data.json b/pr-previews/pr-663/page-data/support/page-data.json deleted file mode 100644 index fdedb57c..00000000 --- a/pr-previews/pr-663/page-data/support/page-data.json +++ /dev/null @@ -1 +0,0 @@ -{"componentChunkName":"component---src-pages-support-js","path":"/support/","result":{"pageContext":{}},"staticQueryHashes":["2468095761"],"slicesMap":{}} \ No newline at end of file diff --git a/pr-previews/pr-663/prompt-editor.png b/pr-previews/pr-663/prompt-editor.png deleted file mode 100644 index cc64b590..00000000 Binary files a/pr-previews/pr-663/prompt-editor.png and /dev/null differ diff --git a/pr-previews/pr-663/releases/index.html b/pr-previews/pr-663/releases/index.html deleted file mode 100644 index e1ba8380..00000000 --- a/pr-previews/pr-663/releases/index.html +++ /dev/null @@ -1,57 +0,0 @@ -Eclipse Theia follows a monthly release cycle. You can find all monthly releases including changelogs and breaking changes here.
In addition, Theia provides a "community release" every three month with extra focus on stability and compatibility.
The list below shows all community releases including the next one planned. In addition, you can find technologies that integrate with Theia, including the respective version that is supposed to be compatible with the community release.
This compatibility information is provided and ensured by the respective project and therefore not in scope for the Theia project team. If you find issues with a technology, please report them at the respective project. If you are interested in getting a technology listed, please open a PR to this repo.
For more information, please refer to this article about the Theia community release.
Community Release Candidate: October 30th, 2024
Community Release Available: November 27th, 2024
Compatible Technologies Listed: December 5th, 2024
Community Release Announcement: December 12th, 2024
Community Release Candidate: July 25th, 2024
Community Release Available: August 29th, 2024
Compatible Technologies Listed: September 5th, 2024
Community Release Announcement: September 12th, 2024
Community Release Candidate: April 25th, 2024
Community Release Available: May 30th, 2024
Compatible Technologies Listed: June 6th, 2024
Community Release Announcement: June 13th, 2024
Community Release Candidate: December 21th, 2023
Community Release Available: January 25th, 2024
Compatible Technologies Listed: February 1st, 2024
Community Release Announcement: February 8th, 2024
Community Release Candidate: October 26th, 2023
Community Release Available: November 30th, 2023
Compatible Technologies Listed: December 7th, 2023
Community Release Announcement: December 14th, 2023
Community Release Candidate: July 27th, 2023
Community Release Available: August 31st, 2023
Compatible Technologies Listed: September 7th, 2023
Community Release Announcement: September 14th, 2023
Community Release Candidate: April 27th, 2023
Community Release Available: May 25th, 2023
Compatible Technologies Listed: June 1st, 2023
Community Release Announcement: June 12th, 2023
Community Release Candidate: January 26th, 2023
Community Release Available: February 23rd, 2023
Compatible Technologies Listed: March 2nd, 2023
Community Release Announcement: March 9th, 2023
Community Release Candidate: August 25th, 2022
Community Release Available: September 29th, 2022
Compatible Technologies Listed: October 6th, 2022
Community Release Announcement: October 18th, 2022
