Creating Custom Fields
This chapter explains how you can collect information beyond that which CiviCRM allows by default through adding custom fields to hold the data you want to collect.
For example, you could add a set of checkboxes to organisations so that you could track the clients that they serve. You can also restrict custom fields to certain types of that object. For example, if you have a contact type Student, you might have a custom field listing the subjects they study.
Custom data fields are always stored as sets of custom fields in CiviCRM. Therefore, adding custom data is a two-stage process:
- Create a custom field set, which is simply like a container to hold these custom fields together.
- Add custom fields to this set. (You may find it helpful to read the information about custom fields first, but you will need to create the field set before you create the fields in it).
To clarify, a field is a unit of information entered into the database, such as someone's primary spoken language, or high school graduation date. A custom field set is a group of fields containing related data - that is, a set of fields related to a certain activity type, to participation in events, or to contributions.
Custom field sets
Custom fields are always part of custom field sets, and each set has a scope as wide or as narrow as you choose. For instance, you might associate a custom field set called "nationality" with all contact types, another set such as "immigration status" with a specific contact type (e.g. Individuals), and yet another set with a specific component (CiviMember, CiviEvent), or with other elements such as Relationships and Groups. The scope of a custom field set is one of the few decisions that is irreversible (you will not be able to change it after creating it) so it is important to consider carefully what you want to associate your custom field set with when you start.
When creating custom field sets, you should ask:
- How will the fields in this set be used?
- What types of contacts or records will these fields be appropriate for?
- Will the fields have broad applicability, or are they relevant to a specific Contact Type, Event, Financial Type, etc.? For example, a field which stores a person's entree choice at a dinner event should be assigned to the Participant record, and not to the Individual Contact record; this data describes the person as a participant in an event (they might not have or make the same choices for another dinner).
Taking the time to think through these questions helps keep your application screens as relevant and clear of superfluous fields as possible. For example, if your custom field set contains contact characteristics such as a field for the "color of eyes", you should associate them with the Individual contact type rather than the generic Contacts option, as this field would be irrelevant to Organization and Household contact types. Another example would be if custom data is specific to a particular event registration page. You should create this custom data for an Event type Participant for the specific Event.
Depending on how many custom fields you are creating, you should also consider grouping the fields topically. For example, you may associate 20 custom fields with Individual contacts, 12 of which relate to an online membership directory. Rather than group all 20 fields in a single custom field set, you may want to split them into two sets - one for the directory-related fields, and a second for more general Individual details.
To create a custom field set and custom fields, go to: Administer > Customize Data and Scrreens > Custom Data. This screen lets you assign a title to the field set, specify what type of records it will be used for, select the display characteristics, and enter help text. The form appears in the following image, and we'll describe each field.
Set NameFor custom field sets which are displayed inline, this name appears as the legend of the field set. If this set uses the tab display style, the name appears as the navigation tab label.
Used ForYou can use this option to ensure that the fields appear only where they are relevant. The choices are:
- Activity: fields that may be assigned to all activities or to a specific activity type, such as Meeting or Phone Call.
- Addresses: creates an address block, which allows the administrator to create additional fields related to an address.
- Contacts: fields that may be assigned to all contacts.
- Contributions: fields that may be assigned to all contributions or to a specific Financial Type, such as Donations or Event Fees.
- Events: fields that may be assigned to all events or a specific event type (e.g., Conference or Fundraiser). These fields are applied to an actual event, not the participant registration record.
- Grants: fields specific to grants.
- Groups: displayed in the Group settings (note that these fields are not searchable).
- Household: fields specific to the Household contact type.
- Individual: fields specific to the Individual contact type.
- Memberships: fields that may be assigned to all membership records or to a specific membership type.
- Organization: fields specific to the Organization contact type.
- Participants: fields that appear on the participant registration record. There are three options for these: general fields applied to all registration records, role-type fields assigned to a specific participant role, and event participant fields assigned to a specific event.
- Pledges: fields specific to pledges.
- Relationships: fields that may be assigned to all relationship records or to a specific relationship type, such as "Spouse of" or "Employee of".
This controls the order in which your custom field sets are presented when you have created more than one set. Lower numbers (e.g. 1, 2) are displayed above higher numbers (e.g. 8, 9).
Each field usually contains a single option. For example, a person has either blue eyes or brown eyes, not both. However, some fields are more complex and may require multiple entries, such as a person's educational history. A single person may have multiple educational degrees, so a custom field set about educational history should allow multiple records.
CiviCRM provides this functionality for custom field sets assigned to contacts (whether to all contact types or to a specific type). To use this option, select the "Does this Custom Field Set allow multiple records?" option. This option has several restrictions:
- It is applied to the whole field set, not to a particular field.
- It must use tab display, not inline display.
- It can be used only for Contacts, not for Activities, Contributions, etc.
- It cannot be used in profiles, such as those used for Events.
- It cannot currently be exported.
Custom field sets for Contact records are displayed either "inline" on the contact summary page (the Summary tab), or as a new tab at the top of the contact record, along with Summary, Contribution, Group, Note, etc. We suggest using tab display for infrequently accessed fields and large sets of fields.
Custom field sets used for components, relationships, or other resources are always displayed inline. Also note that custom field sets configured to handle multiple records will be displayed in the Summary tab.
Is this Custom Field Set active?
If a custom field set is active, its fields can be viewed and changed. Otherwise, the fields are in the CiviCVRM system but hidden from the user interface. This option can be valuable for managing your data, especially if you are migrating from an existing database system.
For example, your existing database may have fields you would like to transfer to CiviCRM for historical data keeping purposes, but plan to then deprecate or migrate to a new data structure. Suppose you are importing membership records from an MS Access database. Each record in Access has a unique ID (key) field, which has no direct benefit in CiviCRM. Rather than ignoring it altogether, you could create a custom field to hold the value, import the records, and then disable the field (keep the Activate option unchecked), thereby hiding it from view and minimising the interface clutter.
Though not visible to users, the field value is stored in the system and can be referenced at a later date. For instance, if you ever need to investigate archived data for a possible discrepancy or compare the field value with a printed record.
Individual fields can be made inactive in the form defining those fields, once the custom field set is active.
Pre-form Help and Post-form Help
If you enter text in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field. Use help at this level to provide instructions related to the entire set of custom fields.
You can specify that you want the custom field set to be "collapsed" on initial display. If you check this box, only the title for this field set is displayed when the page is initially loaded, because the fields are hidden. This is helpful for field sets that are infrequently used because it reduces the screen real estate taken up when the page opens. A similar "collapsed" property is available for the display of custom data in Advanced Search.
Once you have created a custom field set, you can create custom data fields within the set. Click "View and Edit Custom Fields" followed by "New Custom Field" and you will see the screen in the image below. We'll explain each of the options in this section.
After completing the field configuration options, click 'Save' to record the field and return to the field listing for your current custom field set, or click 'Save and New' to save the field and begin defining a new field. You can view a listing of all the custom fields in a custom field set at any time by navigating to Administer > Customize > Custom Data and clicking 'View and Edit Custom Fields'.
With the exception of the data and input field type selection, all of the configuration options may be modified after your initial creation of the field. You may also find it useful to preview your custom fields, as well as the whole set of custom fields, as you are defining them. This is particularly useful for checking the layout of radio button and check-box fields with a large number of choices.
The text next to the field when displayed to the user. Text entered here is also the label shown when you export data. When using fields in a profile, you can overwrite the Field Label. So on this screen you can choose names that are suitable for administrators, and give more user-friendly names when exposing them in profiles.
Custom fields can be of many different types, many of which you've probably encountered when filling out forms on websites. When you create a custom field, CiviCRM presents a dropdown list of data types from which you can select that which best represents the data you plan to store. The menu on the left (shown open in the following figure) indicates the format of data you wish to store, whereas the menu on the right indicates the way you want to interact with the user.
The types of fields are:
- Alphanumeric (i.e. text and number fields), which can be of the following types:
- Text: a simple area in which users can enter text.
- Select: a dropdown box which limits choice to one selection.
- Radio: a list of options where you can make one selection. Unlike a Select box, all the options are visible on the screen at the same time.
- Yes and No: a special kind of radio list with two contrasting options.
- Check-box: a list of options that allows multiple selections.
- Multi-select: a list of options in a single box. You can select multiple selections using control+click.
- Advanced Multi-select: two lists side by side in which items can be moved from one to the other.
- Autocomplete select: an autocomplete widget. The user can start typing, and when the text entered uniquely identifies a selection, the field automatically fills in the complete selection.
- Note: a longer text box which allows multiple lines. Notes come in two flavours:
- plain, and
- rich text, which displays a WYSIWYG editor that allows HTML.
- Integer, i.e. a whole number. This can be displayed as a:
- text box
- select box
- radio list.
- Number: i.e. any number that includes decimals, such as 3.175. This can be displayed as a:
- text box
- select box
- radio list.
- Money: similar to a number, but treated according to the local currency as configured in CiviCRM's administrative pages. This can be displayed as a:
- text box
- select box
- radio list
- Date: a way of entering a date (and optionally time) value using a calendar widget. You can set a range of years which can be selected prior to and after the current date.
- State/Province: a list of available geographical locations as configured in CiviCRM's Localization settings (Administer > Configure > Global Settings >> Localization). Can be offered as either a select box or a multi-select box.
- Country: a list of geographical locations. Can be offered as either a select box or a multi-select box.
- File: offered as a browser where the user can select and upload a file.
- Link: an active internet hyperlink.
- Contact Reference: an autocomplete widget for an existing CiviCRM contact.
We suggest you experiment with creating different field types to get an idea of how they behave. Different options have implications for use. For example, check-boxes enable you to use OR as well as AND searches in Advanced Search, whereas multi-select will not.
Database Field Length
The database field length allows you to specify the number of characters that this field will contain. You should normally leave this at the maximum. In certain cases (for example if you are dealing with extremely large field sets) it might make sense to shorten this field to improve performance and decrease storage space, but setting a shorter length will not make a difference to the vast majority of users.
Controls the order in which the fields appear. You may assign the order in the field edit form, or use the up/down icons on the main field listing table to adjust the field presentation. By default, new fields appear at the bottom of the field list within a set.
Where applicable, you may designate a default value for a field. This value is automatically displayed or selected when users go to a form containing this field.
Pre-form Help and Post-form Help
Ideally, your field name is self-explanatory and users will immediately know what to enter. But in those cases where there is some ambiguity, or where you wish to help regulate how a certain field is used, you may enter help text here. If you enter it in Pre-form Help, your help text appears above the form field, and if you enter text in Post-form Help it appears below the form field.
The help text appears in all uses of the field in administration pages and is inserted as the default help text when fields are assigned to a profile (see 'profiles'). The person creating the profile can remove or change the help text there without impact on the original custom field definition.
When selected, a value must be provided for this field before the form can be submitted. Failure to do so will result in an error message directing the person to complete the required fields.
If you want a field to be required only when a user fills out a particular profile, you can leave this box unchecked and check the Required field later within the profile.
Is this Field Searchable?
Makes the field appear in a panel of custom fields in CiviCRM's Advanced Search page. While you may be tempted to mark every field as searchable, doing so may unnecessarily clutter the Advanced Search custom field panel, when in fact certain fields will probably never be used in that way. You may toggle this option on or off at any time, so do not be overly concerned about arriving at a final decision when you first define a custom field.
As with the active check-box in the form defining the custom field set, this box determines whether the field is disabled or enabled when CiviCRM displays it to the user.
This allows you to designate a field as visible but uneditable. There are two general uses for this field:
- To store data imported from another system that you want available for reference to the user, but do not want them to be able to modify.
- To store data that is controlled through a custom PHP hook rather than through the user interface. CiviCRM has a number of hooks defined that allow developers to modify data, as well as customise forms and screens, without modifying the CiviCRM code base. Read the chapter on hooks for more specific information.
Multiple choice options
For field types that involve selecting from a set of multiple options (such as Select, Radio, Check-box, Multi-select and Advanced Multi-select) you are given the choice of either using an existing set of options that you've already created for another custom field or create a new set. You can enter these values while creating the field, or enter the values later. The option's label is displayed on the form, while the option's value is stored in the contact record.
If you choose to use the same set of options for several fields, you will be notified when making any changes that this will affect an option set used by several fields.
When you create a new set, you have the option of initially entering up to ten multiple choice options in a table. If you need more than ten options, you can create an unlimited number of additional choices after saving this new field by using the 'Edit Multiple Choice Options' link. Go to: Administer > Customize > Custom Data > View and Edit Custom Fields > Edit Multiple Choice Options. You may go to this screen at a later date to modify the label, order and active status of any multiple choice option, or add more choices.
If desired, you can also mark one of the choices as the default option.
Inactive options are hidden when the field is presented.
Choosing between fields, groups and tags
Data fields, groups and tags are three major ways to associate information with contacts. Although it can be tempting to create a custom data field for every attribute of your data, take time to learn about the alternatives. They offer powerful functionality that you may miss out on if you rely only on custom data. Furthermore, using data fields for information where they could be stored more appropriately as groups or tags can slow your system. Finally, proper use of groups and tags makes it much easier for administrative staff to maintain the records.
Some tips that may help you choose are:
- Data that can take a wide range of values, such as a person's address or biography, should be stored in an alphanumeric custom data field.
- Custom data fields can be grouped and displayed on their own tab on the contact's record.
- As the name implies, Groups are used to group contacts. For instance, you'll probably assign board members to one group, staff to another, volunteers to a third, and so on. If you use Drupal, you can assign permissions based on group membership. You can also define a group that CiviCRM automatically adds contacts to and deletes contacts from, based on some characteristic. This feature is called a Smart Group.
- If you plan to use CiviMail for mass mailings and you want certain contacts to get a particular mailing, those contacts must be assigned to a Group. For instance, you may want a press release to go only to certain contacts; those contacts should be assigned to a particular group. This group could be a Smart Group.
- Both Tags and Groups can be structured hierarchically. For instance, a group or tag labeled 'Regions' can have a subgroup or subtag for each geographic region your organisation covers (see "Case study in hierarchical tags" later in this section).
- Tags support more powerful search options than data fields or groups. For instance, visitors can search through multiple tags with both AND and OR operators. Data fields support only lists of words (which is effectively the same as an AND operator), except for fields represented as check-boxes, which support OR operators.
- Tags have a more sophisticated user interface than data fields or groups. The interface allows the visitor to add and remove tags without reloading the page in edit mode.
- Custom data fields can be assigned to a specific record type (e.g., only households), whereas tags will be assigned to all types once the tags are defined.
Custom field set limitations
Bear the following in mind when creating custom fields:
- Limit the number of custom fields in a set to fewer than 40. If you have approached this total, we recommend you import some records and test operations like search and export before finalizing your database design and putting it into production.
Why? CiviCRM stores each custom field set as a MySQL table with a column for each custom field in that set. It is important to consider this as you plan your custom data 'schema', as it will have the same advantages and limitations as other MySQL tables. If you put too many fields in one set, you risk exceeding MySQL's limit for maximum row-size, which may present search and data export issues later on (creating more than 40 custom data sets may result in exceeding MySQL's maximum allowed number of left joins - 64 - when performing operations like exporting data). Consult the MySQL Reference Manual for more details.
- If you have manually customised fields with PHP code, these changes will not be maintaned through updates to CiviCRM. Please keep track of the developments, and re-apply them after updating. Standard custom fields are unaffected.
- Changes in custom field values over time are not tracked (unlike a contact's 'subscription history' for a group).
- Advanced search must be used to locate contacts based on custom field values.