Test Wiki

This is a copy of the UIowa Wiki and should only be used as a read-only reference as it will be periodically reset. No changes made here will be merged with the content in the production environment.

Last Sync with Prod: 6/13/2022

REDCap Documentation
Child pages
  • Embedding User Entered Values with Piping
Skip to end of metadata
Go to start of metadata

Table of Contents

What is Piping?

Piping is a capability within REDCap that allows a form designer to insert user entered values into the text of a data instrument or survey.  Using this feature enables the generation of dynamic questions that appear to be customized for a specific individual.  When used in surveys, this functionality can make  correspondence seem more personal.  Piping lets you use the value of a field immediately after the data has been entered and then it displays that value elsewhere within the form.  This process involves embedding the variable of the piped value within a label, question or response.

In other computer systems the term "piping" might be known as a tokens, variable expansion, keyword substitution or macro replacement.

Where can Piping be Used?

Piping can be used in most places within a form or a survey where you would ordinarily specify text that is displayed to the user.  More specifically, piping can be used in the following locations:

  • Field Label
  • Field Note
  • Section Header
  • Matrix Field Column Headers
  • Survey Instructions
  • Survey Acknowledgement text
  • Survey Invitation email subject
  • Survey Invitation email message

How do I Use Piping?

The syntax for piping is similar to that used for branching logic or calculated fields.  To use piping, simply specify the variable name within two square brackets "[]" and include that variable into any text string at the locations specified above.  For example, your form might contain a field with a "patient"

variable that collects the patient's name similar to the following:

Variable: patient
What is the patient's name?


Next, you might wish to use the patient's actual name within the text of the next question.  To do so, you would specify a field label that embeds the variable name "patient" within to square brackets similar to the following:

Variable: doctor
What is the name of [patient]'s doctor?


In the edit field dialog, the field label might look similar to the following:


The form inside of the online designer might look similar to the following:


As soon as a patient's name is entered, the field label that contains the piping variable will also display the value entered.  For example, during the data collection process via the "Add/Edit Records" page, data entry may look similar to the following:

Notice that the second field which contained a Field Label with Piping specified, now displays the actual value of the patent's name embedded within the question.

Examples using Piping

Some alternative uses of piping are illustrated below.  These examples can be easily used in your project by replacing the variable name with the one that exists in your form:

Piping ExampleWhere Used
[first_name], please complete the survey.Possible Survey Instructions displayed at the top of a survey before the first page.
Thanks [first_name] for taking the survey.Possible Survey Acknowledgement text displayed when the survey is completed.
Regarding [first_name]'s [visit_type]
with [doctor] on [visit_date]		Possible survey subject text regarding a follow-up survey after an appointment.
Dear [title] [last_name]:

Complete the survey concerning [child_name]'s
[visit_type] with Dr [doctor] on [visit_date].
 Possible survey message body text regarding a follow-up survey after an appointment.
When was [child_one] born?Possible question to help associate a specific child with a date field.

Longitudinal Piping

It is also possible to use piping in longitudinal studies.  In order to refer to a specific event, you must specify the event name in square brackets as a prefix to the variable name (also in square brackets).  For example, in order to refer to the variable "drug1" from "visit 1", you would specify "[visit_1_arm_1][drug1]".

Piping in a Report

It is possible to use piping in order to generate a simple report.  This report might be used to display the participant's previous responses or it might be used to verify the participant's answers prior to submission.  The "Descriptive Text" field type in REDCap would be ideal for displaying the text of a report.

Piping Report Example

You may use piping along with a small amount of HTML code in order to provide formatting for a simple report.  In order to build a report that may look similar to the following:


You would use the HTML specified below. Note: You may be able to use the following code as a template in order to build your own report.

Using HTML <div> Tags and Piping for Item Indentation
These are the medications from all your visits:

Visit 1:
<div style="margin-left: 30px;">[visit_1_arm_1][drug1]
[visit_1_arm_1][drug2]
[visit_1_arm_1][drug3]</div>
Visit 2:
<div style="margin-left: 30px;">[visit_2_arm_1][drug1]
[visit_2_arm_1][drug2]
[visit_2_arm_1][drug3]</div>
Visit 3:
<div style="margin-left: 30px;">[visit_3_arm_1][drug1]
[visit_3_arm_1][drug2]
[visit_3_arm_1][drug3]</div>

Piping Table Example

Alternatively, you may use piping along with a small amount of HTML code in order to display a simple table.  In order to build a report that may look similar to the following:


You would use the HTML specified below. Note: You may be able to use the following code as a template in order to build your own report.

Using HTML <table> Tags and Piping to Format a Report
These are the medications from all your visits:

<table border="1" style="border-collapse: collapse; border: 1px solid black;">
   <thead>
      <tr>
         <th style="padding: 4px; background: lightgray; text-align: center; font-weight: bold; vertical-align: middle;">
            Visit 1
         </th>
         <th style="padding: 4px; background: lightgray; text-align: center; font-weight: bold; vertical-align: middle;">
            Visit 2
         </th>
         <th style="padding: 4px; background: lightgray; text-align: center; font-weight: bold; vertical-align: middle;">
            Visit 3
         </th>
      </tr>
   </thead>
   <tbody>
      <tr>
         <td style="padding: 4px;">
            [visit_1_arm_1][drug1]
         </td>
         <td style="padding: 4px;">
            [visit_2_arm_1][drug1]
         </td>
         <td style="padding: 4px;">
            [visit_3_arm_1][drug1]
         </td>
      </tr>
      <tr>
         <td style="padding: 4px;">
            [visit_1_arm_1][drug2]
         </td>
         <td style="padding: 4px;">
            [visit_2_arm_1][drug2]
         </td>
         <td style="padding: 4px;">
            [visit_3_arm_1][drug2]
         </td>
      </tr>
      <tr>
         <td style="padding: 4px;">
            [visit_1_arm_1][drug3]
         </td>
         <td style="padding: 4px;">
            [visit_2_arm_1][drug3]
         </td>
         <td style="padding: 4px;">
            [visit_3_arm_1][drug3]
         </td>
      </tr>
   </tbody>
</table>

Warning Notice

In order to present the information in a more understandable fashion, the HTML code above was formatted using multiple lines and indentation.  However, internally REDCap embeds a HTML "<br>" tag (line break) every time a new line is specified in a descriptive text field type.  Before using the HTML above, make sure you remove all extra new lines and specify the table using only one line of code.  This can be done by pasting the code into an editor and joining the multiple lines of text into one long line before copying and pasting the code into the descriptive text's field label.  REDCap and HTML will ignore multiple spaces, so they do not need to be removed.

 

Advanced Piping Examples

Piping can also be used to define dynamic labels on radio buttons or a matrix.  Consider the following example where we are using three text box fields to specify the values for the labels of three radio boxes.  The form may look similar to the following example within the Online Designer.  Notice the piping used to define the labels of the radio button, the last field on the screenshot:


When the values are entered in the text boxes, they will be displayed as the labels for the radio buttons.  Notice that the radio buttons now contain the user entered values of "Yellow", "Blue", and "Red" in the screenshot below:

Piping could also be used in a matrix to define the row headers.  Notice the piping references "[color_one]", "[color_two]", "[color_three]" specified as the matrix field labels in the screenshot below:


After entering the data for those variables, the values will be displayed as the row labels for the radio buttons during data entry.  Notice the matrix field labels variables now display "Yellow", "Blue", and "Red" in the screenshot below:


Alternatively, piping could also be used to define the column headers in a matrix.  Notice that the piping references "[color_one]", "[color_two]", and "[color_three]" are specified as the matrix column choices in the screenshot below:


Following the data entry process, the expanded values are displayed as the matrix column headers.  Notice the user entered values "Yellow", "Blue", and "Red" are now showing as the matrix column choices in the screenshot below: