Developing Che-Theia plug-ins

Bootstrapping a Che-Theia plug-in development with Yeoman

There are two ways to scaffold a new plug-in development environment in Che-Theia:

Console plug-in generator (based on the Yeoman generator).
Yeoman wizard (launched from the command palette).

List of available plug-in samples

The Che-Theia plug-in generator provides several predefined samples:

Hello World plug-in: The plug-in registers a new Che-Theia command. When the user launches this command, Che-Theia displays a notification with the Hello World message. The example illustrates how to define and use commands in Che-Theia.
Skeleton plug-in: The plug-in prints the current Che-Theia window state in the browser log.
Samples plug-in: The plug-in contains examples of how to use the Che-Theia API:
- Commands sample: The plug-in shows how to define a Che-Theia command with arguments. Command arguments are useful when another plug-in needs to call a command with parameters.
- Information message sample: An example of how to define and show a modal information message.
- Quick-pick sample: An example of how to define a command list with items and a handler for a selected item.
- Status-bar item sample: An example of how to apply information to the status bar. The status bar is a widget located at the bottom of the Che-Theia window (a footer).

Overview of generating plug-ins

To simplify plug-in development, there is a plug-in generator (@theia/generator-plugin) for creating new plug-ins from scratch. The plug-in generator provides the Yeoman wizard for a step-by-step plug-in generation:

Choose project name for the future plug-in.
Select plug-in type. The Che-Theia plug-in API has two plug-in types:
- frontend: The plug-in works on the client side
- back end: The plug-in works on the server side
During plug-in creation, you need to decide the purpose of the plug-in and, accordingly, select the plug-in type.
Select a plug-in sample.

Installing the plug-in generator

Run the following command to install the plug-in generator:
```
$ yarn global add yo @theia/generator-plugin
```
Check that the @theia/plugin generator is available:
```
$ yo --help
```
The command returns a list of pre-installed generators.

Generating a new plug-in in the console

Create a new terminal inside your workspace using the Terminal menu, and run the plug-in generator:
```
$ yo @theia/plugin
```
Alternatively, run yo without any parameters and select the @theia/plugin generator from the list of available generators.
Enter the information to configure the plug-in. For example:

When the plug-in is generated, it appears in the Files panel. The sample is already compiled and contains the plug-in binary file. In this example, the plug-in binary file is named my_first_plugin.theia.

Generating a new plug-in using the Yeoman wizard

Che-theia provides the Yeoman wizard command for creating new plug-ins from the command palette.

To launch the command palette, press Ctrl+Shift+p (or Cmd+Shift+p on macOS).
Type Yeom to filter the commands. Select the Yeoman Wizard command.

Note that launching the wizard may take a few seconds.
Enter the new project name.
Select the desired plug-in type (client-side or server-side).
Select the plug-in sample to use.

When the plug-in is generated, the Yeoman wizard displays a notification.

The plug-in sample displays in the Files panel. Use the Output tab in the bottom panel to access logs for plug-in generation.

The Yeoman wizard only works when a workspace is opened in Che-Theia.

Developing a Che-Theia plug-in using Che

This section describes how to set up an environment for developing the Che-Theia plug-ins in Eclipse Che.

Prerequisites

A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.
chectl management tool is available. See Using the chectl management tool.
1. Create a workspace for development. Che has stack for plug-in development. In the Dashboard, click the Workspaces tab, and click the Add Workspace button.
2. Select the NodeJS React Web Application sample.
3. Generate a plug-in scaffold. The workspace created from this stack provides an easy way to scaffold a new plug-in. When the workspace is started and fully ready, execute the Yeoman Wizard from the command palette:
  1. Press F1 or Ctrl+Shift+p to invoke the command palette, and start typing the command name Yeoman … (note that you can also use the keyboard to navigate through the offered commands).
    
    Figure 1. Launching the Yeoman Wizard
  2. Specify the following fields about the plug-in that you want to create:
plug-in name: For example, my-first-plugin.
plug-in type: Select backend plug-in.

plug-in template: Select the Hello World plug-in.

A message confirming that the plug-in generation has been successful indicates creation of the plug-in.

Figure 2. Yeoman successfully generated a new plug-in

Open the Files panel, to see the sources of the generated plug-in in the src directory.
Build the plug-in. After the plug-in is created, build the plug-in:
1. Open a new terminal in the development container (use Ctrl+`, then select ws/dev).
  
  Figure 3. Opening a new terminal in the development container
2. In the terminal, go to the plug-in directory, and run the yarn command:
  # cd my-first-plugin/ # yarn
  Figure 4. Building a Che-Theia plug-in using yarn
  
  The plug-in generator automatically builds the plug-in after its generation.

Run the plug-in. To see your plug-in in action in the IDE, use the Hosted mode to start a new IDE instance and to install the plug-in in it. You now have two IDEs running: one for developing your plug-in and one for testing it.

In the command palette, run: Hosted Plugin: Start Instance command (press F1, and type the command).

Select the path to the root directory of the plug-in in your workspace.

If you get a warning that your browser prevented the opening of a new tab, click the Open button in the dialog box. A new tab with another Che-Theia instance (with the developed plug-in loaded) is opened.

Figure 5. Running a Che-Theia plug-in in Hosted mode

Debug the plug-in.
1. In the source code of your plug-in, set a breakpoint by clicking behind a line number (in the editor gutter).
2. Using the command palette, stop your Hosted Plug-in instance (if any) by running the Hosted Plugin: Stop Instance command.
3. Start the Hosted Plug-in instance again in the debugging mode by running the Hosted Plugin: Debug Instance command.
4. Switch to the Hosted Instance tab and perform the required actions to reach the code with the breakpoint.
5. Go back to the Main Che-Theia window, and use the Debug panel as you need.
  
  Figure 6. Debugging a Che-Theia plug-in
  
  When developing a frontend plug-in, debug it using your browser’s Developer Tools option.