Reference Guide
Detailed explanations of every feature and function in NutshellList Box
The List box component allows you to add both single- and multiple-select dropdown lists to your screens. You can add a List box to your app by dragging the List box component from the tool bar onto your screen.
List boxes are extremely flexible, with both single- and multiple-select modes
Required Fields
If a List box in your form is mandatory, Nutshell can automatically validate that an end-user has not left it blank. Just set the field to be a required field, and Nutshell will do the rest.
Managing List Items
You can specify the items that appear in your list manually – by entering them by hand in the Properties panel – or dynamically from a data-source, such as a Nutshell database table.
To add your list items by hand, make sure the Static Items option is selected, and add items to the list using the little “+” button.
List items and default selections are managed in the Properties Panel
Each list item has an Option and a Value. The Option is the visible label that will appear in the dropdown list on-screen. The Value is the actual value that will be saved or processed when the form is submitted. You can set them to the same thing if you like.
If you’d like your list to be generated dynamically from a data-source, choose the “Dynamic from data source” option instead. This allows you to generate the list from a Database table, displaying every record in that table as an item in the List box.
Default Option
If your form is just capturing data, your List box probably won’t have anything selected by default. Sometimes it’s helpful to pre-select an item though – either by selecting it from the dropdown in the properties panel, or by selecting them dynamically from a data-source. What do we mean by dynamically? Dynamic data is content that changeable based on something your end-user does, or loaded at run-time from a database table.
You can choose which item should be selected by default when the List box appears on-screen
In the Properties panel, you can select which list item should be selected by default, either by choosing it from the dropdown, or by selecting a value from a database record. Use the lightning bolt button to choose exactly which record. The process of dynamically populating components and form controls is detailed in Key Concepts.
Read-only
Sometimes, you’ll need to display data – for example, in an edit form – which should not be edited. When you set a List box to be read-only, your data will be displayed but will not be editable by the end-user.
Resizing a List Box Component
To resize a List box component, click and drag on a corner of its bounding box. A single-select List box can only be resized horizontally. The height of a single-select List box is dictated by the number of items within it. A multi-select List box can be resized horizontally and vertically.
Alternative Content
There may be times when you need to display a different list of options based on the value of another field in your form. For example, if this List box displays a list of car models, which models are displayed might depend on the value of another List box, containing a list of manufacturers.
List boxes can display a different set of options based on the value of another list box
Imagine that your Manufacturers List box contains two items: Audi and BMW. When Audi is selected, you’ll want to display a list of Audi models in the second List box, whereas if BMW is selected, you’ll want to display a list of BMW models.
To define an alternative list, click on the Default List dropdown in the Properties panel. At the bottom, you’ll see an option to Create Another List. Select this option, and you be asked to give it a name and set some dependencies for it.
Just create another list for each value in your first List box
A dependency is a rule that must be met before a given version of the list will be displayed. An example dependency would be: use the Audi version of this list if the Manufacturers List box is set to Audi, and use the BMW one if it’s set to BMW.
List Box Properties
When a List box component is selected on the Canvas, the following settings are available in the Properties panel:
| Basic Settings | |
|---|---|
| Reference | A unique identifier for the list. This is critical, as it allows you to reference the list directly when mapping to and from a Data component, or inserting data into emails and documents. |
| Placeholder/Label | The text that appears on a List box by default when the List box does not have a default value specified. For example: “Please select…”. This option only applies to single-select List boxes. |
| Select One Item | Selected by default. If this is enabled, the end-user can only select a single item from the List box, which will appear as a dropdown list. |
| Select Multiple Items | If this option is enabled, the end-user will be able to choose more than one item from the List box, which will appear as a box with list items visible on-screen. |
| Restrict users to how many items they can select | If this option is checked, the field will be validated automatically, and the end-user will not be allowed to progress along the workflow until an appropriate number of items have been selected. You can then enter a minimum and maximum number of options for the end user to select from the List box. |
| List Items | You can specify your list items manually, by adding them to a list using the little “+” button. Alternatively, you can generate your list of options automatically from a Nutshell database table. In this case, you’ll be asked to specify which database table to use as the data-source. Every record in this table will be inserted as a list item when the app runs. |
| Default List | Since there can be several versions of a list, depending on the value of other components on the screen, this dropdown allows you to select which one you’re currently editing. By default, there is only one list – Default List – until you add more. When you add more lists, they’ll appear in this dropdown, so that you can switch between them. |
| Display this list if… | This is where you specify the dependencies for the list selected in the dropdown above. In essence, this is saying “Display this list if [another field on this form] is set to [a specific value]”. You can set dependency rules for every version of your list except the default one, which always acts as a fallback when none of the dependencies are met. |
| Default Option | Allows you to specify which of your list items should be selected by default when the form is displayed to your end-user. If your List box is a single-select, you can choose only one; if your List box is a multi-select, you can choose more than one. |
| Read-only | This option will only be available if you’re populating your List box from a database table. If this option is turned on, your end-user will not be able to alter the List box. 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 field has a value. |
| Styling | |
|---|---|
| Various | A host of options to style your single- and multi-select List boxes, 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