HAL Extensions

Version 9

    Extensions are a way to add new features to HAL. Unlike the current version of the management console, HAL.next supports extensions written in JavaScript which can be added at runtime. The current way of writing extensions using Java, GWT modules and compile time binding with maven is not yet implemented, but is planned to be ready for the first final version. This document is about HAL.next and JavaScript extensions and describes how to build and deploy them.

     

    Architecture

    JavaScript extensions consist of one script and one or more optional stylesheets. The script contains both the code to register the extensions and the actual code of the extension. Use HAL.next's JavaScript API to register the extension and to interact with HAL.next and the management endpoint. Here's a code sample for an extension:

     

    let core = hal.core.Core.getInstance();
    let extension = hal.core.ExtensionPoint.header("foo", "Foo", () => {
        // your extension code
    });
    
    core.extensionRegistry.register(extension);
    

     

    The extension's script and stylesheets must be served by endpoints which are known to HAL.next. When HAL.next starts, it injects the scripts and stylesheets of all known extensions which in turn will make them available in HAL.next.

     

    Extension Points

    The console provides three different extension points which can be used by extensions:

    1. Header: Adds a menu item to the "Extensions" dropdown in the header
    2. Finder Item: Adds a new item to a specific finder column (not yet implemented)
    3. Footer: Adds a menu item to the "Extensions" dropdown in the footer

     

    Development

    JavaScript extensions must adhere to certain rules:

    • the code must be in one file
    • the stylesheets can be spread across multiple files
    • the extension must register itself using HAL.next's JavaScript API (there's no lookup / detection mechanism in the console).
    • the extension must not use external dependencies (other than what's provided by the console itself)

     

    To get started quickly you can use the npm package hal-edk (extension development kit). Follow these steps to setup a new extension project:

    1. Create a new npm project
    2. Install a developer dependency for hal-edk:
      npm install --save-dev hal-edk
      This will install the management console in node_modules/hal-edk and create two files in the project's root folder:
      • index.html: Starts the console and loads extension.js
      • extension.js: Registers a noop header extension
    3. Start a local web server and add the URL as allowed origin to the management model.
    4. Open index.html

     

    Deployment

    Extensions can be deployed using two different ways:

    • Server side extensions: Part of the WildFly / EAP installation
    • Standalone extensions: Served by its own and independent from the WildFly / EAP installation

     

    Server Side Extensions

    Server side extension are installed as WildFly modules. The module contains the extension's script and stylesheets. They're served by a custom context on the WildFly HTTP management interface as described in Design notes for preliminary support for custom http management interface handlers.

     

    Server side extensions expose themselves as read-only resources under /subsystem=core-management:

    /subsystem=core-management/console-extension=foo
    {
        "script" => "/extension.js",
        "styles" => [
            "/styles.css"
        ]
    }
    

     

    After installing an extension the console has to be reloaded. During bootstrap the console will read the extensions from the management model and inject the scripts and stylesheets (which in turn will register and add the extensions to HAL.next). A use case for server side extensions are layered products which might want to ship console extensions as additional modules.

     

    Standalone Extensions

    Standalone extensions are independent from the WildFly / EAP installation. The only requirement is that there's a public available endpoint which serves the extension's script and stylesheet. That might be GitHub, OpenShift or any other service which is capable of serving JavaScript and stylesheets.

     

    You have to register standalone extensions using the management console (not yet implemented). The registered extensions are not stored in the management model, but in the browser's local storage. As such they're scoped to the browser and URL which runs the management console.

     

    Examples for standalone extensions might be general purpose add-ons to the console which are not specific to a particular WildFly or EAP installation or product (enhanced log viewer, custom dashboard with specific monitoring data, ...).