Forms guide
This documentation page will be in demand until a form builder is added to HyperPortal.
We can add some custom CSS styles and fonts to brand the appearance of the form. For customization, contact consultants.
The form is formed from the object, which is located in the Portal header — "Templates -> Forms".
This object contains:
- An ID for the form template. The key is required. Installed by the system;
- An object containing data about the form (description and logo). Optional. A logo can exist without a description, as well as a description without a logo.
- Absolute link to the image with the banner;
- Description text. No has limitation on the amount of text. It should be borne in mind that a large volume may look strange (the block will fill the top part of the page and the user will not see the form);
- Absolute link to the image with the logo.
- Max width for form is an optional parameter.
- Specifying the language code.
- Form ID. This field is required, set by the system;
- The key is responsible for the default form language. Read more below (ADD LINK);
- Form title (name). Used only for display in the Portal;
- The key is responsible for the use of the token in the url of the form to identify the user. The key is optional. Its absence is equal to tokenRequired === false.
By structure, the form object has three keys schema , ui and data. We only care about the first two (schema and ui).
There are two localization objects. Form localization (dynamic object, keys based on form schema) and phrase localization (this object).
These phrases are common to all future forms. The list of available phrases will be updated in this documentation (if the developers are not too lazy 😁 )
Key name | Key description |
successMessage | Message for successful form submission. |
submitButtonText | Submit button text |
The lang key allows you to specify the default form language. Default language must refer to the already existing i18n translations. The following text only applies to the form application, in custom projects such as a dealer, the localization logic may differ.
The key is optional. To the form library has been added the logjc to automatically detect the language for the correct display of form data. First of all, the presence of data about the form is checked, and if there is no such data, the fallback language is used, this is either the language that will be passed by the developer into the library component (props - language), or the default language, hardcoded into the application (English). Then, if data for the form is available. the form language is checked (property in the form object - lang) and the list of available localizations into the ui object (ui -> i18n). If this data is not available, the fallback language will also be used (according to the logic described above in this paragraph).
And finally, if all the data is available, and they are correct (and also at each step it is checked that the language is in the list of available languages ui -> i18n), the required language is determined in the following order:
- the interface language passed by the developer into the form component (props - language);
- language specified as form language (form object, key - lang);
- language of the user's browser;
- and in the case of a fallback language, the default application language (English).
Schema is a structured document. It describes the type of form (controls, types, nesting, etc.)
According to the example above: type - group declaration (type object);
required- the names of the required fields are listed here; properties- declaration of controls nested in the group. names of controls - the name of controls in the structure of the form;
UI is a document for the appearance and behavior of controls.
ui:order - array of fields, which sets the display order of controls. The object is NOT required, but not creating it can lead to strange displaying of the order of controls. Fields not listed will appear in random order after those listed. You can also use asterix(*) to specify where to render fields that are not specified.
i18n is the localization object. It is REQUIRED to add (with at least one locale). The structure of the object will be described below.
name of control - the list (the order is not important) indicates the fields to which you need to add properties (not all fields require additional customization).
To localize the form, use the object ui → i18n.
ATTENTION
The object is desirable. but optional. If no translations are specified, the forms will accept the default values (from schema), if they are also absent, then the names of the controls will be added to the titles. It is also worth considering that if the localization object has translations for a control that is not in the form, then blocks will be displayed during rendering, indicating that the controls were not found.
- Defining a localization object;
- Locale declaration;
- The first ui:title after the locale declaration is the title of the form (it will be rendered at the very top of the form);
- The first ui:description after the locale declaration is the form description (will be rendered below the title);
- Name of the control. The name must exactly match the name of the control in the schema.
- ui:title is title for the control. Some controls do not display titles (see below);
- ui:description key to describe the control;
- ui:placeholder key for a hint in the input field. Some controls do not display titles (see below);
- ui:help is the key for the help text.
- Declaration of the type of control;
- Default value. The value must be of the correct type (for a string - a string, for a boolean - a boolean);
- Optional field for custom field validation. The following fields are available:
- email - will add the type email to the field. Will validate the entered value.
- password- will add the type password to the field, thereby hiding the entered value from prying eyes;
- uri- will add the type urito the field, will validate the field for the correctness of the url;
- color - change the type of control to color picker;
- hidden - hide the control from displaying, but leave it in HTML. Doesn't display a title and a placeholder for input. You can set a default value for forwarding information when submitting a form;
- regex - adds validation of the entered value according to the regular expression. For validation to work, you need to add the pattern property. Example - HyperCharge-\\d.
- date - will change the type of control to the calendar;
- date-time - will change the type of control to a calendar with a time;
- Property will create a field with text input and an additional selector with examples of values;
- Validation of the entered value for the minimum string length (applicable only to the string type);
- Validation of the entered value for the maximum string length (applicable only to the string type);
- The property will add the readonly attribute (the field cannot be changed, but can still be selected and on focus outline border will appear);
- The property will add validation for the value as constants (only one value);
- The property will add the disabled attribute (the field cannot be changed, selected and focused);
- Definition of line control as textarea;
- Setting the minimum height of the textarea field. This field is optional.
- Declaration of the type of control. Two values are allowed - number and integer.
- number - all numbers are allowed;
- integer - only integers are allowed.
- Default value. The value must be the same as the type;
- Introduces a restriction on the minimum number (≥);
- Introduces a limit on the maximum number (≤);
- Introduces a restriction on the minimum number, excluding the specified (>);
- Introduces a limit on the maximum number, excluding the specified (<);
- Sets the step size when changing the value with the up/down arrows.
For the slider to work correctly, the scheme needs to be supplemented with a parameter in the ui object.
1. Definition of the type of control; 2. Default value. The value must be the same as the type; 3. Indication of the minimum value of the slider; 4. Indication of the maximum value of the slider; 5. Sets the step size; 6. Specifying the slider widget.
For the slider to work correctly, the scheme needs to be supplemented with a parameter in the ui object.
1. Definition of the type of control; 2. Default value. The value must be the same as the type and in interval from minimum to maximum; 3. Indication of the minimum value of the buttons; 4. Indication of the maximum value of the buttons; 5. Sets the step size is optional parametr, default - 1; 6. Specifying the Range Button widget.
- Definition of the type of control. Strings, numbers and boolean are available (for boolean only Yes/No and these values are set by default);
- Array of available values. Required field for string and number.
- An array of displayed names, the number of elements must match the number of elements in the enum field. This field is optional.
- The name of the control must match the name in the schema;
- Property name to disable specific selector options;
- Array of values to disable. Variants must match the enum key in the control in the schema.
- Array of localized values. You can use follow keywords - enumNames or ui:enumNames. Be careful, the number of values for localization should be the same as specified in the field scheme (point 2). If there are no values for localization or they are less than the values specified in the field scheme (point 2), then the missing values will be taken from the field "enumNames" of the field scheme (point 3), and if they are missing, then from the field "enum" (point 2).
- Definiton of the type of control. Only array is available.
- Required key to enable multiple selector. Works only with the array type;
- Restriction on the minimum number of elements to choose from;
- Restriction on the maximum number of elements to choose from;
- Required key to define a multiple selector;
- Definition of the type of values. Strings and numbers are allowed;
- Array of values must be of the same type from 6 points;
- Array of displayed names, the number of elements must match the number of elements in the enum field. This field is optional;
- The name of the control must match the name in the schema;
- Property name to disable specific selector options;
- Array of values to disable. Variants must match the enum key in the control in the schema.
- Array of localized values. You can use follow keywords - enumNames or ui:enumNames. Be careful, the number of values for localization should be the same as specified in the field scheme (point 7). If there are no values for localization or they are less than the values specified in the field scheme (point 7), then the missing values will be taken from the field "enumNames" of the field scheme (point 8), and if they are missing, then from the field "enum" (point 7).
- Definition of the control type, only boolean is available;
- Definition of the default type. The field is optional.
- Definition of the type of control. Only array is available.
- Required key to enable multiple checkboxes. Works only with the array type;
- Restriction on the minimum number of elements to choose from;
- Restriction on the maximum number of elements to choose from;
- Required key to define multiple checkboxes;
- Definition of the type of values. Strings and numbers are allowed;
- Array of values must be of the same type from 6 points;
- Array of displayed names, the number of elements must match the number of elements in the enum field. This field is optional;
- The name of the control must match the name in the schema;
- Application of the widget multiple checkboxes;
- The key that determines the display of checkbox items. ui:inline=true - inline; ui:inline=false - columns;
- Array of localized values. You can use follow keywords - enumNames or ui:enumNames. Be careful, the number of values for localization should be the same as specified in the field scheme (point 7). If there are no values for localization or they are less than the values specified in the field scheme (point 7), then the missing values will be taken from the field "enumNames" of the field scheme (point 8), and if they are missing, then from the field "enum" (point 7).
Attention!
This custom widget requires required options (links and templateString), and links must be of a specific format. If some options are missed, or the text is not specified for the links, or the value for a link, the widget will throw an exception and the form will crash.
The following describes how to customize this widget. Be attentive and careful!
- Determining the type of controller. Only boolean values are available;
- Defining a custom widget for the Agreements checkbox;
- Optional parameter to show/hide the title of the custom widget (Agreements checkbox);
- Here you can define default field translations (title, help, description);
- Special options for custom Agreement checkbox widget;
- Required option, where you can define links for the checkbox;
- Link key name. The key value must match the key in the template string (at point 10);
- This key is required, means the value for the link (where the user will be sent);
- This key is required, meaning the value for the link text;
- Template string where links from point 6 will be inserted. Places to insert should be circled with a double percent sign (%%).
- Definitionof the type of values. Strings and numbers are allowed;
- Array of values must be of the same type from 2 points;
- An array of displayed names, the number of elements must match the number of elements in the enum field. This field is optional;
- The name of the control must match the name in the schema;
- Application of the radio button widget;
- The key that determines the display of checkbox items. ui:inline=true - inline; ui:inline=false - columns;
- Array of localized values. You can use follow keywords - enumNames or ui:enumNames. Be careful, the number of values for localization should be the same as specified in the field scheme (point 2). If there are no values for localization or they are less than the values specified in the field scheme (point 2), then the missing values will be taken from the field "enumNames" of the field scheme (point 3), and if they are missing, then from the field "enum" (point 2).
- file
- files
- FileWidgetWithPreview
- Definition of the type of control. Only the string is available;
- The name of the control must match the name in the schema;
- Specifying field type "file" or "FileWidgetWithPreview";
- Indication of the list of files available for upload. This field is optional.
- Specifying the type of waiting for multiple downloads of files. Only array is available;
- Required field for specifying multiple downloads of files;
- Definition of the type of control. Only the string is available;
- The name of the control must match the name in the schema;
- Specifying field type "files" or "FileWidgetWithPreview";
- Indication of the list of files available for upload. This field is optional.
This is used to guide users in providing specific images with associated metadata, including positions, labels, and additional options.
The ui property defines the user interface configuration for the form. Defines the custom widget and options for the guided images form.
- Options:
- widget - Configure that use specific widget
- position - An array of objects defining specific positions and their associated labels, overlay images, placeholder images, and position entity IDs.
- guidedImagesDefinitionId - This is a reference to the entityId where images are stored, which is created during the setup of hyper-inspection.
- guidedImages: An array of objects, each representing an image with associated metadata.
- Type - array
- Default: A default value generated using a JSON template string.
- toJson: Represents a custom lambda that converts its argument to a JSON string.
- pick: Custom lambda that selects specific properties from the object passed
- stringify: A custom lambda that converts an object or data structure to a string representation. It is used as an additional for obtaining arrays or objects
- Items: Defines the structure of each item in the array.
- Type - object
- Properties:
- image: The image id or null.
- title: The title of the image.
- entityId: The ID of the entity associated with the image.
- position: The position identifier id.
- isApproved: Approval status of the image.(for new every is null, after change image is also true)
- definitionId: The ID of the definition associated with the image.
- Definition of the type of control. Only the string is available;
- Specifying the control format for the native calendar with time data;
- Ability to disable keyboard input (only clicking on the icon works);
- Possibility to limit the maximum date
- Limit day
- Limit year
- Limit month
- Possibility to limit the minimum date
- Limit day
- Limit year
- Limit month
- Definition of the type of control. Only the string is available;
- Specifying the control format for the native calendar without time data.
- Ability to disable keyboard input (only clicking on the icon works);
- Possibility to limit the maximum date
- Limit day
- Limit year
- Limit month
- Possibility to limit the minimum date
- Limit day
- Limit year
- Limit month
- Definition of the type of control. Only the string is available;
- Specifying the control format for the alternative calendar with time data;
- The name of the control must match the name of the control in the schema;
- Definition of the alternative calendar widget with date and time;
- Specifying the limit of the displayed years (from and to);
- Property for hiding the "Today" date setting button;
- Property for hiding the reset button of the selected date.
- Definition of the type of control. Only the string is available;
- Specifying the control format for the alternative calendar;
- The name of the control must match the name of the control in the schema;
- Definition of the alternative calendar widget with date;
- Specifying the limit of the displayed years (from and to);
- Property for hiding the "Today" date setting button;
- Property for hiding the reset button of the selected date.
This field displays only a title, a description and a help (the control itself will not be added to the HTML). Convenient use for inserting bulky text.
- Indication of the type. Only null is available.