modules/domain/API.php

<?php
// $Id: API.php,v 1.50 2009/11/01 16:30:55 agentken Exp $

/**
 * @defgroup domain_hooks Domain hook functions
 *
 * Core hooks for the Domain module suite.
 */

/**
 * @file
 * API documentation file.
 *
 * @ingroup domain_hooks
 */

/**
 * Notify other modules that we are granting access to a node.
 *
 * This hook allows Domain Access modules to overwrite default behaviors.
 * See http://api.drupal.org/api/function/hook_node_grants/6 for more detail.
 *
 * Note: In Drupal 7, this is a core feature.
 *
 * @see domain_strict_domaingrants()
 *
 * @param &$grants
 *  The existing default $grants, passed by reference.
 * @param $account
 *  The user object of the user requesting the node.
 * @param $op
 *  The node operation being performed (view, update, or delete).
 *
 * @return
 *  No return value. Modify the $grants array, passed by reference.
 *
 * @ingroup domain_hooks
 */
function hook_domaingrants(&$grants, $account, $op) {
  // Add a sample grant privilege to let a user see their content at all times.
  $grants['domain_example'][] = $account->uid;
}


/**
 * Notify other modules that we are saving node access records.
 *
 * This hook allows Domain Access modules to overwrite the default bahaviors.
 * See http://api.drupal.org/api/function/hook_node_access_records/6 for more detail.
 *
 * Note: In Drupal 7, this is a core feature.
 *
 * @param &$grants
 *  The existing default $grants, passed by reference.
 * @param $node
 *  The node object being saved.
 *
 * @return
 *  No return value. Modify the $grants array, passed by reference.
 *
 * @ingroup domain_hooks
 */
function hook_domainrecords(&$grants, $node) {
  // Add a sample access record to let a user see their content at all times.
  $grants[] = array(
    'realm' => 'domain_example',
    'gid' => $node->uid,
    'grant_view' => TRUE,
    'grant_update' => TRUE,
    'grant_delete' => TRUE,
    'priority' => 0,         // If this value is > 0, then other grants will not be recorded
  );
  // Remove the domain_site grant.
  foreach ($grants as $key => $grant) {
    if ($grant['realm'] == 'domain_site') {
      unset($grants[$key]);
    }
  }
}

/**
 * Notifies other modules that we are loading a domain record from the database.
 *
 * Modules may overwrite or add to the $domain array for each domain.
 *
 * When loading lists of domains or generating domain information, either use the proper
 * functions -- domain_default(), domain_lookup(), and domain_domains() -- or invoke this hook.
 *
 * Invoked by domain_lookup() and domain_default().
 *
 * @param &$domain
 *  The current $domain array.
 *
 * @return
 *  No return value.  The $domain array is modified by reference..
 *
 * @ingroup domain_hooks
 */
function hook_domainload(&$domain) {
  // Add a variable to the $domain array.
  $domain['myvar'] = 'mydomainvar';
  // Remove the site_grant flag, making it so users can't see content for 'all affiliates.'
  $domain['site_grant'] = FALSE;
}

/**
 * Notify other modules that we have created a new domain or
 * updated a domain record.
 *
 * For 'update' and 'delete' operations, the $domain array holds the
 * original values of the domain record.  The $edit array will hold the
 * new, replacement values.  This is useful when making changes to
 * records, such as in domain_user_domainupdate().
 *
 * @param $op
 *  The operation being performed: 'create', 'update', 'delete'
 * @param $domain
 * The domain record taken from {domain}, as an array.
 * @param $form_state
 *  The form values processed by the form.  Note that these are not editable since
 *  module_invoke_all() cannot pass by reference.  We set $form_state to an array
 *  by default in case this hook gets called by a non-form function.
 *
 * @ingroup domain_hooks
 */
function hook_domainupdate($op, $domain, $form_state = array()) {
  switch ($op) {
    case 'create':
      db_query("INSERT INTO {mytable} (subdomain, sitename) VALUES ('%s', '%s')", $domain['subdomain'], $domain['sitename']);
      break;
    case 'update':
      db_query("UPDATE {mytable} SET subdomain = '%s', sitename = '%s' WHERE domain_id = %d", $domain['subdomain'], $domain['sitename'], $domain['domain_id']);
      break;
    case 'delete':
      db_query("DELETE FROM {mytable} WHERE subdomain = '%s'", $domain['subdomain']);
      break;
  }
}

/**
 * Returns links to additional functions for the Domain Access module's admin screen
 *
 * Note that if your page requires a user_access check other than 'administer domains'
 * you should explictly check permissions before returning the array.
 *
 * @param $domain
 *  An array of data for the active domain, taken from the {domain} table.
 *    - domain_id -- the unique identifier of this domain
 *    - subdomain -- the host path of the url for this domain
 *    - sitename -- the human-readable name of this domain
 *
 * @return
 *  An array of links to append to the admin screen, in the format:
 *    - title -- the link title
 *    - path -- the link path (a Drupal-formatted path)
 *  The data returned by this function will be passed through the l() function.
 *
 *  If you do not provide a link for a specific domain, return FALSE.
 *
 * @ingroup domain_hooks
 */
function hook_domainlinks($domain) {
  // These actions do not apply to the primary domain.
  if (user_access('my permission') && $domain['domain_id'] > 0) {
    $links[] = array(
      'title' => t('settings'),
      'path' => 'admin/build/domain/myaction/'. $domain['domain_id']
    );
    return $links;
  }
  return FALSE;
}

/**
 * Enables modules to add additional parameters to the $domain array
 * for use by the Domain Navigation module.
 *
 * Used in cases where custom themes may require extra parameters.
 * This hook is called by domain_nav_render().
 *
 * Default parameters should not be changed; these are:
 *
 *    - domain_id -- the unique identifier of this domain
 *    - subdomain -- the host path of the url for this domain
 *    - sitename -- the human-readable name of this domain
 *    - path -- the link path (a Drupal-formatted path)
 *    - active -- a boolean flag indicating the currently active domain
 *
 * @ingroup domain_hooks
 */
function hook_domainnav($domain) {
  $extra = array();
  $extra['test'] = 'test';
  return $extra;
}

/**
 * Enables Domain Access modules to fire cron hooks across all
 * active domains.
 *
 * Each module implementing this hook will have the function run
 * once per active domain record.  The global $_domain variable
 * will be set to the current $domain passed as an argument.
 *
 * This function is especially useful if you need to run node queries
 * that obey node access rules.
 *
 * Note that Domain Prefix and Domain Conf are activated by this hook.
 * That means each domain will have its tables and variables loaded before
 * your function fires.
 *
 * @param $domain
 *  The information for the current domain record, taken from {domain}.
 *
 * @ingroup domain_hooks
 */
function hook_domaincron($domain) {
  // Run a node query.
  $result = db_query_range(db_rewrite_sql("SELECT n.nid FROM {node} n ORDER BY n.changed"), 0, 1);
  $node = db_fetch_object($result);
  // Set a variable for each domain containing the last node updated.
  variable_set('domain_'. $domain['domain_id'] .'_lastnode', $node->nid);
}

/**
 * Some Domain modules require that settings.php be edited to add
 * additional files during the bootstrap process.
 *
 * This hook allows those modules to check to see if they have been installed
 * correctly.  Usually the module is enabled, but the required function is not.
 *
 * @see domain_conf_domaininstall()
 *
 * @ingroup domain_hooks
 */
function hook_domaininstall() {
  // If MyModule is being used, check to see that it is installed correctly.
  if (module_exists('mymodule') && !function_exists('_mymodule_load')) {
    drupal_set_message(t('MyModule is not installed correctly.  Please edit your settings.php file as described in <a href="!url">INSTALL.txt</a>', array('!url' => drupal_get_path('module', 'mymodule') .'/INSTALL.txt')));
  }
}

/**
 * Allows Domain modules to add columns to the domain list view at
 * path 'admin/build/domain/view'.
 *
 * @param $op
 *  The operation being performed.  Valid requests are:
 *    -- 'header' defines a column header according to theme_table.
 *    -- 'select' defines a string of data to be returned.  Must be prefixed.
 *        The {domain} table is prefixed with 'd' -- do not select any columns
 *        from the domain table.  You must not select domain_id from your table.
 *    -- 'join' defines a sql join to use to pull extra data.  To properly enable
 *        sorting of all records, this MUST be a LEFT JOIN.
 *    -- 'data' defines the data to be written in the column for the
 *        specified domain.
 * @param $domain
 *  The $domain object prepared by hook_domainload().
 * @return
 *  Return values vary based on the $op value.
 *    -- 'header' return a $header array formatted as per theme_table().
 *    -- 'select' return a comman-separated list of fields to select from your table.
 *    -- 'join' return a LEFT JOIN statement for connecting your table to the {domain} table.
 *    -- 'data' return a $data element to print in the row.
 *
 * @see domain_user_domaininfo()
 *
 * @ingroup domain_hooks
 */
function hook_domainview($op, $domain = array()) {
  switch ($op) {
    case 'header':
      return array(array('data' => t('MyData'), 'field' => 'my.uid'), array('data' => t('MyName'), 'field' => 'my.name'));
      break;
    case 'select':
      return 'my.uid, my.name';
    case 'join':
      return "LEFT JOIN {mytable} my ON my.domain_id = d.domain_id";
      break;
    case 'data':
      if ($domain['uid']) {
        $account = user_load(array('uid' => $domain['uid']));
        return l($account->name, 'user/'. $account->uid);
      }
      break;
  }
}

/**
 * Allows other modules to add elements to the default Domain settings page.
 *
 * @param &$form
 *  The $form array generated for the Domain settings page.  This must
 *  be passed by reference.
 *  Normally, you should include your form elements inside a new fieldset.
 * @return
 *  No return value.  The $form is modified by reference, as needed.
 */
function hook_domainform(&$form) {
  // Add the form element to the main screen.
  $form['domain_mymodule'] = array(
    '#type' => 'fieldset',
    '#title' => t('Mymodule settings'),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE
  );
  $options = drupal_map_assoc(array(-100, -25, -10, -5, -1, 0, 1, 5, 10, 25, 100));
  $form['domain_mymodule']['domain_mymodule'] = array(
    '#type' => 'select',
    '#title' => t('Mymodule settings variable'),
    '#options' => $options,
    '#default_value' => variable_get('domain_mymodule', 0),
    '#description' => t('You description goes here.')
  );
}

/**
 *  Allows a warning message to be printed when entering specific forms that
 *  may have values that vary on each domain.
 *
 * @return
 *  An array of form_id values representing forms that require warnings.
 *
 * @ingroup domain_hooks
 */
function hook_domainwarnings() {
  // These are the forms for variables set by Domain Conf.
  return array(
    'system_admin_theme_settings',
    'system_date_time_settings',
    'system_site_information_settings',
    'system_site_maintenance_settings'
  );
}

/**
 * Allows modules to specify the target link for a node.
 *
 * @param &$source
 *   The domain array from domain_get_node_match(), passed by reference.
 * @param $nid
 *   The node id.
 * @return
 *   No return value; modify $source by reference.
 */
function hook_domain_source_alter(&$source, $nid) {
  // Taken from the Domain Source module
  $source = domain_source_lookup($nid);
}

/**
 * Allows modules to specify the target link for a Drupal path.
 *
 * Note: This hook is not meant to be used for node paths, which
 * are handled by hook_domain_source_alter(). This hook is split
 * from hook_domain_source_alter() for better performance.
 *
 * Currently, no modules in the package implement this hook.
 *
 * @param &$source
 *   The domain array from domain_get_node_match(), passed by reference.
 * @param $nid
 *   The identifier of the obect being rewritten. For nodes, this is the node id.
 *   In other instances, we may pass a $path string or other variable.
 * @return
 *   No return value; modify $source by reference.
 */
function hook_domain_source_path_alter(&$source, $path) {
  // Always make admin links go to the primary domain.
  $base = arg(0, $path);
  if ($base == 'admin') {
    $source = domain_default();
  }
}

/**
 * Allows modules to add additional form elements for saving as domain-specific
 * settings.
 *
 * When naming your form arrays, remember that the final key is the name of
 * the variable that you wish to alter.  The example below changes the default
 * user picture depending on the active domain.
 *
 * Preferred use is to wrap your form elements in a named fieldset, for easier
 * viewing.
 *
 *  This hook is implemented by the Domain Conf module.
 *
 * You may wish to pair this hook with hook_domainbatch() to allow the mass update
 * of your settings.
 *
 * If you wish to store settings that are not related to another module, you must pass
 * the following parameter:
 *
 * $form['myform']['#domain_setting'] = TRUE;
 *
 * Doing so will tell Domain Access that no default settings page exists, and that values
 * must be stored for the primary domain.  This feature is useful for creating special data
 * that needs to be associated with a domain record but does not need a separate table.
 *
 * Using the variable override of hook_domainconf() is an alternative to creating a module
 * and database table for use with hook_domainload().
 *
 * For site managers who wish to implement this hook in other modules, but cannot wait for
 * patches, you do not need to hack the code.  Simply put your functions inside a domain_conf.inc
 * file and place that inside the domain_conf directory.  This file should begin with <?php and conform
 * to Drupal coding standards.
 *
 * @return
 *  A $form array element as defined by the FormsAPI.
 *
 *  @ingroup domain_hooks
 */
function hook_domainconf() {
  $form['pictures'] = array(
    '#type' => 'fieldset',
    '#title' => t('User picture'),
    '#collapsible' => TRUE,
    '#collapsed' => FALSE,
  );
  $form['pictures']['user_picture_default'] = array(
    '#type' => 'textfield',
    '#title' => t('Default picture'),
    '#default_value' => variable_get('user_picture_default', ''),
    '#size' => 30,
    '#maxlength' => 255,
    '#description' => t('URL of picture to display for users with no custom picture selected. Leave blank for none.')
  );
  return $form;
}

/**
 * Allows modules to expose batch editing functions.
 *
 * This hook makes it easier for site administrators to perform
 * bulk updates.  It is most useful for handling settings changes
 * caused by moving from a staging to a production server.
 *
 * The function works by defining a $batch array that serves as a combination
 * of menu hook and form element.  The $batch array contains all the information
 * needed to create an administrative page and form that will process your settings.
 *
 * For a basic example, see domain_domainbatch().
 *
 * For a more complex example, with custom processing, see domain_theme_domainbatch().
 *
 * The $batch array is formatted according to the following rules:
 *
 * - '#form' [required] An array that defines the form element for this item.  It accepts any
 * values defined by the FormsAPI.  Do not, however, pass the #default_value element
 * here.  That value will be computed dynamically for each domain when the hook is processed.
 *
 *  - '#system_default' [required] Used to fill the #default_value parameter for domains that do not have custom settings.
 *  Typically, this will be the result of a variable_get().  For domain_delete operations, this value should be set to zero (0).
 *
 * - '#meta_description' [required] Used to describe your action to end users.
 *
 *  - '#override_default' [optional] A boolean value used to tell whether to use variable_get() to retrieve the current value.
 *  Use this when complex variables do not allow a normal usage.
 * - '#domain_action' [required] Indicates what submit action will be invoked for this setting.  Allowed values are:
 * --- 'domain' == writes the value to the {domain} table.  Normally, contributed modules will not use this option.
 * --- 'domain_conf' == writes the value to the {domain_conf} table.  Use in connection with hook_domainconf().
 * --- 'domain_delete' == used to delete rows from specific tables.  If this is used, the #table value must be present.
 * --- 'custom' == used if you need your own submit handler. Must be paired with a #submit parameter.
 *
 * - '#submit' [optional] Used with the 'custom' #domain_action to define a custom submit handler for the form.  This value
 * should be a valid function name.  It will be passed the $form_values array for processing.
 *
 * - '#validate' [optional] Used to define a validate handler for the form.  This value
 * should be a valid function name.  It will be passed the $form_values array for processing.
 *
 * - '#lookup' [optional] Used with the 'custom' #domain_action to perform a default value lookup against a custom function.
 * This value should be a valid function name.  Your function must accept the $domain array as a parameter.
 *
 * - '#table' [optional] Used with the 'domain_delete' #domain_action to specify which table a row should be deleted from.
 * This value may be a string or an array, if you need to perform multiple deletes.  Deletes are performed against the domain_id
 * of the selected domains.
 *
 * - '#variable' [optional] Used to perform changes for the default domain, which is stored in the {variables} table. If this
 * value is not set, the root domain will not be exposed for batch editing.
 *
 * - '#data_type' [optional] Used to tell the system how to build your data entry query.  Defaults to 'string'; possible values are:
 * --- 'string' == the query will use '%s' to insert the data.
 * --- 'integer' == the query will use %d to insert the data.
 * --- 'float' == the query will use %f to insert the data.
 * --- 'binary' == the query will use %b to insert the data.
 * For more information, see db_query() in the Drupal API documentation.
 *
 * - '#weight' [optional] Used to weight the item in the menu system.  Should normally be set to zero.  Negative values
 * are reserved for use by the core Domain Access module.  The following values are in use:
 * --- (-10) items used by Domain Access core.
 * --- (-8) items used by Domain Configuration.
 * --- (-6) items used by Domain Theme.
 * --- (-2) items reserved for batch delete actions.
 *
 * - '#group' [optional] Used to place elements into fieldsets for the main domain configuration page. If not set, any
 *    new element will be added to the 'Site configuration' fieldset.
 *
 * - '#update_all' [optional] Allows the batch settings form to use one input field to reset all values. This should beginLogging
 * set to TRUE in most cases. If your value must be unique per domain, set this to FALSE or leave empty.
 *
 * - '#module' [optional] Used to group like elements together on the batch action list.
 *
 * @ingroup domain_hooks
 */
function hook_domainbatch() {
  // A simple function to rename my setting in Domain Configuration.
  $batch = array();
  $batch['mysetting'] = array(
    '#form' => array(
      '#title' => t('My Settings'),
      '#type' => 'textfield',
      '#size' => 40,
      '#maxlength' => 80,
      '#description' => t('A description for the form'),
      '#required' => TRUE,
    ),
    '#domain_action' => 'domain_conf',
    '#meta_description' => t('Edit my setting value.'),
    '#variable' => 'domain_mysetting',
    '#validate' => 'domain_mysetting_validate',
    '#data_type' => 'string',
    '#weight' => 0,
    '#group' => t('My settings'),
    '#update_all' => TRUE,
    '#module' => t('Domain Access'),
  );
  return $batch;
}

/**
 * Return an array of forms for which we cannot run hook_form_alter().
 * @return
 * An array of form ids that should not run through domain_form_alter.
 */
function hook_domainignore() {
  // User login should always be from the current domain.
  return array('user_login');
}

/**
 * The Domain Bootstrap Process.
 *
 * There are some variables that Domain Access and its modules
 * need to set before Drupal finishes loading. In effect, we have to add
 * stages to the Drupal bootstrap process.
 *
 * These processes are initiated after settings.php is loaded, during
 * DRUPAL_BOOTSTRAP_CONFIGURATION. We skip ahead and
 * load DRUPAL_BOOTSTRAP_DATABASE to access db_query() and
 * similar functions.  However, the majority of Drupal functions are
 * not yet available.
 *
 * The following modules will load during the bootstrap process, if enabled:
 *  -- domain
 *  -- domain_alias
 *  -- domain_conf
 *  -- domain_prefix
 *
 * If you create a custom module, it must be registered with the Domain
 * Bootstrap Process. To register, you must:
 *
 * 1) Implement either or both of the following hooks:
 *  -- hook_domain_bootstrap_load().
 *  -- hook_domain_bootstrap_full().
 * 2) Run domain_bootstrap_register() in mymodule_enable().
 * 3) Run domain_bootstrap_unregister('mymodule') in mymodule_disable().
 *
 */
function hook_domain_bootstrap() {
  // Documentation function.
}

/**
 * Hook domain_bootstrap_lookup allows modules to modify the domain record used on the
 * current page on bootstrap level, that is, before it is used anywhere else.
 *
 * This allows modules like Domain Alias to change the domain_id matched to the current
 * domain name before related information is retrieved during domain_init().
 *
 * Note: Because this function is usually called VERY early, many Drupal
 * functions or modules won't be loaded yet.
 *
 * In order for this hook to work your module needs to be registered with
 * domain_bootstrap_register() during hook_enable();
 *
 * Modules must also use domain_bootsrap_unregister('mymodule') during hook_disable().
 *
 * @param $domain
 * An array containing current domain (host) name (used during bootstrap) and
 * the results of lookup against {domain} table.
 * @return
 * An array containing at least a valid domain_id.
 */
function hook_domain_bootstrap_lookup($domain) {
  // Match en.example.org to default domain (id:0)
  if ($domain['subdomain'] == 'en.example.org') {
    $domain['domain_id'] = 0;
  }
  return $domain;
}

/**
 * Hook hook_domain_bootstrap_full allows modules to execute code after the domain
 * bootstrap phases which is called before drupal's hook_boot().
 *
 * This hook can be used to modify drupal's variables system or prefix database
 * tables, as used in the modules domain_conf and domain_prefix.
 *
 * Note: Because this function is usually called VERY early, many Drupal
 * functions or modules won't be loaded yet.
 *
 * In order for this hook to work your module needs to be registered with
 * domain_bootstrap_register() during hook_enable();
 *
 * Modules must also use domain_bootsrap_unregister('mymodule') during hook_disable().
 *
 * @param $domain
 * An array containing current domain and domain_id and any other values
 * added during domain bootstrap phase 2 (DOMAIN_BOOTSTRAP_DOMAINNAME_RESOLVE).
 *
 * @return
 * No return value. However, if you wish to set an error message on failure, you
 * should load and modify the $_domain global and add an 'error' element to the array.
 * This element should only include the name of your module.
 * We do this because drupal_set_message() and t() are not yet loaded.
 *
 * Normally, you do not need to validate errors, since this function will not
 * be called unless $domain is set properly.
 */
function hook_domain_bootstrap_full($domain) {
  global $conf;
  // The language variable should not be set yet.
  // Check for errors.
  if (isset($conf['language'])) {
    global $_domain;
    $_domain['error'] = 'mymodule';
    return;
  }
  // Our test module sets the default language to Spanish.
  $conf['language'] = 'es';
}

/**
 * Allows modules to alter path when rewriting URLs.
 *
 * This hook will fire for all paths and may be resource-intensive.
 * Look at Domain Prefix for best practices implementation. In Domain
 * Prefix, we only include this function if we know it is necessary.
 *
 * @see domain_prefix_init()
 *
 * @param $domain_id
 *  The domain_id taken from {domain}.
 * @param $path
 *  The internal drupal path to the node.
 * @param $path_language
 *  Language code to look up the path in.
 *
 * @ingroup domain_hooks
 */
function hook_domainpath($domain_id, &$path, $path_language = '') {
  // Give a normal path alias
  $path = drupal_get_path_alias($path);
}

/**
 * Demonstrates domain_conf_variable_set().
 *
 * Allows module to reset domain-specific variables.
 * This function is not a hook, it is a helper function
 * that is implemented by the Domain Configuration module.
 *
 * Use this function if you need to reset a domain-specific variable
 * from your own code. It is especially useful in conjunction with
 * hook_domainupdate().
 *
 * @link http://drupal.org/node/367963
 *
 * @param $domain_id
 *  The unique domain ID that is being edited.
 * @param $variable
 *  The name of the variable you wish to set.
 * @param $value
 *  The value of the variable to set. You may leave this
 *  value blank in order to unset the custom variable.
 */
function mymodule_form_submit($form_state) {
  // When we save these changes, replicate them across all domains.
  if (!module_exists('domain_conf')) {
    return;
  }
  $domains = domain_domains();
  foreach ($domains as $domain) {
    $value = $form_state['values']['my_variable'];
    domain_conf_variable_set($domain['domain_id'], 'my_variable', $value);
  }
}