# Field
## Getting Started
Starting in the **Class Designer,** click on the down arrow on the left side of the class you wish to work on. Next, expand the **Fields** for the class. Go to **Add a new field** and enter the name of your field. Press **Enter** to open the field editor.
{% hint style="info" %}
Clicking on an existing field opens it in the field editor to allow changing its configurations.
{% endhint %}
## Common Attributes
The Common section contains general properties of a field. In this section, you can specify how the field is presented in your application by setting the name, description and other information.
### Key
The field key is an internal label for the field in your application.
Field keys are typically used when querying data to define which information to output from a particular query. More information about data queries can be found [here](https://docs.tivity.one/building-an-application/data/query-data).
{% hint style="info" %}
The **Key** field is compulsory when creating a field.
{% endhint %}
### Internal Key
The internal key is a unique identifier for your field and defines your field name in the database.
{% hint style="info" %}
The **Internal Key** field is compulsory when creating a field.
{% endhint %}
### Name
This is the name that is displayed in the application. By clicking on the globe icon, you can define a name for every language.
{% hint style="info" %}
The **Name** field is compulsory when creating a field.
{% endhint %}
### Description
The field description provides additional information to help the user navigate through your application. It can also be used as a hover text.
### Data Type
This field determines what type of data is allowed by the field and saved in the database.
{% hint style="info" %}
The **Data Type** field is compulsory when creating a field.
{% endhint %}
Based on the data type, different [control type](#control-type) options are made available for the user to enter a value for the field.
| **Any** | Label, Html |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Guid** | Label, TextBox, ComboBox, Slider, Html |
| **Boolean** | Checkbox |
| **String** | Label, TextBox, ComboBox, EditComboBox, Slider, Password, TextArea, Email, Phone, Address, Url, HtmlEditor, MarkdownEditor, Html |
| **DateTime** | Label, TextBox, Calendar, DatePicker, TimePicker, Html |
| **Integer** | Label, TextBox, ComboBox, EditComboBox, Slider, Html |
| **Byte** | Label, TextBox, ComboBox, EditComboBox, Slider, Html |
| **Short** | Label, TextBox, ComboBox, EditComboBox, Slider, Html |
| **Long** | Label, TextBox, ComboBox, EditComboBox, Slider, DurationPicker, Html |
| **Float** | Label, TextBox, ComboBox, EditComboBox, Slider, Html |
| **Double** | Label, TextBox, ComboBox, EditComboBox, Slider, Html |
| **Numeric** | Label, TextBox, ComboBox, EditComboBox, Slider, Html |
| **ByteArray** | Preview |
| **Char** | Label, TextBox, ComboBox, EditComboBox, Slider |
| **Xml** | Label, TextBox, TextArea, Content, ComboBox, Slider, Html |
### Control Type
The field control type defines the editor with which a user can interact with the field. Control type options vary based on the data type selected for the field. Below is a list of different control types and how they can be used.
#### **Label**
Labels are used to present a single line of text. The control type 'Label' (or item appearance 'Label') shows the value of the field without the possibility to edit it. The field is visualized like a read-only field without the effects.
{% hint style="info" %}
Supported data types:\
Any, Guid, String, DateTime, Integer, Byte, Short, Long, Float, Double, Numeric, Char, Xml
{% endhint %}
**TextBox**
Textboxes allows the user to enter a single line of text.
{% hint style="info" %}
Supported data types:\
Guid, String, DateTime, Integer, Byte, Short, Long, Float, Double, Numeric, Char, Xml
{% endhint %}
#### Calendar
The calendar control is a combination of a Date Picker and a Time Picker to allow the user to select both a date and a time as input.
{% hint style="info" %}
Supported data type: DateTime
{% endhint %}
#### DatePicker
The date picker control is a textbox that is equipped with a calendar for easier date input.
{% hint style="info" %}
Supported data type: DateTime
{% endhint %}
#### TimePicker
The time picker control is a textbox that is customized for easier input of time value.
{% hint style="info" %}
Supported data type: DateTime
{% endhint %}
#### **ComboBox**
Combo-boxes are used to select a single value from a given set of options. By choosing this control type, additional configurations are presented to the user to configure the combo-box set of options.
{% hint style="info" %}
Supported data types:\
Guid, String, Integer, Byte, Short, Long, Float, Double, Numeric, Char, Xml
{% endhint %}
Based on the **Data Source Type** selected, different fields are presented to finalize the source of combo-box options.
1. **None**\
No data source defined for the option list leaving it blank.\
2. **Class**\
The user can set which class and field to read from to populate the combo-box options.\
3. **Controller**\
The user can use code from a controller to determine how the options list should be built.\
4. **Option**\
The user can manually add possible options in a multi-line textbox (one option per line).\
For Combo-boxes an automatic pagination mechanism is implemented. So even if there are dozens of options there won't be any performance issues when user is searching through the options.
{% hint style="info" %}
An alternate version of the combo-box is the **EditComboBox** control type which has the same configuration options as a normal combo-box.
However, input values for an edit-combo-box is not limited to the option set provided. Users can enter custom values in the input box.
{% endhint %}
#### **Slider**
Sliders allow the user to choose a value graphically. Additional **Options Source** configurations are provided to the user when this control type is selected. These configurations define which options are made available when using the slider.
{% hint style="info" %}
Supported data types:\
Guid, String, Integer, Byte, Short, Long, Float, Double, Numeric, Char, Xml
{% endhint %}
With your data source configurations set, your slider will be ready for use in your application.
#### Password
Password fields are displayed with a single line of escaped text. By default, the password is masked using dots. Selecting the eye icon on the right of the textbox allows the password to be viewed as plain text.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### TextArea
This allowed the user to input multiple lines of text. In the bottom right corner of the input box, a resize option is provided allowing you to increase the height of the text area.
{% hint style="info" %}
Supported data types: String, Xml
{% endhint %}
#### URL
URL control types allows a single line of text to be entered. The input box is customized for adding hyperlinks. An option on the right of the input box allows you to open the hyperlink in a new tab.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### HtmlEditor
Html Editors allows the user to create and edit content in html format - allowing for easier combinations of multimedia and text.
Field Control Type HtmlEditor
{% hint style="info" %}
Supported data type: String
{% endhint %}
HtmlEditor field in the Layout Designer
#### Html
Displays the value of the field as HTML in non-editable format.
{% hint style="info" %}
Supported data type:
Any, Guid, String, DateTime, Integer, Byte, Short, Long, Float, Double, Numeric, Xml
{% endhint %}
#### MarkdownEditor
Markdown Editors allows the user to create and edit content in markdown format - allowing for content consisting of text and multimedia to be created while reducing the complexity of content creation compared to HTML.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### Email
Email control types allows a single line of text to be entered. The input box is customized for email input.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### Phone
Phone control types allows a single line of text to be entered. The input box is customized for phone entry.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### Address
Address control types allows a single line of text to be entered. The input box is equipped with an option to open your address on Google Maps so you can confirm the location.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### Preview
The preview control type works with images stored as byte arrays. Using this control, the byte-array is rendered into the original image in your application.
{% hint style="info" %}
Supported data type: ByteArray
{% endhint %}
#### Content
The content control type can be used with XML content. Similar to text-areas, it allows the user to increase the height by using a resizer at the bottom right corner of the input box.
{% hint style="info" %}
Supported data type: Xml
{% endhint %}
#### DurationPicker
The control type gets ticks and displays them as a duration (TimeSpan). Upon changing the duration, the new value gets saved as ticks (Long). The DurationPicker can be configured (in layout designer) to only display some of the different parts (days, hours, minutes and seconds).
Ticks are defined as 10,000 ticks per millisecond.
{% hint style="info" %}
Supported data type: Long
{% endhint %}
### Data Source Type
#### Class
Data Source Type Class is selectable for control types ComboBox, EditComboBox and Slider.
Data Source Type Class Usage Sample
Selection of Data Source Type Class requires additionaly selection of the class which will serve as a data source and the field of the chosen class.
#### Selection
Data Source Type Selection can be chosen for the Control Types ComboBox, EditComboBox and Slider.
In data source type “Selection” a selection can be selected to be used when a field value is to be selected.
Data Source Type Selection Usage Sample
Is the data source type Selection chosen, the following fields can be filled:
* Selection (required): A selection to choose from. All selections without a context or selections with a context matching the context of the parameter. For Field, Action-Parameter, Template-Parameter and Workflow-Parameter of the configured class is the matching context. For Selection-Parameter the context class is the matching context.
* Key field (required): A field of the selection to use as identification of each entry. The value will be used to store in a class field or parameter. Only fields of the same selection source can be selected.
* Name field (required): A field of the selection to use to display each entry. This can be the same as the key field. Only fields of the same selection source can be selected.
| Field | Required | Remarks |
| --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Data Source Type | Yes | The type of data source. Must be “Selection”. |
| Selection | Yes | The selection that is used as the data source. |
| Key Field | Yes | The field of the selection used as the key field. The value of the key field is saved in the field that is being configured. |
| Name Field | Yes | The field of the selection used as the name field. The value of the name field is displayed. |
| Parameter Default Values (Script) | No |
A script executed before parameters of the chosen selection are evaluated. The script should fill variables named after parameters used in the selection. The script gets to following variables passed:
Context.OfficeId (Guid): The ID of the office/ workspace the selection will be executed in.
Context.ApplicationId (Guid): The ID of the app the selection will be executed in.
Context.ClassId (Guid): The ID of the source class of the selection.
Query.ContextLinkId (Guid): The ID of the link between the class of the field and the class of the selection class (when applicable).
Query.ContextClassId (Guid): The ID of the class of the field.
Query.ContextInstanceId: The ID of the instance which field value is to be changed.
|
#### Controller
Controllers Data Source Type can be chosen for the Control Types ComboBox, EditComboBox and Slider. You get a selection of controllers for different tasks.
#### Option
Data Source Type Option can be chosen for the Control Types ComboBox, EditComboBox and Slider. With this type you can enter the selection possibilities manually.
Data Source Type Option with Sample Options
Data source option can include translations for the name part of an option. Translations are optional and separated through the ':' character. Supported translations are:
* de - German language
* en - English language
* fr - French language
The following data source option definitions are supported:
**ID-only**
* Definition: \\[;\]
* Example: id1;id2;id3
* Only IDs with no names are shown
* ID and name are the same
* ID is saved as the field value
**ID-Name**
* Definition: \:\\[;\:\]
* Example: id1:name1;id2:name2;id3:name3
* Names are shown
* ID and name are separated
* ID is saved as the field value
**ID-Name-Translations**
* Definition: \:\\[:\:\]\[;\:\\[:\:\]]
* Translation for the language of the current user\
or name if no translation found is shown
* ID, name, language and translation are separated
* ID is saved as the field value
Sample image above shows Data Source Type Option with sample of manually entered dummy options in two languages.
## Mapping Attributes
Field data is stored as table columns in the database. The Mapping section defines how the fields are identified and used on a database level by the platform and your application.
### Key
The mapping key defines the exact name of the column that is saved in the database.
{% hint style="info" %}
The **Key** field is compulsory when creating a field.
{% endhint %}
### Data type
The mapping data type specifies the database data type for this field. Below is a table relating some field common data types with their corresponding database mapping data types.
| Common Data Type | Mapping Data Type |
| ---------------- | ----------------- |
| Guid | uniqueidentifier |
| Boolean | bit |
| String | nvarchar |
| DateTime | datetime |
| Integer | integer |
| Byte | tinyint |
| Short | smallint |
| Long | bigint |
| Float | float |
| Double | float |
| Numeric | decimal |
| ByteArray | binary |
| Char | char |
| Xml | xml |
{% hint style="info" %}
For additional information on the mapping data types, click on [this link](https://docs.microsoft.com/en-us/sql/t-sql/data-types/decimal-and-numeric-transact-sql?view=sql-server-2017).
{% endhint %}
### Length
Mapping length defines the maximum length of a field.
{% hint style="info" %}
Default value for length is -1. This defines the length as unlimited.
{% endhint %}
### Is Identity
This checkbox determines whether the current field is a primary key in the database or not.
### Is Nullable
This checkbox defines whether this field can have a **null** value in the database.
## Advanced Attributes
The Advanced section allows you to control how the platform and the application uses the field.
{% hint style="danger" %}
Advanced configurations are changed only in unique cases. During normal use, these configurations are already done by the system and should not be changed.
{% endhint %}
### Quick Search Field
Defines whether a field should be shown when using the Quick Search functionality on the platform.
### Include Data Source in Quick Search
This field option is only available if the field has a class as a data source.
Include Data Source in Quick Search Option
Enabling it, the name field of the class of the data source is included in a quick search or ad hoc query.
### Kind
The platform currently supports two types of fields.
**Real**: A real field has a corresponding entry in the database.\
**Virtual**: A virtual field does not exist in the database. It is instead used to display results calculated or derived from other values.
### Is Required
Defines if the field needs to have a value when a new instance of that class is created.
### Is Read Only
Defines whether the field can be edited.
{% hint style="success" %}
Example: If a field is a unique identifier or a primary key, it may be marked as **Read Only** to prevent users from modifying it.
{% endhint %}
### Is Invisible
This setting defines whether the field is visible in your application.
{% hint style="success" %}
This is especially useful in cases where the user does not need to see or interact directly with a field in the application while the field is still useful in other use-cases (e.g. generating statistics).
{% endhint %}
### Exclude from number formatting
With this option fields with a number data type (Integer, Byte, Short, Long, Float, Double, Numeric) can be configured to be excluded from being formatted.
Sample number Field with the Option
If a field is excluded from being formatted, when the value of the field is displayed or modified, then the default format of the chosen language without group separators is used.
For example, you can see below a Double data type field which is formatted (left box) and which is excluded from number formatting by this option (right box).
Formatted
Excluded from Formatting
### Default Mode
The default mode defines for the field kind Real or Language at what point should a field be saved to the database.
* **None**\
The [default expression](#default-expression) will not be used.
* **Creation** \
The field is saved when the class object is created.
* **Insertion**\
The field is saved when the class object is saved.
### Default Expression
This configuration allows you to generate a default value for a field when an object of the class is created.
{% hint style="success" %}
This is particularly useful when the field value is being automatically generated via a method.
{% endhint %}
### Virtual Field
#### Get Expression Type
For the Virtual field kind it is possible to choose between two expression types:
* Expression
* Script
As the name implies, for the type Expression it is possible to write an expression and for the type Script it is possible to write a script with the [Script Designer](https://docs.tivity.one/building-an-application/execution/scripting) to provide the value of the virtual field.
Virtual Field Expression Types
#### Get Expression
Option for the expression type Expression to write an expression to provide a value for the field kind Virtual.
#### Create and open expression script
Option for expression type Script to write a script with the [Script Designer](https://docs.tivity.one/building-an-application/execution/scripting) which provides the value for the field kind Virtual.
### Store
In the Store section of the Advanced options it is possible to set an expression or write a script which are set during the field saving process.
#### Get Expression Type
Two expression types are available:
* Expression
* Script
Store Expression Types
#### Get Expression
Option for the expression type Expression to write an expression to provide a store value.
#### Create and open expression script
Option for expression type Script to write a script with the [Script Designer](https://docs.tivity.one/building-an-application/execution/scripting) which provides the store value.
## Permissions
This section deals with specific read and write permissions of the field for single users or user groups.
{% hint style="info" %}
More information about permissions can be found in the Rights Designer.
{% endhint %}
For Combo-boxes an automatic pagination mechanism is implemented. So even if there are dozens of options there won't be any performance issues when user is searching through the options.
{% hint style="info" %}
An alternate version of the combo-box is the **EditComboBox** control type which has the same configuration options as a normal combo-box.
However, input values for an edit-combo-box is not limited to the option set provided. Users can enter custom values in the input box.
{% endhint %}
#### **Slider**
Sliders allow the user to choose a value graphically. Additional **Options Source** configurations are provided to the user when this control type is selected. These configurations define which options are made available when using the slider.
{% hint style="info" %}
Supported data types:\
Guid, String, Integer, Byte, Short, Long, Float, Double, Numeric, Char, Xml
{% endhint %}
With your data source configurations set, your slider will be ready for use in your application.
#### Password
Password fields are displayed with a single line of escaped text. By default, the password is masked using dots. Selecting the eye icon on the right of the textbox allows the password to be viewed as plain text.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### TextArea
This allowed the user to input multiple lines of text. In the bottom right corner of the input box, a resize option is provided allowing you to increase the height of the text area.
{% hint style="info" %}
Supported data types: String, Xml
{% endhint %}
#### URL
URL control types allows a single line of text to be entered. The input box is customized for adding hyperlinks. An option on the right of the input box allows you to open the hyperlink in a new tab.
{% hint style="info" %}
Supported data type: String
{% endhint %}
#### HtmlEditor
Html Editors allows the user to create and edit content in html format - allowing for easier combinations of multimedia and text.
