diff --git a/includes/form.inc b/includes/form.inc index 41b0ee2fe706..bec7d1e1c7ee 100644 --- a/includes/form.inc +++ b/includes/form.inc @@ -4256,7 +4256,7 @@ function element_validate_number($element, &$form_state) { * returns any user input in the 'results' or 'message' keys of $context, * it must also sanitize them first. * - * Sample batch operations: + * Sample callback_batch_operation(): * @code * // Simple and artificial: load a node of a given type for a given user * function my_function_1($uid, $type, &$context) { @@ -4308,7 +4308,7 @@ function element_validate_number($element, &$form_state) { * } * @endcode * - * Sample 'finished' callback: + * Sample callback_batch_finished(): * @code * function batch_test_finished($success, $results, $operations) { * // The 'success' parameter means no fatal PHP errors were detected. All @@ -4347,12 +4347,14 @@ function element_validate_number($element, &$form_state) { * @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. + * - operations: (required) Array of operations to be performed, where each + * item is an array consisting of the name of an implementation of + * callback_batch_operation() and an array of parameter. * Example: * @code * array( - * array('my_function_1', array($arg1)), - * array('my_function_2', array($arg2_1, $arg2_2)), + * array('callback_batch_operation_1', array($arg1)), + * array('callback_batch_operation_2', array($arg2_1, $arg2_2)), * ) * @endcode * - title: A safe, translated string to use as the title for the progress @@ -4364,10 +4366,10 @@ function element_validate_number($element, &$form_state) { * @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. + * - finished: Name of an implementation of callback_batch_finished(). This is + * 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 diff --git a/modules/system/form.api.php b/modules/system/form.api.php new file mode 100644 index 000000000000..36c4c85300e0 --- /dev/null +++ b/modules/system/form.api.php @@ -0,0 +1,126 @@ +fetchField(); + } + + // For this example, we decide that we can safely process + // 5 nodes at a time without a timeout. + $limit = 5; + + // With each pass through the callback, retrieve the next group of nids. + $result = db_query_range("SELECT nid FROM {node} WHERE nid > %d ORDER BY nid ASC", $context['sandbox']['current_node'], 0, $limit); + while ($row = db_fetch_array($result)) { + + // Here we actually perform our processing on the current node. + $node = node_load($row['nid'], NULL, TRUE); + $node->value1 = $options1; + $node->value2 = $options2; + node_save($node); + + // Store some result for post-processing in the finished callback. + $context['results'][] = check_plain($node->title); + + // Update our progress information. + $context['sandbox']['progress']++; + $context['sandbox']['current_node'] = $node->nid; + $context['message'] = t('Now processing %node', array('%node' => $node->title)); + } + + // Inform the batch engine that we are not finished, + // and provide an estimation of the completion level we reached. + if ($context['sandbox']['progress'] != $context['sandbox']['max']) { + $context['finished'] = $context['sandbox']['progress'] / $context['sandbox']['max']; + } +} + +/** + * Complete a batch process. + * + * Callback for batch_set(). + * + * This callback may be specified in a batch to perform clean-up operations, or + * to analyze the results of the batch operations. + * + * @param $success + * A boolean indicating whether the batch has completed successfully. + * @param $results + * The value set in $context['results'] by callback_batch_operation(). + * @param $operations + * If $success is FALSE, contains the operations that remained unprocessed. + */ +function callback_batch_finished($success, $results, $operations) { + if ($success) { + // Here we do something meaningful with the results. + $message = t("!count items were processed.", array( + '!count' => count($results), + )); + $message .= theme('item_list', array('items' => $results)); + drupal_set_message($message); + } + else { + // An error occurred. + // $operations contains the operations that remained unprocessed. + $error_operation = reset($operations); + $message = t('An error occurred while processing %error_operation with arguments: @arguments', array( + '%error_operation' => $error_operation[0], + '@arguments' => print_r($error_operation[1], TRUE) + )); + drupal_set_message($message, 'error'); + } +}