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 :doc:`API documentation <../api/module-form_elements>`

Examples
--------

Generating a generic form
^^^^^^^^^^^^^^^^^^^^^^^^^

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

.. code-block:: 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 e.g. :doc:`get_fields <../api/module-form_elements>` 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.

.. code-block:: 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 litte bit:
name the script which is to be called in the ``script`` field.

.. code-block:: javascript

    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,

.. code-block:: json

    {
      "number": "400"
    }

Please refer to the `server side scripting documentation
<https://docs.indiscale.com//caosdb-server/administration/server_side_scripting.html>`_
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 :doc:`API documentation <../api/module-form_elements>`