0. Installation environment

Before you begin, please check that Node.js (https://nodejs.org/en/) is installed. If it has been installed, you can run ‘node -v’ and ‘npm -v’ on local CMD or terminal of CodeArts IDE to view the installation version.

1. Practical tutorial

(1) Create a new extension

Open CodeArts IDE, choose "File > New > Project…", and select "Plugin". Enter the information. To better understand the follow-up tutorial, you are advised to select "Plugin with exposable webview and dialog support" or "Plugin to register a project wizard".

Note: The publisher must be created on the Marketplace. Otherwise, the extension cannot be released on the Marketplace successfully. You can also modify the publisher in package.json before the release.

Click “Create”. Wait until the project is created and choose whether to open the new project in the current window.

(2) Use CodeArts IDE to debug your frontend and backend code

Backend debugging

The backend code of this sample is under "src/node", which runs in the nodejs environment. When the project is created, the backend.ts is generated by default. For lightweight extensions, you only need to add the service functions you want to implement in this file. This file contains three default methods: init(), run(), and stop(). In addition, a doSomething method is added by default. This method is only used as an example and can be modified or deleted as required.

Let's briefly introduce the init, run, and stop methods:

• Init function: As the initialization method of the backend instance, it can do some initializing works when the extension is activated. It will be invoked before run and other functions. Note that: Frontend functions exposed to the backend cannot be invoked in the init function, which means "this.plugin.call" cannot be invoked here.
• Run function: As the main logic function of the backend instance, it is the service function entry. It can easily invoke APIs of CodeArts IDE. For example, "codearts.window.showInformationMessage(`hello world!`);". It can also invoke functions exposed by the frontend, you can use "this.plugin.call" here.
• Stop function: This function is invoked before the extension is stopped. You can clear resources here if necessary.

Backend debugging steps:

1. Add a breakpoint to run() in backend.ts.

2. Open the debugging window: Press F5 or click Debug button on the debugging toolbar to open the Extension Development Host window.

3. Enter the breakpoint and start debugging.

Frontend debugging

Unlike the backend, the frontend code under "src/browser" will eventually be compiled and run in the browser environment. When a project is created, two frontend files, frontend.ts and dynamic-webview.ts, are generated by default. The contents of these two files are similar to the structure of the backend.ts file. The only difference is the running environment. The init(), run(), and stop() methods in these two files are similar. The frontend runs in the browser environment, debugging will rely on the browser's built-in debugging function. To automatically recompile the frontend code, you can run "npm run watch-browser" on the terminal, and then start debugging. If you modify the code after the debugging is started, you only need to press Ctrl+R in the debugging window to refresh.

Frontend debugging steps:

0. Before debugging, set devtool in the webpack.config.js to "inline-source-map", and then run "npm run prepare" on the terminal.

1. Add a breakpoint to run() in frontend.ts.

2. Open the debugging window: Press F5 or click Debug button on the debugging toolbar to open the Extension Development Host window. If you cannot enter the breakpoint, you can use Ctrl+Shift+I to open the 'Developer Tools' and then press Ctrl+R to reload the current window.

3. Open the extension webview, enter the breakpoint and start debugging.

(3) Invoking frontend and backend methods

Backend invokes frontend

1. Define the method for exposing the frontend to the backend.

Open the frontend.ts under "src/browser". The Frontend class extends AbstractFrontend. In addition to the init(), run(), and stop() methods to be implemented, the myApi(message: string) method is customized. If you want to expose the myApi method to the backend, simply add the "@expose('function_id')" decorator to the function.

Note: The function_id in expose decorator must be unique.

@expose('myplugin.page.myApi')
public myApi(message: string): string {
    console.log(message);
    return 'this is a return value from frontend function';
}

2. Invoke the frontend exposed method at the backend.

Open "src/node/backend.ts". In this file, the Backend class extends AbstractBackend and implements the init(), run(), and stop() methods. In run(), you can call myApi method defined in the frontend through "this.plugin.call()" and obtain the return value.

public async run(): Promise<void> {
    const retValue = await this.plugin.call('view_type_of_your_plugin_view::myplugin.page.myApi', 'this is a function call from backend');
    this.plugin.log(LogLevel.INFO, retValue);
}

Frontend invokes backend

Similarly, we can define our own methods on the backend and expose them to the frontend.

1. Define backend method exposed to the frontend.

Open “src/node/backend.ts” and customize a doSomething(name: string) method.

@expose('your_backend_function_identifier')
public doSomething(name: string): boolean {
    codearts.window.showInformationMessage(`hello ${name}!`);
    return true;
}

2. Invoke the backend method exposed to the frontend.

Open "src/browser/frontend.ts" and invoke the doSomething method defined on the backend through "this.plugin.call()" in run().

run(): void {
    this.plugin.call('your_backend_function_identifier', 'world');
}

(4) Event subscription: publish and listen to the events

Listening to the events at the backend

Open backend.ts under "src/node", and add the following code to run() to register and listen to a file deletion event.

const registeredEvent = codearts.workspace.onDidDeleteFiles((event) => {
     codearts.window.showInformationMessage(`${event.files.join(',')} deleted.`);
});
this.plugin.context.subscriptions.push(registeredEvent);

If you want to delete the listener of the event, call dispose() of registeredEvent directly.

You can try registering some other events and testing the effect.

Listening to events at the frontend

Open fronted.ts under "src/browser" and add the following code to run() to register an event that changes the current active editor.

const eventHandler = (eventType: any, evt: any) => {
    // do something
};
this.plugin.subscribeEvent(EventType.WINDOW_ONDIDCHANGEACTIVETEXTEDITOR, eventHandler);

The method of canceling event registration on the frontend is different from that on the backend. You need to use the unsubscribeEvent to cancel the registered event handle.

this.plugin.unsubscribeEvent(EventType.WINDOW_ONDIDCHANGEACTIVETEXTEDITOR, eventHandler);

(5) Internationalization

After the project is created, the "package.nls.json" and "package.nls.zh-cn.json" are generated in the root directory by default. The "package.nls.json" is the default translation, if no translation of the corresponding language is found, the default will be used. "package.nls.zh-cn.json" is a simplified Chinese translation file. If other languages need be supported, you can add another translation file by yourself.

The localize method needs to provide a key parameter to specify the entry in the internationalization file. The subsequent variable parameters are used to replace the placeholder in the translations. You can use the {0} {1} {2} format as a placeholder in an entry. The second parameter of the localize method will be replaced with the placeholder in sequence.

localize(key: string, ...args: any[]): string;

An example is as follows:

{
    "plugin.welcome": "Welcome!",
    "plugin.hello": "Hello {0}!"
}

The localize method of the built-in member——plugin

We also implemented the localize method in the built-in member——plugin. In Frontend class (src/browser/fronted.ts) and Backend class (src/browser/backend.ts) which extends AbstractFrontend and AbstractBackend respectively, you can directly call "this.plugin.localize()" to use translations.

// Without parameters
this.plugin.localize('plugin.welcome');
// With parameters
this.plugin.localize('plugin.hello', 'world');

Directly import localize method

import { localize } from '@cloudide/nls';

Use the following code to get the translation: Hello World!

localize('plugin.hello', 'World');

Internationalization Methods in HTML

Common plugins can use ejs and pug engines to render the user interface. Both ejs and pug engines provide developers with an built-in l10n object that stores a list of translation entries for the current language.

If the ejs engine is used for GUI rendering, you can use translations in the following way:

<%= l10n['plugin.hello'] %>

Developers who use the pug engine can use translations in the following way:

#{l10n['plugin.hello']}

(6) Package and install extension

Run "npm run package" on the terminal to pack the extension.

Install the package in CodeArts IDE.

2. Extension Samples

• Plugin to register view title buttons: codearts-example-view-title-actions
• Plugin to register menu: codearts-example-registerMenu
• Plugin to register project wizard: codearts-example-project-wizard

3. Extension Release

Directly release to the Marketplace through CodeArts IDE

0. If you have not created a publisher, go to the Marketplace to create a publisher. You can refer to the CodeArts IDE Marketplace Help. If you have a publisher but haven’t created a publisher credential, go to the Marketplace Publisher Management to create one. Here are the steps to create a credential:

(1) Click add a credential

(2) Enter the certificate name and set the expiration time.

(3) Created successfully. Please keep the publisher certificate properly. After the window is closed, the certificate cannot be obtained again.

1. Before the release, ensure that the publisher in the package.json is consistent with the publisher and its corresponding certificate.

2. Run "npm run publish" on the terminal, enter the publisher certificate after the packaging is complete, and press Enter to confirm.

3. Wait for the extension to be uploaded and released.

4. The uploaded extension is displayed in the management page of the Marketplace. The default status is grayscale pending release, and the extension requires the user with manager permission to review the pending extension. Then, the user with manager/developer/ower permission can officially release the grayscale release extension. Without approval, the extension will automatically become official and can be searched for on marketplace of CodeArts IDE.

Release through the Marketplace

For details about how to upload and manage your extension in the Marketplace, see the CodeArts IDE Marketplace Help.