From 03b22bf39c51490e9ff9034d293e0c7436e1ebd8 Mon Sep 17 00:00:00 2001
From: Paul Pound <ppound@upei.ca>
Date: Fri, 1 Jun 2012 11:16:26 -0300
Subject: [PATCH] updated islandora.api.inc documentation

---
 islandora.api.php | 86 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 78 insertions(+), 8 deletions(-)

diff --git a/islandora.api.php b/islandora.api.php
index 87a43d0a..7231dff9 100644
--- a/islandora.api.php
+++ b/islandora.api.php
@@ -1,23 +1,83 @@
 <?php
+/**
+ * remove a datastream from a repository object
+ * @param object $fedora_object
+ *  tuque FedoraObject
+ * @param string $datastream_id 
+ */
+function hook_islandora_purge_datastream ($fedora_object, $datastream_id){}
 
-function hook_islandora_purge_datastream ($object_id, $datastream_id){}
-
-function hook_islandora_purge_object($object) {} 
+/**
+ *
+ * @param type $object 
+ *   tuque FedoraObject
+ */
+function hook_islandora_purge_object($islandora_object) {} 
 
-function hook_islandora_view_object($object){}
+/**
+ * allows modules to add to a repository objects display.  If you implement this
+ * hook you should also register your module for view with the get types hook.  
+ * 
+ * islandora gets all displays back in an array and iterates over them.  the order 
+ * they are displayed is based on the order of the key of the array that each
+ * module returns.
+ * 
+ * your module may also want to register a varible that says whether or not it 
+ * should be part of the default display. Modules can also add secondary tabs as
+ * a way to add there output to an islandora display.  the basic image module has 
+ * samples of both (the secondary tabs examples are commented out)
+ * 
+ * @param type $islandora_object
+ *   tuque FedoraObject 
+ */
+function hook_islandora_view_object($islandora_object){}
 
+/**
+ * returns an array listing object types provided by sub modules
+ *  Ex.  array($types['islandora:collectionCModel'][ISLANDORA_VIEW_HOOK] = variable_get('islandora_basic_collection_use_for_default_tab', TRUE);
+ * $types['islandora:collectionCModel'][ISLANDORA_EDIT_HOOK] = FALSE;
+ * 
+ * @return array 
+ */
 function hook_islandora_get_types(){}
 
-function hook_islandora_add_datastream($object) {}
+/**
+ * allows modules to define an object edit page by cmodel
+ * 
+ * your module should return true for ISLANDORA_EDIT_HOOK in its get_types function
+ * 
+ * islandora provides a default implementation that should work for most use cases
+ * @param string $islandora_object
+ * @return string 
+ * 
+ */
+function hook_islandora_edit_object($islandora_object){}
+
+/**
+ * allows modules to alter the fedora object before it is pass through the edit
+ * hooks
+ * @param type $islandora_object 
+ *   a tugue FedoraObject
+ */
+function islandora_islandora_edit_object_alter ($islandora_object){}
+
 
 /**
  * creates and populates a php Fedora object. 
  */
 function hook_islandora_preingest_alter(){}
 
-function hook_islandora_postingest($object){}
-
-function hook_islandora_datastream_edit($object, $dsid){}
+/**
+ * modules can implement this hook to add or remove datastreams after an
+ * object has been ingested.  
+ * 
+ * Each module should check for the newly ingested repository objects content 
+ * model to make sure it is a type of object they want to act on.  
+ * 
+ * @param type $islandora_object 
+ *   tugue FeodoraObject
+ */
+function hook_islandora_postingest($islandora_object){}
 
 /**
  * Register potential ingest routes. Implementations should return an array containing possible routes.
@@ -42,3 +102,13 @@ function hook_islandora_object_alter ($fedora_object){}
  *   an arr of rendered views
  */
 function hook_islandora_display_alter ($arr){}
+
+/**
+ *
+ * @param type $islandora_object
+ *   a tuque FedoraObject
+ * @param array $content_models
+ * @param string $collection_pid 
+ */
+function hook_islandora_ingest_pre_ingest($islandora_object, $content_models, $collection_pid){}
+