function hook_domain_batch in Domain Access 7.3

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_domain_batch().

For a more complex example, with custom processing, see domain_theme_domain_batch().

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_domain_conf(). --- '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.

'#permission' [optional] A string identifying the permission required to

access this setting. If not provided, defaults to 'administer domains'.

'#permission' [optional] A string identifying the permission required to

access this setting. If not provided, defaults to 'administer domains'. Your module should ensure that the proper permission is set here.

'#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.

'#collapsed' [optional] Indicates that the form fieldset should appear

collapsed on the configuration page.

'#update_all' [optional] Allows the batch settings form to use one input

field to reset all values. This should be 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.

File

./domain.api.php, line 462: API documentation file.

Code

function hook_domain_batch() {

  // 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,
    ),
    '#permission' => 'administer domains',
    '#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'),
    '#collapsed' => FALSE,
    '#update_all' => TRUE,
    '#module' => t('Domain Access'),
  );
  return $batch;
}

You are here

function hook_domain_batch in Domain Access 7.3

Related topics

File

Code

API Navigation