---
title: Forms guide
slug: forms-guide
docTags:
createdAt: 2021-06-04T08:55:30.000Z
---
This documentation page will be in demand until a form builder is added to HyperPortal.
***
# Branding settings
We can add some custom **CSS styles **and **fonts **to brand the appearance of the form. **For customization, contact consultants.**
# Form Object
The form is formed from the object, which is located in the Portal header — `"Templates -> Forms".`
This object contains:
```json
{
"definitionId": "test", // 1
"form": { // 2
"ui": { ... },
"data": { ... },
"schema": { ... }
},
"head": { // 3
"banner": "Absolute URL to image", // 3.1
"description": "Description text", // 3.2
"logo": "Absolute URL to image" // 3.3
"formMaxWidth": 700, // 3.4
},
"i18n": { // 4
"en": {...} // 4.1
},
"id": "test_id", // 5
"lang": "en", // 6
"title": "Test form title", // 7
"tokenRequired": true // 8
}
```
1. An ID for the form template. The key is **required**. Installed by the **system;**
2. An object containing the [schema](https://app.archbee.io/docs/ffeACTZ47_Cw3ctxvLLBM/MpFuSbYrh2Vv-5tJdaVie#nt-schema), [UI ](https://app.archbee.io/docs/ffeACTZ47_Cw3ctxvLLBM/MpFuSbYrh2Vv-5tJdaVie#3k-ui)and default data for the form. Read more below;
3. 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.
1. Absolute link to the image with the banner;
2. *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);
3. Absolute link to the image with the logo.
4. Max width for form is an optional parameter.
4. [Localization ](https://app.archbee.io/docs/ffeACTZ47_Cw3ctxvLLBM/MpFuSbYrh2Vv-5tJdaVie#3d-localization-of-phrases)object. NOT TO BE CONFUSED WITH FORM LOCALIZATION. Read more below;
1. Specifying the language code.
5. Form ID. This field is **required**, set by the **system;**
6. The key is responsible for the default form language. Read more below (**ADD LINK**);
7. Form title (name). Used **only** for display in the Portal;
8. 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`).
***
# Localization of phrases
There are two localization objects. [Form localization](https://app.archbee.io/docs/ffeACTZ47_Cw3ctxvLLBM/MpFuSbYrh2Vv-5tJdaVie#l3-form-schema-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 |
***
# Form language
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 logic 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:
1. the interface language passed by the developer into the form component (props - `language`);
2. language specified as form language (form object, key - `lang`);
3. language of the user's browser;
4. and in the case of a fallback language, the default application language (English).
***
# Schema
`Schema `is a structured document. It describes the type of form (controls, types, nesting, etc.)
```json
{
"schema": {
"type": "object",
"required": [
"validations__required_control"
],
"properties": {
"string_controls__single_string": {
"type": "string"
},
"number_controls__integer_range_steps": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"multipleOf": 10,
"default": 0
}
}
}
}
```
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
`UI` is a document for the appearance and behavior of controls.
```json
{
"ui": {
"ui:order": [
"radioButtons",
"*",
"firstName"
],
"radioButtons": {
"ui:widget": "radio",
"ui:options": {
...
}
},
"i18n": {
"en": {
...
},
"nl": {
...
},
}
}
}
```
`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).
***
# Form schema localization
To localize the form, use the object `ui` →` i18n.`
:::hint{type="warning"}
## 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.
:::
```json
{
"schema": {
// ... schema definition
},
"ui": {
"i18n": { // 1
"en": { // 2
"ui:title": "Form title", // 3
"ui:description": "Form description", // 4
"string_controls__single_string": { // 5
"ui:title": "Single string field", // 6
"ui:description": "Description of single string field", // 7
"ui:placeholder": "Placeholder of single string field", // 8
"ui:help": "Help of single string field" // 9
},
// ... next control
}
// ... next locale
}
}
}
```
1. Defining a localization object;
2. Locale declaration;
3. 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);
4. The first `ui:description` after the locale declaration is the form description (will be rendered below the title);
5. Name of the control. The name must exactly match the name of the control in the schema.
6. `ui:title` is title for the control.
Some controls do not display titles (see below);
7. `ui:description` key to describe the control;
8. `ui:placeholder` key for a hint in the input field. Some controls do not display titles (see below);
9. `ui:help` is the key for the help text.
***
# Controls
## Conditional Fields
This functionality allows the field(s) to be displayed only when certain custom conditions are met. The condition always works using the ‘IS’ logic:
If \[propertyId] value IS \[expectedValue] ,then the specified fields are shown.
```json
{
"type": "object",
"properties": {
"clientType": {
"enum": [
"Personal",
"Buisness"
]
}
},
"allOf": [
{
"if": {
"properties": {
"clientType": {
"const": "Personal"
}
}
},
"then": {
"properties": {
"firstName": {
"type": "string",
"title": "First Name"
}
},
"required": [
"firstName"
]
}
},
{
"if": {
"properties": {
"clientType": {
"const": "Buisness"
}
}
},
"then": {
"properties": {
"companyName": {
"type": "string",
"title": "Company Name"
},
"companySize": {
"type": "string",
"enum": [
"1-10",
"11-50",
"50+"
]
}
},
"required": [
"companyName",
"companySize"
]
}
},
{
"required": [
"clientType"
]
}
]
}
```
1. It specifies in the ‘allOf’ section at the schema level
2. The property from which the data for the condition will be taken must exist in the schema
3. Each element in the ‘allOf’ array consists of the ‘if’ and ‘then’ objects
4. Inside the ‘if’, specify the propertyId whose value must be compared. Inside the ‘const’, specify the expected value for the condition to be successfully executed
5. Inside the ‘then’, specify which properties should be drawn if the condition is met, and also which of them should be required
## String controls
```json
{
"stringControl": {
"type": "string", // 1
"default": "default value", // 2
"format": "uri" // 3
"examples": [ // 4
"Example 1",
"Example 2",
"Example 3"
],
"minLength": 5, // 5
"maxLength": 5, // 6
"readOnly": true, // 7
"const": "3.14" // 8
}
}
```
```json
{
"ui": {
"stringControl": {
"ui:disabled": "true" // 9
}
}
}
```
1. Declaration of the type of control;
2. Default value. The value must be of the correct type (for a string - a string, for a boolean - a boolean);
3. Optional field for custom field validation.
The following fields are available:
1. `email` - will add the type `email` to the field. Will validate the entered value.`
`
2. `password`- will add the type `password `to the field, thereby hiding the entered value from prying eyes;
3. `uri`- will add the type `uri`to the field, will validate the field for the correctness of the url;
4. `color` - change the type of control to color picker;
5. `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;
6. `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`.
7. `date` - will change the type of control to the calendar;
8. `date-time` - will change the type of control to a calendar with a time;
4. Property will create a field with text input and an additional selector with examples of values;
5. Validation of the entered value for the `minimum `string length (applicable only to the `string` type);
6. Validation of the entered value for the `maximum `string length (applicable only to the `string` type);
7. The property will add the `readonly `attribute (the field cannot be changed, but can still be selected and on focus outline border will appear);
8. The property will add validation for the value as `constants `(only one value);
9. The property will add the `disabled `attribute (the field cannot be changed, selected and focused);
### Textarea
```json
{
"ui": {
"stringControlName": {
"ui:widget": "textarea", // 1
"ui:rows": 10 // 2
}
}
}
```
1. Definition of line control as `textarea`;
2. Setting the minimum height of the textarea field. This field is optional.
***
## Numeric controls
```json
{
"numberControlName": {
"type": "number", // 1
"default": 15, // 2
"minimum": 5, // 3
"maximum": 5, // 4
"exclusiveMinimum": 5, // 5
"exclusiveMaximum": 5, // 6
"multipleOf": 0.01 // 7
}
}
```
1. Declaration of the type of control.
Two values are allowed - `number` and `integer`.
1. `number` - all numbers are allowed;
2. `integer` - only integers are allowed.
2.
Default value. The value must be the same as the type;
3. Introduces a restriction on the minimum number `(≥);`
4. Introduces a limit on the maximum number `(≤);`
5. Introduces a restriction on the minimum number, excluding the specified `(>);`
6. Introduces a limit on the maximum number, excluding the specified `(<);`
7. Sets the step size when changing the value with the `up/down` arrows.
### Range
For the slider to work correctly, the scheme needs to be supplemented with a parameter in the `ui` object.
```json
{
"rangeControlName": {
"type": "number", // 1
"default": 0, // 2
"minimum": 5, // 3
"maximum": 5, // 4
"multipleOf": 0.01 // 5
}
}
```
```json
{
"ui": {
"rangeControlName": {
"ui:widget": "range" // 6
}
}
}
```
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.
### RangeButton
For the slider to work correctly, the scheme needs to be supplemented with a parameter in the `ui` object.
```json
{
"rangeControlName": {
"type": "number", // 1
"default": 9, // 2
"minimum": 1, // 3
"maximum": 10, // 4
"multipleOf": 1 // 5
}
}
```
```javascript
{
"ui": {
"i18n": {
"en": {
"rangeControlName": {
"ui:start_range": "start_range",
"ui:end_range": "end_range"
}
}
},
"rangeControlName": {
"ui:widget": "RangeButtonWidget"
}
}
}
```
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.
***
## Select controls
### Single select
```json
{
"singleSelectControlName": {
"type": "number", // 1
"default": 3,
"enum": [ 1, 2, 3 ], // 2
"enumNames": [ // 3
"One (value - `chair`)",
"Two (value - `window`)",
"Three (value - `table`)"
]
}
}
```
```json
{
"ui": {
"singleSelectControlName": { // 4
"ui:enumDisabled": [ // 5
2 // 6
]
}
}
}
```
```json
{
"ui": {
"i18n": {
"en": {
"singleSelectControlName": {
// ... default locales (title, help, description)
"enumNames": [ // 7
"Lozalized value 1",
"Lozalized value 1"
],
},
// ... next control
}
// ... next locale
}
}
}
```
1. Definition of the type of control.
Strings, numbers and boolean are available (for boolean only `Yes/No` and these values are set by default);
2. Array of available values. Required field for string and number.
3. An array of displayed names, the number of elements must match the number of elements in the `enum` field. This field is optional.
4. The name of the control must match the name in the schema;
5. Property name to disable specific selector options;
6. Array of values to disable. Variants must match the `enum` key in the control in the schema.
7. 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).**
### Multiple select
```json
{
"multipleSelectControlName": {
"type": "array", // 1
"default": [ "floor", "door" ],
"uniqueItems": true, // 2
"minItems": 2, // 3
"maxItems": 4, // 4
"items": { // 5
"type": "string", // 6
"enum": [ // 7
"chair",
"window",
"table",
"floor",
"door"
],
"enumNames": [ // 8
"One (value - `chair`)",
"Two (value - `window`)",
"Three (value - `table`)",
"Four (value - `floor`)",
"Five (value - `door`)"
]
}
}
}
```
```json
{
"ui": {
"multipleSelectControlName": { // 9
"ui:enumDisabled": [ // 10
"table" // 11
]
}
}
}
```
```json
{
"ui": {
"i18n": {
"en": {
"multipleSelectControlName": {
// ... default locales (title, help, description)
"enumNames": [ // 12
"Lozalized value 1",
"Lozalized value 1"
],
},
// ... next control
}
// ... next locale
}
}
}
```
1. Definiton of the type of control.
Only `array` is available.
2. Required key to enable multiple selector. Works only with the `array `type;
3. Restriction on the `minimum` number of elements to choose from;
4. Restriction on the `maximum` number of elements to choose from;
5. Required key to define a multiple selector;
6. Definition of the type of values. Strings and numbers are allowed;
7. Array of values must be of the same type from 6 points;
8. Array of displayed names, the number of elements must match the number of elements in the `enum` field. This field is optional;
9. The name of the control must match the name in the schema;
10. Property name to disable specific selector options;
11. Array of values to disable. Variants must match the `enum` key in the control in the schema.
12. 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).**
### Dynamic data from portal
```json
{
"propertyIdFromDefinitionOfForm": { // 1
"type": "string", // 2
"enum": [], // 3
"enumNames": [], // 4
"default": "defaultValueForChoosing", // 5
}
}
```
```json
{
"ui": {
"propertyIdFromDefinitionOfForm": { // 6
"ui:enumDisabled": [ // 7
'valueForDisablingOption' // 8
]
}
}
}
```
```json
{
"ui": {
"i18n": {
"en": {
"propertyIdFromDefinitionOfForm": {
// ... default locales (title, help, description)
"enumNames": [ // 8
"Lozalized value 1", // 9
"Lozalized value 1"
],
"ui:enumNames": [ // 8
"Lozalized value 1", // 9
"Lozalized value 1"
],
},
// ... next control
}
// ... next locale
}
}
}
```
1. Controller name, which must match the propertyId of form definition;
2. Controller type `string` to pull entities from the Portal;
3. **This option must be ignored,** otherwise the form control management switches to **manual data handling mode**. If this parameter is specified (**array of string values or empty array**), then the values for the form control will be pulled from this array, **ignoring the Portal filters**
4. If the form control is set to **manual mode** (**point 3 is enabled**), then this parameter can be used to set localization for options of select. **The priority of applying translations is** as follows: **first the parameter from point 8, then the parameter from point 4**. **If point 3 is not enabled, then the values of this point will be ignored.**
5. **EntityId** from the Portal that should be set by default. Make sure this value is included in the filter result for this property.
6. Controller name, which must match the 1 point;
7. Option to set the value as disabled **(cannot be selected in the form)**
8. List of values that** will be disabled**
9. Array of **localized** values. You can use follow keywords - `enumNames` or `ui:enumNames`. ***Be careful,*** if this option has values specified, **dynamic titles for translations from the Portal will not be retrieved.** That is, **the values for the selection will be pulled**, but the **translations for these options will be taken from here**
10. A list of values that will be specified as translation strings.
***
## Checkboxes and radio buttons
### Single checkbox
```json
{
"singleCheckbox": {
"type": "boolean", // 1
"default": false // 2
}
}
```
1. Definition of the control type, only `boolean` is available;
2. Definition of the default type. The field is optional.
### Multiple checkboxes
```json
{
"multipleCheckboxes": {
"type": "array", // 1
"uniqueItems": true, // 2
"minItems": 2, // 3
"maxItems": 4, // 4
"items": { // 5
"type": "string", // 6
"enum": [ // 7
"chair",
"window",
"table",
"floor",
"door"
],
"enumNames": [ // 8
"One (value - `chair`)",
"Two (value - `window`)",
"Three (value - `table`)",
"Four (value - `floor`)",
"Five (value - `door`)"
]
}
}
}
```
```json
{
"ui": {
"multipleCheckboxes": { // 9
"ui:widget": "checkboxes", // 10
"ui:inline": true // 11
}
}
}
```
```json
{
"ui": {
"i18n": {
"en": {
"multipleCheckboxes": {
// ... default locales (title, help, description)
"enumNames": [ // 12
"Lozalized value 1",
"Lozalized value 1"
],
},
// ... next control
}
// ... next locale
}
}
}
```
1. Definition of the type of control.
Only `array` is available.
2. Required key to enable multiple checkboxes. Works only with the `array` type;
3. Restriction on the `minimum` number of elements to choose from;
4. Restriction on the `maximum` number of elements to choose from;
5. Required key to define multiple checkboxes;
6. Definition of the type of values. Strings and numbers are allowed;
7. Array of values must be of the same type from 6 points;
8. Array of displayed names, the number of elements must match the number of elements in the `enum` field. This field is optional;
9. The name of the control must match the name in the schema;
10. Application of the widget `multiple checkboxes`;
11. The key that determines the display of checkbox items.
`ui:inline=true` - inline;
`ui:inline=false` - columns;
12. 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).**
13.
### Agreements checkbox
:::hint{type="warning"}
### 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!**
:::
```json
{
"agreement_checkbox": {
"type": "boolean", // 1
}
}
```
```json
{
"ui": {
"agreement_checkbox": {
"ui:widget": "AgreementsCheckboxWidget", // 2
"ui:field": "custom" // 3
},
"i18n": {
"en": {
"agreement_checkbox": {
// ... // 4
"ui:options": { // 5
"links": { // 6
"legal": { // 7
"link": "https://google.com/2", // 8
"text": "the Terms of Service" // 9
},
"privacy": { // 7
"link": "https://google.com/1", // 8
"text": "Privacy Policy" // 9
}
},
"templateString": "I accept %%privacy%% and %%legal%%." // 10
}
}
}
}
}
}
```
1. Determining the type of controller. Only `boolean` values are available;
2. Defining a custom widget for the `Agreements checkbox`;
3. Optional parameter to `show/hide` the title of the custom widget (`Agreements checkbox`);
4. Here you can define default field translations (`title, help, description`);
5. Special options for custom `Agreement checkbox` widget;
6. Required option, where you can define `links` for the checkbox;
7. Link `key` name. The `key` value must match the `key` in the template string (at point 10);
8. This `key` is required, means the `value for the link` (where the user will be sent);
9. This `key` is required, meaning the value for the `link text`;
10. Template string where `links` from point 6 will be inserted. Places to insert should be circled with a `double percent` sign (`%%`).
### Radio buttons
```json
{
"radioButtons": {
"type": "string", // 1
"enum": [ // 2
"chair",
"window",
"table",
"floor",
"door"
],
"enumNames": [ // 3
"One (value - `chair`)",
"Two (value - `window`)",
"Three (value - `table`)",
"Four (value - `floor`)",
"Five (value - `door`)"
]
}
}
```
```json
{
"ui": {
"radioButtons": { // 4
"ui:widget": "radio", // 5
"ui:inline": true // 6
}
}
}
```
```json
{
"ui": {
"i18n": {
"en": {
"radioButtons": {
// ... default locales (title, help, description)
"enumNames": [ // 7
"Lozalized value 1",
"Lozalized value 1"
],
},
// ... next control
}
// ... next locale
}
}
}
```
1. Definitionof the type of values. Strings and numbers are allowed;
2. Array of values must be of the same type from 2 points;
3. An array of displayed names, the number of elements must match the number of elements in the `enum` field. This field is optional;
4. The name of the control must match the name in the schema;
5. Application of the `radio button` widget;
6. The key that determines the display of checkbox items.
`ui:inline=true` - inline;
`ui:inline=false` - columns;
7. 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).**
***
## Upload file(s)
### Avaible file widget:
- file
- files
- FileWidgetWithPreview
### Single file
```json
{
"uploadFile": {
"type": "string" // 1
}
}
```
```json
{
"ui": {
"uploadFile": { // 2
"ui:widget": "file", // 3
"ui:accept": ".pdf,.jpg" // 4
}
}
}
```
1. Definition of the type of control. Only the string is available;
2. The name of the control must match the name in the schema;
3. Specifying field type "**file**" or "**FileWidgetWithPreview**";
4. Indication of the list of files available for upload. This field is optional.
### Multiple files
```json
{
"multipleUploadFiles": {
"type": "array", // 1
"items": { // 2
"type": "string" // 3
}
}
}
```
```json
{
"ui": {
"multipleUploadFiles": { // 4
"ui:widget": "files" // 5 files or FileWidgetWithPreview
"ui:accept": ".pdf,.jpg" // 6
}
}
}
```
1. Specifying the type of waiting for multiple downloads of files. Only `array` is available;
2. Required field for specifying multiple downloads of files;
3. Definition of the type of control. Only the `string` is available;
4. The name of the control must match the name in the schema;
5. Specifying field type "**files**" or "**FileWidgetWithPreview**";
6. Indication of the list of files available for upload. This field is optional.
**FileWidgetWithPreview** can be used with `list` or `carousel` parameter:
```json
"images": {
"ui:widget": "FileWidgetWithPreview",
"ui:options": {
"accept": ".jpeg, .png, .jpg, .pdf",
"imageCover": true,
"displayMode": "list",
"isFileFullWidth": false,
"pdfSinglePageMode": false,
"fileMaxHeight": "400"
}
}
```
## FileWidgetWithPreview
### Overview
This widget is used to display and upload various file types in multiple modes, including list and carousel views, with scrollable and zoom-enabled file previews.
### UI Configuration
The ui property defines the user interface configuration for the form. Defines the custom widget, options for the guided files form, and the display mode for the files.
```azcli
{
"form": {
"ui": {
"fileProperty": {
"ui:widget": "FileWidgetWithPreview",
"ui:files": [], // must not be specified
"ui:options": {
"accept": ".jpeg, .png, .jpg, .pdf", // all file types if undefined
"imageCover": true, // default value if undefined
"displayMode": "list", // default value if undefined
"fileMaxHeight": "400", // 100% if undefined
"isFileFullWidth": false, // default value if undefined
"pdfSinglePageMode": true // default value if undefined
}
}
}
}
```
- **Options**:
- **ui\:widget - **Configure that use specific widget.
- **ui\:files - **This field is filled with the metadata of the files. The widget automatically adds and filled this parameter based on the file IDs specified in the form data.
- **accept - **List of acceptable file formats for display (If the parameter is undefined, all file types that the widget can display are allowed).
- **imageCover - **`true` – cover makes an image fill its container completely while maintaining its aspect ratio, potentially cropping parts of the content if the container’s proportions don’t match the media. `false` – contain makes an image fit entirely within its container while maintaining its aspect ratio, potentially leaving empty space if the container’s proportions don’t match the media.
- **displayMode - **`list` – standard mode showing file icons in a list layout. `carousel` – slider mode displaying files in a carousel view.
- **fileMaxHeight - **Maximum height restriction for each file. For example, if there is a single PDF on the page, this prevents it from taking up the entire page height.
- **isFileFullWidth - **setting, that makes files stretch to the full width of the screen and display stacked vertically (for example, when showing a PDF file).
- **pdfSinglePageMode - **setting that allows PDF files to be displayed in a multi-page mode with scroll enabled.
### Schema
**Multiple mode (example schema configuration)**
This mode supports adding multiple files.
**Important**: For the UI configuration, there is no need to additionally add `items` in the settings.
```azcli
{
"form": {
"schema": {
"properties": {
"fileProperty": {
"type": "array",
"items": {
"type": "string"
},
"readOnly": false // default value if undefined
}
}
}
}
}
```
**Displaying a single file**
The plugin allows you to display more files that are specified in the date, but does not allow to add.
```azcli
{
"form": {
"schema": {
"properties": {
"fileProperty": {
"type": "string",
"readOnly": false // default value if undefined
}
}
}
}
}
```
:::Heading{depth="3" indent="1"}
Parameters
:::
:::Paragraph{listStyleType="disc" indent="2"}
**readOnly - **if `true`, adding and deleting files is **disabled**.
:::
### Data
This section specifies the IDs of files stored in the Image Service. The plugin automatically retrieves the file metadata and adds it to the widget’s UI configuration (`ui: files`).
**Multiple mode schema**
```azcli
{
"form": {
"data": {
"fileProperty": [
"bhRLnamndzRhnuq_KhjlQ",
"wIbmWQpavmuIFBnEePPhp",
"SklydLZSJROTVdjjYcHUB"
]
},
}
}
```
**Single mode schema**
```azcli
{
"form": {
"data": {
"fileProperty": "SklydLZSJROTVdjjYcHUB"
},
}
}
```
## Guide images
### Overview
This is used to guide users in providing specific images with associated metadata, including positions, labels, and additional options.
### UI Configuration
The ui property defines the user interface configuration for the form. Defines the custom widget and options for the guided images form.
```azcli
{
"form": {
"ui": {
"guidedImagesForm": { // 1
"ui:widget": "GuideFileWithPreviewWidget", // 2
"ui:options": {
"position": [
{
"key": "frontLeft", // 3
"labels": { // 4
"de": "Vorne links",
"en": "Front left",
"fr": "Avant gauche",
"it": "Anteriore sinistro",
"nl": "Vooraan links",
"pl": "Przedni lewy"
},
"overlayImage": "YwmFfNaqyiv_coXCxg_Oz", // 5
"placeholderImage": "ZeHCknOGusCllwlBg_oNc", // 6
"positionEntityId": "cVnvDBbfrEZfQDIXqKZmU" // 7
},
{
"key": "frontRight",
"labels": {
"de": "Vorne rechts",
"en": "Front right",
"fr": "Avant droit",
"it": "Anteriore destro",
"nl": "Rechtsvoor",
"pl": "Przednie prawe"
},
"overlayImage": "FDanKpMBLrjkAYJDEXnVa",
"placeholderImage": "acjDWVrmQtMMADFywMkWo",
"positionEntityId": "wxGiQWuEIlAbkWcTKDfPl"
},
{
"key": "rearLeft",
"labels": {
"de": "Hinten links",
"en": "Rear left",
"fr": "Arrière gauche",
"it": "Posteriore sinistro",
"nl": "Links achter",
"pl": "Tył lewy"
},
"overlayImage": "GvrdyqCnoUIfacvfDlPCi",
"placeholderImage": "rGlRzroTYDhwMkfkjzBKP",
"positionEntityId": "wwGijsNYFkBGNSlVYUcH_"
},
{
"key": "rearRight",
"labels": {
"de": "Hinten rechts",
"en": "Rear right",
"fr": "Arrière droit",
"it": "Posteriore destro",
"nl": "Rechts achter",
"pl": "Tylny prawy"
},
"overlayImage": "pFlflLvhHaVCkWhKmnJfX",
"placeholderImage": "JjjFgMUOmbhnlGQXszwPn",
"positionEntityId": "UuQixAqjNjMbYaogagehV"
},
{
"key": "steerHigh",
"labels": {
"de": "Hoch steuern",
"en": "Steer high",
"fr": "Dirigez-vous vers le haut",
"it": "Guida in alto",
"nl": "Stuur hoog",
"pl": "Kieruj się wysoko"
},
"positionEntityId": "ZKxdvLW_HtVWaWSjjwmtq"
},
{
"key": "coPilotHigh",
"labels": {
"de": "Co-Pilot hoch",
"en": "Co-pilot high",
"fr": "Copilote haut",
"it": "Copilota alto",
"nl": "Co-piloot hoog",
"pl": "Drugi pilot wysoki"
},
"positionEntityId": "UeIveLagHcSrzKfNoQOIk"
},
{
"key": "sleepCabin",
"labels": {
"de": "Schlafkabine",
"en": "Sleep cabin",
"fr": "Cabine de couchage",
"it": "Cabina letto",
"nl": "Slaapcabine",
"pl": "Kabina sypialna"
},
"positionEntityId": "IjQLDxOjD_ZMFNPbFYRqS"
},
{
"key": "interiorLight",
"labels": {
"de": "Innenbeleuchtung",
"en": "Interior light",
"fr": "Lumière intérieure",
"it": "Luce interiore",
"nl": "Binnenverlichting",
"pl": "Wewnętrzne światło"
},
"positionEntityId": "FCJhigLNTd_MQUMgVJlZl"
},
{
"key": "frigOpen",
"labels": {
"de": "Kühlschrank offen",
"en": "Frig open",
"fr": "Frigo ouvert",
"it": "Frigo aperto",
"nl": "Frigo open",
"pl": "Lodówka otwarta"
},
"positionEntityId": "Y_tInkPeCE_FNaJ_aDSuk"
},
{
"key": "centralHeat",
"labels": {
"de": "Zentralheizung",
"en": "Central heat",
"fr": "Chauffage central",
"it": "Calore centrale",
"nl": "Centrale verwarming",
"pl": "Centralne ogrzewanie"
},
"positionEntityId": "bmyoUDWmVRrP_UYToheRm"
},
{
"key": "rightSteer",
"labels": {
"de": "Richtig lenken",
"en": "Right steer",
"fr": "Direction à droite",
"it": "Sterzo destro",
"nl": "Rechts sturen",
"pl": "Kieruj w prawo"
},
"positionEntityId": "xhPjNxVnMVPaqyVAUfBmX"
},
{
"key": "dashboard",
"labels": {
"de": "Armaturenbrett",
"en": "Dashboard",
"fr": "Tableau de bord",
"it": "Pannello di controllo",
"nl": "Dashboard",
"pl": "Panel"
},
"positionEntityId": "LqMssIgZggkyLHJUZGRhN"
}
],
"guidedImagesDefinitionId": "inspectionGuideImage" // 8
}
}
}
}
}
```
- **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.
### Properties
```json
{
"properties": {
"guidedImagesForm": {
"type": "array",
"items": {
"type": "object",
"properties": {
"image": {
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"entityId": {
"type": "string"
},
"position": {
"type": "string"
},
"isApproved": {
"type": [
"boolean",
"null"
]
},
"definitionId": {
"type": "string"
}
}
},
"title": "Guide images",
"default": "{{#toJson}}{{#fn.pick}}{{#fn.stringify}}formItem.guidedImages{{/fn.stringify}}|title,definitionId,entityId,position,image,isApproved{{/fn.pick}}{{/toJson}}"
}
}
}
```
- **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.
***
## Calendars
### Native calendar with date and time
```json
{
"dateTimeCalendar": {
"type": "string", // 1
"format": "date-time", // 2
"disabledInput": true, // 3
"relativeMaximum": { // 4
"day": 4, // 4.1
"year": 4, // 4.2
"month": 4 // 4.3
},
"relativeMinimum": { // 5
"day": 4, // 5.1
"year": 4, // 5.2
"month": 4 // 5.3
}
}
}
```
1. Definition of the type of control. Only the `string` is available;
2. Specifying the control format for the native calendar with time data;
3. Ability to disable keyboard input (only clicking on the icon works);
4. Possibility to limit the maximum date
1. Limit `day`
2. Limit `year`
3. Limit `month`
5. Possibility to limit the minimum date
1. Limit `day`
2. Limit `year`
3. Limit `month`
### Native calendar with date
```javascript
{
"dateCalendar": {
"type": "string", // 1
"format": "date", // 2
"disabledInput": true, // 3
"relativeMaximum": { // 4
"day": 4, // 4.1
"year": 4, // 4.2
"month": 4 // 4.3
},
"relativeMinimum": { // 5
"day": 4, // 5.1
"year": 4, // 5.2
"month": 4 // 5.3
}
}
}
```
1. Definition of the type of control. Only the `string` is available;
2. Specifying the control format for the native calendar without time data.
3. Ability to disable keyboard input (only clicking on the icon works);
4. Possibility to limit the maximum date
1. Limit `day`
2. Limit `year`
3. Limit `month`
5. Possibility to limit the minimum date
1. Limit `day`
2. Limit `year`
3. Limit `month`
### Alternative calendar with date and time
```json
{
"altDateTimeCalendar": {
"type": "string", // 1
"format": "date-time" // 2
}
}
```
```json
{
"ui": {
"altDateTimeCalendar": { // 3
"ui:widget": "alt-datetime", // 4
"ui:yearsRange": [ // 5
1980,
2030
],
"ui:hideNowButton": false, // 6
"ui:hideClearButton": false // 7
}
}
}
```
1. Definition of the type of control. Only the `string` is available;
2. Specifying the control format for the alternative calendar with time data;
3. The name of the control must match the name of the control in the schema;
4. Definition of the alternative calendar widget with date and time;
5. Specifying the limit of the displayed years (`from and to`);
6. Property for hiding the "Today" date setting button;
7. Property for hiding the reset button of the selected date.
### Alternative calendar with date
```javascript
{
"altDateCalendar": {
"type": "string", // 1
"format": "date" // 2
}
}
```
```javascript
{
"ui": {
"altDateCalendar": { // 3
"ui:widget": "alt-date", // 4
"ui:yearsRange": [ // 5
1980,
2030
],
"ui:hideNowButton": false, // 6
"ui:hideClearButton": false // 7
}
}
}
```
1. Definition of the type of control. Only the `string` is available;
2. Specifying the control format for the alternative calendar;
3. The name of the control must match the name of the control in the schema;
4. Definition of the alternative calendar widget with date;
5. Specifying the limit of the displayed years (`from and to`);
6. Property for hiding the "Today" date setting button;
7. Property for hiding the reset button of the selected date.
***
## Nullable control
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.
```json
{
"nullable": {
"type": "null" // 1
}
}
```
1. Indication of the type. Only `null` is available.