eloqua_api

-- SUMMARY --

This module gives developers an easy, configurable way to integrate Drupal forms
with the Eloqua automated marketing platform.  If you do not already have or are
not considering an Eloqua subscription, this module is not for you.  If you are
not a developer or you do not have a developer to help you integrate Drupal with
Eloqua, this module is also probably not for you.


-- INSTALLATION --

* Enable the module
* Give appropriate roles the "administer eloqua api" permission.
* Configure the module at /admin/config/system/eloqua-api/settings


-- CONFIGURATION --

At a minimum, you will need to set the following on the aforementioned
configuration page:

* The URL to which Eloqua data will be sent via an HTTP POST request.
* Your Eloqua Site ID.
* You will need to enable at least one form.

See the "usage overview" section below for more details on enabled forms.
Additional details on the "push defined values" check are also explained there.

You may optionally configure whether or not to log Eloqua form submittals.


-- USAGE OVERVIEW --

This module provides a function eloqua_api_post($params) that will perform
an asynchronous HTTP POST request to the URL specified on the module's
configuration page.  If you'd like, you may simply use this function in your own
custom module to post values to Eloqua.

Additionally, this module allows developers the ability to make forms Eloqua
aware by adding a small submit handler to all forms marked "enabled" on the
module's configuration page.  Depending on the value of "manual field mapping,"
it will either use the standard $form_state['values'] array or the custom
$form_state['eloqua_values'] array for parameters sent to eloqua_api_post().

By default, this module is set to use eloqua_values and the only exposed form is
the user registration form, so nothing will happen.

Please use the following code samples to guide your Eloqua integration.


-- CODE EXAMPLES --

You'll likely want to create a custom module that depends on this module. Here
are a few snippets to help you get started. Everything you need can be
accomplished with a few simple form alters.

/**
 * Implements hook_form_alter().
 */
function MY_MODULE_form_alter(&$form, &$form_state, $form_id) {
  switch ($form_id) {
    // Expose the form you want to the Eloqua API Configuration Settings.
    case 'eloqua_api_admin_settings':
      $form['eloqua_api_forms']['eloqua_api_enabled_forms']['#options'][] = 'MY_FORM_ID';
      break;

    // Add a validation function to the form you exposed above.
    case 'MY_FORM_ID':
      $form['#validate'][] = 'MY_MODULE_eloqua_validate';
      break;
  }
}

/**
 * Validation handler to map Eloqua fields to be pushed.
 *
 * This is where you define what fields will be pushed to Eloqua.
 */
function MY_MODULE_eloqua_validate($form, &$form_state) {
  // Maybe you want to send the e-mail address.
  $fields['mail'] = $form_state['values']['mail'];

  // Additional fields here...
  $fields['foo'] = $form_state['values']['foo'][LANGUAGE_NONE][0]['value'];

  // Add more fields here...

  // Add your field mappings here so the Eloqua API module sees them.
  $form_state['eloqua_values'] += $fields;
}


-- HIDDEN FEATURES --

In your settings.php file, you may set...

$conf['eloqua_api_skip_post'] = TRUE;

...in order to prevent form submittals from posting to Eloqua in your dev and
staging server environments.