Tasks

Nova’s Tasks system offer users a freeform, highly-configurable way of running external operations from within the IDE.

The simplest way of using Tasks is by adding a simple “Custom Script” task configuration that is always available from a user’s project settings. This allows the user to define a script that will execute either on the local machine or a remote server when the configuration is run, forwarding its output to an IDE output report.

Extensions can extend this idea further in two ways:

Defining a Task Template

Defining a Task template in your extension adds a new item to the project settings “Add Task” interface of a user’s Project Settings. This allows a user to instantiate your template as one or more new configurations within their project. Each configuration added references the template in your extension for configuration options, allowing the extension to evolve without the need to recreate configurations.

Templates are great for defining a user-customizable task that should persist with their project and is not necessarily reliant on other configuration files within the project.

A template defines what command is executed when the user runs a configuration created from it, along with the arguments it is passed. Arguments are defined a way that allows them to be edited by a user in the configuration editor, much like an extension’s preferences.

The extension’s extension.json can include a taskTemplates object defining the templates that are exposed by the extension.

Each item in the object is keyed by the template’s identifier, which should not change once an extension is released: Configurations created from it reference this identifier to determine how the configuration is executed.

The value of each item is an object defining how the template behaves.

Here is an example of a configuration which executes a local PHP development web server:

"taskTemplates": {
    "webserver": {
        "name": "PHP Webserver",
        "description": "Runs the PHP development server.",
        "persistent": true,
        "tasks": {
            "run": {
                "shell": true,
                "command": "php",
                "args": [
                    "-S", "$(Config:php.host):$(Config:php.port)",
                    "-t", "$(Config:php.document-root)",
                    "$(Config:php.custom-args)"
                ],
                "env": {
                }
            }
        },
        "config": [
            {
                "key": "php.host",
                "title": "Host",
                "type": "string",
                "placeholder": "localhost",
                "default": "localhost"
            },
            {
                "key": "php.port",
                "title": "Port",
                "type": "number",
                "placeholder": "8000",
                "default": 8000,
                "min": 1,
                "max": 65535
            },
            {
                "key": "php.document-root",
                "title": "Document Root",
                "type": "path",
                "default": "."
            },
            {
                "key": "php.custom-args",
                "title": "Additional Arguments",
                "description": "Custom arguments to pass to the PHP webserver command.",
                "type": "string"
            }
        ]
    }
}

Task Actions

The most important details of a template are defined in its tasks section. This object maps each action, by name, to an object that defines how and what process should be invoked.

Available actions are: build, run, clean.

Value Description
command The executable command to invoke
shell If true, the command will be executed within a shell
args An array of interpolated strings passed to the command
env Interpolated environment variables set for the command

The command value is the executable name that will be invoked by the IDE. This may be a path to a script, relative to the extension root (such as Scripts/run.sh), or a command available on the user’s PATH.

For most cases, be careful when specifying paths for the command. If the path is not valid on all user’s computers it can cause the run to fail. Use absolute paths when the expectation is that the tool being invoked is required to be at this location. Otherwise, use a singular command name that will be interpreted against the user’s PATH, or against the extension’s container. Alternatively, the command value may contain string substitutions (see Arguments, below) that allow the configuration itself to build the path that is referenced at runtime.

Note: In previous versions of Nova (before Nova 2), the tasks value was instead a singular task value that could only specify one task action (for Run). This was amended to support multiple actions.

Arguments

The args and env values can be interpolated, meaning the values may contain special string substitutions that are resolved at runtime. These substitutions follow a similar format to shell substitutions: $VariableName for singular variables, and $(Expression) for more complex expressions. The former is simply a shorthand subset of the latter which can only contain alphanumeric characters and the underscore. The variables and expressions available include those listed in [Variables & Expressions][variables], as well as configuration items defined by the template itself (see “Configuration” below).

Configuration

Each template may define a config section, which uses the same format as Preferences items. These configuration items may be referenced in the string substitution of arguments and environment passed to the template’s executable using the format $(Config:my.config-key). The value will be checked against those set for the configuration, as well as the user’s project and global preferences.

Deprecation

If a task template should be replaced with another, or removed entirely, an extension may optionally declare it as deprecated for any amount of time needed to inform the user that the template will be replaced or removed.

To specify a task template as deprecated, use the deprecated property on the template object. The value of this property may be:

The deprecation notice will be shown in the task template’s edit pane of the project settings.

"taskTemplates": {
    "webserver": {
        "name": "PHP Webserver",
        "description": "Runs the PHP development server.",
        "deprecated": "Consider using the other thing instead."
        "tasks": {...}
    }
}

Defining a Task Assistant

Added in Nova 2.

In many cases, requiring a user to add an instance of a task via a Task Template may be too much overhead. If the task in question is defined by existing files or metadata in the project and can be detected by an extension, a simpler option may be to contribute a Task Assistant.

A Task Assistant is a JavaScript object that is registered with the AssistantRegistry. It allows an extension to dynamically construct and return task objects to be displayed in the IDE interface and invoked by the user.

For more information, see the AssistantRegistry and Task classes.

For tasks that may change over time (such as in response to a user updating a configuration file, or changing configuration values in the extension), an extension may invoke the reloadTasks(identifier) method on the global Workspace object.