Commit 5a5f34b0 authored by webchick's avatar webchick

#528822 by jhodgdon: Batch example should explain that a file must be included when necessary.

parent 5007ba8a
......@@ -2857,14 +2857,15 @@ function _form_set_class(&$element, $class = array()) {
* array('my_function_2', array()),
* ),
* 'finished' => 'my_finished_callback',
* 'file' => 'path_to_file_containing_myfunctions',
* );
* batch_set($batch);
* // only needed if not inside a form _submit handler :
* batch_process();
* @endcode
*
* Note - if the batch 'title', 'init_message', 'progress_message',
* or 'error_message' could contain any user input, it is the responsibility of
* Note: if the batch 'title', 'init_message', 'progress_message', or
* 'error_message' could contain any user input, it is the responsibility of
* the code calling batch_set() to sanitize them first with a function like
* check_plain() or filter_xss().
*
......@@ -2940,42 +2941,40 @@ function _form_set_class(&$element, $class = array()) {
*/
/**
* Open a new batch.
* Opens a new batch.
*
* @param $batch
* An array defining the batch. The following keys can be used:
* 'operations': an array of function calls to be performed.
* Example:
* @code
* array(
* array('my_function_1', array($arg1)),
* array('my_function_2', array($arg2_1, $arg2_2)),
* )
* @endcode
* All the other values below are optional.
* batch_init() provides default values for the messages.
* '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, @percentage,
* @estimate and @elapsed.
* 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': 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().
* 'css': an array of paths to CSS files to be used on the progress page.
* 'url_options': options passed to url() when constructing redirect
* URLs for the 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:
* @code
* array(
* array('my_function_1', array($arg1)),
* array('my_function_2', array($arg2_1, $arg2_2)),
* )
* @endcode
* - '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, @percentage,
* @estimate and @elapsed. 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().
* - 'css': Array of paths to CSS files to be used on the progress page.
* - 'url_options': options passed to url() when constructing redirect
* URLs for the batch.
*
* Operations are added as new batch sets. Batch sets are used to ensure
* clean code independence, ensuring that several batches submitted by
......@@ -3033,7 +3032,7 @@ function batch_set($batch_definition) {
}
/**
* Process the batch.
* Processes the batch.
*
* Unless the batch has been marked with 'progressive' = FALSE, the function
* issues a drupal_goto and thus ends page execution.
......@@ -3124,7 +3123,7 @@ function batch_process($redirect = NULL, $url = 'batch', $redirect_callback = 'd
}
/**
* Retrieve the current batch.
* Retrieves the current batch.
*/
function &batch_get() {
$batch = &drupal_static(__FUNCTION__, array());
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment