function batch_set in Drupal 6

Same name and namespace in other branches

1. 8 core/includes/form.inc \batch_set()
2. 7 includes/form.inc \batch_set()
3. 9 core/includes/form.inc \batch_set()

Opens a new batch.

Parameters

$batch: An array defining the batch. The following keys can be used -- only 'operations' is required, and batch_init() provides default values for the messages.

• 'operations': Array of function calls to be performed. Example:

array(
  array(
    'my_function_1',
    array(
      $arg1,
    ),
  ),
  array(
    'my_function_2',
    array(
      $arg2_1,
      $arg2_2,
    ),
  ),
);

• 'title': Title for the progress page. Only safe strings should be passed. Defaults to t('Processing').
• 'init_message': Message displayed while the processing is initialized. Defaults to t('Initializing.').
• 'progress_message': Message displayed while processing the batch. Available placeholders are @current, @remaining, @total, and @percentage. Defaults to t('Completed @current of @total.').
• 'error_message': Message displayed if an error occurred while processing the batch. Defaults to t('An error has occurred.').
• 'finished': Name of a function to be executed after the batch has completed. This should be used to perform any result massaging that may be needed, and possibly save data in $_SESSION for display after final page redirection.
• 'file': Path to the file containing the definitions of the 'operations' and 'finished' functions, for instance if they don't reside in the main .module file. The path should be relative to base_path(), and thus should be built using drupal_get_path().

Operations are added as new batch sets. Batch sets are used to ensure clean code independence, ensuring that several batches submitted by different parts of the code (core / contrib modules) can be processed correctly while not interfering or having to cope with each other. Each batch set gets to specify its own UI messages, operates on its own set of operations and results, and triggers its own 'finished' callback. Batch sets are processed sequentially, with the progress bar starting fresh for every new set.

Related topics

6 calls to batch_set()

install_tasks in ./install.php

Tasks performed after the database is initialized.

locale_languages_predefined_form_submit in includes/locale.inc

Process the language addition form submission.

locale_system_update in modules/locale/locale.module

Imports translations when new modules or themes are installed or enabled.

node_access_rebuild in modules/node/node.module

Rebuild the node access database. This is occasionally needed by modules that make system-wide changes to access levels.

node_mass_update in modules/node/node.admin.inc

Make mass update of nodes, changing all nodes in the $nodes array to update them with the field values in $updates.

... See full list

File

includes/form.inc, line 2564

Code

function batch_set($batch_definition) {
  if ($batch_definition) {
    $batch =& batch_get();

    // Initialize the batch
    if (empty($batch)) {
      $batch = array(
        'sets' => array(),
      );
    }
    $init = array(
      'sandbox' => array(),
      'results' => array(),
      'success' => FALSE,
    );

    // Use get_t() to allow batches at install time.
    $t = get_t();
    $defaults = array(
      'title' => $t('Processing'),
      'init_message' => $t('Initializing.'),
      'progress_message' => $t('Remaining @remaining of @total.'),
      'error_message' => $t('An error has occurred.'),
    );
    $batch_set = $init + $batch_definition + $defaults;

    // Tweak init_message to avoid the bottom of the page flickering down after init phase.
    $batch_set['init_message'] .= '<br/>&nbsp;';
    $batch_set['total'] = count($batch_set['operations']);

    // If the batch is being processed (meaning we are executing a stored submit handler),
    // insert the new set after the current one.
    if (isset($batch['current_set'])) {

      // array_insert does not exist...
      $slice1 = array_slice($batch['sets'], 0, $batch['current_set'] + 1);
      $slice2 = array_slice($batch['sets'], $batch['current_set'] + 1);
      $batch['sets'] = array_merge($slice1, array(
        $batch_set,
      ), $slice2);
    }
    else {
      $batch['sets'][] = $batch_set;
    }
  }
}