LabKey is changing the user interface for defining "domains", another name for the set of fields or columns in a grid of data. Each field, or column, can also have various properties and settings to control display and behavior of the data. Beginning with release 19.3.0, the following components will utilize the new field editor covered in this topic.
- Assay Designs
- Data Classes
- Sample Sets
- Site User Properties
- Study Additional Properties
- Extensible Table Definitions
Other components, including lists, datasets, issues, specimens will continue to use the
previous method of defining fields until a future release.
Topics:
Create New Fields
To use the Field Editor to create a new set of fields and their properties, you can follow this example for defining additional study properties. By default, there are no additional properties predefined in a study.
- Follow the instructions in this topic to install the tutorial study if you don't already have a study to work with.
- In your study, click the Manage tab.
- Click Edit Additional Properties.
- To get started, click Add Field.
- Give the field a Name. If you enter a field name with a space in it, you will be warned that SQL queries, R scripts, and other code are easiest to write when field names only contain combination of letters, numbers, and underscores, and start with a letter or underscore.
- Use the drop down menu to select the Data Type. Each data type can have a different set of properties you can set. Once you have saved fields, you can only make limited changes to the type.
- You can use the checkbox if you want to make it required that that field have a value in every row.
- Continue to add any new fields you need - one for each column of your data.
- Click Save to save and exit the editor.
Edit Fields
To edit fields, reopen the editor and make the changes you need. If you attempt to navigate away with unsaved changes you will have the opportunity to save or discard them. When you are finished making changes, click
Save.
Once you have saved a field or set of fields, you can change the name and most options and other settings. However, you can only make limited changes to the type of a field. You can change among text types, but cannot change a text field into a number or a boolean, for example.
Rearrange Fields
To change field order, drag and drop the rows using the six-block handle on the left.
Delete Fields
To delete a field, open the properties panel using the
and click
Remove Field.
Click
Save when finished.
Add Field Properties
Each field can have additional properties defined. The properties available vary based on the field type. To open the properties for a field, click the
icon on the right (it will become a
handle for closing the panel).
All fields have:
Text/Multi-Line Text/Flag Options
- Text Options/Multi-line Text Field Options/Flag Options: Maximum Text Length. Sets the maximum character count for the field. Options are:
- Unlimited
- No longer than X characters: provide a value in the box. The default is 4000.
- Name and Linking Options
- Conditional Formatting and Validation Options: Conditional formats and regular expression validators.
Boolean Options
- Boolean Field Options: Format for Boolean Values: Use boolean formatting to specify the text to show when a value is true and false. Text can optionally be shown for null values. For example, "Yes;No;Blank" would output "Yes" if the value is true, "No" if false, and "Blank" for a null value.
- Name and Linking Options
- Conditional Formatting and Validation Options: Conditional formats and regular expression validators.
Integer/Decimal Options
Date Time Options
User Options
Subject/Participant Options
Lookup Options
- Lookup Definition Options:
- Select the Target Folder, Schema, and Table from which to look up the value. Once selected, the value will appear in the top row of the field description.
- Lookup Validator: Ensure Value Exists in Lookup Target. Check the box to require that any value is present in the lookup's target table or query.
- Name and Linking Options
- Conditional Formatting and Validation Options: Conditional formats, regular expressions, and range validators.
Sample Options
- Sample Options: Select the sample reference for this field. You can choose to reference all available samples or select a specific sample type to filter by. This selection will be used to validate and link incoming data, populate lists for data entry, etc.
- Name and Linking Options
- Conditional Formatting and Validation Options: Conditional formats and regular expression validators.
Name and Linking Options
All types of fields allow you to set the following properties:
- Description: An optional text description. This will appear in the hover text for the field you define.
- Label: Different text to display in column headers for the field. This label may contain spaces. The default label is the Field Name with camelCasing indicating separate words. For example, the field "firstName" would by default be labelled "First Name".
- Import Aliases: Define alternate field names to be used when importing from a file to this field. Multiple aliases may be separated by spaces or commas. To define an alias that contains spaces, use double-quotes (") around it.
- URL: Use this property to change the display of the field value within a data grid into a link. Multiple formats are supported, which allow ways to easily substitute and link to other locations in LabKey. Learn more about using URL Formatting Options.
Conditional Formatting and Validation Options
All fields offer conditional formatting criteria and regular expression validation. Numeric, date, and user fields also offer range expression validation.
Create Conditional Format Criteria
- Click Add Format to open the conditional format editor popup.
- Specify one or two Filter Type and Filter Value pairs.
- Select Display Options for how to show fields that meet the formatting criteria:
- Bold
- Italic
- Strikethrough
- Text Color: Choose from the picker or type into the #000000 area to specify a text (or fill) color to use.
- You will see a preview of text on the right.
- Add an additional format to the same field by clicking Add Formatting. A second panel will be added to the popup.
- When you are finished defining your conditional formats, click Apply.
Create Regular Expression Validator
- Click Add Regex to open the popup.
- Enter the Regular Expression that this field's value will be evaluated against. All regular expressions must be compatible with Java regular expressions as implemented in the Pattern class.
- Description: Optional description.
- Error Message: Enter the error message to be shown to the user when the value fails this validation.
- Check the box for Fail validation when pattern matches field value in order to reverse the validation: With this box unchecked (the default) the pattern must match the expression. With this box checked, the pattern may not match.
- Name: Enter a name to identify this validator.
- You can use Add Regex Validator to add a second condition. The first panel will close and show the validator name you gave. You can reopen that panel using the (pencil) icon.
- Click Apply when your regex validators for this field are complete.
- Click Save.
Create Range Expression Validator
- Click Add Range to open the popup.
- Enter the First Condition that this field's value will be evaluated against. Select a comparison operator and enter a value.
- Optionally enter a Second Condition.
- Description: Optional description.
- Error Message: Enter the error message to be shown to the user when the value fails this validation.
- Name: Enter a name to identify this validator.
- You can use Add Range Validator to add a second condition. The first panel will close and show the validator name you gave. You can reopen that panel using the (pencil) icon.
- Click Apply when your range validators for this field are complete.
- Click Save.
Advanced Settings for Fields
Open the editing panel for any field and click
Advanced Settings to access even more options:
- Display Options: Use the checkboxes to control how and in which contexts this field will be available.
- Show field on default view of the grid
- Show on update form when updating a single row of data
- Show on insert form when updating a single row of data
- Show on details page for a single row
- Default Value Options: Automatically supply default values when a user is entering information or when imported data tables have missing values.
- Default Type: How the default value for the field is determined. Options:
- Last entered: (Default) If a default value is provided (see below), it will be entered and editable for the user's first use of the form. During subsequent uploads, the user will see their last entered value.
- Editable default: An editable default value will be entered for the user. The default value will be the same for every user for every upload.
- Fixed value: Provides a fixed default value that cannot be edited.
- Default Value: Click Set Default Values to set default values for all the fields in this section of the assay design.
- Miscellaneous Options:
- PHI Level: (Premium Feature) Use the drop down to set the Protected Health Information (PHI) level of data in this field. Learn about using PHI Levels in this topic: Compliance: Setting PHI Levels on Fields
- Make this field available as a measure: Check the box for fields that contain data to be used for charting and other analysis. These are typically numeric results. Learn more about using Measures and Dimensions for analysis.
- Make this field available as a dimension: Check the box for fields of non-numerical categories that can be included in a chart. Dimensions define logical groupings of measures. Learn more about using Measures and Dimensions for analysis.
- Make this field a recommended variable: Check the box to indicate that this is an important variable. These variables will be displayed as recommended when creating new charts or reports.
- Track reason for missing data values: Check this box to enable the field to hold special values to indicate data that has failed review or was originally missing. Administrators can set custom Missing Value indicators at the site and folder levels. Learn more about using Missing Value Indicators.
Related Topics
