Wish list (API changes)

Issue Summary

Here is a wish list for how DCL might better support a wide range of use-cases:

1. Include a low level API for importing contact (this actually exists): dcl_importer_get_contacts($login, $password, $provider). However, the return should not be array($names, $emails), but instead an array of objects/arrays with $contact->name, $contact->email[] , etc. Looking at the Google Data Contacts type could provide some guidance on what information should be associated with a Contact. The $provider parameter could be less cryptic than a single letter; at best, it would be the name of the class/provider file to be imported, or the identifier of a registered import provider (see below).
2. (lazy form) If the API call above (dcl_importer_get_contacts) is invoked with no arguments then it uses the current Forms implementation to prompt the user for contact information and provider. Of course given the implementation of Forms in Drupal this also means the form can be invoked on its own. One thing to think about is how the form knows about different provider implementations if they're external to the dcl_importer module; this can be accomplished of course with a new hook: (eg., hook_importer_register() -> array('name' => array('label' => t('Gmail'), 'callback' => php_callback), ...)).
3. Results manipulation: Include a multistep form/flow which takes an array of Contacts and allows a user to select up to N entries from their contact list. Returns up to N Contact entries. A good example might be the workflow in LinkedIn to send an email to your contacts (Compose Message): a list on the left, as you click/unclick, the results list on the right is manipulated.

4. Integration with the invite module should not be hard-coded in DCL-importer, or should at best be a configurable option. We have currently patched the module to do the following in dcl_importer_form:
   

   <?php
  
  // NOTE: Don't hard code this into the submit function:
  $form['#redirect'] = 'invite';
?>

   So we can override the redirect later if we want to alter the form. This also removes the call to drupal_goto in the function dcl_importer_form_submit. We did not remove the registration of the MENU_LOCAL_TASK but that could be made optional or removed as well.

   Another possible implementation would be to patch invite to expose a hook which could be invoked by dcl_importer and other modules to register a list of imported contacts after import. In the case of invite, this would simply set the appropriate $_SESSION entry.

5. The address ($login) manipulation which takes place in dcl_importer_form_submit should not take place there but should take place in dcl_importer_get_contacts; more precisely, it should be done by each provider module separately.
6. The provider API should be consistent; the dispatcher function dcl_importer_get_contacts should simply invoke the appropriate registered provider with the $login and $password and receive the contact list as a result. This should make it much easier to just plug in new provider implementations; in the best design, adding a new provider would mean absolutely no changes to the dcl_importer code. Provider registration can be accomplished by a hook in each new provider module (see above).

Please add more suggestions to the list and comments on these suggestions. If you've got patches please attach them as well. Can we flesh out the form of a Contacts object? Can we separate out each import provider into its own module implementing the provider hook?