Reference Guide
Detailed explanations of every feature and function in NutshellText Field
The Text Field component allows you to capture text information within a form, including automatic validation for various types for data.
Text Fields can automatically validate several types of user-input including email addresses
Whilst Text Fields can accommodate any type of text-oriented content you want to collect, Nutshell provides automatic validation for the following types of data:
Plain Text
For anything you like, including any combination of text and numbers. Nutshell can automatically validate the length of the text an end-user types into the field, if you wish. If you’re a technical wizard, you can set custom validation rules too.
Email
For email addresses. Nutshell can validate the structure of the address an end-user types into the field, if you wish, to prevent end-users entering incorrectly formatted addresses.
Password
For password entry, where the input should be masked for security purposes.
Telephone
For telephone numbers. While it might seem more logical to use a Number field for telephone numbers, they sometimes include other characters, such as # or brackets. Nutshell can validate the length of the telephone number an end-user types into the field, if you wish, against a standard UK telephone number.
Post Code
For United Kingdom post codes. Nutshell can validate the structure of the post code an end-user types into the field, if you wish, to prevent end-users entering incorrectly formatted information.
Required Fields
If a text field in your form is mandatory, Nutshell can automatically validate that an end-user has not left it blank. Just set the text field to be a required field, and Nutshell will do the rest.
Nutshell will not allow the end-user to progress until all required fields have a value
Validation
Nutshell provides automatic validation for the various data-types listed above, so if you’re capturing email addresses, post codes or telephone numbers, you don’t need to do anything more than enabling validation.
Nutshell will automatically detect invalid user input and present an error message
Advanced users can validate against custom rules. For example, if your organisation uses custom product or job codes that follow a specific pattern, you can make sure they’re entered correctly into your app.
Custom validation rules are defined using Regular Expressions. If you don’t know what a Regular Expression is, you can find out more about them on WikipediaFind more information here or ask a member of your IT team.
How to write Regular Expressions is beyond the scope of this document, but suffice to say that you can enter a Regular Expression, and set a custom error message to display if the end-user’s input doesn’t match.
Default Content
Normally, if your form is just capturing data, the text field will be empty by default. Sometimes, it’s helpful to auto-populate fields with dynamic values. What do we mean by dynamic? Dynamic data is content that changeable based on something your end-user does.
Anywhere you see the blue thunderbolt, you can insert content dynamically from a data-source
You can set the default value of your text field to:
- The content of a form field on another screen (it must be a screen that the end-user will have already passed before reaching the current one)
- The content of a field within a database record (you’ll be able to set the search criteria to determine exactly which record)
- The content of a Variable (you’ll be able to choose which one)
Use the familiar lightning bolt button next to the Default Content field to select the data-source.
Read Only
Sometimes, you’ll need to display data – for example, in an edit form – which should not be edited. When you set a text field to be read-only, your data will be displayed but not editable by the end-user.
Multiple Lines
When you need to capture a lot of text – for example, a description of something – you can set a text field to allow for multiple lines. Text within a multi-line text field will wrap to fill the space provided.
Resizing a Text Field
To resize a text field component, click and drag on a corner of its bounding box. If your text field is single-line (the default setting), you’ll only be able to resize it horizontally. If your text field is set to multi-line, you’ll be able to scale it vertically too.
Text Field Properties
When a Text Field component is selected on the Canvas, the following settings are available in the Properties panel:
| Basic Settings | |
|---|---|
| Reference | A unique identifier for the Text Field. This is critical, as it allows you to reference the Text Field directly when mapping to and from a Data component, or inserting data into emails and documents. |
| Data Type | The type of data that you expect to be collected in this text field. Leave this as Plain Text if you’re not sure, or if you don’t really mind. Additional options for Email, Password, Telephone and Post Code are also available. |
| Placeholder/Label | If you choose not to use a separate label for this text field, you can have the label appear as a placeholder within the field itself. It is recommended that you use a separate label if possible, as the placeholder disappears as soon as the end-user starts typing into the text field. |
| Default Content | If your text field should already have a value in it when the screen loads, you can specify it here. Default content can either be typed by hand in the properties panel, or dynamically populated using a data-source. Use the lightning bolt button to specify the source. |
| Minimum Length | If you’d like to make sure your end-users input a minimum number of characters into this text field, enter the minimum number here. If this option has a value, Nutshell will validate your end-user’s input regardless of whether validation is turned on. If this option is left blank, it is simply ignored. |
| Maximum Length | If you’d like to make sure your end-users don’t input more than a maximum number of characters into this text field, enter the maximum number here. If this option has a value, Nutshell will validate your end-user’s input regardless of whether validation is turned on. If this option is left blank, it is simply ignored. |
| Allow Multiple Lines (wrapped) | If this option is enabled, your text field can be used to capture larger strings of text across several lines. Anything the end-user enters will be wrapped to fit the text field. This option is turned off by default. |
| Read-only | If this option is turned on, the text field will not be editable. This is useful when editing records where some information is allowed to change, and other information should not change. |
| Validation Settings | |
|---|---|
| Required Field | If enabled, Nutshell will not allow the end-user to progress along the workflow until this text field has a value. |
| Validate Field | If enabled, Nutshell will not allow the end-user to progress along the workflow until this field has a value that matches the given validation rules. |
| Automatic | Available if Validate Field is enabled. If your text field is set to Email, Telephone or Post Code, and this option is enabled, Nutshell will validate the input automatically for you. |
| Custom | Available if Validate Field is enabled. If your text field is collecting data in a custom pattern, you can specify that pattern using a Regular Expression, and define an error message that will display if the end-user’s input does not match. |
| Styling | |
|---|---|
| Various | A host of options to style your text field, that should be pretty familiar if you’ve ever used a basic document editor like Microsoft Word. |
Just getting started? Try the Tutorials section for handy quick-start guides.
Prefer to watch the action? Try our series of short video tutorials.
Can't find what you're looking for?
If you can't find the answer to your problem here, please contact Nutshell's support team via our dedicated help desk.
Floor 1, Baltimore House
Gateshead, Tyne and Wear
NE8 3DF
United Kingdom