DevGuide Cells

Getting Started

Cell types are managed by the Vizier API layer. The only situation in which the UI layer needs to be modified is when adding new input node types. Broadly, cells are defined through two components:

• Package: A specification of the front-end interface for a set of related cells
• Processor: A specification of the back-end implementation of how the cell is implemented. Vizier's default packages and processors are defined in webapi-async/resources/packages and webapi-async/resources/packages.

The vizier command-line utility loads package definitions from the colon-separated (:) path in the environment variable VIZIERSERVER_PACKAGE_PATH

The vizier command-line utility loads processor definitions from the path in the environment variable VIZIERSERVER_PROCESSOR_PATH

Defining a Package

Packages are defined through JSON files with the suffix .pckg.json. The file should parse as a JSON object with one field per package defined. For example, the Markdown package defines a single package (markdown) with a single cell type (Markdown Code).

A package definition is a JSON object consisting of three fields:

• commands: A JSON array of command objects (as defined below)
• id: A unique package identifier (a string)
• category: A grouping identifier (e.g., 'visualization' or 'code') that dictates how commands are displayed in the Vizier API. Packages with identical categories will be displayed together.

A command definition is a JSON object consisting of four fields:

• format: Rules for defining a concise string representation of the specified cell that is displayed when the cell is collapsed. These should be specified as an JSON array of format objects.
• id: A package-unique command identifier (a string)
• name: The human-readable name of the cell type
• parameter: Rules for taking cell configuration for the cell. The resulting fields are displayed when the cell is expanded. These should be specified as a JSON array of parameter objects.

format Objects

A format object specifies how to render a piece of data in the cell, and used primarily to display the "collapsed" representation of a cell. There are three required fields:

• lspace: A boolean that indicates whether to render the cell with a space separating it from the field to its left.
• rspace: A boolean that indicates whether to render the cell with a space separating it from the field to its right.
• type: The type of the format. See below for available types and their parameters.
  • const: A constant string
    • value: The value to display
  • var: A variable provided by the cell
    • value: The identifier of the variable to display here. See the parameter objects. Rendering rules are defined by the type of the corresponding parameter.

parameter Objects

A parameter object specifies a parameter for the cell, including type information and data entry details. There are six required fields:

• id: A unique identifier of the variable that this parameter configures
• name: The human-readable name describing this parameter
• index: An integer denoting the position of this parameter in the display???
• hidden: True if this parameter should be hidden from the user
• required: True if this parameter requires a value
• datatype: The type of parameter. One of the following:
  • dataset: Pop-up menu to select one dataset. No additional fields required.
  • colid: Pop-up menu to select one column. [[Defaults to selecting columns from the first dataset parameter in the cell???]]
  • rowid: A row identifier.
  • bool: A checkbox.
  • decimal: A decimal number
  • string: Free text entry parameter. No additional fields required. Optionally, to create a pop-up list add a values field that's an array of objects with the following fields:
    • isDefault: true if this should be the default for the pop-up. false otherwise.
    • text: The text to display for this option.
    • value: The value to use for the parameter if this option is selected.
  • fileid: A file picker (specify by URL or Upload).
  • list: A variable-length list of replicated parameters. To define the sub-parameters of each "row" of the list, add a parent field to each sub-parameter with the id of the list parameter.
  • record: A block used to define a JSON object. To define the sub-parameters of the record, add a parent field to each sub-parameter with the id of the record parameter.
  • code: A code entry block. Requires a language field set to sql, python, scala, or markdown

Defining a Processor

A processor definition is a YAML file with the suffix *.yaml that declares code for processing cells from one or more packages. For example, see pycell.yaml. Required fields include:

• packages: An array of strings defining a list of package names implemented by this processor.
• engine: A record with the fields:
  • className: The name of the class implementing the processor.
  • moduleName: The name of the module in which the processor class resides.

The processor class should be a subclass of vizier.engine.task.processor.TaskProcessor. For examples, see the PyCellTaskProcessor. A processor class must implement a single function:

    def execute_script(self, args, context):
        """Execute a single cell
        Parameters
        ----------
        args: vizier.viztrail.command.ModuleArguments
            User-provided command arguments
        context: vizier.engine.task.base.TaskContext
            Context in which a task is being executed
        Returns
        -------
        vizier.engine.task.processor.ExecResult
        """