function hook_domainbatch in Domain Access 6.2

Same name and namespace in other branches

5 API.php \hook_domainbatch()
7.2 domain.api.php \hook_domainbatch()

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.

'#permission' [optional] A string identifying the permission required to access this setting. If not provided, defaults to 'administer domains'.

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

File

./API.php, line 522: API documentation file.

Code

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

You are here

function hook_domainbatch in Domain Access 6.2

Related topics

File

Code

API Navigation