Engee documentation

Working with Genie in Engee

Engee provides the ability to develop custom applications directly in its environment using the Genie framework. This allows users to create their own applications, web interfaces and various integration solutions without leaving the Engee workspace.

Engee is a ready and customised environment for running applications created with usage of the Genie framework. Engee also provides basic functionality for modifying them. The following article shows you the basic principles of working with Genie, knowing them, you will be able to adapt ready-made applications to your needs.

Genie is a framework for developing web applications for Julia. Read more about the framework at official site.

xref:tutorial/filter-designer.adoc[], xref:guide/radar-equation-calculator.adoc[] and xref:tutorial/calculation-of-the-power-grid-modes.adoc[] are already written and fully functional on Genie.
The Engee environment is optimised to work with the Genie framework and despite the Julia kernel and support for Python, it is not recommended to use any other frameworks.

Genie usage

To create your own application in Engee, follow these instructions. An application can be in the form of a .jl script or a directory with an app.jl file. Placement of such applications is done within the /user directory. The following are the basic steps for running, managing, and working with Genie-based applications.

  1. Place the application - the created application should be placed in the /user directory. If the application is a directory, make sure it contains the app.jl file. Placement example:

    /user/apps/MyGenieApp/
    app.jl
    public/
    src/

  2. Start Application - Run the following command to start the application:

    engee.genie.start("/user/apps/MyGenieApp", devel=true, log_file="/user/apps/MyGenieApp")

    here:

    • devel: optional parameters, enables development mode, allowing you to see changes without restarting.

    • log_file: path to save application logs. It is optional.

      If a relative path is specified, the command searches for the application relative to the current directory.

  3. Stop application - to stop a running application, execute:

    engee.genie.stop("/user/apps/MyGenieApp")

    The path can be set as relative or absolute.

  4. List of running applications - to check which applications are currently running, run the command:

    engee.genie.list()

  5. Transfer data from application to session - the engee.genie.send(wsVarName, value) function is used to send a value from an application on Genie to the Engee workspace. The first argument wsVarName specifies the variable name as a string. The second argument value is the value that is stored in the variable. If there is no variable with this name, it is created automatically. Use this function to save intermediate results and user data in general. For example:

    engee.genie.send("a", 42)
engee.genie.send("message", "Hello")

  6. Getting data from a session to an application - the engee.genie.recv(wsVarName; context=…​) function allows you to get the value of a variable from the Engee environment while running an application on Genie. The wsVarName argument specifies the name of the variable. If the variable is defined in another module, the context parameters are used to specify in which namespace to look for it. This is necessary if the variable is pre-defined outside the scope of the main application module. For example:

    engee.genie.recv("a")
engee.genie.recv("message")
engee.genie.recv("value"; context=MyModule)

  7. Executing code in the workspace - the engee.genie.eval(code::AbstractString) function allows you to execute arbitrary code on Julia in the Engee workspace directly from the Genie application. It is used to run individual expressions, debug or dynamically execute code without having to restart the application.

    engee.genie.eval("x = 10")
engee.genie.eval("println(\"Значение x: \$x\")")

    The passed code::AbstractString is executed in the global area of the current Engee* session. In this way it is possible to manipulate variables or logic from the outside by passing commands from the Genie application inside the Engee** session.

  8. View application logs - to get logs of a running application, use the command:

    engee.genie.logs("/user/apps/MyGenieApp")

    If the log_file parameter was not specified when the application was started, the command will still output the current logs.

Usage of third-party packages in the application

You can use third-party packages in an application. To do this, load the Project.toml file and run the command:

engee.genie.pkg_instantiate("/path/to/app")

In this case:

  • The app.jl and Project.toml files must be in the /path/to/app directory.

  • Project.toml should not contain Engee packages, but they will still be available to Genie.

Additional commands for working with packages:

To view a list of installed packages

To display a list of all packages used in an application, run the command:

engee.genie.pkg_status("/path/to/app")
Install new packages

To install one or more packages, use:

engee.genie.pkg_add("/path/to/app", "SomePackage")

or

engee.genie.pkg_add("/path/to/app", ["SomePackage1", "SomePackage2"])
Deleting packages

To remove one or more packages, execute:

engee.genie.pkg_rm("/path/to/app", "SomePackage")

or

engee.genie.pkg_rm("/path/to/app", ["SomePackage1", "SomePackage2"])

Restrictions and specifics of usage

  • It is not possible to install new packages that are not included in the Engee build. However, you can use the following command to see the available packages:

    print(read("/usr/local/genie/Project.toml",String))

  • An application represented as a directory with an app.jl file is considered a standard application. This is the recommended way to organise the project.

A detailed description of public methods of genie programme management is presented in the article Genie’s public methods of programme management.

Example of creating an application

Create an app.jl file in the /user directory file browser file browser 7:

genie app 2 -> genie app 3

In the app.jl file, add the code of the application written with the Genie framework:

module App
using GenieFramework
@genietools

@app begin
    @in N = 0
    @out squared = 0
    @onchange N begin
        squared = N^2
    end
end

function ui()
    [
        cell([
            p("Enter a number to calculate its square:")
        ]),
        cell([
            textfield("N", :N)
        ]),
        cell([
            bignumber("The square of the number is:", :squared)
        ])
    ]
end

@page("/", ui)
end
Detailed description of the application code

  1. Module creation:

    module App

    This is the beginning of an App module. In Julia, modules are used to organise code and isolate it. All application code will be inside this module.

  2. Connecting the GenieFramework library:

    using GenieFramework
@genietools

    Here:

    • using GenieFramework: A plug-in library for running web applications;

    • @genietools: A macro that prepares the environment for the application, including connecting the necessary resources (such as icons and styles).

  3. Declaring a reactive application:

    @app begin
    @in N = 0
    @out squared = 0

    Here:

    • @app: Start of the reactive application code block;

    • @in N = 0: Declare a reactive variable N that will store a custom value;

    • @out squared = 0: Declare a reactive variable `squared that will hold the square of a number. This variable is read-only.

  4. Reactive logic:

    @onchange N begin
        squared = N^2
end

    Here:

    • @onchange N: Indicates that the following code block is executed when the value of variable N changes;

    • squared = N^2: Updates the value of the variable squared (squares the entered number).

  5. User Interface Definition:

    function ui()
    [
        cell([
            p("Enter a number to calculate its square:")
        ]),
        cell([
            textfield("N", :N)
        ]),
        cell([
            bignumber("The square of the number is:", :squared)
        ])
    ]
end

    Here:

    • function ui(): Define the function that creates the application interface;

    • cell([…​]): Packing the interface elements into a structural block:

      • First block cell([]): Display text with the instruction: "Enter a number to calculate its square";

      • Second block cell([]): Number entry field (textfield("N", :N));

        • "N": Signature of the input field;

        • :N:: The relationship of the field to the variable N;

      • Third block cell([]): Display the result (the square of the number) using bignumber;

        • "The square of the number is:": Signature;

        • :squared: Link to the variable `squared.

  6. Creating a route and closing the module

    @page("/", ui)
end

    here:

    • @page("/"): Specifies the route for the application’s home page (/);

    • ui: Indicates that the page content will be generated by the ui function;

    • end: End of the App module.

Next, save the app.jl application file with your changes:

genie app 4

And run the application with the command:

engee.genie.start("/user/app.jl")

This application allows you to square an entered number, demonstrating how you can create your own applications right in the Engee workspace.

genie app 1

If the Engee session has been terminated and the application remains open, the system will generate an error:

genie app 5

  1. Genie’s public methods of programme management

  2. Working with Julia packages

  3. Stipple.jl