Date: Fri, 29 Mar 2024 09:19:08 -0400 (EDT) Message-ID: <162062711.13.1711718348030@lyrasis1-roc-mp1> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_12_1210810023.1711718348029" ------=_Part_12_1210810023.1711718348029 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Multi-paged ingest forms are supported in Islandora 7. They allo= w the user to step though a series of HTML forms which in turn manipulate o= ne or more Fedora Objects; adding data-streams, adding relationships, manip= ulating metadata. Once every form page has been submitted, Islandora will a= utomatically ingest all the prepared Fedora Objects.
Multi-paged ingest forms have a concept of "steps," such that a steps ar= e a sequential list of actions. Steps must be traversed to completion, at w= hich point the prepared Fedora objects will be ingested. There are currentl= y two types of steps supported by the multi-paged ingest forms:
Form steps: Expected to return a normal single paged Dr= upal Form.
Callback Steps: Expected to execute a single function a= nd render nothing.
For every page request to the multi-paged ingest form, a single form ste= p is executed. Zero or more callbacks steps may be executed for every page = request. Since callback steps don't render anything to the user they are ex= ecuted consecutively in the order in which they appear.
For example, we have the series of steps below:
callback_1, callback_2, form_1, callback_3, callback_4, form= _2, callback_5
Although optional, it's worth noting that typically form/callback steps = are expected to also define undo functions. These revert t= he changes they have been made to the prepared objects. The undo functions = are called when a user clicks on the previous button in the form and return= s to the previous form step.
To support this a module need only declare what steps they wish to add a= nd what functions those steps perform.
To let islandora know what steps you are providing you must implement th= e islandora_ingest_steps hook(s):
functio= n hook_islandora_ingest_steps(array $form_state); function hook_CMODEL_islandora_ingest_steps(array $form_state);
Which can be implemented by modules to conditionally add new steps. Thes= e functions are expected to return an associative array containing the appr= opriate steps to apply given the current $form_state:
Each step should consist of a unique name mapped to an array of properti= es which take different parameters based upon type:
Forms do not need to describe their undo. It's assumed = to take the form of:
functio= n form_id_undo_submit(array $form, array &$form_state);
/** * Implements hook_islandora_ingest_steps(). */ function islandora_basic_image_islandora_sp_basic_image_islandora_ingest_st= eps() { return array( 'islandora_basic_image' =3D> array( 'weight' =3D> 10, 'type' =3D> 'form', 'form_id' =3D> 'islandora_basic_image_image_upload_form', 'module' =3D> 'islandora_basic_image', 'file' =3D> 'includes/image_upload.form.inc', ), ); }
Sometimes you will want to conditionally include/remove steps based on o= ther steps. You can do this via the alter hook(s):
functio= n hook_islandora_ingest_steps_alter(array &steps, array $form_state); function hook_CMODEL_islandora_ingest_steps_alter(array &steps, array $= form_state);
/** * Implements hook_islandora_ingest_steps_alter(). */ function islandora_marcxml_islandora_ingest_steps_alter(array &$steps, = array &$form_state) { if (isset($steps['xml_form_builder_metadata_step'])) { $metadata_step_storage =3D islandora_ingest_form_get_step_storage($form= _state, 'xml_form_builder_metadata_step'); if (isset($metadata_step_storage['association']) && $metadata_s= tep_storage['association']['dsid'] =3D=3D 'MODS') { $steps['islandora_marcxml_upload'] =3D array( 'type' =3D> 'form', 'weight' =3D> 1, 'form_id' =3D> 'islandora_marcxml_file_form', 'args' =3D> array(), 'file' =3D> 'includes/file.form.inc', 'module' =3D> 'islandora_marcxml', ); } } }
As you seen in the previous step, there are some functions (islandora_in= gest_form_get_step_storage) that help retrieve and persist information into= the form storage. This allows our steps to share information with one anot= her, as well as manipulate the list of prepared Fedora Objects.
There are two levels of storage: per step storage and <= strong>shared storage. Shared storage is first populated with the = configuration that was passed to islandora_ingest_form. Step storage will o= ften contain custom data related to that particular step, and any submitted= values for form steps:
functio= n &islandora_ingest_form_get_shared_storage(array &$form_state); function &islandora_ingest_form_get_step_storage(array &$form_state= , $step_id =3D NULL);
And two functions for grabbing the prepared objects, one for grabbing al= l the objects, and one for grabbing the current object:
functio= n &islandora_ingest_form_get_objects(array &$form_state); function &islandora_ingest_form_get_object(array &$form_state);
functio= n xml_form_builder_islandora_ingest_steps(array &$form_state) { module_load_include('inc', 'xml_form_builder', 'includes/associations'); $shared_storage =3D islandora_ingest_form_get_shared_storage($form_state)= ; $metadata_step_storage =3D &islandora_ingest_form_get_step_storage($f= orm_state, 'xml_form_builder_metadata_step'); $association_step_storage =3D &islandora_ingest_form_get_step_storage= ($form_state, 'xml_form_builder_association_step'); $association_step_storage['models'] =3D isset($association_step_storage['= models']) ? $association_step_storage['models'] : $shared_storage['models']= ; $associations =3D xml_form_builder_get_associations(array(), $association= _step_storage['models'], array()); $metadata_step_storage['association'] =3D isset($metadata_step_storage['a= ssociation']) ? $metadata_step_storage['association'] : current($associatio= ns); $num_associations =3D count($associations); $select_association_step =3D ($num_associations > 1) ? array( 'weight' =3D> 0, 'type' =3D> 'form', 'form_id' =3D> 'xml_form_builder_select_association_form', 'module' =3D> 'xml_form_builder', 'file' =3D> 'includes/select_association.form.inc', 'args' =3D> array($associations), ) : NULL; $metadata_step =3D ($num_associations >=3D 1) ? array( 'weight' =3D> 5, 'type' =3D> 'form', 'form_id' =3D> 'xml_form_builder_ingest_form', 'module' =3D> 'xml_form_builder', 'file' =3D> 'includes/ingest.form.inc', 'args' =3D> array($metadata_step_storage['association']), ) : NULL; return array( 'xml_form_builder_association_step' =3D> $select_association_step, 'xml_form_builder_metadata_step' =3D> $metadata_step, ); }