Developing Che-Theia plug-ins

Bootstrapping a Che-Theia plug-in development with Yeoman

Two methods are available 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 open 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 configure an environment for developing the Che-Theia plug-ins in Eclipse Che.

Prerequisites

A running instance of Che. To install an instance of 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 for the desired plug-in:
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. The two IDEs are 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 a click 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.