========================= Module: ``form_elements`` ========================= .. contents:: Local Navigation :local: Children ======== .. toctree:: :maxdepth: 1 Description =========== form_elements module for reusable form elemenst which already have a basic css styling. IMPORTANT CONCEPTS - FIELD - an HTMLElement which wraps a LABEL element (the fields name) and the INPUT element together. By default, FIELDS are a flat and stringy list of key-value pairs. Use SUBFORMS for nesting FIELDS. FIELDS come in the following flavours: - INTEGER - DOUBLE - DATE - RANGE - REFERENCE_DROP_DOWN - GROUP - a set of FIELDS and SUBFORMS. FIELDS and SUBFORMS can belong to multiple groups. The group can be used to disable or enable a set of FIELDS or SUBFORMS at once. Therefore, GROUPS are mainly used for the look and feel of the form. However, disabled fields are also ignored in the json-conversion of a form. - SUBFORM - an HTMLElement which contains FIELDS and other SUBFORMS. SUBFORMS can be used to nest FIELDS, which is not supported by HTML5 but allows only for flat key-value pairs. .. _module-form_elements.get_cache_key: Function: ``get_cache_key`` =========================== .. js:function:: get_cache_key() .. _module-form_elements.get_cache_value: Function: ``get_cache_value`` ============================= .. js:function:: get_cache_value() .. _module-form_elements.cache_form: Function: ``cache_form`` ======================== .. js:function:: cache_form() .. _module-form_elements.set_cached: Function: ``set_cached`` ======================== .. js:function:: set_cached() .. _module-form_elements.set_cached_value: Function: ``set_cached_value`` ============================== .. js:function:: set_cached_value() .. _module-form_elements.is_set: Function: ``is_set`` ==================== .. js:function:: is_set() .. _module-form_elements.load_cached: Function: ``load_cached`` ========================= .. js:function:: load_cached() .. _module-form_elements._get_alert_decision: Function: ``_get_alert_decision`` ================================= .. js:function:: _get_alert_decision() .. _module-form_elements._set_alert_decision: Function: ``_set_alert_decision`` ================================= .. js:function:: _set_alert_decision() .. _module-form_elements.make_alert: Function: ``make_alert`` ======================== Make an alert, that is a dialog which can intercept a function call and asks the user to proceed or cancel. .. js:function:: make_alert(config) :param AlertConfig config: Make an alert, that is a dialog which can intercept a function call and asks the user to proceed or cancel. :return HTMLElement: Make an alert, that is a dialog which can intercept a function call and asks the user to proceed or cancel. .. _module-form_elements.init: Function: ``init`` ================== .. js:function:: init() .. _module-form_elements.make_reference_option: Function: ``make_reference_option`` =================================== Return an OPTION element with entity reference. The OPTION element for a SELECT form input shows a short summary/description of an entity and has the entity's id as value. If the `desc` parameter is undefined, the entity_id is shown instead. .. js:function:: make_reference_option(entity_id[, desc]) :param string entity_id: the entity's id. :param string desc: the description for the entity. :return HTMLElement: OPTION element. .. _module-form_elements._make_option: Function: ``_make_option`` ========================== Return an `option` element for a `select`. .. js:function:: _make_option(value, label) :param string value: the actual value of the option element. :param string label: the string which is shown for this option in the drop-down menu of the select input. :return HTMLElement: Return an `option` element for a `select`. .. _module-form_elements._init_functions: Function: ``_init_functions`` ============================= (Re-)set this module's functions to standard implementation. .. js:function:: _init_functions() .. _module-form_elements.parse_script_result: Function: ``parse_script_result`` ================================= Convert the reponse of a server-side scripting call into a {@link ScriptingResult} object. .. js:function:: parse_script_result(result) :param XMLDocument result: Convert the reponse of a server-side scripting call into a {@link ScriptingResult} object. :return ScriptingResult: Convert the reponse of a server-side scripting call into a {@link ScriptingResult} object. .. _module-form_elements.make_reference_drop_down: Function: ``make_reference_drop_down`` ====================================== Search and retrieve entities and create a SELECT from element. .. js:function:: make_reference_drop_down(config) :param ReferenceDropDownConfig config: all necessary parameters for the configuration. :return HTMLElement: SELECT element. .. _module-form_elements.init_select_picker: Function: ``init_select_picker`` ================================ Test 16 .. js:function:: init_select_picker() .. _module-form_elements.init_actions_box: Function: ``init_actions_box`` ============================== Test 17 .. js:function:: init_actions_box() .. _module-form_elements.field_ready: Function: ``field_ready`` ========================= Return a promise which resolves with the field when the field is ready. This function is especially useful if the caller can not be sure if the field_ready_event has been dispatched already and the field is ready or if the fields creation is still pending. .. js:function:: field_ready(field) :param HTMLElement field: Return a promise which resolves with the field when the field is ready. This function is especially useful if the caller can not be sure if the field_ready_event has been dispatched already and the field is ready or if the fields creation is still pending. :return Promise: the field-ready promise .. _module-form_elements.form_to_object: Function: ``form_to_object`` ============================ Generate a java script object representation of a form and extract the files from the form. The property names (aka keys) are the names of the form fields and subforms. The values are single strings or arrays of strings. If the field was had a file-type input, the value is a string identifying the file blob which belongs to this key. Subforms lead to nested objects of the same structure. .. js:function:: form_to_object(form) :param HTMLElement form: a form generated by this module. :return Array.: - an array of length 2. The first element is an object representing the fields of the form. The second contains a list of file blobs resulting from file inputs in the form. .. _module-form_elements.make_submit_button: Function: ``make_submit_button`` ================================ .. js:function:: make_submit_button() .. _module-form_elements.make_cancel_button: Function: ``make_cancel_button`` ================================ .. js:function:: make_cancel_button() .. _module-form_elements.make_form_field: Function: ``make_form_field`` ============================= Return a new form field (or a subform). This function is intended to be called by make_form and recursively by other make_* functions which create subforms or other deeper structured form fields. This function also configures the caching, whether a form field is 'required' or not, and the help for each field. .. js:function:: make_form_field(config) :param FieldConfig config: the configuration of the form field :return HTMLElement: Return a new form field (or a subform). This function is intended to be called by make_form and recursively by other make_* functions which create subforms or other deeper structured form fields. This function also configures the caching, whether a form field is 'required' or not, and the help for each field. .. _module-form_elements.add_help: Function: ``add_help`` ====================== .. js:function:: add_help() .. _module-form_elements.make_heading: Function: ``make_heading`` ========================== .. js:function:: make_heading() .. _module-form_elements.make_form_wrapper: Function: ``make_form_wrapper`` =============================== .. js:function:: make_form_wrapper() .. _module-form_elements.make_form: Function: ``make_form`` ======================= Create a form. The returned element is a container which contains a HTML form element. The fields are ready or they will emit a {@link field_ready_event} when they are. .. js:function:: make_form(config) :param FormConfig config: Create a form. The returned element is a container which contains a HTML form element. The fields are ready or they will emit a {@link field_ready_event} when they are. :return HTMLElement: Create a form. The returned element is a container which contains a HTML form element. The fields are ready or they will emit a {@link field_ready_event} when they are. .. _module-form_elements.make_subform: Function: ``make_subform`` ========================== Return a new subform. .. js:function:: make_subform(config) :param SubFormConfig config: the configuration of the subform. :return HTMLElement: Return a new subform. .. _module-form_elements.dismiss_form: Function: ``dismiss_form`` ========================== .. js:function:: dismiss_form() .. _module-form_elements.enable_group: Function: ``enable_group`` ========================== .. js:function:: enable_group() .. _module-form_elements.disable_group: Function: ``disable_group`` =========================== .. js:function:: disable_group() .. _module-form_elements.get_group_fields: Function: ``get_group_fields`` ============================== .. js:function:: get_group_fields() .. _module-form_elements.get_fields: Function: ``get_fields`` ======================== Return an array of field with name .. js:function:: get_fields(name) :param string name: the field name :return Array.: array of fields .. _module-form_elements.add_field_to_group: Function: ``add_field_to_group`` ================================ .. js:function:: add_field_to_group() .. _module-form_elements.disable_fields: Function: ``disable_fields`` ============================ .. js:function:: disable_fields() .. _module-form_elements.enable_fields: Function: ``enable_fields`` =========================== .. js:function:: enable_fields() .. _module-form_elements.enable_name: Function: ``enable_name`` ========================= .. js:function:: enable_name() .. _module-form_elements.disable_name: Function: ``disable_name`` ========================== .. js:function:: disable_name() .. _module-form_elements.make_script_form: Function: ``make_script_form`` ============================== .. js:function:: make_script_form() .. _module-form_elements.make_generic_form: Function: ``make_generic_form`` =============================== Return a generic form, bind the config.submit to the submit event of the form. The `config.fields` array may contain `form_elements.field_config` objects or HTMLElements. .. js:function:: make_generic_form() :return HTMLElement: Return a generic form, bind the config.submit to the submit event of the form. The `config.fields` array may contain `form_elements.field_config` objects or HTMLElements. .. _module-form_elements.init_form_caching: Function: ``init_form_caching`` =============================== .. js:function:: init_form_caching() .. _module-form_elements.show_results: Function: ``show_results`` ========================== .. js:function:: show_results() .. _module-form_elements.show_errors: Function: ``show_errors`` ========================= .. js:function:: show_errors() .. _module-form_elements.make_footer: Function: ``make_footer`` ========================= .. js:function:: make_footer() .. _module-form_elements.make_error_message: Function: ``make_error_message`` ================================ .. js:function:: make_error_message() .. _module-form_elements.make_success_message: Function: ``make_success_message`` ================================== .. js:function:: make_success_message() .. _module-form_elements.make_submitting_info: Function: ``make_submitting_info`` ================================== .. js:function:: make_submitting_info() .. _module-form_elements.make_message: Function: ``make_message`` ========================== .. js:function:: make_message() .. _module-form_elements.make_range_input: Function: ``make_range_input`` ============================== Return a new form field representing a range of numbers. .. js:function:: make_range_input(config) :param RangeFieldConfig config: Return a new form field representing a range of numbers. :return HTMLElement: Return a new form field representing a range of numbers. .. _module-form_elements._make_field_wrapper: Function: ``_make_field_wrapper`` ================================= Return a DIV with class `caosdb-f-field` and a data attribute `data-field-name` which contains the name. The DIV is used to wrap LABEL and INPUT elements of a form together. .. js:function:: _make_field_wrapper(name) :param string name: the name of the field. :return HTMLElement: a DIV. .. _module-form_elements.make_date_input: Function: ``make_date_input`` ============================= Return a new date field. .. js:function:: make_date_input(config) :param FieldConfig config: Return a new date field. :return HTMLElement: Return a new date field. .. _module-form_elements.make_text_input: Function: ``make_text_input`` ============================= Return a new text field. .. js:function:: make_text_input(config) :param TextFieldConfig config: Return a new text field. :return HTMLElement: Return a new text field. .. _module-form_elements.make_double_input: Function: ``make_double_input`` =============================== Return an input field which accepts double values. `config.type` is set to "number" and overrides any other type. .. js:function:: make_double_input(config.) :param FieldConfig config.: Return an input field which accepts double values. `config.type` is set to "number" and overrides any other type. :return HTMLElement: a double form field. .. _module-form_elements.make_integer_input: Function: ``make_integer_input`` ================================ Return an input field which accepts integers. `config.type` is set to "number" and overrides any other type. .. js:function:: make_integer_input(config.) :param FieldConfig config.: Return an input field which accepts integers. `config.type` is set to "number" and overrides any other type. :return HTMLElement: an integer form field. .. _module-form_elements.make_file_input: Function: ``make_file_input`` ============================= Return a new form field for a file upload. .. js:function:: make_file_input(config) :param FileFieldConfig config: configuration for this form field. :return HTMLElement: Return a new form field for a file upload. .. _module-form_elements.make_select_input: Function: ``make_select_input`` =============================== Return a select field. IMPORTANT: The select picker has to be initialized by the client by calling ``form_elements.init_select_picker(ret, config.value)`` (see below and https://gitlab.com/linkahead/linkahead-webui/-/issues/208). .. js:function:: make_select_input(config) :param SelectFieldConfig config: Return a select field. IMPORTANT: The select picker has to be initialized by the client by calling ``form_elements.init_select_picker(ret, config.value)`` (see below and https://gitlab.com/linkahead/linkahead-webui/-/issues/208). :return HTMLElement: a select field. .. _module-form_elements.make_checkbox_input: Function: ``make_checkbox_input`` ================================= Return a checkbox input field. .. js:function:: make_checkbox_input(config.) :param form_elements.checkbox_config config.: Return a checkbox input field. :return HTMLElement: a checkbox form field. .. _module-form_elements.set_required: Function: ``set_required`` ========================== Add `caosdb-f-form-field-required` class to form field. .. js:function:: set_required(field) :param HTMLElement field: the required form field. .. _module-form_elements.make_required_marker: Function: ``make_required_marker`` ================================== Return a span which is to be inserted before a field's label text and which marks that field as required. .. js:function:: make_required_marker() :return HTMLElement: span element. .. _module-form_elements.get_enabled_required_fields: Function: ``get_enabled_required_fields`` ========================================= .. js:function:: get_enabled_required_fields() .. _module-form_elements.get_enabled_fields: Function: ``get_enabled_fields`` ================================ .. js:function:: get_enabled_fields() .. _module-form_elements.check_form_validity: Function: ``check_form_validity`` ================================= Check form validity and return if the form is valid. .. js:function:: check_form_validity(form) :param HTMLElement form: the form elemeng. :return boolean: true iff the form is valid. .. _module-form_elements.all_required_fields_set: Function: ``all_required_fields_set`` ===================================== .. js:function:: all_required_fields_set() .. _module-form_elements.is_valid: Function: ``is_valid`` ====================== .. js:function:: is_valid(form) :param HTMLElement form: the form be validated. .. _module-form_elements.toggle_submit_button_form_valid: Function: ``toggle_submit_button_form_valid`` ============================================= .. js:function:: toggle_submit_button_form_valid() .. _module-form_elements.init_validator: Function: ``init_validator`` ============================ .. js:function:: init_validator() .. _module-form_elements.make_form_modal: Function: ``make_form_modal`` ============================= Return a modal HTML element containing the given form. .. js:function:: make_form_modal(form, title, explanationText) :param HTMLElement form: the form to be shown in the modal :param string title: the title of the form modal :param string explanationText: An optional paragraph shown between modal title and form. .. _module-form_elements.make_scripting_submission_button: Function: ``make_scripting_submission_button`` ============================================== Return a submission button that triggers a given server-side-script. .. js:function:: make_scripting_submission_button(script, buttonName) :param string script: Name of the server-side script to be triggered :param string buttonName: Display name of the submission button .. _module-form_elements._make_input: Function: ``_make_input`` ========================= Return an input and a label, wrapped in a div with class `caosdb-f-field`. .. js:function:: _make_input(config, input) :param object config: config object with `name`, `type` and optional `label` :param string input: optional specification of the HTML input element. `` is used as default where `name` and `type` stem from the config object. :return HTMLElement: a form field. .. _module-form_elements._make_input_label_str: Function: ``_make_input_label_str`` =================================== Return a string representation of a LABEL element, ready for parsing. This function is used by other functions to generate a LABEL element. The config's `name` goes to the `for` attribute, the `label` is the text node of the resulting LABEL element. .. js:function:: _make_input_label_str(config) :param object config: a config object with `name` and `label`. :return string: a html string for a LABEL element. .. _module-form_elements.version: Member: ``version``: .. _module-form_elements.dependencies: Member: ``dependencies``: .. _module-form_elements.logger: Member: ``logger``: .. _module-form_elements.cancel_form_event: Member: ``cancel_form_event``: Event. On form cancel. .. _module-form_elements.submit_form_event: Member: ``submit_form_event``: Event. On form submit. .. _module-form_elements.field_changed_event: Member: ``field_changed_event``: Event. On field change. .. _module-form_elements.field_enabled_event: Member: ``field_enabled_event``: Event. On field enabled. .. _module-form_elements.field_disabled_event: Member: ``field_disabled_event``: Event. On field disabled. .. _module-form_elements.field_ready_event: Member: ``field_ready_event``: Event. On field ready (e.g. for reference drop downs) .. _module-form_elements.field_error_event: Member: ``field_error_event``: Event. On field error (e.g. for reference drop downs) .. _module-form_elements.form_success_event: Member: ``form_success_event``: Event. Form submitted successfully. .. _module-form_elements.form_error_event: Member: ``form_error_event``: Event. Error after form was submitted. .. _module-form_elements.cache[undefined]: Member: ``cache[undefined]``: .. _module-form_elements.localStorage[undefined]: Member: ``localStorage[undefined]``: .. _module-form_elements.checkbox: Member: ``checkbox``: .. _module-form_elements.desc: Member: ``desc``: .. _module-form_elements.type: Member: ``type``: .. _module-form_elements.actions_box: Member: ``actions_box``: .. _module-form_elements.data[undefined]: Member: ``data[undefined]``: .. _module-form_elements.data[undefined]: Member: ``data[undefined]``: .. _module-form_elements.value: Member: ``value``: .. _module-form_elements.data[undefined]: Member: ``data[undefined]``: .. _module-form_elements.data[undefined]: Member: ``data[undefined]``: .. _module-form_elements.fieldname: Member: ``fieldname``: .. _module-form_elements.filename: Member: ``filename``: .. _module-form_elements.blob: Member: ``blob``: .. _module-form_elements.data[undefined]: Member: ``data[undefined]``: .. _module-form_elements.data[undefined]: Member: ``data[undefined]``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.field: Member: ``field``: .. _module-form_elements.cursor: Member: ``cursor``: .. _module-form_elements."margin-left": Member: ``"margin-left"``: .. _module-form_elements.form: Member: ``form``: .. _module-form_elements.form: Member: ``form``: .. _module-form_elements.form: Member: ``form``: .. _module-form_elements.name: Member: ``name``: .. _module-form_elements.submit: Member: ``submit``: .. _module-form_elements.margin: Member: ``margin``: .. _module-form_elements.cached: Member: ``cached``: .. _module-form_elements.required: Member: ``required``: .. _module-form_elements.type: Member: ``type``: .. _module-form_elements.cached: Member: ``cached``: .. _module-form_elements.required: Member: ``required``: .. _module-form_elements.type: Member: ``type``: .. _module-form_elements.type: Member: ``type``: .. _module-form_elements.display: Member: ``display``: .. _module-form_elements.type: Member: ``type``: .. _module-form_elements.AlertConfig: Typedef: ``AlertConfig`` ======================== Config for an alert Properties ---------- - ``string title``: an optional title for the alert. - ``string severity``: a bootstrap class suffix. Other examples: warning, info - ``string message``: informs the user what they are about to do. - ``function proceed_callback``: the function which is called then the user hits the "Proceed" button. - ``function cancel_callback``: a callback which is called then the cancel button is clicked. By default, only the alert is being closed an nothing happens. - ``string proceed_text``: the text on the proceed button. - ``string cancel_text``: the text on the cancel button. - ``string remember_my_decision_id``: if this parameter is present, a checkbox is appended to the alert ("Don't ask me again."). If the checkbox is checked the next time the make_alert function is called with the same remember_my_decision_id is created, the alert won't show up and the proceed_callback is called without any user interaction. - ``string remember_my_decision_text``: label text for the checkbox. - ``HTMLElement proceed_button``: an optional custom proceed button. - ``HTMLElement cancel_button``: an optional custom cancel button. .. _module-form_elements.FieldConfig: Typedef: ``FieldConfig`` ======================== The configuration for double, integer, date input elements. There are several specializations of this configuration object. {@link ReferenceDropDownConfig}, {@link RangeFieldConfig}, {@link SelectFieldConfig}, {@link FileFieldConfig} Properties ---------- - ``string name``: The configuration for double, integer, date input elements. There are several specializations of this configuration object. {@link ReferenceDropDownConfig}, {@link RangeFieldConfig}, {@link SelectFieldConfig}, {@link FileFieldConfig} - ``string type``: The configuration for double, integer, date input elements. There are several specializations of this configuration object. {@link ReferenceDropDownConfig}, {@link RangeFieldConfig}, {@link SelectFieldConfig}, {@link FileFieldConfig} - ``string label``: The configuration for double, integer, date input elements. There are several specializations of this configuration object. {@link ReferenceDropDownConfig}, {@link RangeFieldConfig}, {@link SelectFieldConfig}, {@link FileFieldConfig} - ``string help``: The configuration for double, integer, date input elements. There are several specializations of this configuration object. {@link ReferenceDropDownConfig}, {@link RangeFieldConfig}, {@link SelectFieldConfig}, {@link FileFieldConfig} - ``boolean required``: The configuration for double, integer, date input elements. There are several specializations of this configuration object. {@link ReferenceDropDownConfig}, {@link RangeFieldConfig}, {@link SelectFieldConfig}, {@link FileFieldConfig} - ``boolean cached``: The configuration for double, integer, date input elements. There are several specializations of this configuration object. {@link ReferenceDropDownConfig}, {@link RangeFieldConfig}, {@link SelectFieldConfig}, {@link FileFieldConfig} .. _module-form_elements.ReferenceDropDownConfig: Typedef: ``ReferenceDropDownConfig`` ==================================== Configuration object for a drop down menu for selecting references. `make_reference_drop_down` generates such a drop down menu using a SELECT input with the references as its OPTION elements. The `query` parameter contains a query which is executed. The resulting entities are used to generate the OPTIONs. The OPTIONs' values are generated by the `make_value` call-back function from the entities. If `make_value` is undefined the entities' ids are used as values. The description which is generated by a `make_desc` call-back function. If `make_desc` is undefined, the ids are shown instead. The generated HTMLElements also contain a LABEL tag showing the text defined by `label`. If the `label` property is undefined, the `name` is shown instead. Properties ---------- - ``string name``: The name of the select input. - ``string query``: Query for entities. - ``function make_value``: Call-back for the generation of the OPTIONs' values from the entities. - ``function make_desc``: Call-back for the generation of the OPTIONs' description from the entities. - ``boolean multiple``: Whether it is possible to select multiple options at once. - ``string value``: Pre-selected value of the SELECT. - ``string label``: LABEL text. - ``string type``: This should be "reference_drop_down" or undefined. This property is used by `make_form_field` to decide which type of field is to be generated. .. _module-form_elements.ScriptingResult: Typedef: ``ScriptingResult`` ============================ Properties ---------- - ``string code``: - ``string call``: - ``string stdout``: - ``string stderr``: .. _module-form_elements.FormConfig: Typedef: ``FormConfig`` ======================= Configuration objects which are passed to {@link make_form}. Note: either the `script` or the `name` property must be defined. If the former is defined, the latter will be overriden. Properties ---------- - ``Array. fields``: array of fields. The order is the order in which they appear in the resulting form. - ``string script``: if present the form will call a server-side script on submission. - ``string name``: The name of the form. This is being overridden by the `script` parameter if present. - ``function submit``: a callback which handles the submission of the form. This parameter is being overridden if the `script` parameter is present. .. _module-form_elements.SubFormConfig: Typedef: ``SubFormConfig`` ========================== Properties ---------- - ``Array. fields``: array of fields. The order is the order in which they appear in the resulting subform. .. _module-form_elements.RangeFieldConfig: Typedef: ``RangeFieldConfig`` ============================= Properties ---------- - ``FieldConfig from``: the start point of the range. This is usually an integer or double input field. - ``object {FieldConfig``: to - the end point of the range. This is usually an integer or a double input field. .. _module-form_elements.TextFieldConfig: Typedef: ``TextFieldConfig`` ============================ Field config for a text field (config.type = 'text'). Properties ---------- - ``string pattern``: a regex pattern which validates the value of the text field. .. _module-form_elements.FileFieldConfig: Typedef: ``FileFieldConfig`` ============================ Properties ---------- - ``boolean multiple``: whether to accept multiple files. - ``string accept``: a comma separated list of file extensions which are accepted (exclusively). .. _module-form_elements.SelectOptionConfig: Typedef: ``SelectOptionConfig`` =============================== Properties ---------- - ``string value``: the value of the select option. - ``string label``: a visible representation (think: description) of the value of the select option. defaults to the value itself. .. _module-form_elements.SelectFieldConfig: Typedef: ``SelectFieldConfig`` ============================== Properties ---------- - ``SelectOptionConfig SelectFieldConfig``: options