It's becoming a common request from our clients to find user-friendly ways to integrate CiviCRM data with the rest of their Drupal website functionality. Oftentimes content creators without direct user access to CiviCRM need to do simple things, such as create, update, and delete contacts in simple, specific ways. 

Example Use Case

A hypothetical organization advertises various community service projects that they organize and coordinate. Each service project can have it's own page, created by adding a Project content type to display a description, images, videos, slideshows or other information for each project. You'll probably use a View to show multiple Project listings on a page. All that is standard Drupal site building content and functionality. No problem.

But what if the organization wants to display to the user the Project Coordinator(s), which they also want to store in CiviCRM as contact(s)? Their Drupal website content creators need to be able to select, create, and update CiviCRM contacts for the coordinator on the Project node edit form. What if you also want them to create and manage simple CiviCRM Events through the same form? The website content creators are not given access to the CiviCRM backend. The organization wants the form to be styled like the rest of the Drupal site and be fully responsive.

Challenge

You have CiviCRM data that you need to use with Drupal's standard field and node display and theme structure. What to do?

The Solution

CiviCRM Entity to the rescue!

CiviCRM Entity is a Drupal module which exposes many CiviCRM entities as true Drupal entities. That means that almost any module that can use Drupal entities can also access and manipulate CiviCRM data, Drupal style. This includes many commonly used modules such as Views, Rules, Search API, Entityqueue, and many more.

You can use a standard Drupal Entity Reference field and integrate nearly 30 different CiviCRM entities in the standard Drupal way, into any of your node or entity infrastructures. Contacts, Addresses, Emails, Phone numbers, Events, Contributions, Memberships, Activities, and many more CiviCRM entities can be referenced in a consistent manner.

System Requirements

Drupal 7 and CiviCRM 4.4 or higher 

Install the following Drupal modules and their dependencies:

• CiviCRM Entity
• Entity Reference
• Inline Entity Form
• CiviCRM Entity Inline
• Display Suite
• Display Suite sub-module Display Suite Forms

Follow the instructions provided by civicrm.org for CiviCRM database Views integration. This is necessary for the stock Views integration, as well as some CiviCRM Entity related functionality (in this case the Entity Reference / Inline Entity Form autocomplete search tool).

The following instructions show how to configure an Entity Reference field with the Inline Entity Form widget to select, add, edit, and delete contacts for a hypothetical Project Coordinator field on a Project content type.

Project Coordinator Reference Field

Create a content type called Project, and go to the Manage Fields page for the new content type.

Next create a new field, Project Coordinator, that is of type Entity Reference, with widget "Inline entity form - Multiple values".

When you first add the field, configure it to have Target type of "CiviCRM Contact".

On the next screen, the field instance settings, you can configure settings for the Inline Entity Multiple Values widget.

Options include:

• Allow users to add new contacts
• Allow users to add existing contacts
• Autocomplete matching options (Contains or Starts With)
• Delete referenced contacts when the parent is deleted
• Override labels

Make sure to also set the Number of Values in the field settings to 2 or more, up to "Unlimited", when using the Inline Entity Form Multiple Values widget.

Configure Contact Add/Edit Form

CiviCRM Entity module exposes CiviCRM data as proper Drupal entities.  With Display Suite and Display Suite Forms enabled, you can manage what fields appear on your contact edit form.

Navigate to <site_root>/admin/structure/types/manage/civicrm_contact

Enable Display Suite handling of this form by selecting a layout from the "Select a layout" list, in the Layout for civicrm contact in form vertical tab. Save.

Now you will be able to hide fields from rendering on the edit form, leaving only those specific to the client needs.

A Dash of Code

For the Display Suite Forms settings to take affect in the inline entity form, we need to add a touch of code. This code should be added to a custom module, and once enabled, the inline entity forms will respect display suite custom form settings. Assuming your content type machine name is project, replace YOURMODULE with the name of your module, and $field_name with the name of the entity reference field which is referencing a CiviCRM entity. The class that is added to the attributes depends on the Display Suite layout being used. The code below is for the One Column layout.

// implements hook_form_FORMID_alter(). // form id in this example is project_node_form -- the form for the Project content type edit form function YOURMODULE_form_project_node_form_alter(&$form, &$form_state){ $field_name = 'field_coordinator'; if (isset($form[$field_name]['und']['form'])) { $form[$field_name]['und']['form']['#attributes']['class'] = array('ds-1col'); $form[$field_name]['und']['form']['#theme'] = array('ds_forms_custom_form'); } foreach($form[$field_name]['und']['entities'] as $key => &$entity) { if(is_int($key) && isset($entity['form'])){ $entity['form']['#attributes']['class'] = array('ds-1col'); $entity['form']['#theme'] = array('ds_forms_custom_form'); } } }

Permissions

The only CiviCRM permissions the content creator user role needs to fully use this functionality are:

• CiviCRM: view all contacts (To select existing contacts for a reference field)
• CiviCRM: edit all contacts (To create or edit contacts from the inline entity form for a reference field)
• CiviCRM: delete contacts (To delete contacts from the inline entity form for a reference field)

Notice that they do not require 'access CiviCRM' permissions.

Create a Project Node

You will now be able to Search for and select, create, edit, and delete contacts from the Project node add/edit form.

The edit widget for the entity reference field, with one contact already created:
 

Search for contacts by hitting the "Add existing contact" button:

Or add new contacts by hitting the "Add New contact" button. Enter the values and then click "Create Contact". Save the node for changes to take effect and the entity reference item label to appear.

Now the content creators can select, create, update, or delete CiviCRM contacts with ease and assign them as Project Coordinator(s) for the Project nodes! You can follow the same procedure for CiviCRM Events, and nearly 30 other entities. Cool, yeah?

Have fun with your own specific implementations!

Skvare is a leader in Drupal and CiviCRM integration. Contact us to get questions answered and for consultations to make the most of your Drupal and CiviCRM installation.