diff --git a/includes/ingest.form.inc b/includes/ingest.form.inc index db031dc0..f39d38ff 100644 --- a/includes/ingest.form.inc +++ b/includes/ingest.form.inc @@ -26,6 +26,8 @@ * be related. * - models: An array of content model PIDs, to which the new object might * subscribe + * - parent: The parent of the child to be ingested. This is needed for XACML + * to correctly apply the parent's POLICY to children. * * @return array * The form definition of the current step. @@ -133,6 +135,50 @@ function islandora_ingest_form_get_step(array &$form_state, $step_id = NULL) { return NULL; } +/** + * Gets the next step. + * + * If the current step is not defined, its assumed to be the first step. + * + * @param array $form_state + * The Drupal form state. + * @param string $step + * The step relative to the result, if not provided the current step is used. + * + * @return string + * The next step if found, NULL otherwise. + */ +function islandora_ingest_form_get_next_step(array &$form_state, array $step = NULL) { + $step = isset($step) ? $step : islandora_ingest_form_get_step($form_state); + $next_step_id = islandora_ingest_form_get_next_step_id($form_state, $step['id']); + if ($next_step_id) { + return islandora_ingest_form_get_step($form_state, $next_step_id); + } + return NULL; +} + +/** + * Gets the previous step. + * + * If the current step is not defined, its assumed to be the first step. + * + * @param array $form_state + * The Drupal form state. + * @param string $step + * The step relative to the result, if not provided the current step is used. + * + * @return string + * The next step if found, NULL otherwise. + */ +function islandora_ingest_form_get_previous_step(array &$form_state, array $step = NULL) { + $step = isset($step) ? $step : islandora_ingest_form_get_step($form_state); + $next_step_id = islandora_ingest_form_get_previous_step_id($form_state, $step['id']); + if ($next_step_id) { + return islandora_ingest_form_get_step($form_state, $next_step_id); + } + return NULL; +} + /** * Gets the ID of the current step. * @@ -160,12 +206,15 @@ function islandora_ingest_form_get_current_step_id(array &$form_state) { * * @param array $form_state * The Drupal form state. + * @param string $step_id + * The ID of the step relative to the result, if not provided the current + * step_id is used. * * @return string * The next step ID if found, NULL otherwise. */ -function islandora_ingest_form_get_next_step_id(array &$form_state) { - $step_id = islandora_ingest_form_get_current_step_id($form_state); +function islandora_ingest_form_get_next_step_id(array &$form_state, $step_id = NULL) { + $step_id = isset($step_id) ? $step_id : islandora_ingest_form_get_current_step_id($form_state); $step_ids = array_keys(islandora_ingest_form_get_steps($form_state)); $index = array_search($step_id, $step_ids); $count = count($step_ids); @@ -182,12 +231,15 @@ function islandora_ingest_form_get_next_step_id(array &$form_state) { * * @param array $form_state * The Drupal form state. + * @param string $step_id + * The ID of the step relative to the result, if not provided the current + * step_id is used. * * @return string * The previous step ID if found, NULL otherwise. */ -function islandora_ingest_form_get_previous_step_id(array &$form_state) { - $step_id = islandora_ingest_form_get_current_step_id($form_state); +function islandora_ingest_form_get_previous_step_id(array &$form_state, $step_id = NULL) { + $step_id = isset($step_id) ? $step_id : islandora_ingest_form_get_current_step_id($form_state); $step_ids = array_keys(islandora_ingest_form_get_steps($form_state)); $index = array_search($step_id, $step_ids); if ($index !== FALSE && --$index >= 0) { @@ -233,13 +285,15 @@ function islandora_ingest_form_decrement_step(array &$form_state) { * Build a list of steps given only configuration. * * XXX: This is used to give an indication of whether there are any steps for a - * given list of content models. + * given configuration. * * @param array $configuration * The list of key/value pairs of configuration. */ function islandora_ingest_get_approximate_steps(array $configuration) { try { + // @todo, we need to expand the configuration before we can validate it? + // I think this need some thinking. islandora_ingest_form_validate_configuration($configuration); } catch (InvalidArgumentException $e) { @@ -270,16 +324,19 @@ function islandora_ingest_get_approximate_steps(array $configuration) { * @return array * The form definition of the current step. */ -function islandora_ingest_form_execute_step(array $form, array &$form_state) { +function islandora_ingest_form_execute_step(array $form, array &$form_state, $step_id = NULL) { // Load any required files for the current step. islandora_ingest_form_load_include($form_state); - $step = islandora_ingest_form_get_step($form_state); + $step = isset($step_id) ? islandora_ingest_form_get_step($form_state) : islandora_ingest_form_get_step($form_state, $step_id); switch ($step['type']) { + case 'callback': + // Execute all the consecutive callbacks, and move then attempt to process + // the next step. + islandora_ingest_form_execute_consecutive_callback_steps($form, $form_state, $step); + return islandora_ingest_form_execute_step($form, $form_state); + case 'form': - $args = array($form, &$form_state); - $args = isset($step['args']) ? array_merge($args, $step['args']) : $args; - $form = call_user_func_array($step['form_id'], $args); - return islandora_ingest_form_stepify($form, $form_state, $step); + return islandora_ingest_form_execute_form_step($form, $form_state, $step); case 'batch': // @todo Implement if possible. @@ -288,6 +345,56 @@ function islandora_ingest_form_execute_step(array $form, array &$form_state) { return array(); } +/** + * Assumes the given $step is a 'form' step. + */ +function islandora_ingest_form_execute_form_step(array $form, array &$form_state, array $step) { + $args = array($form, &$form_state); + $args = isset($step['args']) ? array_merge($args, $step['args']) : $args; + $form = call_user_func_array($step['form_id'], $args); + return islandora_ingest_form_stepify($form, $form_state, $step); +} + +/** + * Assumes the given $step is a 'callback' step. + */ +function islandora_ingest_form_execute_consecutive_callback_steps(array $form, array &$form_state, array $step) { + do { + islandora_ingest_form_execute_callback_step($form, $form_state, $step); + islandora_ingest_form_increment_step($form_state); + $step = islandora_ingest_form_get_step($form_state); + } while (isset($step) && $step['type'] == 'callback'); +} + +/** + * Assumes the given $step is a 'callback' step. + */ +function islandora_ingest_form_execute_callback_step(array $form, array &$form_state, array $step) { + $args = array(&$form_state); + $args = isset($step['do_function']['args']) ? array_merge($args, $step['do_function']['args']) : $args; + call_user_func_array($step['do_function']['function'], $args); +} + +/** + * Assumes the given $step is a 'callback' step. + */ +function islandora_ingest_form_undo_consecutive_callback_steps(array $form, array &$form_state, array $step) { + do { + islandora_ingest_form_undo_callback_step($form, $form_state, $step); + islandora_ingest_form_decrement_step($form_state); + $step = islandora_ingest_form_get_step($form_state); + } while (isset($step) && $step['type'] == 'callback'); +} + +/** + * Assumes the given $step is a 'callback' step. + */ +function islandora_ingest_form_undo_callback_step(array $form, array &$form_state, array $step) { + $args = array(&$form_state); + $args = isset($step['undo_function']['args']) ? array_merge($args, $step['undo_function']['args']) : $args; + call_user_func_array($step['undo_function']['function'], $args); +} + /** * Append Prev/Next buttons submit/validation handlers etc. * @@ -297,22 +404,20 @@ function islandora_ingest_form_execute_step(array $form, array &$form_state) { * The Drupal form state. * * @return array - * The stepified drupal form definition for the given step. + * The stepified Drupal form definition for the given step. */ function islandora_ingest_form_stepify(array $form, array &$form_state, $step) { - $first_step = islandora_ingest_form_on_first_step($form_state); - $last_step = islandora_ingest_form_on_last_step($form_state); - $form['prev'] = $first_step ? NULL : islandora_ingest_form_previous_button($form_state); - $form['next'] = $last_step ? islandora_ingest_form_ingest_button($form_state) : islandora_ingest_form_next_button($form_state); - + $first_form_step = islandora_ingest_form_on_first_form_step($form_state); + $last_form_step = islandora_ingest_form_on_last_form_step($form_state); + $form['prev'] = $first_form_step ? NULL : islandora_ingest_form_previous_button($form_state); + $form['next'] = $last_form_step ? islandora_ingest_form_ingest_button($form_state) : islandora_ingest_form_next_button($form_state); // Allow for a hook_form_FORM_ID_alter(). drupal_alter(array('form_' . $step['form_id'], 'form'), $form, $form_state, $step['form_id']); - return $form; } /** - * Checks if we are on the first step. + * Checks if we are on the first form step. * * @param array $form_state * The Drupal form state. @@ -320,14 +425,16 @@ function islandora_ingest_form_stepify(array $form, array &$form_state, $step) { * @return bool * TRUE if we are currently on the first step, FALSE otherwise. */ -function islandora_ingest_form_on_first_step(array &$form_state) { - $step_id = islandora_ingest_form_get_current_step_id($form_state); - $step_ids = array_keys(islandora_ingest_form_get_steps($form_state)); - return array_search($step_id, $step_ids) == 0; +function islandora_ingest_form_on_first_form_step(array &$form_state) { + $step = NULL; + do { + $step = islandora_ingest_form_get_previous_step($form_state, $step); + } while (isset($step) && $step['type'] != 'form'); + return !$step; } /** - * Checks if we are on the last step. + * Checks if we are on the last form step. * * @param array $form_state * The Drupal form state. @@ -335,11 +442,12 @@ function islandora_ingest_form_on_first_step(array &$form_state) { * @return bool * TRUE if we are currently on the last step, FALSE otherwise. */ -function islandora_ingest_form_on_last_step(array &$form_state) { - $step_id = islandora_ingest_form_get_current_step_id($form_state); - $step_ids = array_keys(islandora_ingest_form_get_steps($form_state)); - $count = count($step_ids); - return array_search($step_id, $step_ids) == --$count; +function islandora_ingest_form_on_last_form_step(array &$form_state) { + $step = NULL; + do { + $step = islandora_ingest_form_get_next_step($form_state, $step); + } while (isset($step) && $step['type'] != 'form'); + return !$step; } /** @@ -356,11 +464,15 @@ function islandora_ingest_form_on_last_step(array &$form_state) { function islandora_ingest_form_previous_button(array &$form_state) { // Before we move back to the previous step we should tell the previous step // to undo whatever its submit handler did. - $prev_step_id = islandora_ingest_form_get_previous_step_id($form_state); - $prev_step = islandora_ingest_form_get_step($form_state, $prev_step_id); - $form_id = $prev_step['form_id']; - $submit_callback = $form_id . '_undo_submit'; - $submit = function_exists($submit_callback) ? array($submit_callback, 'islandora_ingest_form_previous_submit') : array('islandora_ingest_form_undo_submit'); + $prev_step = islandora_ingest_form_get_previous_step($form_state); + if ($prev_step['type'] == 'form') { + $form_id = $prev_step['form_id']; + $submit_callback = $form_id . '_undo_submit'; + $submit = function_exists($submit_callback) ? array($submit_callback, 'islandora_ingest_form_previous_submit') : array('islandora_ingest_form_previous_submit'); + } + else { + $submit = array('islandora_ingest_form_previous_submit'); + } return array( '#type' => 'submit', '#value' => t('Previous'), @@ -391,6 +503,11 @@ function islandora_ingest_form_previous_button(array &$form_state) { */ function islandora_ingest_form_previous_submit(array $form, array &$form_state) { islandora_ingest_form_decrement_step($form_state); + $step = islandora_ingest_form_get_step($form_state); + // Undo all callbacks that occured after the previous step. + if ($step['type'] == 'callback') { + islandora_ingest_form_undo_consecutive_callback_steps($form, $form_state, $step); + } $form_state['rebuild'] = TRUE; } @@ -446,8 +563,10 @@ function islandora_ingest_form_next_submit(array $form, array &$form_state) { */ function islandora_ingest_form_stash_info(array &$form_state) { $storage = &islandora_ingest_form_get_step_storage($form_state); - $storage['values'] = $form_state['values']; - unset($form_state['values']); + if ($storage) { + $storage['values'] = $form_state['values']; + unset($form_state['values']); + } } /** @@ -493,12 +612,17 @@ function islandora_ingest_form_ingest_button(array &$form_state) { * * Attempts to ingest every object built by the previous steps. * - * @param array $form - * The Drupal form. * @param array $form_state * The Drupal form state. */ function islandora_ingest_form_submit(array $form, array &$form_state) { + // Execute any remaining callbacks. + islandora_ingest_form_increment_step($form_state); + $step = islandora_ingest_form_get_step($form_state); + if (isset($step) && $step['type'] == 'callback') { + islandora_ingest_form_execute_consecutive_callback_steps($form, $form_state, $step); + } + // Ingest the objects. foreach ($form_state['islandora']['objects'] as $object) { try { islandora_add_object($object); @@ -625,6 +749,8 @@ function islandora_ingest_form_get_steps(array &$form_state) { $shared_storage = &islandora_ingest_form_get_shared_storage($form_state); foreach (islandora_build_hook_list(ISLANDORA_INGEST_STEP_HOOK, $shared_storage['models']) as $hook) { // Required for pass by reference. + // @todo Change this around so that it isn't passed by reference, there + // Is an alter below that can handle that requirement. foreach (module_implements($hook) as $module) { $function = $module . '_' . $hook; $module_steps = (array) $function($form_state); @@ -635,6 +761,10 @@ function islandora_ingest_form_get_steps(array &$form_state) { foreach (islandora_build_hook_list(ISLANDORA_INGEST_STEP_HOOK, $shared_storage['models']) as $hook) { drupal_alter($hook, $steps, $form_state); } + // Add any defaults. + foreach ($steps as $key => &$step) { + $step['id'] = $key; + } uasort($steps, 'drupal_sort_weight'); return $steps; } diff --git a/islandora.api.php b/islandora.api.php index d1d58f4f..17db59ad 100644 --- a/islandora.api.php +++ b/islandora.api.php @@ -304,7 +304,7 @@ function hook_islandora_datastream_modified(FedoraObject $object, FedoraDatastre } /** - * Notify modules that the given datastream was ingested. + * Notify modules that the given datastream was modified. * * @see hook_islandora_datastream_modified() */ @@ -386,15 +386,26 @@ function hook_islandora_undeletable_datastreams(array $models) { * @return array * An associative array of associative arrays which define each step in the * ingest process. Each step should consist of a unique name mapped to an - * array of properties (keys) including: - * - type: The type of step. Currently, only "form" is implemented. - * - weight: The "weight" of this step--heavier(/"larger") values sink to the - * end of the process while smaller(/"lighter") values are executed first. + * array of properties (keys) which take different paramaters based upon type: + * - type: Type of step. Only "form" and "callback" are implemented so far. + * Required "form" type specific parameters: * - form_id: The form building function to call to get the form structure * for this step. * - args: An array of arguments to pass to the form building function. - * And may optionally include both: + * Required "callback" type specific parameters: + * - do_function: An associate array including: + * - 'function': The callback function to be called. + * - 'args': An array of arguments to pass to the callback function. + * - undo_function: An associate array including: + * - 'function': The callback function to be called to reverse the + * executed action in the ingest steps. + * - 'args': An array of arguments to pass to the callback function. + * Shared parameters between both types: + * - weight: The "weight" of this step--heavier(/"larger") values sink to the + * end of the process while smaller(/"lighter") values are executed first. + * Both types may optionally include: * - module: A module from which we want to load an include. + * "Form" type may optionally include: * - file: A file to include (relative to the module's path, including the * file's extension). */ @@ -406,6 +417,18 @@ function hook_islandora_ingest_steps(array $form_state) { 'form_id' => 'my_cool_form', 'args' => array('arg_one', 'numero deux'), ), + 'my_cool_step_callback' => array( + 'type' => 'callback', + 'weight' => 2, + 'do_function' => array( + 'function' => 'my_cool_execute_function', + 'args' => array('arg_one', 'numero deux'), + ), + 'undo_function' => array( + 'function' => 'my_cool_undo_function', + 'args' => array('arg_one', 'numero deux'), + ), + ), ); } /**