From 3b466cdeaa1a349cfa963a5b448e512d4fcdf477 Mon Sep 17 00:00:00 2001 From: planger Date: Thu, 4 Apr 2024 11:32:20 +0000 Subject: [PATCH] =?UTF-8?q?Deploy=20preview=20for=20PR=20540=20?= =?UTF-8?q?=F0=9F=9B=AB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pr-previews/pr-540/docs/authoring_extensions/index.html | 4 ++-- pr-previews/pr-540/docs/blueprint_documentation/index.html | 4 ++-- pr-previews/pr-540/docs/composing_applications/index.html | 2 +- pr-previews/pr-540/docs/enhanced_tab_bar_preview/index.html | 2 +- pr-previews/pr-540/docs/json_rpc/index.html | 4 ++-- pr-previews/pr-540/docs/toolbar/index.html | 4 ++-- pr-previews/pr-540/docs/user_getting_started/index.html | 4 ++-- .../pr-540/docs/user_install_vscode_extensions/index.html | 4 ++-- pr-previews/pr-540/docs/user_toolbar/index.html | 2 +- .../pr-540/page-data/docs/authoring_extensions/page-data.json | 2 +- .../page-data/docs/blueprint_documentation/page-data.json | 2 +- .../page-data/docs/composing_applications/page-data.json | 2 +- .../page-data/docs/enhanced_tab_bar_preview/page-data.json | 2 +- pr-previews/pr-540/page-data/docs/json_rpc/page-data.json | 2 +- pr-previews/pr-540/page-data/docs/toolbar/page-data.json | 2 +- .../pr-540/page-data/docs/user_getting_started/page-data.json | 2 +- .../docs/user_install_vscode_extensions/page-data.json | 2 +- pr-previews/pr-540/page-data/docs/user_toolbar/page-data.json | 2 +- pr-previews/pr-540/support/index.html | 2 +- 19 files changed, 25 insertions(+), 25 deletions(-) diff --git a/pr-previews/pr-540/docs/authoring_extensions/index.html b/pr-previews/pr-540/docs/authoring_extensions/index.html index 106473b1..c0c943c2 100644 --- a/pr-previews/pr-540/docs/authoring_extensions/index.html +++ b/pr-previews/pr-540/docs/authoring_extensions/index.html @@ -49,12 +49,12 @@ } })

Authoring Theia Extensions

-

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 the different available extension mechanisms of Theia (Plugins vs. Extensions) before you continue reading.

+

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 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.

Theia’s Architecture

A Theia app is composed of so-called extensions. An extension provides a set of widgets, commands, handlers, etc. for a specific functionality. Theia itself ships a number of extensions, e.g. for editors, terminals, the project view etc. Each extension resides in its own npm package.

Theia defines a plethora of contribution interfaces that allow extensions to add their behaviour to various aspects of the application. Just 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 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.

+

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.

Prerequisites

Prerequisites information are available from the Theia repository.

Project Layout

diff --git a/pr-previews/pr-540/docs/blueprint_documentation/index.html b/pr-previews/pr-540/docs/blueprint_documentation/index.html index 6cc2e24e..16433476 100644 --- a/pr-previews/pr-540/docs/blueprint_documentation/index.html +++ b/pr-previews/pr-540/docs/blueprint_documentation/index.html @@ -49,8 +49,8 @@ } })

Extending/Adopting the Theia IDE

-

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.

+

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.

diff --git a/pr-previews/pr-540/docs/composing_applications/index.html b/pr-previews/pr-540/docs/composing_applications/index.html index dca022e0..69616a79 100644 --- a/pr-previews/pr-540/docs/composing_applications/index.html +++ b/pr-previews/pr-540/docs/composing_applications/index.html @@ -53,7 +53,7 @@ This guide describes the manual steps to build a Theia-based product, there are two ways to avoid this manual set-up:

We still recommend reading the manual guide first, it allows you to understand the structure of a Theia-based project.

Requirements

diff --git a/pr-previews/pr-540/docs/enhanced_tab_bar_preview/index.html b/pr-previews/pr-540/docs/enhanced_tab_bar_preview/index.html index b2fc344c..032e1212 100644 --- a/pr-previews/pr-540/docs/enhanced_tab_bar_preview/index.html +++ b/pr-previews/pr-540/docs/enhanced_tab_bar_preview/index.html @@ -49,7 +49,7 @@ } })

Enhanced Tab Bar Preview

-

By default, Theia shows the value of a widget's caption property when users hover above a widget's tab (see also widgets). +

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. diff --git a/pr-previews/pr-540/docs/json_rpc/index.html b/pr-previews/pr-540/docs/json_rpc/index.html index a222b761..0a6cc255 100644 --- a/pr-previews/pr-540/docs/json_rpc/index.html +++ b/pr-previews/pr-540/docs/json_rpc/index.html @@ -102,7 +102,7 @@

ConnectionHandlers. To save resources the hood all MessagingContributions are routed over one websocket connection (multiplexing).

-

To dig more into ContributionProvider see this section.

+

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:

@@ -176,7 +176,7 @@

taskWatcher's client (taskWatcher.getTaskClient())

-

See more information about how events work in theia here.

+

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. diff --git a/pr-previews/pr-540/docs/toolbar/index.html b/pr-previews/pr-540/docs/toolbar/index.html index 1cb6e741..abaf83ed 100644 --- a/pr-previews/pr-540/docs/toolbar/index.html +++ b/pr-previews/pr-540/docs/toolbar/index.html @@ -49,8 +49,8 @@ } })

Dynamic Toolbar

-

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).

+

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)) {
diff --git a/pr-previews/pr-540/docs/user_getting_started/index.html b/pr-previews/pr-540/docs/user_getting_started/index.html
index d4ba5d8f..befa233a 100644
--- a/pr-previews/pr-540/docs/user_getting_started/index.html
+++ b/pr-previews/pr-540/docs/user_getting_started/index.html
@@ -60,7 +60,7 @@
 
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.
Go to previous Page : Project GoalsGo to next page : Installing VS Code Extensions
\ No newline at end of file diff --git a/pr-previews/pr-540/docs/user_install_vscode_extensions/index.html b/pr-previews/pr-540/docs/user_install_vscode_extensions/index.html index 4b40fb4a..40abd934 100644 --- a/pr-previews/pr-540/docs/user_install_vscode_extensions/index.html +++ b/pr-previews/pr-540/docs/user_install_vscode_extensions/index.html @@ -50,7 +50,7 @@ })

Installing VS Code Extensions in Theia

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.

+

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”.

@@ -62,4 +62,4 @@

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.

Go to previous Page : Getting StartedGo to next page : Using the dynamic Toolbar
\ No newline at end of file +

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.

Go to previous Page : Getting StartedGo to next page : Using the dynamic Toolbar

\ No newline at end of file diff --git a/pr-previews/pr-540/docs/user_toolbar/index.html b/pr-previews/pr-540/docs/user_toolbar/index.html index 09c6c7f3..ebeac4cc 100644 --- a/pr-previews/pr-540/docs/user_toolbar/index.html +++ b/pr-previews/pr-540/docs/user_toolbar/index.html @@ -50,7 +50,7 @@ })

Using the dynamic Toolbar 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.

+

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".

Theia Toolbar Visibility

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"). diff --git a/pr-previews/pr-540/page-data/docs/authoring_extensions/page-data.json b/pr-previews/pr-540/page-data/docs/authoring_extensions/page-data.json index c3a82e76..43ffe1a9 100644 --- a/pr-previews/pr-540/page-data/docs/authoring_extensions/page-data.json +++ b/pr-previews/pr-540/page-data/docs/authoring_extensions/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/authoring_extensions","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Authoring an Extension"},"html":"

Authoring Theia Extensions

\n

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 the different available extension mechanisms of Theia (Plugins vs. Extensions) before you continue reading.

\n

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.

\n

Theia’s Architecture

\n

A Theia app is composed of so-called extensions. An extension provides a set of widgets, commands, handlers, etc. for a specific functionality. Theia itself ships a number of extensions, e.g. for editors, terminals, the project view etc. Each extension resides in its own npm package.

\n

Theia defines a plethora of contribution interfaces that allow extensions to add their behaviour to various aspects of the application. Just 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.

\n

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.

\n

Prerequisites

\n

Prerequisites information are available from the Theia repository.

\n

Project Layout

\n

We are going to create a monorepo (a repository containing multiple npm packages) named theia-hello-world-extension containing three packages: hello-world-extension, browser-app and electron-app. The first contains our extension, the latter two the Theia applications to run our extension in browser and electron mode. We are going to use yarn instead of npm, because it allows to structure such monorepos into workspaces. In our case, each workspace contains its own npm package. Common dependencies of these packages are 'hoisted' by yarn to their common root directory. We are also going to use lerna to run scripts across workspaces.

\n

To ease the setup of such a repository we have created a code generator to scaffold the project. It will also generate the hello-world example. Run it using

\n
npm install -g yo generator-theia-extension\nmkdir theia-hello-world-extension\ncd theia-hello-world-extension\nyo theia-extension # select the 'Hello World' option and complete the prompts
\n

Let's have look at the generated code now. The root package.json defines the workspaces, the dependency to lerna and some scripts to rebuild the native packages for browser or electron.

\n
{\n  \"private\": true,\n  \"scripts\": {\n    \"prepare\": \"lerna run prepare\",\n    \"rebuild:browser\": \"theia rebuild:browser\",\n    \"rebuild:electron\": \"theia rebuild:electron\"\n  },\n  \"devDependencies\": {\n    \"lerna\": \"2.4.0\"\n  },\n  \"workspaces\": [\n    \"hello-world-extension\", \"browser-app\", \"electron-app\"\n  ]\n}
\n

We also got a lerna.json file to configure lerna:

\n
{\n  \"lerna\": \"2.4.0\",\n  \"version\": \"0.1.0\",\n  \"useWorkspaces\": true,\n  \"npmClient\": \"yarn\",\n  \"command\": {\n    \"run\": {\n      \"stream\": true\n    }\n  }\n}
\n

Implementing the Extension

\n

Next let's look at the generated code for our extension in the hello-world-extension folder. Let’s start with the package.json. It specifies the package’s metadata, its dependencies to the (bleeding edge) Theia core package, a few scripts and dev dependencies, and the theia-extensions.

\n

The keyword theia-extension is important: It allows a Theia app to identify and install Theia extensions from npm.

\n
{\n  \"name\": \"hello-world-extension\",\n  \"keywords\": [\n    \"theia-extension\"\n  ],\n  \"version\": \"0.1.0\",\n  \"files\": [\n    \"lib\",\n    \"src\"\n  ],\n  \"dependencies\": {\n    \"@theia/core\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"rimraf\": \"latest\",\n    \"typescript\": \"latest\"\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}
\n

The last property theiaExtensions 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.

\n

In the frontend module we export a default object that is a InversifyJS ContainerModule with bindings for a command contribution and a menu contribution.

\n
export default new ContainerModule(bind => {\n    // add your contribution bindings here\n    bind(CommandContribution).to(HelloWorldCommandContribution);\n    bind(MenuContribution).to(HelloWorldMenuContribution);\n});
\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.

\n
export 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...
\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.

\n

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
...\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}
\n

Executing the Extension In the Browser

\n

Now we want to see our extension in action. For this purpose, the generator has created a package.json in the folder browser-app. It defines a Theia browser application with a couple of statically included extensions, including our hello-world-extension. All remaining files in this directory have been auto-generated by yarn calling the theia-cli tool during the build, as defined in the scripts section.

\n
{\n  \"name\": \"browser-app\",\n  \"version\": \"0.1.0\",\n  \"dependencies\": {\n    \"@theia/core\": \"latest\",\n    \"@theia/filesystem\": \"latest\",\n    \"@theia/workspace\": \"latest\",\n    \"@theia/preferences\": \"latest\",\n    \"@theia/navigator\": \"latest\",\n    \"@theia/process\": \"latest\",\n    \"@theia/terminal\": \"latest\",\n    \"@theia/editor\": \"latest\",\n    \"@theia/languages\": \"latest\",\n    \"@theia/markers\": \"latest\",\n    \"@theia/monaco\": \"latest\",\n    \"@theia/messages\": \"latest\",\n    \"hello-world-extension\": \"0.1.0\"\n  },\n  \"devDependencies\": {\n    \"@theia/cli\": \"latest\"\n  },\n  \"scripts\": {\n    \"prepare\": \"theia build\",\n    \"start\": \"theia start\",\n    \"watch\": \"theia build --watch\"\n  },\n  \"theia\": {\n    \"target\": \"browser\"\n  }\n}
\n

Now we have all pieces together to build and run the application.\nTo run the browser app, enter:

\n
cd browser-app\nyarn start <path to workspace>
\n

Point your browser to http://localhost:3000. Then choose Edit > Say Hello from the menu: A message \"Hello World!\" should pop up.

\n

Executing the Extension In Electron

\n

The package.json for the Electron app looks almost the same, except for the name and the target property.

\n
{\n  \"name\": \"electron-app\",\n  ...\n  \"theia\": {\n    \"target\": \"electron\"\n  }\n}
\n

Before running the electron app, you additionally have to rebuild some native modules:

\n
yarn rebuild:electron\ncd electron-app\nyarn start <path to workspace>
\n

Deploying the Extension

\n

If you want to make your extension publicly available, we recommend publishing it to npm. This can be achieved by calling yarn publish from the extension package's directory. Of course, you need a valid account for that.

","fields":{"slug":"authoring_extensions"}}},"pageContext":{"slug":"authoring_extensions"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/authoring_extensions","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Authoring an Extension"},"html":"

Authoring Theia Extensions

\n

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 the different available extension mechanisms of Theia (Plugins vs. Extensions) before you continue reading.

\n

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.

\n

Theia’s Architecture

\n

A Theia app is composed of so-called extensions. An extension provides a set of widgets, commands, handlers, etc. for a specific functionality. Theia itself ships a number of extensions, e.g. for editors, terminals, the project view etc. Each extension resides in its own npm package.

\n

Theia defines a plethora of contribution interfaces that allow extensions to add their behaviour to various aspects of the application. Just 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.

\n

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.

\n

Prerequisites

\n

Prerequisites information are available from the Theia repository.

\n

Project Layout

\n

We are going to create a monorepo (a repository containing multiple npm packages) named theia-hello-world-extension containing three packages: hello-world-extension, browser-app and electron-app. The first contains our extension, the latter two the Theia applications to run our extension in browser and electron mode. We are going to use yarn instead of npm, because it allows to structure such monorepos into workspaces. In our case, each workspace contains its own npm package. Common dependencies of these packages are 'hoisted' by yarn to their common root directory. We are also going to use lerna to run scripts across workspaces.

\n

To ease the setup of such a repository we have created a code generator to scaffold the project. It will also generate the hello-world example. Run it using

\n
npm install -g yo generator-theia-extension\nmkdir theia-hello-world-extension\ncd theia-hello-world-extension\nyo theia-extension # select the 'Hello World' option and complete the prompts
\n

Let's have look at the generated code now. The root package.json defines the workspaces, the dependency to lerna and some scripts to rebuild the native packages for browser or electron.

\n
{\n  \"private\": true,\n  \"scripts\": {\n    \"prepare\": \"lerna run prepare\",\n    \"rebuild:browser\": \"theia rebuild:browser\",\n    \"rebuild:electron\": \"theia rebuild:electron\"\n  },\n  \"devDependencies\": {\n    \"lerna\": \"2.4.0\"\n  },\n  \"workspaces\": [\n    \"hello-world-extension\", \"browser-app\", \"electron-app\"\n  ]\n}
\n

We also got a lerna.json file to configure lerna:

\n
{\n  \"lerna\": \"2.4.0\",\n  \"version\": \"0.1.0\",\n  \"useWorkspaces\": true,\n  \"npmClient\": \"yarn\",\n  \"command\": {\n    \"run\": {\n      \"stream\": true\n    }\n  }\n}
\n

Implementing the Extension

\n

Next let's look at the generated code for our extension in the hello-world-extension folder. Let’s start with the package.json. It specifies the package’s metadata, its dependencies to the (bleeding edge) Theia core package, a few scripts and dev dependencies, and the theia-extensions.

\n

The keyword theia-extension is important: It allows a Theia app to identify and install Theia extensions from npm.

\n
{\n  \"name\": \"hello-world-extension\",\n  \"keywords\": [\n    \"theia-extension\"\n  ],\n  \"version\": \"0.1.0\",\n  \"files\": [\n    \"lib\",\n    \"src\"\n  ],\n  \"dependencies\": {\n    \"@theia/core\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"rimraf\": \"latest\",\n    \"typescript\": \"latest\"\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}
\n

The last property theiaExtensions 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.

\n

In the frontend module we export a default object that is a InversifyJS ContainerModule with bindings for a command contribution and a menu contribution.

\n
export default new ContainerModule(bind => {\n    // add your contribution bindings here\n    bind(CommandContribution).to(HelloWorldCommandContribution);\n    bind(MenuContribution).to(HelloWorldMenuContribution);\n});
\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.

\n
export 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...
\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.

\n

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
...\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}
\n

Executing the Extension In the Browser

\n

Now we want to see our extension in action. For this purpose, the generator has created a package.json in the folder browser-app. It defines a Theia browser application with a couple of statically included extensions, including our hello-world-extension. All remaining files in this directory have been auto-generated by yarn calling the theia-cli tool during the build, as defined in the scripts section.

\n
{\n  \"name\": \"browser-app\",\n  \"version\": \"0.1.0\",\n  \"dependencies\": {\n    \"@theia/core\": \"latest\",\n    \"@theia/filesystem\": \"latest\",\n    \"@theia/workspace\": \"latest\",\n    \"@theia/preferences\": \"latest\",\n    \"@theia/navigator\": \"latest\",\n    \"@theia/process\": \"latest\",\n    \"@theia/terminal\": \"latest\",\n    \"@theia/editor\": \"latest\",\n    \"@theia/languages\": \"latest\",\n    \"@theia/markers\": \"latest\",\n    \"@theia/monaco\": \"latest\",\n    \"@theia/messages\": \"latest\",\n    \"hello-world-extension\": \"0.1.0\"\n  },\n  \"devDependencies\": {\n    \"@theia/cli\": \"latest\"\n  },\n  \"scripts\": {\n    \"prepare\": \"theia build\",\n    \"start\": \"theia start\",\n    \"watch\": \"theia build --watch\"\n  },\n  \"theia\": {\n    \"target\": \"browser\"\n  }\n}
\n

Now we have all pieces together to build and run the application.\nTo run the browser app, enter:

\n
cd browser-app\nyarn start <path to workspace>
\n

Point your browser to http://localhost:3000. Then choose Edit > Say Hello from the menu: A message \"Hello World!\" should pop up.

\n

Executing the Extension In Electron

\n

The package.json for the Electron app looks almost the same, except for the name and the target property.

\n
{\n  \"name\": \"electron-app\",\n  ...\n  \"theia\": {\n    \"target\": \"electron\"\n  }\n}
\n

Before running the electron app, you additionally have to rebuild some native modules:

\n
yarn rebuild:electron\ncd electron-app\nyarn start <path to workspace>
\n

Deploying the Extension

\n

If you want to make your extension publicly available, we recommend publishing it to npm. This can be achieved by calling yarn publish from the extension package's directory. Of course, you need a valid account for that.

","fields":{"slug":"authoring_extensions"}}},"pageContext":{"slug":"authoring_extensions"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/blueprint_documentation/page-data.json b/pr-previews/pr-540/page-data/docs/blueprint_documentation/page-data.json index f1f84a7f..e9617f46 100644 --- a/pr-previews/pr-540/page-data/docs/blueprint_documentation/page-data.json +++ b/pr-previews/pr-540/page-data/docs/blueprint_documentation/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/blueprint_documentation","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Extending/Adopting the Theia IDE"},"html":"

Extending/Adopting the Theia IDE

\n

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

\n

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.

\n

The 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.

\n

This 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\".

\n\n

Building a product and installers

\n

The Theia IDE build uses electron-builder to package the product as a desktop application.

\n

The 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.

\n

The following commands may be run from the root directory of the repository.

\n

To install dependencies and build the application, simply execute yarn.

\n

You can also directly run the unpackaged application, e.g. to test it during development with yarn electron start.

\n

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.

\n

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\".

\n

Signing

\n

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.

\n

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.

\n

Adding/Removing Features

\n

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.

\n

Updating Bundled VS Code Extensions

\n

All 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:

\n
    \n
  • install (which is the same as just running yarn)
    • \n
  • prepare
    • \n
  • download:plugins
    • \n
\n

To 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.

\n

Extension sources

\n

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.

\n

Customizing Theia Extensions

\n

Eclipse 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.

\n

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.

\n

The 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.

\n

Branding

\n

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.

\n

Customizing the App

\n

Application Window Title

\n

The 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:\nOpen the file and adapt the value of property theia.frontend.config.applicationName to the desired name.

\n

Application Icons

\n

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:

\n
    \n
  • macOS: icons.icns
    • \n
  • Windows: icon.ico
    • \n
  • Linux: icons subfolder
    • \n
\n

Customizing the Welcome Page

\n

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.

\n

The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:

\n
    bind(TheiaBlueprintGettingStartedWidget).toSelf();\n    bind(WidgetFactory).toDynamicValue(context => ({\n        id: GettingStartedWidget.ID,\n        createWidget: () => context.container.get<TheiaBlueprintGettingStartedWidget>(TheiaBlueprintGettingStartedWidget),\n    })).inSingletonScope();
\n

To use another custom widget, remove this code and bind your widget correspondingly.

\n

Customizing the About Dialog

\n

The 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.

\n

The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:

\n
isBound(AboutDialog) ? rebind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope() : bind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope();
\n

To use another custom dialog widget, remove this code, extend Theia’s AboutDialog class, and (re)bind it as above.

\n

Customizing the Preferences

\n

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.

\n

Customizing the Installer

\n

The installers are created using electron-builder.\nThe corresponding configuration file is located at applications/electron/electron-builder.yml.

\n

Installer File Base Name

\n

The installer files’ base names are defined by the productName property in applications/electron/electron-builder.yml.

\n

Windows Installer

\n

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:

\n
    \n
  • Icons
    • \n
  • Sidebar image
    • \n
  • License
    • \n
  • One click installation
    • \n
  • Automatic application start after installation
    • \n
  • Whether users can change the installation directory
    • \n
\n

More 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.

\n

Configure Publish and Update

\n

The 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.

\n

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.\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.

","fields":{"slug":"blueprint_documentation"}}},"pageContext":{"slug":"blueprint_documentation"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/blueprint_documentation","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Extending/Adopting the Theia IDE"},"html":"

Extending/Adopting the Theia IDE

\n

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

\n

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.

\n

The 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.

\n

This 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\".

\n\n

Building a product and installers

\n

The Theia IDE build uses electron-builder to package the product as a desktop application.

\n

The 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.

\n

The following commands may be run from the root directory of the repository.

\n

To install dependencies and build the application, simply execute yarn.

\n

You can also directly run the unpackaged application, e.g. to test it during development with yarn electron start.

\n

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.

\n

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\".

\n

Signing

\n

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.

\n

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.

\n

Adding/Removing Features

\n

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.

\n

Updating Bundled VS Code Extensions

\n

All 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:

\n
    \n
  • install (which is the same as just running yarn)
    • \n
  • prepare
    • \n
  • download:plugins
    • \n
\n

To 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.

\n

Extension sources

\n

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.

\n

Customizing Theia Extensions

\n

Eclipse 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.

\n

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.

\n

The 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.

\n

Branding

\n

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.

\n

Customizing the App

\n

Application Window Title

\n

The 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:\nOpen the file and adapt the value of property theia.frontend.config.applicationName to the desired name.

\n

Application Icons

\n

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:

\n
    \n
  • macOS: icons.icns
    • \n
  • Windows: icon.ico
    • \n
  • Linux: icons subfolder
    • \n
\n

Customizing the Welcome Page

\n

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.

\n

The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:

\n
    bind(TheiaBlueprintGettingStartedWidget).toSelf();\n    bind(WidgetFactory).toDynamicValue(context => ({\n        id: GettingStartedWidget.ID,\n        createWidget: () => context.container.get<TheiaBlueprintGettingStartedWidget>(TheiaBlueprintGettingStartedWidget),\n    })).inSingletonScope();
\n

To use another custom widget, remove this code and bind your widget correspondingly.

\n

Customizing the About Dialog

\n

The 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.

\n

The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts like this:

\n
isBound(AboutDialog) ? rebind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope() : bind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope();
\n

To use another custom dialog widget, remove this code, extend Theia’s AboutDialog class, and (re)bind it as above.

\n

Customizing the Preferences

\n

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.

\n

Customizing the Installer

\n

The installers are created using electron-builder.\nThe corresponding configuration file is located at applications/electron/electron-builder.yml.

\n

Installer File Base Name

\n

The installer files’ base names are defined by the productName property in applications/electron/electron-builder.yml.

\n

Windows Installer

\n

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:

\n
    \n
  • Icons
    • \n
  • Sidebar image
    • \n
  • License
    • \n
  • One click installation
    • \n
  • Automatic application start after installation
    • \n
  • Whether users can change the installation directory
    • \n
\n

More 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.

\n

Configure Publish and Update

\n

The 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.

\n

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.\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.

","fields":{"slug":"blueprint_documentation"}}},"pageContext":{"slug":"blueprint_documentation"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/composing_applications/page-data.json b/pr-previews/pr-540/page-data/docs/composing_applications/page-data.json index e3b0e023..85716d7d 100644 --- a/pr-previews/pr-540/page-data/docs/composing_applications/page-data.json +++ b/pr-previews/pr-540/page-data/docs/composing_applications/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/composing_applications","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Build your own IDE/Tool"},"html":"

Build your own IDE/Tool

\n

This guide will teach you how to build 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.\nThis guide describes the manual steps to build a Theia-based product, there are two ways to avoid this manual set-up:

\n\n

We still recommend reading the manual guide first, it allows you to understand the structure of a Theia-based project.

\n

Requirements

\n

The detailed list of prerequisites is located at the main Theia repository:

\n\n

Setup

\n

Start with creating a new empty directory and moving into it:

\n
mkdir my-app\ncd my-app
\n

Create package.json in this directory:

\n
{\n  \"private\": true,\n  \"dependencies\": {\n    \"@theia/callhierarchy\": \"latest\",\n    \"@theia/file-search\": \"latest\",\n    \"@theia/git\": \"latest\",\n    \"@theia/markers\": \"latest\",\n    \"@theia/messages\": \"latest\",\n    \"@theia/mini-browser\": \"latest\",\n    \"@theia/navigator\": \"latest\",\n    \"@theia/outline-view\": \"latest\",\n    \"@theia/plugin-ext-vscode\": \"latest\",\n    \"@theia/preferences\": \"latest\",\n    \"@theia/preview\": \"latest\",\n    \"@theia/search-in-workspace\": \"latest\",\n    \"@theia/terminal\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"@theia/cli\": \"latest\"\n  }\n}
\n

In a nutshell, Theia applications and extensions are Node.js packages. Each package has a package.json file that manifests package metadata,\nlike name, version, its runtime and build time dependencies and so on.

\n

Let's have a look at the created package:

\n
    \n
  • Its name and version are omitted since we are not going to use it as a dependency, and\nit's marked as private since it is not going to be published as a Node.js package on its own.
    • \n
  • \n

    We've listed required extensions as runtime dependencies, e.g. @theia/navigator.

    \n
      \n
    • Some extensions require additional tooling installed, in such cases, please consult the corresponding extension documentation.
      • \n
    • Use this link to see all published extensions.
      • \n
    \n
    • \n
  • We've listed @theia/cli as a build-time dependency. It provides scripts to build and run the application.
    • \n
\n

Consuming VS Code Extensions

\n

As part of your application, it is also possible to consume (and package) VS Code extensions.\nThe Theia repository contains a guide on how to\ninclude such extensions as part of the application's package.json.

\n

An example package.json may look like the following:

\n
{\n  \"private\": true,\n  \"dependencies\": {\n    \"@theia/callhierarchy\": \"latest\",\n    \"@theia/file-search\": \"latest\",\n    \"@theia/git\": \"latest\",\n    \"@theia/markers\": \"latest\",\n    \"@theia/messages\": \"latest\",\n    \"@theia/navigator\": \"latest\",\n    \"@theia/outline-view\": \"latest\",\n    \"@theia/plugin-ext-vscode\": \"latest\",\n    \"@theia/preferences\": \"latest\",\n    \"@theia/preview\": \"latest\",\n    \"@theia/search-in-workspace\": \"latest\",\n    \"@theia/terminal\": \"latest\",\n    \"@theia/vsx-registry\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"@theia/cli\": \"latest\"\n  },\n  \"scripts\": {\n    \"prepare\": \"yarn run clean && yarn build && yarn run download:plugins\",\n    \"clean\": \"theia clean\",\n    \"build\": \"theia build --mode development\",\n    \"start\": \"theia start --plugins=local-dir:plugins\",\n    \"download:plugins\": \"theia download:plugins\"\n  },\n  \"theiaPluginsDir\": \"plugins\",\n  \"theiaPlugins\": {\n    \"vscode-builtin-extensions-pack\": \"https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.50.1/file/eclipse-theia.builtin-extension-pack-1.50.1.vsix\"\n  },\n  \"theiaPluginsExcludeIds\": [\n    \"ms-vscode.js-debug-companion\",\n    \"vscode.extension-editing\",\n    \"vscode.git\",\n    \"vscode.git-ui\",\n    \"vscode.github\",\n    \"vscode.github-authentication\",\n    \"vscode.microsoft-authentication\"\n  ]\n}
\n

The following properties are used to consume built-in plugins (bundled extensions):

\n
    \n
  • theiaPluginsDir: the relative path to deploy plugins into
    • \n
  • theiaPlugins: the collection of plugins to download (individual plugins or extension-packs) - can point to any valid download URL (ex: Open VSX, GitHub Releases, etc.)
    • \n
  • theiaPluginsExcludeIds: the list of plugin ids to exclude when resolving extension-packs
    • \n
\n

Building

\n

First, install all dependencies.

\n
yarn
\n

Second, use Theia CLI to build the application.

\n
yarn theia build
\n

yarn looks up theia executable provided by @theia/cli in the context of our application\nand then executes the build command with theia.\nThis can take a while since the application is built in production mode by default,\ni.e. obfuscated and minified.

\n

Running

\n

After the build is finished, we can start the application:

\n
yarn theia start --plugins=local-dir:plugins
\n

or rely on the start script from package.json:

\n
yarn start
\n

You can provide a workspace path to open as a first argument\nand --hostname, --port options to deploy the application on specific network interfaces and ports,\ne.g. to open /workspace on all interfaces and port 8080:

\n
yarn start /my-workspace --hostname 0.0.0.0 --port 8080
\n

In the terminal, you should see that Theia application is up and listening:

\n\"Terminal\"\n

Open the application by entering the printed address in a new browser page.

\n

Troubleshooting

\n

Plugins not appearing

\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:

\n
export THEIA_DEFAULT_PLUGINS=local-dir:plugins
\n

Building native dependencies behind a proxy

\n

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:

\n
[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.0
\n

This 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:

\n
 npm_config_tarball=/path/to/node-v8.15.0-headers.tar.gz yarn install
","fields":{"slug":"composing_applications"}}},"pageContext":{"slug":"composing_applications"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/composing_applications","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Build your own IDE/Tool"},"html":"

Build your own IDE/Tool

\n

This guide will teach you how to build 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.\nThis guide describes the manual steps to build a Theia-based product, there are two ways to avoid this manual set-up:

\n\n

We still recommend reading the manual guide first, it allows you to understand the structure of a Theia-based project.

\n

Requirements

\n

The detailed list of prerequisites is located at the main Theia repository:

\n\n

Setup

\n

Start with creating a new empty directory and moving into it:

\n
mkdir my-app\ncd my-app
\n

Create package.json in this directory:

\n
{\n  \"private\": true,\n  \"dependencies\": {\n    \"@theia/callhierarchy\": \"latest\",\n    \"@theia/file-search\": \"latest\",\n    \"@theia/git\": \"latest\",\n    \"@theia/markers\": \"latest\",\n    \"@theia/messages\": \"latest\",\n    \"@theia/mini-browser\": \"latest\",\n    \"@theia/navigator\": \"latest\",\n    \"@theia/outline-view\": \"latest\",\n    \"@theia/plugin-ext-vscode\": \"latest\",\n    \"@theia/preferences\": \"latest\",\n    \"@theia/preview\": \"latest\",\n    \"@theia/search-in-workspace\": \"latest\",\n    \"@theia/terminal\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"@theia/cli\": \"latest\"\n  }\n}
\n

In a nutshell, Theia applications and extensions are Node.js packages. Each package has a package.json file that manifests package metadata,\nlike name, version, its runtime and build time dependencies and so on.

\n

Let's have a look at the created package:

\n
    \n
  • Its name and version are omitted since we are not going to use it as a dependency, and\nit's marked as private since it is not going to be published as a Node.js package on its own.
    • \n
  • \n

    We've listed required extensions as runtime dependencies, e.g. @theia/navigator.

    \n
      \n
    • Some extensions require additional tooling installed, in such cases, please consult the corresponding extension documentation.
      • \n
    • Use this link to see all published extensions.
      • \n
    \n
    • \n
  • We've listed @theia/cli as a build-time dependency. It provides scripts to build and run the application.
    • \n
\n

Consuming VS Code Extensions

\n

As part of your application, it is also possible to consume (and package) VS Code extensions.\nThe Theia repository contains a guide on how to\ninclude such extensions as part of the application's package.json.

\n

An example package.json may look like the following:

\n
{\n  \"private\": true,\n  \"dependencies\": {\n    \"@theia/callhierarchy\": \"latest\",\n    \"@theia/file-search\": \"latest\",\n    \"@theia/git\": \"latest\",\n    \"@theia/markers\": \"latest\",\n    \"@theia/messages\": \"latest\",\n    \"@theia/navigator\": \"latest\",\n    \"@theia/outline-view\": \"latest\",\n    \"@theia/plugin-ext-vscode\": \"latest\",\n    \"@theia/preferences\": \"latest\",\n    \"@theia/preview\": \"latest\",\n    \"@theia/search-in-workspace\": \"latest\",\n    \"@theia/terminal\": \"latest\",\n    \"@theia/vsx-registry\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"@theia/cli\": \"latest\"\n  },\n  \"scripts\": {\n    \"prepare\": \"yarn run clean && yarn build && yarn run download:plugins\",\n    \"clean\": \"theia clean\",\n    \"build\": \"theia build --mode development\",\n    \"start\": \"theia start --plugins=local-dir:plugins\",\n    \"download:plugins\": \"theia download:plugins\"\n  },\n  \"theiaPluginsDir\": \"plugins\",\n  \"theiaPlugins\": {\n    \"vscode-builtin-extensions-pack\": \"https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.50.1/file/eclipse-theia.builtin-extension-pack-1.50.1.vsix\"\n  },\n  \"theiaPluginsExcludeIds\": [\n    \"ms-vscode.js-debug-companion\",\n    \"vscode.extension-editing\",\n    \"vscode.git\",\n    \"vscode.git-ui\",\n    \"vscode.github\",\n    \"vscode.github-authentication\",\n    \"vscode.microsoft-authentication\"\n  ]\n}
\n

The following properties are used to consume built-in plugins (bundled extensions):

\n
    \n
  • theiaPluginsDir: the relative path to deploy plugins into
    • \n
  • theiaPlugins: the collection of plugins to download (individual plugins or extension-packs) - can point to any valid download URL (ex: Open VSX, GitHub Releases, etc.)
    • \n
  • theiaPluginsExcludeIds: the list of plugin ids to exclude when resolving extension-packs
    • \n
\n

Building

\n

First, install all dependencies.

\n
yarn
\n

Second, use Theia CLI to build the application.

\n
yarn theia build
\n

yarn looks up theia executable provided by @theia/cli in the context of our application\nand then executes the build command with theia.\nThis can take a while since the application is built in production mode by default,\ni.e. obfuscated and minified.

\n

Running

\n

After the build is finished, we can start the application:

\n
yarn theia start --plugins=local-dir:plugins
\n

or rely on the start script from package.json:

\n
yarn start
\n

You can provide a workspace path to open as a first argument\nand --hostname, --port options to deploy the application on specific network interfaces and ports,\ne.g. to open /workspace on all interfaces and port 8080:

\n
yarn start /my-workspace --hostname 0.0.0.0 --port 8080
\n

In the terminal, you should see that Theia application is up and listening:

\n\"Terminal\"\n

Open the application by entering the printed address in a new browser page.

\n

Troubleshooting

\n

Plugins not appearing

\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:

\n
export THEIA_DEFAULT_PLUGINS=local-dir:plugins
\n

Building native dependencies behind a proxy

\n

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:

\n
[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.0
\n

This 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:

\n
 npm_config_tarball=/path/to/node-v8.15.0-headers.tar.gz yarn install
","fields":{"slug":"composing_applications"}}},"pageContext":{"slug":"composing_applications"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/enhanced_tab_bar_preview/page-data.json b/pr-previews/pr-540/page-data/docs/enhanced_tab_bar_preview/page-data.json index 85ec6e11..a97a0233 100644 --- a/pr-previews/pr-540/page-data/docs/enhanced_tab_bar_preview/page-data.json +++ b/pr-previews/pr-540/page-data/docs/enhanced_tab_bar_preview/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/enhanced_tab_bar_preview","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Enhanced Tab Bar Preview"},"html":"

Enhanced Tab Bar Preview

\n

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.

\n

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.

\n

Enabling the enhanced tab bar preview

\n

The enhanced tab bar preview is disabled by default and needs to be explicitly enabled with a via the preference window.tabbar.enhancedPreview.

\n\"A\n

After enabling the enhanced tab bar preview, users will see the following on hovering over a widget's tab:

\n\"A\n

Specifying the contents of the preview

\n

The 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:

\n
    @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;
\n

Customization of the preview

\n

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.

\n

Styling of the outer element

\n

The 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:

\n
.theia-hover.extended-tab-preview {\n    border-radius: 10px;\n}
\n

Styling of the content element

\n

To style the elements inside of the preview, class names are assigned to the different components of the preview.\nThose are:

\n
    \n
  • .theia-horizontal-tabBar-hover-div (for the outer box)
    • \n
  • .theia-horizontal-tabBar-hover-title (for the title)
    • \n
  • .theia-horizontal-tabBar-hover-caption (for the caption).
    • \n
\n

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.

\n
.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}
\n

After those rules are applied the preview will look as shown below:

\n\"A\n

Changing the content element

\n

To 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:

\n
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}
\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.

\n
    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    });
","fields":{"slug":"enhanced_tab_bar_preview"}}},"pageContext":{"slug":"enhanced_tab_bar_preview"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/enhanced_tab_bar_preview","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Enhanced Tab Bar Preview"},"html":"

Enhanced Tab Bar Preview

\n

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.

\n

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.

\n

Enabling the enhanced tab bar preview

\n

The enhanced tab bar preview is disabled by default and needs to be explicitly enabled with a via the preference window.tabbar.enhancedPreview.

\n\"A\n

After enabling the enhanced tab bar preview, users will see the following on hovering over a widget's tab:

\n\"A\n

Specifying the contents of the preview

\n

The 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:

\n
    @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;
\n

Customization of the preview

\n

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.

\n

Styling of the outer element

\n

The 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:

\n
.theia-hover.extended-tab-preview {\n    border-radius: 10px;\n}
\n

Styling of the content element

\n

To style the elements inside of the preview, class names are assigned to the different components of the preview.\nThose are:

\n
    \n
  • .theia-horizontal-tabBar-hover-div (for the outer box)
    • \n
  • .theia-horizontal-tabBar-hover-title (for the title)
    • \n
  • .theia-horizontal-tabBar-hover-caption (for the caption).
    • \n
\n

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.

\n
.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}
\n

After those rules are applied the preview will look as shown below:

\n\"A\n

Changing the content element

\n

To 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:

\n
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}
\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.

\n
    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    });
","fields":{"slug":"enhanced_tab_bar_preview"}}},"pageContext":{"slug":"enhanced_tab_bar_preview"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/json_rpc/page-data.json b/pr-previews/pr-540/page-data/docs/json_rpc/page-data.json index e056d3e0..fcecef1c 100644 --- a/pr-previews/pr-540/page-data/docs/json_rpc/page-data.json +++ b/pr-previews/pr-540/page-data/docs/json_rpc/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/json_rpc","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Communication via RPC"},"html":"

Communication via RPC

\n

In this section we will explain how you can create a backend service and\nthen connect to it over RPC.

\n

We will use the task execution system as a small example of that.

\n

Overview

\n

This works by creating a service exposed by the express framework and\nthen connecting to that over a websocket connection.

\n

Registering a service

\n

So the first thing you will want to do is expose your service so that the\nfrontend can connect to it.

\n

You will need to create backend server module file similar to this (task-backend-module.ts):

\n
import { 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();
\n

Let's go over that in detail:

\n
import { ConnectionHandler, RpcConnectionHandler } from '@theia/core/lib/common/messaging';
\n

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.

\n

We'll see more on how this is done as we go.

\n

The ConnectionHandler is a simple interface that specifies the path of the\nconnection and what happens on connection creation.

\n

It looks like this:

\n
import { 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}
\n
import { TaskClient, TaskServer, taskPath } from '../common/task-protocol';
\n

The task-protocol.ts file contains the interfaces that the server and the\nclient need to implement.

\n

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.

\n

We will get more into that later.

\n
    bind<ConnectionHandler>(ConnectionHandler).toDynamicValue(ctx => {
\n

Here a bit of magic happens, at first glance we're just saying here is an\nimplementation of a ConnectionHandler.

\n

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).

\n

To dig more into ContributionProvider see this section.

\n

So now:

\n
   new RpcConnectionHandler<TaskClient>(taskPath, client => {
\n

This does a few things if we look at this class implementation:

\n
export 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}
\n

We see that a websocket channel is created on the taskPath (\"/services/task\") by the extension of the ConnectionHandler.

\n

And let's look at what it does onConnection :

\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

Let's go over this line by line:

\n
       const factory = new this.factoryConstructor();
\n

This creates a ProxyFactory on path \"services/task\".

\n
        const proxy = factory.createProxy();
\n

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.

\n
        factory.target = this.targetFactory(proxy);
\n

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        }
\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.

\n

And it returns the taskServer as the object that will be exposed over RPC.

\n
 factory.listen(channel);
\n

This connects the factory to the channel and establishes the RPC protocol.

\n

Connecting to a service

\n

So now that we have a backend service let's see how to connect to it from\nthe frontend.

\n

To do that you will need something like this:

\n

(From task-frontend-module)

\n
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});
\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();
\n

Let's go line by line:

\n
        const connection = ctx.container.get(WebSocketConnectionProvider);
\n

Here we're getting the websocket connection, this will be used to create a proxy from.

\n
        const taskWatcher = ctx.container.get(TaskWatcher);
\n

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())

\n

See more information about how events work in theia here.

\n
        return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());
\n

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.

\n
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);
\n

So here at the last line we're binding the TaskServer interface to a\nRPC proxy.

\n

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    }
\n

So it's very similar to the backend example.

\n

Maybe 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.

\n

So again there's multiple things going on here what this does is that:

\n
    \n
  • it creates a JsonRpc Proxy on path \"services/task\".
    • \n
  • it exposes the taskWatcher.getTaskClient() object.
    • \n
  • it returns a proxy of type TaskServer.
    • \n
\n

So now instances of TaskServer are proxied over RPC to the\nbackend's TaskServer object.

\n

Complete example

\n

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"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/json_rpc","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Communication via RPC"},"html":"

Communication via RPC

\n

In this section we will explain how you can create a backend service and\nthen connect to it over RPC.

\n

We will use the task execution system as a small example of that.

\n

Overview

\n

This works by creating a service exposed by the express framework and\nthen connecting to that over a websocket connection.

\n

Registering a service

\n

So the first thing you will want to do is expose your service so that the\nfrontend can connect to it.

\n

You will need to create backend server module file similar to this (task-backend-module.ts):

\n
import { 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();
\n

Let's go over that in detail:

\n
import { ConnectionHandler, RpcConnectionHandler } from '@theia/core/lib/common/messaging';
\n

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.

\n

We'll see more on how this is done as we go.

\n

The ConnectionHandler is a simple interface that specifies the path of the\nconnection and what happens on connection creation.

\n

It looks like this:

\n
import { 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}
\n
import { TaskClient, TaskServer, taskPath } from '../common/task-protocol';
\n

The task-protocol.ts file contains the interfaces that the server and the\nclient need to implement.

\n

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.

\n

We will get more into that later.

\n
    bind<ConnectionHandler>(ConnectionHandler).toDynamicValue(ctx => {
\n

Here a bit of magic happens, at first glance we're just saying here is an\nimplementation of a ConnectionHandler.

\n

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).

\n

To dig more into ContributionProvider see this section.

\n

So now:

\n
   new RpcConnectionHandler<TaskClient>(taskPath, client => {
\n

This does a few things if we look at this class implementation:

\n
export 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}
\n

We see that a websocket channel is created on the taskPath (\"/services/task\") by the extension of the ConnectionHandler.

\n

And let's look at what it does onConnection :

\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

Let's go over this line by line:

\n
       const factory = new this.factoryConstructor();
\n

This creates a ProxyFactory on path \"services/task\".

\n
        const proxy = factory.createProxy();
\n

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.

\n
        factory.target = this.targetFactory(proxy);
\n

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        }
\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.

\n

And it returns the taskServer as the object that will be exposed over RPC.

\n
 factory.listen(channel);
\n

This connects the factory to the channel and establishes the RPC protocol.

\n

Connecting to a service

\n

So now that we have a backend service let's see how to connect to it from\nthe frontend.

\n

To do that you will need something like this:

\n

(From task-frontend-module)

\n
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});
\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();
\n

Let's go line by line:

\n
        const connection = ctx.container.get(WebSocketConnectionProvider);
\n

Here we're getting the websocket connection, this will be used to create a proxy from.

\n
        const taskWatcher = ctx.container.get(TaskWatcher);
\n

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())

\n

See more information about how events work in theia here.

\n
        return connection.createProxy<TaskServer>(taskPath, taskWatcher.getTaskClient());
\n

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.

\n
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);
\n

So here at the last line we're binding the TaskServer interface to a\nRPC proxy.

\n

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    }
\n

So it's very similar to the backend example.

\n

Maybe 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.

\n

So again there's multiple things going on here what this does is that:

\n
    \n
  • it creates a JsonRpc Proxy on path \"services/task\".
    • \n
  • it exposes the taskWatcher.getTaskClient() object.
    • \n
  • it returns a proxy of type TaskServer.
    • \n
\n

So now instances of TaskServer are proxied over RPC to the\nbackend's TaskServer object.

\n

Complete example

\n

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"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/toolbar/page-data.json b/pr-previews/pr-540/page-data/docs/toolbar/page-data.json index bda504d2..eca47063 100644 --- a/pr-previews/pr-540/page-data/docs/toolbar/page-data.json +++ b/pr-previews/pr-540/page-data/docs/toolbar/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/toolbar","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Dynamic Toolbar"},"html":"

Dynamic Toolbar

\n

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.

\n

To enable the toolbar, simply include the Theia extension \"@theia/toolbar\" into your Theia-based product (also see the documentation on composing Theia applications).

\n

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.\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).

\n
if (isBound(ToolbarDefaultsFactory)) {\n  rebind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);\n} else {\n  bind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);\n}
","fields":{"slug":"toolbar"}}},"pageContext":{"slug":"toolbar"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/toolbar","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Dynamic Toolbar"},"html":"

Dynamic Toolbar

\n

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.

\n

To enable the toolbar, simply include the Theia extension \"@theia/toolbar\" into your Theia-based product (also see the documentation on composing Theia applications).

\n

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.\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).

\n
if (isBound(ToolbarDefaultsFactory)) {\n  rebind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);\n} else {\n  bind(ToolbarDefaultsFactory).toService(MyCustomToolbarDefaultsFactory);\n}
","fields":{"slug":"toolbar"}}},"pageContext":{"slug":"toolbar"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/user_getting_started/page-data.json b/pr-previews/pr-540/page-data/docs/user_getting_started/page-data.json index cae3c969..c21c5d89 100644 --- a/pr-previews/pr-540/page-data/docs/user_getting_started/page-data.json +++ b/pr-previews/pr-540/page-data/docs/user_getting_started/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_getting_started","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Using Theia As An End User"},"html":"

Using the \"Theia IDE\" as an End User

\n

The Theia IDE is a modern and open IDE for cloud and desktop. The Theia IDE is based on the Theia platform.

\n\n\"Theia\n

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.

\n

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:

\n\n

Please 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"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_getting_started","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Using Theia As An End User"},"html":"

Using the \"Theia IDE\" as an End User

\n

The Theia IDE is a modern and open IDE for cloud and desktop. The Theia IDE is based on the Theia platform.

\n\n\"Theia\n

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.

\n

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:

\n\n

Please 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"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/user_install_vscode_extensions/page-data.json b/pr-previews/pr-540/page-data/docs/user_install_vscode_extensions/page-data.json index 7da05336..9be808b3 100644 --- a/pr-previews/pr-540/page-data/docs/user_install_vscode_extensions/page-data.json +++ b/pr-previews/pr-540/page-data/docs/user_install_vscode_extensions/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_install_vscode_extensions","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Installing VS Code Extensions in Theia"},"html":"

Installing VS Code Extensions in Theia

\n

You can install VS Code extensions into Theia-based products via the Open VSX Registry, aka “Theia Marketplace” or “Theia Extension Registry”.

\n

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.

\n

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”.

\n

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.

\n

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”.

\n\"Theia\n

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.

\n

Compatibility

\n

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.

\n

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...\").

\n

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.

\n

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.

\n

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.

\n

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.

","fields":{"slug":"user_install_vscode_extensions"}}},"pageContext":{"slug":"user_install_vscode_extensions"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_install_vscode_extensions","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Installing VS Code Extensions in Theia"},"html":"

Installing VS Code Extensions in Theia

\n

You can install VS Code extensions into Theia-based products via the Open VSX Registry, aka “Theia Marketplace” or “Theia Extension Registry”.

\n

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.

\n

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”.

\n

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.

\n

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”.

\n\"Theia\n

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.

\n

Compatibility

\n

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.

\n

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...\").

\n

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.

\n

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.

\n

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.

\n

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.

","fields":{"slug":"user_install_vscode_extensions"}}},"pageContext":{"slug":"user_install_vscode_extensions"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/page-data/docs/user_toolbar/page-data.json b/pr-previews/pr-540/page-data/docs/user_toolbar/page-data.json index 13229d2f..f98339ca 100644 --- a/pr-previews/pr-540/page-data/docs/user_toolbar/page-data.json +++ b/pr-previews/pr-540/page-data/docs/user_toolbar/page-data.json @@ -1 +1 @@ -{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_toolbar","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Using the dynamic Toolbar in Theia"},"html":"

Using the dynamic Toolbar in Theia

\n

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.

\n

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.

\n

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\".

\n\"Theia\n

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\").\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\n

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.

","fields":{"slug":"user_toolbar"}}},"pageContext":{"slug":"user_toolbar"}}} \ No newline at end of file +{"componentChunkName":"component---src-templates-doc-js","path":"/docs/user_toolbar","result":{"data":{"markdownRemark":{"frontmatter":{"title":"Using the dynamic Toolbar in Theia"},"html":"

Using the dynamic Toolbar in Theia

\n

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.

\n

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.

\n

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\".

\n\"Theia\n

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\").\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\n

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.

","fields":{"slug":"user_toolbar"}}},"pageContext":{"slug":"user_toolbar"}}} \ No newline at end of file diff --git a/pr-previews/pr-540/support/index.html b/pr-previews/pr-540/support/index.html index aa0ce14b..f5a7837b 100644 --- a/pr-previews/pr-540/support/index.html +++ b/pr-previews/pr-540/support/index.html @@ -48,4 +48,4 @@ } } }) -
\ No newline at end of file +
\ No newline at end of file