Tags: how-to

Creating forms for the LinkAhead Web Interface#

Note

This page has been migrated from the old documentation, and has not yet been fully revised. There might be inconsistencies or errors when using with current LinkAhead versions.

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, such as get_fields, which are 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 little 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 sent 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