REDCap: Field Embedding

Field embedding allows you to customize the layout of your data collection instrument. Instead of all fields being stacked vertically on top of one another, you can use field embedding to position fields in tables or horizontally across the page. Field embedding is an advanced REDCap feature, but can be used without any knowledge of HTML, CSS, or needing to use action tags - you can embed fields just by using the rich text editor in the Online Designer. Field Embedding gives you a great deal of control over the look and feel of your instrument, allowing you to create tables or grids to make your instrument more compact, group related fields closer together, or create forms or surveys that are similar to existing instruments or templates that were designed outside of REDCap.

Field Embedding Fundamentals

Try Field Embedding With a Demo Project or Instrument

Use the demonstration field embedding project template:

Field embedding can be used in both new and existing projects. For new projects, or to try field embedding out, there is now a template project available in REDCap that demonstrates the setup for multiple uses of field embedding. To use this template, choose, "Use a template" when you create a new project, and choose "Field Embedding Example Project":

This image is described in the text above
How to create a new project using the Field Embedding Example Project template.

Upload a demonstration instrument to an existing project:

Alternatively, if you have a project already built or in progress, you can upload this example instrument which demonstrates the setup for a variety of field embedding uses. To upload the demonstration instrument:

  1. Save this instrument ZIP file: Download Field Embedding Demo Instrument ZIP
  2. In the Online Designer, choose the "Upload" button to upload the ZIP file for the instrument:

Choose the 'Upload' button from the 'Add new instrument' menu in the Online Designer
How to upload the demonstration instrument as a ZIP file in the Online Designer.

Basic Introduction to Field Embedding

Image showing the floating help box described
A valuable reference.

Tip: REDCap now has a floating help box, "How to embed a field elsewhere" that will show up in the Online Designer. Click on this box for detailed instructions and references when you're designing your instruments. There are also tan Field Embedding help icons located at the top of the page in the Online Designer, and in the "Edit Field" pop-up box. These help resources are developed by the REDCap Consortium to help end-users make full use of REDCap's advanced features.

Field Embedding Syntax

Field embedding works similarly to piping in REDCap. To embed a field, you will place the unique variable name in between curly brackets or braces, e.g. {first_name} and then insert it somewhere else.

Important: You must first create the field(s) that you want to embed. Once you have created the fields you intend to embed elsewhere, you can place them into a descriptive text field, the label of field, a section header, or into a choice label for a multiple choice question. When a field is embedded elsewhere, a green box will appear in the right corner indicating that the field is embedded.

Screenshot of a 'f_name' text-entry field and a 'l_name' text entry field.
Two fields (f_name and l_name) are created and embedded in a descriptive text field.
Edit Field screenshot with the Rich Text Editor Box Checked
The text labels and variable names are arranged in a descriptive field with a table, using the Rich Text Editor.
The 'First Name:' and 'Last Name:' fields are displayed on the same line.
Result: Both fields and their text labels appear on the same line.

Limitations of Field Embedding

Field embedding has some limitations that you must keep in mind when designing your instrument:

  • The field label you set for a field that is embedded elsewhere is hidden. Field embedding only re-locates the input section of a field. The field label is not also re-located. (Note: you may still choose to use a field label for an embedded field, but it will only be for reference to your study team during instrument design or data analysis.)
  • All the fields you are embedding have to be present on the same instrument.
  • If you are designing a multi-page survey (using sections to split the survey into multiple pages for survey respondents), then all of the fields you are embedding must be in the same section.
  • The Record ID field cannot be embedded.
  • You cannot nest embedded fields (e.g. you cannot embed a field in another embedded field or embed a field in itself.)
  • Field Embedding does NOT work in the Mobile App.

Tips and Tricks for Field Embedding

Using Branching Logic

Field embedding supports branching logic. You will set branching logic for the field that is being embedded, and the branching logic will operate at that location.

If a field is embedded and has branching logic, the branching logic for that field will operate as it normally does, in which the embedded field will be hidden when its branching logic evaluates to FALSE. Additionally, if the host field contains branching logic that causes it to be hidden, then all fields embedded within it will be hidden as well (since they are considered part of the host field). When the host field is being hidden, if any of the embedded fields inside the host field have a value, then the user viewing the data entry form (surveys are excluded) will be given the 'Erase current value of the field?' prompt for each embedded field. In this case, if the user responds to the prompt with 'Cancel' in regard to erasing the value of any of the embedded fields, then the host field will not be hidden but will remain visible.

Display Icons for Embedded Fields

Embedded fields default to hiding the icons that normally appear besides a field (data history, field comments or data resolution workflow, and missing data codes if they are enabled on the project.) If you would like the icons to be displayed for a field, append ":icons" to the variable name inside the curly brackets, e.g. {first_name:icons}. This will display the icons for that field. Note:If you know that you will need the icons to display next to the fields, it is recommended you that you add the :icons text to the embedded variable name early in your instrument design process, as the icons displaying can modify the precise formatting of the fields, especially for large grids or tables.

Image demonstrates the process described above
Appending ":icons" to the variable name in the curly brackets will display the normal field icons for an embedded field.

Use the @PLACEHOLDER Action Tag as a Label for Grouped Embedded Fields

When grouping related short-text fields together (e.g. first and last name, address fields, medication name and dosage) you may not want to insert label text before each text-entry box. However, you can use the @PLACEHOLDER Action Tag to supply "placeholder" text inside the field. This text will never be saved as an actual value, and will disappear as soon as someone starts entering data. If you are trying to creat a compact web instrument, this trick can save some space while still providing field label information to users entering data or survey respondents.

Screenshot demonstrates use of the placeholder tag described above
Example of using @PLACEHOLDER Action Tag in place of label text for grouped short-text entry fields. Note that the @PLACEHOLDER action tag is in the field of origin, which is embedded in a descriptive text field.

Best Practices and Recommendations for Using Field Embedding

  • Plan Ahead!Field embedding greatly expands your capability to design and format your instruments. Take time at the start of designing your instruments to consider how the entire instrument will flow, and what fields you want to embed. If you will be using branching logic or required fields, you can save time by planning ahead how you want your instrument to function.
  • Make sure to test thoroughly! Field embedding can add significant complexity to your instruments. With advanced formatting and field dependencies, there is more opportunity to introduce errors. It is always a good idea to thoroughly test your instruments, but especially when you are using advanced features like field embedding.
    • Test the display using a variety of devices and browsers. Anticipate the different ways the instrument may be used - e.g. if you anticipate study subjects might take surveys on a mobile device. Test the display of your instruments in several different browsers.
  • Don't leave embedded field labels blank. Although the labels for fields that you embed elsewhere will not be displayed in the instrument, it is best to include a short descriptive label. This label will show up in your codebook, data dictionary, and when you are editing your instrument in the Online Designer. This will be valuable documentation during both instrument design and data analysis. If you do not include labels, your codebook and data dictionary will become puzzles.
  • If you have questions or difficulties with using field embedding, reach out to SMPH REDCap support at redcap@ictr.wisc.edu

Examples of Using Field Embedding:

For detailed setup of the following examples, see the Field Embedding Demonstration Template or Instrument.

Example: Create a Table of Short Text-Entry Fields

Image provides an example of Short Text Entry Fields
Example of a table of short text-entry fields, allowing compact display of a large number of related fields.

Example: Create a Text-Entry Field for an "Other" Multiple Choice Option

Image demonstrates an 'other' multiple choice option
Example of using field embedding in a multiple choice option label to create a free-text field when 'Other' is selected.

Example: Create a Matrix with Multiple Columns

Example of a matrix with multiple columns
Example of using field embedding to create a matrix with multiple columns and data types.

Example: Group Related Fields Together

Example of field embedding where related fields are grouped together
Example of grouping related fields together to improve the flow of data entry.




Keywords:REDCap, Field Embedding, Tables, Formatting, Other   Doc ID:108574
Owner:Amy S.Group:SMPH Research Informatics
Created:2021-01-25 14:19 CDTUpdated:2022-08-09 14:11 CDT
Sites:Institute for Clinical and Translational Research, SMPH Research Informatics
Feedback:  0   0