Documentation

Creating forms in AbleOrganizer

Heads up! This is a long article that covers some important information about how to work with forms in AbleOrganizer. You can read through it, or jump ahead to information on specific topics:

One of the most powerful tools in AbleOrganizer is the dynamic form builder. This allows you to control the information you ask for along with each piece of content in your site.

With it, you can control what fields are contained in each form, what messages are displayed when the form is filled out, where people go afterwards, what information gets prepopulated into forms, and much more. The form builder was designed so that forms can be created through a web-based, drag-and-drop interface. No programming required.

Creating a new form

The form builder used by AbleOrganizer is called CRM Core Profile. Administrators can access it by going to admin/structure/crm-core/crm-core-profile. This screen will provide you with a complete list of the forms that are already built for your site. If you installed the sample content as part of AbleOrganizer, you will this screen already contains a number of forms. You can feel free to use the example forms as part of your website.

At the top of the screen, you will notice controls for creating new forms.

  • Add a new profile, which allows you to create a new profile.
  • Import a profile, which allows you to import forms created on other sites.

You can use these links when you are ready to create your own forms. Before going there, let's explain what all the options mean on the 

  • Machine name, which is a special code that is used for tokens within the system. You can use this machine name when you want to pre-populate some forms and reports.
  • Display, which provides some details about how users can access the form. More on that later.
  • Path, which lists the URL where the form can be accessed, provided it has been set up as a standalone form.
  • Status, which tells you whether or not the form is active. An inactive form is turned off throughout your website and will not display when attached to content.
  • Edit, which takes you to the edit screen for the selected form. The edit screen is described in detail below.
  • Settings, which takes you to the settings screen for the selected form. The settings screen is described in detail below.
  • Clone, which allows to create a copy of your form and save it as a new form.
  • Export, which allows you to export your form and use it on a new site. This is especially useful if you are creating your forms on a staging server and looking to move your forms to a production version of your AbleOrganizer site.

There are also links to the Edit screen and the Settings screen, which are used to control the information collected by forms and how they behave in your website. It's helpful to think about these screens in different ways. The Edit screen is where you control what is collected, and the Settings screen is where you control how the form behaves. 

The edit screen

The Edit screen is used to control what information is collected by your form. This is the first screen you will see when creating a new form, it allows you to give the form a name and specify the type of information you want to collect. It has a drag and drop interface for controlling the order of fields, which means you can also control how this form will look when it appears on a website. 

This screen will grow and add information dyamically as you select options for your form. When you are creating a new form, or editing an existing form, a number of form fields and vertical tabs will appear a the top of the screen that allow you to control the basic settings of the form. The screen will look similar to the one that appears below:

Adding entities to a CRM Core Profile
Click to expand

The way this part of the Edit screen works is simple to understand:

  • Give your profile form a name. The name should be descriptive and easy to identify when someone is selecting it from a list. 
  • Check the box to enable the form (if it is not already checked). This makes the form available for use within the system. When this is unchecked, the form will not appear anywhere in your site.
  • Select the information you want to collect in the form. CRM Core Profile is designed to collect information about contacts, activities, petitions and payments through your website (this list will expand over time). For each type of information, check the box to add it to your form, then select the type of item. For instance, if you want to add a contact, check the box to add a contact to the form, then select the contact type. You can add multiple types of information to each form.
  • When you select a type of information to add to your form, you will be presented with a list of fields to add to the screen. Select the fields you want to collect through your form.

As you add fields to your form, a list of form fields will appear beneath the basic controls. The list of form fields will look similar to the ones presented below:

Form fields on the edit screen
Click to expand

This list is a visual representation of your form. It allows you to control the order, visibility and default value of each field. The specific options that appear will be different depending on the type of being being added. CRM Core Profile provides support for most major field types that are used in Drupal, and can easily be extended to add support for new or unique field types that may appear on your site.

For each field, there are some basic options available to you. It's useful to understand the meaning of each form control:

  • The checkbox to the left of the field name controls the visibility of the field. When this box is checked, the field will be visible to your users. When this box is not checked, the field will not be visible but will still be part of the form. You can use invisible form fields to securely pass default values into AbleOrganizer without needing to worry about the form values being changed.
  • The field name appears next to the visibility checkbox. The field name lists the label associated with the field, along with the type of information it is associated with (in parentheses). This is useful for keeping track of fields with similar labels coming from different entities.
  • The hidden checkbox is used to make form fields hidden. This is useful when you need to set a default value from within the client web browser once a form is generated. 
  • Default value appears for most field types. With it, you can set a value to be used when this form is saved to the system. This field supports tokens and is especially useful in situations where you need to capture information from another entity when a form is saved (for instance, when someone pays for something through your form and you need to capture the amount of the transaction).

The settings screen - general settings

The Settings screen is used to control how your form behaves once someone submits a form. You can use this screen to set messages to display upon submission, control the page users are redirected to, control the options for contact matching, control whether or not the form is prepopulated, and more.

One thing that is important to understand about the settings screen is that the specific controls that appear depend upon what you have selected in the Edit screen. For instance, if you have not added a contact to your form, you will not be presented with controls for contact matching. Each set of controls is broken out into its own section, in order to make management a little simpler.

The display settings block controls how people will be able to access your form, what happens after it is submitted, and what messages appear for users when they submit the form. It will appear on the settings page for every form, and looks similar to what you see below:

CRM Core Profile settings screen - display settings
Click to expand

The controls here are pretty simple to understand:

  • Check the box to create a page if you are looking to present the form by itself. This is useful for creating contact forms on your website that will be presented outside of other content, and for creating forms for internally managing data about contacts.
  • The page title and the page path can be added to the form once you have checked the box to create a page. Use these to control the title associated with the page along with the URL used to access it.
  • Check the box to create a block if you are looking to present the form by itself within a block. The form will appear on the blocks page in Drupal, and you will be able to add it to any page in your system.
  • The block title field will appear when you select the option to add the form as a block. Use this to control the title of the block.
  • Redirect path allows you to control where users will be taken after completing the form. Enter a valid URL in this field to control this behavior. Leave this field blank to bring users back to the same page they used to fill out the form.
  • Message to users allows you to control the message that will be displayed when users fill out the form. Leave this field blank if you don't want to present a message - but, honestly, isn't it nice to say thank you when someone takes the time to fill in your form?

The settings screen - permissions

The permissions settings block allows you to control who can see your form. Permissions allow you to associate forms with specific roles in your system. You can select the roles that are able to access a specific form and all other roles will be denied access to the form. It is important to remember that, by default, the forms you create in CRM Core Profile can be accessed by anyone who can see the form. If you don't assign permissions to the form, potentially anyone with the link could be entering data in your system!

CRM Core Profile settings screen - permissions settings
Click to expand

The settings screen - contact matching

The contact matching block will appear when you are working with a form that collects information about contacts. It allows you to control how matching rules are applied to contacts. Select one of the options from this list in order to choose how the form will save contact data in CRM Core:

CRM Core Profile settings screen - contact matching settings
Click to expand
  • Most often, you will want to select the default contact matching rules. This simply applies the matching engines configured by default for CRM Core.
  • Not applying matching rules means that any contact information added to the system will simply be stored in CRM Core without checking to see if there is already a record for that contact. This is useful in situations where you need to collect information but don't really care about duplicates.
  • Selecting the matching engines to apply allows you to control what rules are applied when identifying matches. Support for this feature is incomplete, and it should be used with care when you have more than one matching engine configured for CRM Core.

The settings screen - prepopulating forms

The prepopulate form values block allows you to control whether or not a form is prepopulated when a user sees it. You can use these controls to fill out contact fields when someone comes to the form. Check the box at the top to prepopulate the form values, and a number of options will appear for how to prepopulate the form.

CRM Core Profile settings screen - prepopulate settings
Click to expand
  • Select the currently logged in user option if you want to prepopulate a form based on who is logged into the site. CRM Core Profile will find the contact record associated with a user account and use it to prepopulate the form.
  • User accounts passed through a URL will allow you to prepopulate a form using someone's unique user id. Use this option for internal management links that do not require someone to be logged in.
  • Contact ids passed through a URL will populate a form with information taken directly from a contact. Use this option for internal managament links that do not require someone to be logged in, which will be managed by someone with access to work with contact records.

The settings screen - advanced options

This article covers the basics of how to manage forms in CRM Core Profile. While managing forms may seem complex at first, the process becomes pretty simple once you get the hang of it.

The dynamic form builder includes a number of advanced tools that provide options beyond those listed here.

  • The form builder also allows you to add widgets for processing payments and displaying petition counters. These options are a little more complex and beyond the scope of this article. The example forms that ship with AbleOrganizer can help you to get started with these items.
  • For donation and event registration forms, you can include payment processing tools within the form itself. See the articles on each to understand the options.
  • If you are including a commerce item in your form, you can select the payment processors used to handle the payment.
  • Profile forms support the use of tokens. Tokens are codes that tell the system to prepopulate the values of fields based on other information stored in the system. Look for a token browser on the edit screen, which lists all of the tokens available for use.
  • You can export any form in the system for use on another site. You can export forms as code and simply import them into CRM Core Profile, or you can export them as part of a feature. Either approach works just fine.
  • It's often faster and simpler to clone an existing form and customize it to your needs than creating a new form from scratch. The example forms provided with CRM Core are good examples you can use for your own work.
  • Finally, the form builder used in AbleOrganizer is an open source project called CRM Core Profile. It is a module for Drupal that is continually improving. If the screens you see don't exactly match up with the ones presented in this article, don't worry - the same basic functionality will always be there. It just might be better.