OG Tasks Documentation

OG Tasks provides a mechanism to create tasks to be run for a group, either automatically on creation, or optionally once the group has been created.

Tasks are defined by way of a hook function, hook_og_tasks_info(). This function takes two parameters: $entity_type and $entity. Both of these parameters refer to the OG entity. The type is often "node" or "taxonomy_term", and the entity itself as an object is passed into the second param. They can be used to set up different tasks for different types of OG objects, for example.

The hook_og_tasks_info() function should return an array of og_tasks objects.

A typical hook_og_tasks_info function will look something like this:

/**
 * Implements hook_og_tasks_info().
 */
function my_module_og_tasks_info($entity_type, $entity) {
  $tasks = array();
  $path = drupal_get_path('module', 'my_module');

  // Navigation menu.
  $tasks['menu'] = new og_task(array(
    'title' => t('Create Navigation'),
    'description' => t('Creating a menu that is associated to the site that will drive the navigation.'),
    'required' => TRUE,
    'callback' => 'my_module_og_task_create_menu',
    'file' => $path . '/includes/menu.inc',
    'completed' => my_module_has_menu($entity),
  ));

  return $tasks;
}

Title and description are self-explanatory. The more important items follow.

Required determines whether or not the task runs automatically, or is optional. If it is set to "TRUE", then it will run on group creation; otherwise it will be available to manually run optionally at any time afterwards.

Callback is the function that the task will run. Generally, it's a custom function defined elsewhere in your module that performs tasks. In the example case above, my_module_og_task_create_menu() creates a menu for the group.

If the callback function is in an include, file defines where that is.

Completed defines an additional callback function, which returns a boolean indicating whether or not the task has been run. Essentially, after you write the primary callback function, you then write an additional function that checks to see whether or not the task has successfully completed.

Example Functions

Below are the sample functions referenced in our hook_og_tasks_info().
From my_module/includes/menu.inc

/**
 * Og_task callback to create a group specific menu.
 */
function my_module_og_task_create_menu($entity, $task, &$context) {
  my_module_add_term_menu($entity);
  $context['results'][] = t('Menu was created.');
  $context['message'] = t('Menu "@menu_name" was created', array('@menu_name' => my_module_term_menu_name($entity))) . ' ' . $task->title;
}

From my_module.module

/**
 * Determine if we have a menu set for a group.
 */
function my_module_has_menu($entity) {
  $menu = my_module_get_term_menu($entity);
  $parent_terms = field_get_items('taxonomy_term', $entity, 'parent_taxonomy');
  if (!empty($parent_terms)) {
    return TRUE;
  }
  else {
    return !empty($menu);
  }
}