This article covers all objects and field types that can be placed onto forms within the form builder. The mobile app supports some additional field types that are not supported on the web browser. These are noted in the table of contents list below.
Fields can be dragged out from the toolbox onto the form canvas. Once a field is on the canvas, tap on it to access the underlying field properties. Examples are shown below on both the web and mobile app interface:
Each form object has its own set of unique properties. Those are included in the corresponding descriptions of each field below. Some properties are common across all field types.
Common Field Properties
Field Name (data fields only)
The variable name was given to the field (data fields only). This is alphanumeric with no spaces. This is where naming conventions like CDISC or SDTM can be used.
Once data has been entered or the study version is published, the field name cannot be changed.
Reporting label
The more user-friendly name given to a variable/field. If this exists, it will be displayed throughout the system in place of the main Field name. Ad-hoc reporting and data exports display the field name by default.
Hidden
Hides the field in all scenarios for any user viewing the form in data entry (still shows in data exports). A common example/use-case:
Number field is being used to computed a value that users don’t need to see during data entry
Field Source Verification (FLSV)
Forces field level review for the workflow review level where FLSV is being enforced. This adds a ‘Lock’ icon next to the field when being viewed by the applicable review user.
Tooltip
Displays text to the user when hovering over the field with a mouse. Web support only.
Show in Log
Display the field in the log table if the field is part of a Log Form
Required
Make a data variable required when it's not being hidden. Error displays to the user when the field is left blank.
Conditional Actions
Create custom field logic and edit checks
Layout
Sizing in Width and grid location on the form
Note regarding field naming: When defining the variable name to be used for the fields on your forms, do not use any of the system’s Reserved Words
Labels (Non-data-storing objects)
Text Labels
Labels are used to identify items on a Form such as Section Headers or fields. Labels are used to identify a form field when a form is exported or used in reports. If Labels are long and cumbersome, Users can define a Reporting Label within the Form Field which will take precedence over the related Fields Label.
When a label or design tool is dragged and dropped into the form builder, the label or tool becomes active. To edit an existing label or design tool in a form, simply click on the label or design tool to make it active.
An active tool is designated by the field having a moving dotted line (marching ants!).
When clicked, the Properties for the label or design tool will display in the properties section of the Form Builder as shown in the figure below.
When a New Label is dragged into the Form Builder body/grid, the Text Editor pop-up window will display allowing the Label Text to be entered.
Properties specific to text labels:
Field
A label can be related to a specific data field, which will allow for the label to be hidden when a hide conditional action is added to the label’s associated field. The label associated with a field will be displayed as the data field's label in the data extracts if the data field does not have its own reporting label.
Include in Export
Allows the label to be exported in the data extracts.
In the example below, the weight field has two labels, but we want one of the labels to display in the data extracts next to the actual weight value. To do this, be sure the unit label is related to the weight field, and the box to Include in Export is checked.
When a label is exported with the data in the data extracts, it will have a column name matching that of the field it is associated with and an "_Label" attached to the end. For example, in the above image, the "Lbs" label will be included in the data exports next to the Weight value (PE_WT) and have a column header titled "PE_WT_LABEL".
Image Label or Spacer
Displays a static image similar to how a text label displays static text. To select an image to display within an image label, it first must exist in the central Image Library.
Spacer
If no image is defined for the image label, it will display as an invisible object which can serve to space objects apart from one another. When using an image label as a spacer, be sure to include the property “Upon Render, Omit Outline”.
Separator
A visual separator bar to split up sections of a form. There is no functional purpose of a separator. They can be conditionally hidden if needed.
Help Button
Help buttons can be used to embed reference information, such as documents, external URLs, or bodies of text into a popup window. They are useful to keep a form simplified and focused on the data entry, rather than putting large amounts of text directly onto the form.
The key factor of a help button is what will happen when the user taps on it. There are three options detailed more below. Those are:
Open a popup window containing pre-defined text
Open a new browser page/URL
Open a PDF Consent document
Properties specific to help buttons
Report Label
The text which displays on the help button itself
Display Consent PDF
Enabling this will map the button to the consent PDF defined within the Informed consent configuration settings. Usually mapped to the site-specific Informed Consent document that has been upload in the Site Documents Section.
The uploaded Informed Consent document that you upload in the site documents must not have any spaces within the file name.
Webpage URL
Opens a specified web URL in a separate tab for the user’s reference. Alternative to linking to a public URL, read how to create custom web pages within the system to create links to.
When defining a URL in the help button properties, the complete URL must be defined. Example: http://www.crucialdatasolutions.com .
Not including the protocol (typically http or https) will prevent the page from opening.
Quick Help Text
Opens a window with help text for the user to read
The option to display consent PDF will override the other options (displaying a web page or help text)
Table (Normalized Table)
A Normalized Table is a sub-form used to log repeating records of data within a single ‘Parent’ record where the table exists. A common example is the medical history form. Medical history is normally collected just one time during a subject's screening, but the amount of data collected is unknown, so it's often necessary to have a table within the form so the user can enter data all at once. The alternative to this is a Log Form where the user can enter a record, save and then enter a new record.
Normalized Tables can be dynamic or fixed. By default, they are dynamic where the user adds rows on-demand. If set as Fixed, a pre-defined number of rows will be displayed, and the user will be unable to add new ones.
When a Normalized Table is dragged and dropped into the body/grid of the Form Builder, the Form Fields dialog box opens to allow users to add Form Fields as shown below. Users can Drag and Drop Form Fields into the Normalized Tables Dialog box.
In the figure below:
Radio Group form field has been dragged and dropped into the Fields dialog box.
Displayed in the left column are the Form Fields properties that can be assigned to the field.
Each field that is dragged into the table has properties that can be edited the same way they normally would be. Select the field in the dialog box, go to the Properties section of the Form Builder and fill in the appropriate properties.
To add the column header, type in the Label column highlighted in yellow. If the header is long, you can use a <br> tag to break the text to a new line when it's displayed in the table. This prevents the column in the table from being too wide when the header text is long.
Field properties display in the left column as form fields are added to the builder. User’s select field properties by typing, clicking on links, or clicking on the properties.
Once the normalized table is created, users can single-click on the table to activate the properties panel. The properties for a normalized table are below.
Properties specific to normalized tables:
Fields
Select this to open up the list of field types that are included in the table, or drag out new field types to add
View/Edit
To edit the fields defined in a normalized table, click the View/Edit link. This link opens the normalized table’s Fields Definition dialog. The Fields Definition dialog allows the user to add Form Fields, Properties, and Type in Column Headers for a Normalized Table.
Maximum Rows
Will set the maximum number of rows that can be added to each defined normalized table. The maximum is 100 rows per table.
Report Name
Users enter names for each table to help identify the table when extracting data. For example, a user could enter Medications Table to signify that the information collected in this table contains Medications.
Fixed Rows
Users may want to have a normalized table that has a fixed and required number of rows. The fixed rows attribute allows the user to define a normalized table that has a fixed number of rows. The table determines how many fixed rows to have by the first column in the table.
When defining a Fixed Row table, the first column must be either a select (dropdown) or radio button field. These are the only two types of fields that have a fixed number of responses. The field choices will determine the number of rows in the table.
The figure below shows the structure of the normalized table in the Form Builder.
When rendered, the table looks like the figure below.
Notice there is no Add Row or Delete Row option for this table. Since the table is fixed in length, users cannot add or delete any rows. Each row is represented by a single value. That value is defined in the field choices of the first column of the table.
Each field choice is rendered into a row. Therefore, the number of field choices you have in the first column of the table determines the number of rows in the table. Remember each row is actually attached to the Field Choice Value. Therefore, changing the text of the field will change that for all defined tables. Likewise, deleting a field choice will delete all related rows in the rendered table.
Conditional Actions cannot disable or hide normalized tables on the form, but they can check a condition outside of the table. For example, checking to make sure data exists in the table if something outside the table meets a condition.
Data Fields (data-storing objects)
Text types
Text
When a text field is dragged and dropped into the form builder workspace or an existing text field is selected, the text properties appear in the toolbox as shown below. Text fields are designed to store single or multiple lines of alphanumeric text (unless a Field Mask is defined as discussed below).
Properties specific to text fields:
Maximum Length
The Maximum Length field allows the Form Designer to set the maximum number of characters allowed in the field. If the Maximum length is not defined, the default length is 10 characters. To designate a Maximum Length for the field, simply enter the desired number of characters for the field to accept.
Field Mask
The Field Mask allows the Form Designer to set a pattern of how the text should appear in the field when the data needs to be entered in a certain way.
For example, to create a text field to capture a telephone number, set the Maximum Length to 14. Then, set the mask so that the code appears as a telephone number (###-###-####). When a telephone number is entered in the form, only the numbers and not the dashes will need to be entered.
The characters on this page define what the user will be allowed to enter. Any other character used will be counted as a "literal" meaning it will be displayed as-is.
If the intention is simply to populate a text field fully, when the user does not need to enter any text of their own, field masking should not be used. The suggested method, in that case, is to use a text label and set the label to be included in the data exports.
Special Type
The Special Type dropdown control allows users to designate the field for a special purpose including:
Name of a randomization configuration - for populating a Randomization ID
Barcode (mobile) - Adds a barcode scanner to the field when displayed on the mobile app
ICD lookup - Allows a user to click on the field to open a quick search for ICD codes
Regular Expression (RegEx)
This allows a study designer to require specific formatting in a text field based on a predefined expression. Read here for more info about regex functionality.
A Regex error message can also be defined. This will fire as a query if the data entered does NOT match what the expression requires. Here’s an example:
RegEx Examples
Objective | Expression |
|---|---|
Only enter numeric characters 0-9 with a maximum limit of six characters | ^[0-9]{1,6}$ |
Alphanumeric string, upper and lowercase characters, with a minimum limit of 10 and a maximum limit of 20 | ^([a-zA-Z0-9_-]){10,20}$ |
Only allow 10 numeric digits | ^[0-9]{10}$ |
Must be a 10-digit US phone number with hyphens included | ^\d{3}-\d{3}-\d{4}$ |
Memo
The Memo Field allows for the storage of large amounts of alphanumeric information. Some typical uses for this data type would be notes, comments, or descriptions.
The Memo Properties enable the Form Designer to define how the memo field will be configured to capture the desired information. When a Memo form field is dragged and dropped onto the Form Builder body/grid, the Memo Properties appear in the Toolbox as shown in the figure below.
Properties specific to memo fields:
Maximum Length
The Maximum Length property allows the Form Designer to set the maximum number of characters allowed in the field. The system default is 3,000 characters. To set a different limit of up to 10,000 characters, enter a value in the Maximum Length property.
The Email Address Field is a text field designed to store text formatted as an email. Only syntactically correct email addresses are accepted in the field when the form is completed.
When an Email Address form field is dragged and dropped onto the Form Builder body/grid, the Email Address Properties appear in the Toolbox as shown in the figure below.
Properties specific to email address fields
Special Type
The special type selected here is Subjects Email.
Mask E-Mail
By checking this, the email will be masked with hidden characters when typing within the form.
Barcode (App Only)
A Barcode scanner is a text field with access to open a camera (when completed via the mobile app). When the camera is opened, it will scan for one of 21 different barcodes or QR types to pull the text automatically into the data field. Additionally, FDA device registry data can be automatically pulled into other fields on the same form if applicable.
To add a barcode field to a form, use the Barcode field within the mobile app form builder or a text field on the web form builder (with special property type “Barcode”)
Placing special type bar code scanning field steps. See figure below:
Select text field from the form properties area of toolbox
Drag field on the form and add a proper label
Name the field and reporting label
Set field length to proper length to fit in the entire bar code. Default is 10.
Select Special Type field called Bar code (Mobile) from the drop-down selection
Click the Save Form button
Here is an example of a form that collects a barcode value. On the TrialKit mobile app, users can directly scan barcodes into the form by tapping the barcode icon on the right side of the field.
Once a barcode is scanned, in addition to auto-filling the barcode field, the system can instantly access the FDA device registry to auto-fill other device-related data. An example is shown here:
To auto-fill device data from the FDA's database, the following field naming conventions must be used, where the items below need to be appended to the end of each of the corresponding fields:
_DEVBARCODE_003
_EXPIRATION_DATE_003
_LOT_NUMBER_003
_UDI_003
_ISSUING_AGENCY_003
_DI_003
_BRANDNAME_003
_VERSIONMODELNUMBER_003
_COMPANYNAME_003
_GMDNPTDEFINITION_003
Number Types
Number
Number fields store numerical values. Both decimals and whole numbers are supported. Which numerical format is accepted is determined by the Number Properties selected for the Number field.
Non-numerical values are not accepted in a numeric field.
When a Number field is dragged and dropped onto the Form Builder body/grid, the Number Properties (labeled #1 in the figure below) will appear in the Toolbox.
Properties specific to number fields
Maximum Length
The Maximum Length field allows the Form Designer to set the maximum number of numbers allowed in the field. If the Maximum length property is not defined, the default length is 6 numbers. To designate a Maximum Length for the field, simply enter a value in the maximum length property.
Decimal Places
The Decimal places field allows the Form Designer to define the number of places accepted after a decimal. For example: To set the number field to display 23.46, the Maximum length should be 5 and the Decimal places would be 2. If the Decimal Place property is not defined - the field defaults to zero.
Special Type - Horizontal Slider (Mobile)
Used to provide end-users the ability to slide an indicator on a horizontal slider. This is set on numeric fields only and can be used effectively on pain scale forms.
Slider (Horizontal Slider)
The non-scale horizontal slider allows a user to slide an indicator from left to right on a plain line (no markings) to get a value. The visibility of that value depends on the settings.
This is created within the web form builder by setting a regular number field with the special type property “Horizontal Slider”.
Vertical Slider
The Vertical Slider Scale (VAS) allows the Form Designers to provide a vertical scale in which the user on a mobile app can use their finger to slide on a scale to a particular value. The VAS could be used, as an example, to ask a patient how they feel today on a scale of 1 to 10.
Due to the touch requirement, this field type only renders on the mobile app. The web form will display as a numeric entry.
The unique properties for the VAS field are the following:
Tick Attributes - This allows the Form Designer to change the size, spacing, and number of ticks that will be displayed on the scale
Ball Size - Controls the size of the ball the user grabs and slides up and down.
Upper Descriptor - Sets the text to be displayed at the high end (top) of the VAS field
Lower Descriptor - Sets the text to be displayed at the low end (bottom) of the VAS field
Number of Steps - Works with the step increment to set the high value of the scale. For example, if you have 5 steps and 2 step increments, the top of the scale will be 10. If only 1 step increment was used, the max of the scale would be 5
Step Increment - How many steps will be shown on the scale. If 2 steps are used with 10 steps, the user will see 2, 4, 6, 8, …. all the way up to 20 for the max value of the scale
Start Step - The Form Designer can start where to start the bottom of the scale.
Score Box - When the user slides the scale up and down the value or “score” of where the slider stops is shown to the left of the slider control
Score Label Title - Allows the Form Designer to name the value or “score”. For example, Pain Scale
Hide Score Box - If “On” will hide the value or “score” of the slider from the user.
Pain Scale
A tappable standard numerical horizontal scale of 1-10 common for use in rating pain.
This can be added by setting a number field’s special type property to “pain scale”.
The field will render on a form only on the mobile app. The web will render this as a number field.
Other than size, there are no customizable parameters for this scale type.
Coded Types
Single-Select Dropdown
The Drop Down Field is used to create a list of choices from which a user may select when completing a form. When the user selects a choice the field displays that choice in the Drop Down field in the form.
When a Drop Down form field is dragged and dropped onto the Form Builder body/grid, the Drop Down Properties appear in the Toolbox as shown in the figure below.
Properties specific to Dropdown fields
Field Choices
The Field Choices dialog box allows the Form Designer to input a list of choices in the Dropdown field.
Clicking the View/Edit control will open the field choices dialog box shown in the figure above. The number that precedes the View/Edit control indicates the number of Field Choices available in the dropdown list.
Below is the field choice dialog box -To enter the dropdown choices, type in each of the desired choices in the Text column of the Field Choices dialog box. Press the Tab key to move to the Value column or the Enter key to move to the next row in the Text Column.
REMEMBER to click the OK button to close the dialog box and tap SAVE on the form.
Choices can be moved in order by dragging them into the list. Choice text and coded values can also be edited.
Important: The value must be a non-negative number starting with zero. No other limits exist regarding the order or sequence they must follow. These values can also be used in scoring scenarios where multiple different choice fields are factors in a computation somewhere else.
Batch Importing Coded Choices
Choices can also be imported in bulk if there are many to create. This is done via a 2-column CSV file. Read more here.
Special Type
Used to map the choices to one of the following:
Country List
Language List
Visit Interval
Inventory Lists
Medical Coding attributes
Local labs
Single-Select Radio
These are similar to the dropdown fields described above, but allow the user to see all choices on screen rather than first tapping to see all choices.
Properties specific to Radio fields
Orientation
The Orientation dropdown control allows the Form Designer to select how the Radio Group Field Choices will display on the form. The Orientation dropdown choices are shown in the figure below:
To select the orientation in which the Radio Group will be displayed, use the mouse to highlight and then click on the desired choice.
Horizontal – Selecting “Horizontal” displays the Radio Group field choices horizontally (across the page from left to right) as shown in the figure below.
Vertical – Selecting “Vertical” displays the Radio Group field choices vertically (down the page from top to bottom) as shown in the figure below.
Multi-Column – The Multi-Column choice is currently non-functional but is reserved for future use. It will be used in conjunction with the Group Property which is also currently non-functional.
Multi-Select Field
These are similar to single-select choice fields with both text and coded values, but they allow a user to include multiple choices in their selection which then get stored as comma-delimited codes. You can use one field object to handle scenarios where users might need to Select all choices that apply. This is alternative to having multiple check boxes which each act as separate variables.
A unique aspect of this field type is with its use when mapped to Inventory via its “special type” field property. It will display an icon next to it which opens a popup reference window of the inventory available at the current site. Example here:
Date/time
Date/Time fields are used to collect dates and/or times on a form. For all Subject CRFs, at least one of these is required.
Drag out as many date fields as needed:
For subject type forms, use the form properties to identify one of the date fields as the visit/transaction date.
This is the date field that the system will use to calculate visits or date windows as needed.
Properties specific to Date/Time fields
Date/Time Type (Time Control)
None - (Time only) Only the date will be entered by the user. This will need to be a complete date. If the user deletes a part of the date, the system will auto-fill it to make it a real date. This is the most common option used.
Time - (Date+time) Both the date and time will be entered by the user. Due to the field type, this must be a full date+time. Users will not have the option to keep either one blank if only part of it is known. To give users the option to add one or both, we advise splitting the date and time into separate fields or adding a checkbox for the user to tick if one portion is unknown.
Time with seconds - Similar to the Date+time field, but including seconds as well.
Time Only - The user will enter only a time
Time Only with seconds
Partial Date - Read more below
By default, all users on the system will see the 24-hour time format on all time fields. Users can independently change their preferences to the 12-hour format if they choose.
When users enter midnight as a time in 24-hour format, some users will input 2400 and others will enter 0000. If entering 24, the system automatically kicks the value down to the next acceptable value, 23. The accepted format for midnight is 0000.
Note, the appearance of the field in the form builder will not reflect the time control option chosen. The form can be tested in the Subject Manager to view how the users will see the field and do the data entry.
Partial Date
Users will be able to select a date and delete a part that is unknown. Any part of the date that is deleted will be auto-completed with zeroes. If the month is deleted, the day will also be automatically zeroed out. Partial Dates will only be displayed in the format, DD-Mon-YYYY. If a date field is set as the form visit/transaction date in the form properties, do not make it a partial date.
The system cannot use partial dates as the form's transaction date.
At this time you cannot do range checks or ANY conditional actions on Partial Date fields. (Planned update coming)
Do not change an existing time date field to a partial date. You need to delete and start with a new field AND A NEW FIELD NAME.
Checkbox
Checkbox Fields enable Form Designers to provide a number of fields from which multiple selections can be made and stored individually as “True” (checked) or “False” (unchecked).
Checkboxes are rendered in the Form Builder preview mode or on a form as a square box. A check is stored as a value of TRUE. Unchecked is stored as FALSE.
Checkboxes do not support the required attribute because a value of false is still a value.
A label describing each checkbox is normally displayed adjacent to the checkbox as shown in the figure below. A checkbox can be selected (or deselected) by clicking the mouse inside the checkbox field on the form.
When a Checkbox form field is dragged and dropped onto the Form Builder body/grid, the Checkbox Properties appear in the Toolbox as shown in the figure below.
Properties specific to Checkbox fields
Text
This sets a visual label to go with the checkbox (not shown in data exports). An alternative to this is by using a label separately like other field types. The difference is, using an embedded label via this property helps the form render the checkbox and label as one object.
Be sure the checkbox width is set long enough to support the text label if it is being used. Otherwise, the text may wrap underneath the checkbox
Paper Consent
Applicable for studies using eConsent, but where some patients in the study are providing consent via any other means.
Select this option for one checkbox on the form if the form where the checkbox resides is the registration form for the study. The system will use this to check if the patient should be forced to consent electronically or if consent is being provided another way (checkbox gets checked on the registration form for that patient).
Multi-Media Types
Audio, Image, and Video - App Only
Multi-Media Fields are for use with the TrialKit mobile application only!
https://crucialdatasolutions.atlassian.net/wiki/pages/resumedraft.action?draftId=227901506 fields that have a “Special Type” property (TrialKit mobile app only) that allows the Form Designer to capture data using the following media fields when the form is opened on a user's mobile app:
Analog Signature - Use finger/stylus to sign or scribble on a form
Audio Recording - Record audio to an mp3 file
Still Image - Snap a photo to a jpeg file
Video Recording - Record a video to an mp4 file
To set up one of these fields for use on mobile devices, use the Special Type property highlighted below for upload fields.
Each of the special type media fields will be displayed on the mobile app as shown below.
Analog Signature allows users to sign their screen or hand-held device and make a copy of their signature that can be attached to the patient record.
Audio Fields allows a user to speak into a hand-held device microphone and directly upload an audio file to a patient record. Tap the red record button to start recording, tap the square box to stop recording. Tap the play button to preview your audio. To re-record just repeat the steps.
Still Photo Fields allows a user to take pictures in real-time or select an existing photo from a camera roll and upload it to a patient record. Tap on the camera icon to take a photo from the device or select the camera roll icon to choose an existing photo from a hand-held device.
Video Fields enables the production and upload of a video into a patient record. Play the video by clicking the play icon.
Please note videos must be 60 seconds or less to upload successfully.
Signature
Allows for the user to draw a handwritten signature inside of a box. This gets stored stored as a .png image file with the form data.
Sketch Pad - App only
The Sketch Pad field allows the Form Designers to provide an area on the form where the user can “sketch” on top on a static/defined image.
Due to the touch requirement, this field type only renders on the mobile app. The web form will only display the background image itself, similar to an image label object. Users must be on the mobile app during data entry to draw on top of that image.
The unique properties for the sketch pad are the following:
Background Image - Allows the Form Designer to select an image to be displayed as the background of the Sketch Pad. The background images to choose from are in stored in the Image Library. Images will be sized to fit in the size of the Sketch Pad box. In other words, if the image is distorted, adjust the field size to the appropriate height/width.
Brush Site (1-20) - Allows the Form Designer to set the brush size that is used to draw on the Sketch Pad area.
Color (RGB) - The Form Designer can choose the color of the brush that is used when drawing on the Sketch Pad by sliding the amount of Red, Green, or Blue colors. A preview of the color will be shown in the properties panel. By default, the color is set to black.
Activity Ring - iOS Only
Allows the user who is entering data, when connected to an Apple Watch, to pull in activity data.
Upload
File Upload fields allow a data-entry user to upload a file within a form.
Please note there is a 200 Mb file size limit.
Review the image below for the following:
When a File Upload field location
Example after being dropped onto the form
The file upload properties appear in the toolbox as shown in the figure below.
During data entry the File Upload field displays a Choose File or Browse button depending on which browser is used. A user can click on the Choose File button and select a file from the desired directory or sub-directory within the user’s local computer/network.
This opens the file system on the computer to select a file. After selecting a file, tap the upload button
When the file has completed the upload process, the file name will be displayed below the Upload progress bar as shown in the figures below.
When the form is saved, the File Name and Date Uploaded window appears on the form as shown in the figures below.
The uploaded file can be accessed either directly on the form where it was saved or in the central Administrative File Repository
