Adding a Reference field

This article describes how to add a Reference field when designing a Form.

Reference fields are very useful fields which make it possible to connect Forms to other Forms or to the built-in Geographic database of ActivityInfo. Users can link their Records to the Records of another Form.

Using a Reference field and multiple Keys in the referenced Form, you can also create a 'cascading' effect to allow users to select from a series of options. See How to add a Reference field to reference many fields of another Form.

Reference fields or Selection fields

Reference fields and Selection fields are similar, as they allow you to create lists of options. However, they serve different purposes, therefore it is important to choose the appropriate Field type when designing a Form.

• Selection field: creating a list of options inside the Form
• Reference field: references another Form where each option is another Record. Here it is possible to include more information about that option (i.e. meta-data or other kind of information) in the referenced Form. You can use as many fields as needed to capture that information and by making them Key fields you can also bring that information into the initial Form (creating the 'cascading effect').

We strongly suggest you to consider the following best practices:

• Use a Single Selection field to capture a basic list of options that don't require further meta-data or additional information. Examples: age categories, list of options for biological sex, etc.
• Use a Reference field to link to a Reference Form where you will collect additional information for each option (Record). You expect changes to occur on that data (data is described as dynamic rather than static) and you need to link to these options in many Forms in your Database in a consistent way. Examples: partner organizations, list of institutions/entities, etc.
• When referencing a Form, users are able to select from a list of options added to that Form using the Reference field. To limit the options that appear to them to selected options you can set validation rules to the Reference field.
• You can add a prefix to the Serial Number to customize it and make it more readable for your users. This allows you to show - without revealing much information- what the Record is about, if you choose to use the Serial Number as the common reference.
• The maximum length of the characters of a Key field to appear in a dropdown result of a Reference field is 128 characters.

How to add a Reference field to reference one Record of another Form

To add a Reference field, follow these steps:

1. In the Form you want to refer to, make sure you have defined as Key field the field that users will select from. To do so, open the Form Design page of that Form, click on the field, check "Key" and save the Form.

By default, Key fields are used to look up a specific Record in a Form. Alternatively, select the Fields you wish to include in a look up or add your own custom Formulas.

When designing a Form, you can configure what fields on a reference Form may be useful for lookup and the order of displaying them. These may or may not be key fields, or may be just a subset of key fields.

2. Navigate to your Form, and in the Form Design page, click on "Reference" to select it from the Fields palette.

3. Select the Form that contains the Records you want to link to. The Forms of the current Database are shown first. To find a Form in another Database, click on the arrows to reveal the contents of each Database.
4. Click "Continue".

5. Fill in the Properties of the Reference field by providing:

• Label: type the question for which the user will select an option
• Description: optionally provide a description
• Code: optionally provide a code

6. In the "Settings" check the boxes you want to apply for the field.

7. Click "Done" to add the Field.
8. Continue adding Fields to your Form. When you finish adding Fields, click on "Save" to save the Form.

Record Entry

While adding Records, users can select a Record out of the list of Records of the referenced Form.

In this example, the referenced field is a Single Selection field, defined as a Key field. That is why users see the specific options in the dropdown list.

When lookup fields are defined, the options shown in the dropdown correspond to the lookup fields defined by the Form designer.

How to add a Reference field to reference many fields of another Form (cascading effect)

When the referenced Form has more than one Key field, users select a value for each Key field in turn. Each choice narrows down the options of the next Key field. This is called the 'cascading effect'.

1. In the Form you want to reference, define as Key fields all the fields you want your Form to refer to.

2. Add the Reference field to your Form by following steps 2 to 8 of How to add a Reference field to reference one Record of another Form.

While adding Records, users see one dropdown list for each Key field of the referenced Form. After users select a Province, the list of schools only shows the schools of that Province.

In this example, the referenced Form has three Key fields:

• a Reference field, "Province", which references a Form of provinces
• a Text field, "School name"
• a Single Selection field, "Classroom type"