Apps

Apps are Node.js based scripts, which are running with a web view and can also interact with a Visual Studio Code instance.

They can be run for a workspace or globally for an user.

You are able to use one of the following frameworks to realize an UI:

• Vue with Vuetify (recommended)
• MD Bootstrap Free and jQuery 3

Global apps

Create an app

To create a global app, press F1, select Power Tools: Apps and choose the command Create App ....

Then enter the name and description for your app and the extension will create a folder inside your user home directory (${homeDir}/.vscode-powertools/.apps/${appName}) with a boilerplate, with which you can start.

The following files will be created:

Name	Description
.egoignore	Is used to ignore the files, which should not be saved, when you create a package of the app.
app.vue	The vue file, where you can define and setup your <template>, <script> and <style> tags.
index.js	The Node.js script that is used as a bridge between Visual Studio Code and the web view.
LICENSE	The license, you would like to use for your app.
package.json	The package file, with all meta data. This is also required, if you need additional npm packages for your app. In that case the file contains a vue property with a (true) value, which indicates to use Vue instead of jQuery.
README.md	Describe your app here (with Markdown).

Open the new app by pressing F1, selecting Power Tools: Apps, choosing the command Open App ... and then starting it, by selecting the entry with the name of the app.

For more information, have a look at the Vue / Vuetify page.

Package your app

If you want to share your app with others, you have to build a package from it.

Press F1, select Power Tools: Apps and choose the command Build App Package ....

The extension will save your app to an .ego-app file.

Install app from package

Press F1, select Power Tools: Apps and choose the command Install App ... to install an app from an .ego-app package file.

Workspace apps

Instead of creating a global app, you are also able to define an app only for a workspace.

If you prefer Vue, instead of MD Bootstrap with jQuery, have a look at the Vue / Vuetify page.

Create an apps section to the settings.json file in the .vscode sub folder of your workspace and add one or more entry:

{
    "ego.power-tools": {
        "apps": [
            {
                "name": "My app",
                "description": "My awesome app",
                "script": "my_app.js"
            }
        ]
    }
}

For that example first create the my_app.js file in your .vscode folder and use the following skeleton:

/**
 * Is invoked on an event.
 */
exports.onEvent = async (args) => {
    // args => s. https://egomobile.github.io/vscode-powertools/api/interfaces/_contracts_.appeventscriptarguments.html

    // s. https://code.visualstudio.com/api/references/vscode-api
    const vscode = args.require('vscode');

    switch (args.event) {
        case 'on.command':
            // is invoked, when the web view has
            // been post a (command) message
            if ('hello_from_webview_command' === args.data.command) {
                // this has been send from
                // 'ego_on_loaded()' function
                // in 'my_app.ejs'

                vscode.window.showInformationMessage(
                    'From WebView: ' + JSON.stringify(args.data.data, null, 2)
                );

                // send this back to 'my_app.ejs'
                await args.post('hello_back_from_extension', {
                    'message': 'Hello, Otto!'
                });
            }
            break;

        case 'on.loaded':
            // page inside web view has been completely loaded
            break;

        case 'on.hidden':
            // web view has went to the background
            break;
        case 'on.shown':
            // web view has went to the foreground
            break;

        case 'on.close':
            // the web view is going to be closed
            break;

        case 'on.disposed':
            // the web view has been disposed
            break;
    }
};

/**
 * The web view is going to be disposed.
 */
exports.onDispose = (args) => {
    // TODO
};


/**
 * This returns the title, which is displayed in the tab
 * of the web view.
 */
exports.getTitle = (args) => {
    // args => https://egomobile.github.io/vscode-powertools/api/interfaces/_contracts_.appeventscriptarguments.html

    return "My app";
};

/**
 * This returns the HTML code for the body.
 */
exports.getHtml = (args) => {
    // args => https://egomobile.github.io/vscode-powertools/api/interfaces/_contracts_.appeventscriptarguments.html

    return args.renderFile(
        'my_app.ejs',
        {
            'page_title': "My app",
        }
    );
};

Then create the view file my_app.ejs:

<div class="container">
  <h1><%= page_title %></h1>

  <pre id="last-message-from-extension"></pre>
</div>

<style>

/* put your custom styles here */

</style>

<script>

/**
 * This is called, when a command
 * has been received from the app script.
 */
function ego_on_command(command, data) {
    switch (command) {
        case 'hello_back_from_extension':
            // this has been send from
            // 'onEvent()' function
            // in 'my_app.js'

            $('#last-message-from-extension').text(
                'From extension:\n\n' + JSON.stringify(data, null, 2)
            );
            break;
    }
}

/**
 * This is called, after the
 * page has been completely loaded.
 */
function ego_on_loaded() {
    // TODO

    // this is send to 'onEvent()' function
    // in 'my_app.js'
    ego_post('hello_from_webview_command', {
        'message': 'Hello, Echo!'
    });
}

</script>

Now you should be able to open the app by pressing F1, selecting Power Tools: Apps and choosing Open App ... command.

Settings

Name	Description	Required?
button	The optional button for starting the app.	no
description1	A description of the app.	no
if	(JavaScript) Code that checks if button is available or not. s. Conditional Settings	no
importValues	Defines a list of properties, which uses (external) values for itself. s. Import Settings	no
name1	The (display) name of the app.	no
onCreated	The (JavaScript) code to executed after app has been created. s. Executable Settings	no
onDestroyed	The (JavaScript) code to executed after app has been destroyed. s. Executable Settings	no
options	Options for the script, which will be available in all options properties of the 1st arguments of all known event methods, defined in .js file (code-behind).	no
platforms	A list of one or more platform IDs, where the button should be available on. s. process.platform	no
script1	The path to the script that should be invoked. Relative paths will be mapped to the .vscode sub folder of the workspace or the .vscode-powertools sub folder inside the current user's home directory.	yes
vue	Use Vuetify instead of MD Bootstrap or not. Default: (false)	no

^{1 supports placeholders}

button

Name	Description	Required?
color1	The RGB text color.	no
isRight	Display button one the right side or not. Default: (false)	no
priority	A (numeric) value that defines the priority, the button should be displayed with.	no
text1 2	The (display) text.	no
tooltip1	The tooltip text.	no

^{1 supports placeholders
2 supports icons}

Scripting

Web View

s. app.js

Functions

ego_apply_highlight( selector )

Applies syntax highlighting to the elements of the current selector.

ego_from_markdown( markdown, tag? )

Creates an element from Markdown.

ego_is_nil( val )

Checks if a value is null or undefined.

ego_log( msg )

Logs a message.

ego_open_external_url( url, text )

Asks the user in Visual Studio Code, if an external URL should be opened.

ego_post( command, data )

Posts a command with (optional) data from the web view to the app (script).

ego_to_string( val )

Converts a value to a string, which is NOT null or undefined.

App stores

The extension can manage app stores, which are catalogs of apps.

To open a store, simply press F1, choose Power Tools: Apps and execute Open Store ... command.

Custom stores

By default, a default app store is used.

You can define an own, by pressing F1 and choosing Power Tools: Global Settings.

The JSON, that describes a store, uses the AppStore interface.

Key bindings

If you would like to define key bindings for quick access, you are able to setup a shortcut for the following commands:

Name	Description
ego.power-tools.openApp	Opens the list of apps, where the user can select the one, which should be opened.