Overview

Goby has built-in API extension capabilities. allowing goby-supported parts to be customized or enhanced.

This document includes following items:

• How to build, run, debug, test and release extensions.
• How to use goby’s extensions and API better.
• Guidelines and code example to help you get started quickly.

What can extensions do?

1. Expand the workbench by adding custom components and views to interface.

If you want to have a general overview of all APIs, please refer to the function overview. The extension has included code example and guide.

How to build an extension?

It’s not easy to make a good extension. Let’s take a look at what each chapter of this tutorial can do:

• Get started We will give you a "Hello World" example to get started.
• Extension development Contains various extension development processes, such as testing, packaging and publishing etc.
• Extension functions We disassembled goby’s API into several parts to help you get the development details for each scene.
• Example Includes code example and guide. Detailing specific API usage.
• Appendix Includes the details of goby API, contributors and other related information.

Get started

Your first extension

In this section, you will learn some basic concepts.Please install the Debug extension of goby first . After that, you need to download a project from (helloWorld). Unzip it under directory goby/extensions then start goby.

Click "Start scan", you will find a hello button at the top of the pop-up window, click the button, if another pop-up windows with (helloWorld) appears. Congratulations! You have finished this Step.

Extension Development

Now let’s change the pop-up information:

• Make sure you are in the "goby/extensions/helloWorld/src/" directory
• Edit file "extension.js", replace "helloWorld" in function "goby.showInformationMessage" with "helloGoby"
• Restart goby, click the hello button.

Now you should see the changed information:

Use JavaScript

In the document we mainly use JavaScript to develop goby extensions.

Resolving extension structure

In last section, you have learned create a new basic extension by yourself. But how does it work?

The next two concepts will help you:

• Publishing configuration：goby expands the fields of package.json (extension list) to facilitate the development of extensions.
• Goby API：your extension code depends on various JavaScript API.

In general, your extension is to extend the goby’s function by combining publishing content configuration and goby API. You can find appropriate contributions and goby API for your extensions in the "Overview of extension functions".

Now let’s take a look of the example code in "helloWorld", And how the two concepts we mentioned above are applied.

Extension directory structure

      ├── .gitignore          // Ignore build output and node_modules 
      ├── README.md           // Help document
      ├── CHANGELOG.md        // Update log file
      ├── src
      │   └── extension.js    // Source codeextension is installed successfully, this function will be 
      ├── package.json        // extension configuration list

Now let’s concentrate on the key parts of the extension——package.json and extensions.js

extension list

Every Goby extension must contain package.json, That is the extension configuration list. Package.json includes some of Node.js keywords. Such as scripts, dependencies,and goby unique fields, such as publisher, initEvents, contributes etc. All this can be found in reference of extension list. We only introduce some important fields in this section.

• name: The extension’s name.
• publisher: The publisher’s name. Goby will combine "publisher" and "name" as a extension’s ID.
• main: The main entrance of extension.
• initEvents 和 contributes: Initialize event and publish configurations.
• engines: Describes the lowest version of goby that this extension depends on.

    {
            "name": "helloWorld",
            "publisher": "goby",
            "description": "helloWorld by goby",
            "version": "0.1.0",
            "icon": "",
            "engines": "1.6.170",
            "initEvents": "",
            "main": "./src/extension.js",
            "contributes": {
              "views": {
                "scanDia": [
                  {
                    "command": "hello",
                    "title": "hello"
                  }
                ]
              }
            },
            "scripts": {},
            "devDependencies": {},
            "dependencies": {}
          }

Extension’s entry file

Entry file needs to export a function, activate, when the extension is installed successfully, this function will be executed.

    function activate (content) {
            goby.registerCommand('hello', function (content) {
              goby.showInformationMessage("helloWorld");
            });
          }
          
          exports.activate = activate;

Summary

In this section, you learned how to create, run and debug extensions, and also the basic concepts of Goby extension development. This is only a beginner's guide, how to develop extensions will be explained in further detail in later sections.

Extension development

Testing extensions

The development version of Goby provides running and debugging capabilities for extension development. Just put your extension into the goby/extensions directory, and start Goby.

You can click the view button, choose toggle developer tools to open the console.

Publishing

Functions:

• User registration
• Packing
• Publishing
• Deleting

User registration

Before publishing, you should register first.

Packing

We only accept ".zip" format packages currently, you can convert and upload it by yourself or use automatic packaging (Please refer to the next section, we will tell you how to pack your extensions).

Warning: the entire extension folder must be zipped when packaging, that means after performing automatic decompression, make sure that the directory structure of the entire extension is complete.

Publishing

After login, you can publish your extensions from Your Profile-Extensions management, when zip archive is uploaded, we will have specialized personnel to review. Once approved, the extension will appear in the market list.

Deleting

You can delete extension in the Your Profile center.

Packaging extensions

As mentioned before, when the goby extension is submitted, only zip format upload is supported. As for JavaScript, there are many optional packaging tools. This section mainly demonstrates the use of jszip for packaging.

1. Install the jszip first

        npm install jszip

2. Then, create build.js in your extension directory

          var JSZip = require('jszip');
          var fs = require('fs');
          var path = require("path");
          var zip = new JSZip();

          // packaging files
          zip.file("package.json", fs.readFileSync(__dirname+"/package.json"));
          zip.file("CHANGELOG.md", fs.readFileSync(__dirname + "/CHANGELOG.md"));
          zip.file("README.md", fs.readFileSync(__dirname + "/README.md"));

          // package files in the folder
          var src = zip.folder("src");
          src.file("extension.js", fs.readFileSync(__dirname + "/src/extension.js"));

          // compress
          zip.generateAsync({
            // select nodebuffer as the compression type，it will return the value of zip file in callback functions ，and then use fs to save to local disk.
            type: "nodebuffer"
          }).then(function (content) {
            let zip = '.zip';
            // write into disk
            fs.writeFile(__dirname + zip, content, function (err) {
              if (!err) {
                // if written successfully
                console.log('Compression successfully');
              } else {
                console.log('Compression failed');
              }
            });
          });

3. Finally, execute the packaging command in the extension directory. You will see the packaged zip file in goby/extensions.

    node ./build.js

Additionally, jszip is just one of the packaging methods, you can choose your favorite instead.

Extension Functions

Overview

Goby provides some methods for extensions to extend the capabilities. But sometimes it is not easy to find the appropriate publishing configuration and goby API. This section contains following parts:

• Available function for extension.
• Some inspiration

However, we will also tell you some limitations, such as: extensions cannot modify the underlying DOM of Goby UI.

Common Functions

Common functions are the core functions you may use in any extension.

Including:

• Registration order
• Configure the entry point for views
• Use custom views
• Configure extension settings
• Notifications
• Event Notifications

Extension workbench

The extension workbench is the view entry point that user can customize, it can enhance the function of goby. For example, you can add new button on the pop-up window to import spe