---
last_review: "2025-01-01"
last_reviewer: "-"
documented_code: [ ]
---

```{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.
:::
% TODO: Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/94
% TODO: Split into explanation and how-to? Or rewrite?, a Dev tutorial might make sense

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](/reference/webui/api/module-form_elements.rst)

## Examples

### Generating a generic form

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

```javascript
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](/reference/webui/api/module-form_elements.rst), 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.

```javascript
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.

```javascript
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,

```json
{
  "number": "400"
}
```

Please refer to the [server side scripting documentation](/tutorial/scripting/server_side_scripting/server_side_scripting.md)
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](/reference/webui/api/module-form_elements.rst)