Creating forms for the LinkAhead Web Interface

The form_elements module provides a library for generating forms from simple config objects. The forms are styled for the seamless integration into the LinkAhead web interface and are especially useful for calling server side scripts.

See also the API documentation

Examples

Generating a generic form

The following code snippet adds a form to the body of the HTML document.

function my_special_submit_handler (form) {
    // handle form submision
};
const config = {
    name: "my_form",
    fields: [
        { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND Experiment", required: true },
        { type: "integer", name: "number", label: "A Number", required: true },
        { type: "date", name: "date", label: "A Date", required: false },
        { type: "text", name: "comment", label: "A Comment", required: false },
    ],
    submit: my_special_submit_handler
};
const form = form_elements.make_form(config);
$("body").append(form);

The form has four fields:

1. A drop-down menu which contains all Records of type “Experiment” as options,

2. an integer field, labeled “A Number”,

3. a date field, labeled “A Date”, and

4. a text field, labeled “A Comment”.

The first two fields are required and the form cannot be submitted without it. The latter are optional.

On submission, the function my_special_submit_handler is being called with the form element as only parameter.

As the generated form is a plain HTML form, the javascript form API can be used. However, there are special methods in the form_elements module e.g. get_fields which are especially designed to interact with the forms generated by the make_form factory.

Placing the form in a panel below the navbar

There are functions in the form_panel module to make it easy to place forms at the typical location: below the navbar. The following shows how the config (csv_form_config, see above) is passed to init_show_form_panel_button. A direct call to make_form is no longer necessary.

const title = "Upload CSV File"; // title of the form and text in the toolbox
const panel_id = "csv_upload_form_panel";
const accepted_file_formats = [".csv"]
const csv_form_config = {
    fields: [{
        type: "file",
        name: "csvfile",
        label: "Upload CSV file",
        required: true,
        cached: false,
        accept: accepted_file_formats.join(","),
        help: "Select JSON export that you want to upload."
    }],
};

/**
 * Add a button to the navbar, saying "Upload CSV File" which opens a
 * form for file upload.
 */
const init_show_form_panel_button = function () {
    navbar.add_tool(title, tool_box, {
        callback: form_panel.create_show_form_callback(
            panel_id,
            title,
            csv_form_config)
    });
};

const init = function () {
    init_show_form_panel_button();
}

This example also illustrates how you can add a file upload to the form.

Calling a server-side script

If you intend to call a server-side script, the config has to be changed a litte bit: name the script which is to be called in the script field.

const config = {
    script: "process.py",
    fields: [
        { type: "integer", name: "number", label: "A Number", required: true }
    ],
};

On submission, the form data will be send as a json file to the script and passed as the first parameter. The call would look like ./process.py form.json and the file would contain, for example,

{
  "number": "400"
}

Please refer to the server side scripting documentation to learn how to use form data and uploaded files within a server side script.

API Documentation

For more and advanced options for the form see the API documentation