ISLANDORA-1748 -- add hook_datastream_filename_alter().

Why:

* The islandora_datastream_filenamer module allows the file names of downloadable datastreams to be modified, using tokens such as the object pid, datastream id, etc.
* But in order to work, it requires a patch be applied to islandora core.

This change addresses the need by:

* Creates a new drupal_alter hook in islandora/includes/datastream.inc: hook_datastream_filename_alter().
* Documents the hook in islandora.api.inc

Reference Links:

* https://jira.duraspace.org/browse/ISLANDORA-1748

includes/datastream.inc

@@ -63,6 +63,11 @@ function islandora_view_datastream(AbstractDatastream $datastream, $download = F
     if ($duplicate_extension_position === FALSE) {
       $filename .= $extension;
     }
+
+    // Allow other modules to modify or replace the filename.
+    drupal_alter('datastream_filename', $filename, $datastream);
+
+
     header("Content-Disposition: attachment; filename=\"$filename\"");
   }
 

islandora.api.php

@@ -945,3 +945,21 @@ function callback_islandora_breadcrumbs_backends(AbstractObject $object) {
   // Do something to get an array of breadcrumb links for $object, root first.
   return array($root_link, $collection_link, $object_link);
 }
+
+/**
+ * Permit modules to alter the filename of a downloaded datastream.
+ *
+ * @param string $filename
+ * @param AbstractDatastream $datastream
+ */
+function hook_datastream_filename_alter(&$filename, AbstractDatastream $datastream) {
+
+  // Example taken from islandora_datastream_filenamer.
+  $pattern = variable_get('islandora_ds_download_filename_pattern', FALSE);
+  if($pattern) {
+    $filename = token_replace($pattern,
+      array('datastream' => $datastream),
+      array('clear' => TRUE)
+    );
+  }
+}