better documentation, tests

islandora.api.php

@@ -340,7 +340,12 @@ function hook_cmodel_pid_dsid_islandora_datastream_ingested(AbstractObject $obje
  *   datastream.
  */
 function hook_islandora_datastream_modified(AbstractObject $object, AbstractDatastream $datastream, array $params) {
-
+  // Sample of sanitizing a label.
+  $datastream->label = trim($datastream->label);
+  // Sample of using modifyDatastream parameters.
+  if (isset($params['mimetype'])) {
+    $datastream->label .= " ({$params['mimetype']})";
+  }
 }
 
 /**
@@ -662,8 +667,9 @@ function hook_cmodel_pid_islandora_overview_object_alter(AbstractObject &$object
  *   Optional object to which derivatives will be added
  * @param array $ds_modified_params
  *   An array that will contain the properties changed on the datastream if
- *   derivatives were triggered from a datastream_modified hook. Can be
+ *   derivatives were triggered from a datastream_modified hook, as well as a
- *   populated manually, but likely empty otherwise.
+ *   'dsid' key naming the datastream that was modified. Can be populated
+ *   manually, but likely empty otherwise.
  *
  * @return array
  *   An array containing an entry for each derivative to be created. Each entry
@@ -746,6 +752,16 @@ function hook_islandora_derivative_alter(&$derivatives, AbstractObject $object,
       unset($derivatives[$key]);
     }
   }
+  // Example of altering out derivative generation if only a specified set of
+  // datastream parameters have been modified.
+  $mask = array(
+    'label' => NULL,
+    'dateLastModified' => NULL,
+    'dsid' => NULL,
+  );
+  if (empty(array_diff_key($ds_modified_params, $mask))) {
+    $derivatives = array();
+  }
 }
 
 /**

islandora.module

@@ -1800,6 +1800,9 @@ function islandora_islandora_datastream_ingested(AbstractObject $object, Abstrac
  */
 function islandora_islandora_datastream_modified(AbstractObject $object, AbstractDatastream $datastream, $params) {
   module_load_include('inc', 'islandora', 'includes/derivatives');
+  $params += array(
+    'dsid' => $datastream->id,
+  );
   $logging_results = islandora_do_derivatives($object, array(
     'source_dsid' => $datastream->id,
     'force' => TRUE,

tests/derivatives.test

@@ -248,6 +248,22 @@ class IslandoraDerivativesTestCase extends IslandoraWebTestCase {
     $this->assertEqual(3, count($_islandora_derivative_test_derivative_functions), 'Expected 3 derivative functions when there is no source_dsid, got ' . count($_islandora_derivative_test_derivative_functions) . '.');
   }
 
+  /**
+   * Tests that a derivative can be conditional on the source_dsid modification.
+   */
+  public function testConditionalDerivative() {
+    $object = $this->constructBaseObject();
+    // Derivatives should fire.
+    $ds = $object->constructDatastream('SOMEOTHERDATASTREAM');
+    $ds->label = 'Some Label';
+    $ds->mimetype = 'some/mime';
+    $object->ingestDatastream($ds);
+    $this->assertEqual(1, count($object['SOMEWEIRDDERIV']), 'Expected one version of SOMEWEIDDERIV when unconditionally creating derivatives, got ' . count($object['SOMEWEIRDDERIV']));
+    // Derivatives should not fire.
+    $object['SOMEOTHERDATASTREAM']->label = 'Changed Label';
+    $this->assertEqual(1, count($object['SOMEWEIRDDERIV']), 'Expected the version count of SOMEWEIRDDERIV to remain the same when only changing the label of its source, got ' . count($object['SOMEWEIRDDERIV']));
+  }
+
   /**
    * Helper function that will construct a base object.
    */

tests/hooks.test

@@ -214,6 +214,18 @@ class IslandoraHooksTestCase extends IslandoraWebTestCase {
     }
     $this->repository->purgeObject($object->id);
 
+    // Test modifying a datastream conditionally on the modification parameters.
+    $object = $this->repository->constructObject('test:testModifiedDatastreamHook');
+    $this->repository->ingestObject($object);
+    $ds = $object->constructDatastream('TEST');
+    $object->ingestDatastream($ds);
+    $_SESSION['islandora_hooks']['hook'][ISLANDORA_DATASTREAM_MODIFIED_HOOK] = FALSE;
+    $_SESSION['islandora_hooks']['iteration'][ISLANDORA_DATASTREAM_MODIFIED_HOOK] = 0;
+    $_SESSION['islandora_hooks']['alter'][ISLANDORA_DATASTREAM_MODIFIED_HOOK] = FALSE;
+    $object->label = "New Label!";
+    $ds->mimetype = "mr/mime";
+    $this->assertEqual('New Label! (Mr. Mime)', $object->label, 'Modified object conditionally on datastream modification.');
+
     // Test purging with FedoraRepository::purgeObject().
     $object = $this->repository->constructObject('test:testPurgedDatastreamHook');
     $this->repository->ingestObject($object);

tests/islandora_derivatives_test.module

@@ -34,9 +34,36 @@ function islandora_derivatives_test_some_cmodel_islandora_derivative() {
         'islandora_derivatives_test_create_nosource_datastream',
       ),
     ),
+    array(
+      'source_dsid' => 'SOMEOTHERDATASTREAM',
+      'destination_dsid' => 'SOMEWEIRDDERIV',
+      'weight' => '0',
+      'function' => array(
+        'islandora_derivatives_test_derive_other_datastream',
+      ),
+    ),
   );
 }
 
+/**
+ * Implements hook_islandora_CMODEL_PID_derivative_alter().
+ */
+function islandora_derivatives_test_some_cmodel_islandora_derivative_alter(&$derivatives, AbstractObject $object, $ds_modified_params) {
+  // Use a mask to determine if only the label has been modified.
+  $diff = array_diff_key($ds_modified_params, array(
+    'label' => NULL,
+    'dateLastModified' => NULL,
+  ));
+  // If that's the case, don't proceed.
+  if (empty($diff)) {
+    foreach ($derivatives as $key => $derivative) {
+      if ($derivative['source_dsid'] == 'SOMEOTHERDATASTREAM') {
+        unset($derivatives[$key]);
+      }
+    }
+  }
+}
+
 /**
  * Creates the DERIV datastream for use in testing.
  *
@@ -140,6 +167,22 @@ function islandora_derivatives_test_create_nosource_datastream(AbstractObject $o
   }
 }
 
+/**
+ * Derives the SOMEWEIRDDERIV datastream.
+ *
+ * @param AbstractObject $object
+ *   An AbstractObject representing a Fedora object.
+ * @param bool $force
+ *   Whether or not derivative generation is to be forced.
+ */
+function islandora_derivatives_test_derive_other_datastream(AbstractObject $object, $force = FALSE) {
+  global $_islandora_derivative_test_derivative_functions;
+  $_islandora_derivative_test_derivative_functions[] = 'islandora_derivatives_test_derive_other_datastream';
+  if (!isset($object['SOMEWEIRDDERIV']) || isset($object['SOMEWEIRDDERIV']) && $force === TRUE) {
+    islandora_derivatives_test_add_datastream($object, 'SOMEWEIRDDERIV', 'wat');
+  }
+}
+
 /**
  * Helper function that adds/modifies the datastream to the object in testing.
  *

tests/islandora_hooks_test.module

@@ -140,13 +140,17 @@ function islandora_hooks_test_islandora_datastream_ingested(AbstractObject $obje
 /**
  * Implements hook_islandora_datastream_modified().
  */
-function islandora_hooks_test_islandora_datastream_modified(AbstractObject $object, AbstractDatastream $datastream) {
+function islandora_hooks_test_islandora_datastream_modified(AbstractObject $object, AbstractDatastream $datastream, array $params) {
   if ($object->id == 'test:testModifiedDatastreamHook' && $datastream->id == "TEST") {
     $_SESSION['islandora_hooks']['hook'][ISLANDORA_DATASTREAM_MODIFIED_HOOK] = TRUE;
     if ($_SESSION['islandora_hooks']['iteration'][ISLANDORA_DATASTREAM_MODIFIED_HOOK]++ < 3) {
       $new_label = 'New Label! + ' . $_SESSION['islandora_hooks']['iteration'][ISLANDORA_DATASTREAM_MODIFIED_HOOK];
       $datastream->label = $new_label;
     }
+    if (isset($params['mimetype'] && $params['mimetype'] == 'mr/mime')) {
+      $new_label = 'New Label! (Mr. Mime)';
+      $object->label = $new_label;
+    }
   }
 }