Commit 54f2161e authored by Mark Jordan's avatar Mark Jordan
Browse files

Updated API documentation.

parent 2cac9b95
......@@ -5,7 +5,7 @@
[BagIt](https://wiki.ucop.edu/display/Curation/BagIt) is a specification for packaging content and metadata about that content into a format that can be shared between applications. This module provides a framework for generating Bags for Islandora objects. It is a fork of the [Islandora BagIt](https://github.com/Islandora/islandora_bagit) module. The main differences between it and this module are:
* this module does not provide a usere-facing option to generate Bags, it only provides a Drush command.
* this module does not probide implementations of Islandora hooks to detect when an object or datastream has been ingested or modified.
* this module does not provide implementations of Islandora hooks to detect when an object or datastream has been ingested or modified.
* this module replaces Islandora BagIt's plugins with submodules.
Islandora sites should not enable both this module and Islandora BagIt. Only one should be enabled since they share permissions and hook definitions.
......@@ -34,13 +34,15 @@ To install the Islandora BagIt Light module:
## Configuration
All configuration for this module is performed either via Drush options.
All configuration for this module is performed either via Drush options and .ini files.
## Submodules
### Extending and customizing the BagIt module
Islandora BagIt Light ...
### Modifying a Bag from your own modules
## Modifying a Bag from your own modules
This module provides a drupal_alter() hook, which allows other modules to use hook_islandora_bagit_alter($bag, $islandora_object). Your module can modify the current Bag using any of the methods provided by the BagItPHP library. Each implementation of this hook must take $bag and $islandora_object as parameters; $islandora_object is provided so you can access properties of the object in your module easily. A typical implementation looks like this:
......@@ -56,7 +58,7 @@ This module provides a drupal_alter() hook, which allows other modules to use ho
*/
function mymodule_islandora_bagit_alter($bag, $islandora_object) {
// Add some custom metadata to bag-info.txt.
$bag->bagInfoData('Some-Arbitrary-Field', 'Foo bar baz');
$bag->setBagInfoData('Some-Arbitrary-Field', 'Foo bar baz');
// Add a file that is not managed by a plugin. Note: extra files
// should be added by plugins if possible, since files that are
// added in drupal_alter() hooks are not counted in Payload-Oxum
......@@ -69,7 +71,7 @@ function mymodule_islandora_bagit_alter($bag, $islandora_object) {
Note that implementations of hook_islandora_bagit_alter() must call $bag->update() themselves, typically at the very end of the function.
### Post-Bag-creation hook
## Post-Bag-creation hook
Islandora BagIt provides an additional hook, islandora_bagit_post_create, that allows other modules to get notifications that a Bag has just been created. A basic implementation is:
......@@ -90,7 +92,7 @@ function mymodule_islandora_bagit_post_create($pid, $bag_path) {
This hook can be used to send notification emails after a Bag has been created, to add the Bag to a queue for further processing, or to copy the Bag to a different server.
### Drush integration
## Drush integration
Bags can be created for individual Islandora objects or for all objects in a given collection using Drush:
......@@ -98,7 +100,7 @@ Bags can be created for individual Islandora objects or for all objects in a giv
where UID is the user ID or user name of the fedoraAdmin user (or equivalent), 'object' or 'collection' indicates whether you want to create a Bag for a single object or a Bag for every member of a collection, and PID is the PID of the Islandora object or collection.
### Permissions and security
## Permissions and security
This module is intended for users who have a fairly high level of permissions on a Drupal site. Because the goal is to package up all or some of the datastreams in an Islandora object, users who can create and download Bags should have access to those datastreams. However, the module does check the current users' access to a datastream before adding it to the Bag.
......
......@@ -31,3 +31,43 @@ function hook_islandora_bagit_get_files($islandora_object, $tmp_ds_directory) {
return $files_to_add;
}
/**
* Informs other module that a Bag has been created.
*
* @param string $pid
* The PID of the object the Bag was created for.
* @param string $bag_path
* The path to the new Bag.
*/
function hook_islandora_bagit_post_create($pid, $bag_path) {
watchdog('bagit', 'Bag created for !object at !path.',
array('!object' => $pid, '!path' => $bag_path));
}
/**
* Implementation of drupal_alter().
*
* Implementations can modify the current Bag using any of the
* methods provided by the BagItPHP library.
*
* @param object $bag
* A BagIt object instantiated in the Islandora BagIt Light module.
*
* @param object $islandora_object
* The current $islandora_object.
*/
function mymodule_islandora_bagit_alter($bag, $islandora_object) {
// Add some custom metadata to bag-info.txt.
$bag->setBagInfoData('Some-Arbitrary-Field', 'Foo bar baz');
// Add a file that is not managed by a plugin. Note: extra files
// should be added within implementations of hook_islandora_bagit_get_files()
// whenever possible, since files added in drupal_alter() hooks are not
// counted in Payload-Oxum values generated by the Islandora BagIt
// Light module.
$bag->addFile('/path/to/file.txt', 'myfile.txt');
// Update the Bag (this is required in all implementations).
$bag->update();
}
Supports Markdown
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