Default refresh mode

When you work with remote entities (such as Characters, Guild and Items), if you don't like the default modes, you can write your own method for refreshing an entity. Three methods for refreshing entities are supported out-of-the-box and a threshold can be set.

  1. At loading time: each time you load a remote entity from the database, the lastFetched timestamp get checked, and the entity get refreshed from the battle.net API if needed (compared with threshold value). Because each time an entity needs an update, the loading hook make a remote API call, this mode is best suited for small guild website for instance where you need the last up-to-date information.
  2. Via cron: each cron runs, all remote entities that needs a refresh will be queued in a separate thread using the Drupal cron queue API. This allows long running tasks such as massive character update to be run in parallel for instance. This mode is best suited for both small guild website or large community website as the remote API call is defined.
  3. By code: this mode does not refresh the entity at all, developers that wants to provide their own methods can lock the module API into this mode for instance, and write their own implementation for character refresh. This mode is for website that need complete control over API calls.

Here is a list of instructions:

Install hooks

Set the entities you wants to control to custom mode. In your install hooks, you can do it by setting the variable following the pattern $entity_type . '_refresh_method'.

<?php
/**
 * Implements hook_install().
 */
function mymodule_install() {
  variable_set('wow_character_refresh_method', WOW_REFRESH_EXPLICITELY);
  variable_set('wow_guild_refresh_method', WOW_REFRESH_EXPLICITELY);
}
?>

Locking administrative UI

Once you set the method to refresh explicitely, it is a good practise to lock the administrator into this choice. Because the admin UI is a drupal form, you can easily hook it and flag the entity settings as locked.

<?php
/**
 * Implements hook_form_FORM_ID_alter().
 *
 * Locks the administrative UI to prevent settings the refresh mode.
 */
function mymodule_form_wow_character_admin_settings_alter(&$form, &$form_state) {
  $form['entity']['wow_character_refresh_method']['#disabled'] = TRUE;
  $form['entity']['wow_character_refresh_method']['#description'] = t('Refresh settings are managed by mymodule.');
}
function mymodule_form_wow_guild_admin_settings_alter(&$form, &$form_state) {
  $form['entity']['wow_guild_refresh_method']['#disabled'] = TRUE;
  $form['entity']['wow_guild_refresh_method']['#description'] = t('Refresh settings are managed by mymodule.');
}
?>

Use the refresh methods

By convention, entities that implements a refresh method should use the entity_type_refresh function. This method is a shorthand that calls battle.net API with If-Modified-Header set to the 'lastFetched' value. It is considered as good practise to use this header and Blizzard recommands it in their documentation.

You shall have a look at how wow_character_refresh() and wow_guild_refresh() are implemented for more information.

You may wants to overrides the CharacterController, you may have a look at hook_entity_info_alter() and the RemoteEntityController which implements some logic about remote entities. Beware that if you implements the controller from scratch, some of core functionalities may be broken. You should always run the test suit to check that your code is complient.