batch_set

• Drupal 6
• Drupal 7

• View documentation
• List references

Definition

batch_set($batch_definition)
includes/form.inc, line 2407

Description

Open a new batch.

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 his 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.

Parameters

$batch An array defining the batch. The following keys can be used: 'operations': an array of function calls to be performed. Example:

<?php

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

?>

All the other values below are optional. batch_init() provides default values for the messages. 'title': title for the progress page. 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 @percent. Defaults to t('Remaining @remaining of @total.'). 'error_message': message displayed if an error occurred while processing the batch. Defaults to t('An error has occurred.'). 'finished': the 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': the path to the file containing the definitions of the 'operations' and 'finished' functions, for instance if they don't reside in the original '.module' file. The path should be relative to the base_path(), and thus should be built using drupal_get_path().

Related topics

Name	Description
Batch operations	Functions allowing forms processing to be spread out over several page requests, thus ensuring that the processing does not get interrupted because of a PHP timeout, while allowing the user to receive feedback on the progress of the ongoing operations.

Code

<?php
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;
    }
  }
}
?>