Expose Contribution Pages as an Entity

Rocxa had done this on our site already on the 1.x branch. Here's a patch that includes some of the additions for the 2.x branch.

I haven't added the field formatters, I'm not quite sure what to do there yet. But hopefully someone can build on this patch to implement the feature fully.

(It looks like access is controlled is duplicated in civicrm_entity_access and civicrm_entity_op_access at the moment? Since civicrm_entity_access looks like it's outdated should we open a separate issue to remove it?) - see #2505111: Access control is duplicated

@markusa - this looks OK to me - do you have any comments on the formatters?

Re separate ticket - I haven't got my head around the permissions you mention - but yes probably worth documenting & discussing in a ticket.

Ok, so each entity had its own function to set which fields should use what kind of formatter.

Since civicrm data on these entities are properties and not fields, you cannot use the set of standard field formatter hooks that the Drupal API provides.

For this reason, had to set custom display settings in a display suite hook. This functionality is only available with the display suite module enabled. checkout the api documentation:
http://www.drupalcontrib.org/api/drupal/contributions!ds!ds.api.php/func...

implemented around line 1870

/*
 *  Implements hook_ds_fields_info()
 *  setup custom display suite "field" handling for CiviCRM properties
 *
 */
function civicrm_entity_ds_fields_info($entity_type) {

so here for each property of an entity we can add display suite display formatting options.

we do so and we also define a rendering function _civicrm_entity_render_fields

  // Basic wrapper and class settings for all CiviCRM properties, also makes the label visibility work
  foreach($properties as $name => $settings) {
    $fields[$entity_type][$name] = array(
      'title' => $settings['label'],
      'field_type' => 2,
      'function' => '_civicrm_entity_render_fields',
      'properties' => array(
        'settings' => array(
          'wrapper' => array('type' => 'textfield', 'description' => t('Eg: h1, h2, p')),
          'class' => array('type' => 'textfield', 'description' => t('Put a class on the wrapper. Eg: block-title')),
        ),
       'default' => array('wrapper' => 'div', 'class' => 'civicrm-field'),
      ),
    );

this bit at the end calls a function to decide which function to call for what entity, to manually set each field's formatter by property

so

  //add specific property formatters
  _civicrm_entity_add_formatters($entity_type,$fields);

So I see in the patch that a new case was added for the contribution pages and the function created.

Good to go.

now I'd install the devel module then dsm($fields) and see what all you're working with.

I wrote general functions to add the formatter types, you just need to create the arrays for each type and call the functions.

3 types of formatters:
1)Link fields -- these are used to output a link to another civicrm entity, like the contact_id property on a contribution can be rendered as a link to the contact view page.

The contact entity formatter assigning function is a good example of what to do.

function _civicrm_entity_contact_formatters(&$fields){
  $link_fields = array(
    array(
      'link_field' => 'employer_id_contact', //property name
      'target' => 'civicrm_contact', //target entity machine name
    ),
  );
  _civicrm_entity_link_addformatters('civicrm_contact',$link_fields,$fields);
  $option_fields = array(
    'preferred_communication_method', //property name
    'prefix_id',
    'suffix_id',
    'communication_style_id',
    'gender_id',
  );
  _civicrm_entity_option_addformatters('civicrm_contact',$option_fields,$fields);
  $yes_no_fields = array(
    'is_deceased', //property name
    'do_not_email',
    'do_not_phone',
    'do_not_sms',
    'do_not_trade',
    'do_not_mail',
    'is_opt_out',
    'is_deleted',
    'contact_is_deleted',
  );
  _civicrm_entity_yesno_addformatters('civicrm_contact',$yes_no_fields,$fields);
}

So whatever fields are ids that match to another entity could be suited to be a link field.

 array(
      'link_field' => 'employer_id_contact', //property name
      'target' => 'civicrm_contact', //target entity machine name
    ),

2)Options fields are fields that are civicrm select list options fields, which can be queried with the api getoptions call

3)yes_no_fields are properties that are booleans.

So just create some arrays with the same structure with the same names and call the same functions except use the contribution page entity machine name as the first parameter like so to add the yes no field formatters:
_civicrm_entity_yesno_addformatters('civicrm_contribution_page',$yes_no_fields,$fields);

Link field candidates:
financial_type_id
created_id
campaign_id

Options field candidates:
maybe payment_processor ? not too many options fields here.

Yes no field candidates:
any field starting with is_

I've been wanting to have time to look at redoing or "automating" what property gets what handler, but I haven't had the necessary time yet.

This will work for now, and does give the flexibility albeit with too much code

So just add the properties you want to use what formatter to arrays similarly as the functions for the other entities, and call the same functions, and you'll be good to go.

For people who want to make their custom fields have display formatters at this time could easily add a line or two in the module and have it.

So if you had custom fields on the contact entity, you could just add the custom field property names to the appropriate arrays.

For example if you had a custom field, with id = 1 and it was a select list or other options type field then add this:
'custom_1', //and this if custom field id:1 is a options type field
to the $options_fields array

function _civicrm_entity_contact_formatters(&$fields){
  $link_fields = array(
    array(
      'link_field' => 'employer_id_contact', //property name
      'target' => 'civicrm_contact', //target entity machine name
    ),
  );
  _civicrm_entity_link_addformatters('civicrm_contact',$link_fields,$fields);
  $option_fields = array(
    'preferred_communication_method', //property name
    'prefix_id',
    'suffix_id',
    'communication_style_id',
    'gender_id',
    'custom_1', //and this if custom field id:1 is a options type field
  );
  _civicrm_entity_option_addformatters('civicrm_contact',$option_fields,$fields);
  $yes_no_fields = array(
    'is_deceased', //property name
    'do_not_email',
    'do_not_phone',
    'do_not_sms',
    'do_not_trade',
    'do_not_mail',
    'is_opt_out',
    'is_deleted',
    'contact_is_deleted',
    'custom_2', //and this if custom field id:2 is a yes/no or boolean type custom field
  );
  _civicrm_entity_yesno_addformatters('civicrm_contact',$yes_no_fields,$fields);
}

Thanks for the detailed response markusa.

This is very naive, but where can I actually 'see' these fields in action to test them? Or if I dsm the $fields from _civicrm_entity_*_formatters, what page is that going to appear on. I can't see a way to 'create' the entities through the Drupal UI?

Answered my own question: I forgot to enable a layout in the 'Manage display' tab for the entity, so Display Suite wasn't active on the entity yet!

However I still can't see where these formatters are set / used in order to test them?

So you should have a path "/civicrm-contribution-page/1" where 1 is the id of the contribution page. That would be the view page.

Thanks markusa. New patch, now includes the template file that was missing. I think it's ready for review now.

@markusa - Can you let me know if you've had a look at this (& if you are feeling keen turn it into a PR on github - or else I'll do that part)

Sorry, I would have done it has a pull request. Perhaps it could be documented on the project page if PRs are preferable?

I've created a PR here based on #9 - patch #9 didn't apply against the 7.x-2.x branch on GitHub so I've refactored it.
https://github.com/eileenmcnaughton/civicrm_entity/pull/46

I've merged this - thanks for the fix!