Commit a32f022b authored by jhodgdon's avatar jhodgdon
Browse files

Issue #1516934 by jmarkel: Fix up docs for batch_set()

parent 6a3b9396
......@@ -4503,13 +4503,24 @@ function _form_set_class(&$element, $class = array()) {
*/
/**
* Opens a new batch.
*
* @param $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.
* Adds a new batch.
*
* Batch operations are added as new batch sets. Batch sets are used to spread
* processing (primarily, but not exclusively, forms processing) over several
* page requests. This helps to ensure that the processing is not interrupted
* due to PHP timeouts, while users are still able to receive feedback on the
* progress of the ongoing operations. Combining related operations into
* distinct batch sets provides clean code independence for each batch set,
* ensuring that two or more batches, submitted independently, can be processed
* without mutual interference. Each batch set may specify its own set of
* operations and results, produce its own UI messages, and trigger its own
* 'finished' callback. Batch sets are processed sequentially, with the progress
* bar starting afresh for each new set.
*
* @param $batch_definition
* An associative array defining the batch, with the following elements (all
* are optional except as noted):
* - operations: (required) Array of function calls to be performed.
* Example:
* @code
* array(
......@@ -4517,35 +4528,26 @@ function _form_set_class(&$element, $class = array()) {
* 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.
* - title: A safe, translated string to use as the 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, @percentage,
* @estimate and @elapsed. Defaults to t('Completed @current of @total.').
* - 'error_message': Message displayed if an error occurred while processing
* - 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
* 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.
* - 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.
*/
function batch_set($batch_definition) {
if ($batch_definition) {
......
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