ENHANCEMENT: completing the DMS interface

code/DMSInterface.php

@@ -11,24 +11,52 @@
 interface DMSInterface {
 
 	/**
-	 * Factory method that returns an instance of the DMS. This could be anything that implements the DMSInterface
+	 * Factory method that returns an instance of the DMS. This could be any class that implements the DMSInterface.
 	 * @static
 	 * @abstract
-	 * @return DMSinstance
+	 * @return DMSInterface An instance of the Document Management System
 	 */
 	static function getDMSInstance();
 
 	/**
+	 * Takes a File object or a String (path to a file) and copies it into the DMS. The original file remains unchanged.
 	 * When storing a document, sets the fields on the File has "tag" metadata. E.g: filename, path, etc. all become
 	 * single-value tags on the Document.
 	 * @abstract
-	 * @param File $file
-	 * @return mixed
+	 * @param $file File object, or String that is path to a file to store
+	 * @return boolean Success or Failure of the store operation
 	 */
-	function storeDocument(File $file);
+	function storeDocument($file);
 
-	function getByTag($category = null, $value = null);
-	function getByFullTextSearch($searchText);
-	function getByTitle($searchTitle);
+	/**
+	 *
+	 * Returns a number of Document objects based on the a search by tags. You can search by category alone,
+	 * by tag value alone, or by both. I.e: getByTag("fruits",null); getByTag(null,"banana"); getByTag("fruits","banana")
+	 * @abstract
+	 * @param null $category The metadata category to search for
+	 * @param null $value The metadata value to search for
+	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
+	 * @return DocumentInterface
+	 */
+	function getByTag($category = null, $value = null, $showEmbargoed = false);
 
+	/**
+	 * Returns a number of Document objects that match a full-text search of the Documents and their contents
+	 * (if contents is searchable and compatible search module is installed - e.g. FullTextSearch module)
+	 * @abstract
+	 * @param $searchText String to search for
+	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
+	 * @return DocumentInterface
+	 */
+	function getByFullTextSearch($searchText, $showEmbargoed = false);
+
+
+	/**
+	 * Returns a list of Document objects associated with a Page
+	 * @abstract
+	 * @param $page SiteTree to fetch the associated Documents from
+	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
+	 * @return DataList Document list associated with the Page
+	 */
+	function getByPage($page, $showEmbargoed = false);
 }

code/DocumentInterface.php

@@ -1,8 +1,8 @@
 <?php
 /**
  * Interface for a Document used in the Document Management System. A document is create by storing a File object in an
- * instance of the DMSInterface. All write operations on the Document create a new relation, so there is no explicit
- * write() method that needs to be called.
+ * instance of the DMSInterface. All write operations on the Document create a new relation, so we never need to
+ * explicitly call the write() method on the Document DataObject
  */
 interface DocumentInterface {
 
@@ -14,37 +14,166 @@ interface DocumentInterface {
 	function delete();
 
 	/**
-	 * Could be a simple wrapper around $myDoc->Pages()->add($myPage)
+	 * Associates this document with a Page. This method does nothing if the association already exists.
+	 * This could be a simple wrapper around $myDoc->Pages()->add($myPage) to add a has_many relation
 	 * @abstract
-	 * @param $pageObject
-	 * @return mixed
+	 * @param $pageObject Page object to associate this Document with
+	 * @return null
 	 */
 	function addPage($pageObject);
+
+	/**
+	 * Removes the association between this Document and a Page. This method does nothing if the association does not exist.
+	 * @abstract
+	 * @param $pageObject Page object to remove the association to
+	 * @return mixed
+	 */
 	function removePage($pageObject);
+
+	/**
+	 * Returns a list of the Page objects associated with this Document
+	 * @abstract
+	 * @return DataList
+	 */
 	function getPages();
 
 	/**
-	 * Can be implemented as a key/value store table (although it is more like category/value, because the same category can occur multiple times)
+	 * Adds a metadata tag to the Document. The tag has a category and a value.
+	 * Each category can have multiple values by default. So: addTag("fruit","banana") addTag("fruit", "apple") will add two items.
+	 * However, if the third parameter $multiValue is set to 'false', then all updates to a category only ever update a single value. So:
+	 * addTag("fruit","banana") addTag("fruit", "apple") would result in a single metadata tag: fruit->apple.
+	 * Can could be implemented as a key/value store table (although it is more like category/value, because the
+	 * same category can occur multiple times)
 	 * @abstract
-	 * @param $category
-	 * @param $value
-	 * @return mixed
+	 * @param $category String of a metadata category to add (required)
+	 * @param $value String of a metadata value to add (required)
+	 * @param bool $multiValue Boolean that determines if the category is multi-value or single-value (optional)
+	 * @return null
 	 */
 	function addTag($category, $value, $multiValue = true);
 
-	function addTags($twoDimensionalArray);
-	function removeTag($category = null, $value = null);
+	/**
+	 * Quick way to add multiple tags to a Document. This takes a multidimensional array of category/value pairs.
+	 * The array should look like this:
+	 * $twoDimensionalArray = new array(
+	 *      array('fruit','banana'),
+	 *      array('fruit','apple')
+	 * );
+	 * @abstract
+	 * @param $twoDimensionalArray array containing a list of arrays
+	 * @param bool $multiValue Boolean that determines if the category is multi-value or single-value (optional)
+	 * @return null
+	 */
+	function addTags($twoDimensionalArray, $multiValue = true);
+
+	/**
+	 * Removes a tag from the Document. If you only set a category, then all values in that category are deleted.
+	 * If you specify both a category and a value, then only that single category/value pair is deleted.
+	 * Nothing happens if the category or the value do not exist.
+	 * @abstract
+	 * @param $category Category to remove (required)
+	 * @param null $value Value to remove (optional)
+	 * @return null
+	 */
+	function removeTag($category, $value = null);
+
+	/**
+	 * Deletes all tags associated with this Document.
+	 * @abstract
+	 * @return null
+	 */
 	function removeAllTags();
+
+	/**
+	 * Returns a multi-dimensional array containing all Tags associated with this Document. The array has the
+	 * following structure:
+	 * $twoDimensionalArray = new array(
+     *      array('fruit','banana'),
+     *      array('fruit','apple')
+     * );
+	 * @abstract
+	 * @return array Multi-dimensional array of tags
+	 */
 	function getAllTags();
 
+	/**
+	 * Returns a link to download this document from the DMS store
+	 * @abstract
+	 * @return String
+	 */
 	function downloadLink();
 
+	/**
+	 * Hides the document, so it does not show up when getByPage($myPage) is called
+	 * (without specifying the $showEmbargoed = true parameter). This is similar to expire, except that this method
+	 * should be used to hide documents that have not yet gone live.
+	 * @abstract
+	 * @return null
+	 */
+	function embargo();
+
+	/**
+	 * Returns if this is Document is embargoed.
+	 * @abstract
+	 * @return bool True or False depending on whether this document is embargoed
+	 */
+	function isEmbargoed();
+
+	/**
+	 * Hides the document, so it does not show up when getByPage($myPage) is called. Automatically un-hides the
+	 * Document at a specific date.
+	 * @abstract
+	 * @param $datetime String date time value when this Document should expire
+	 * @return null
+	 */
+	function embargoUntilDate($datetime);
+
+	/**
+	 * Clears any previously set embargos, so the Document always shows up in all queries.
+	 * @abstract
+	 * @return null
+	 */
+	function clearEmbargo();
+
+	/**
+	 * Hides the document, so it does not show up when getByPage($myPage) is called.
+	 * (without specifying the $showEmbargoed = true parameter). This is similar to embargo, except that it should be
+	 * used to hide documents that are no longer useful.
+	 * @abstract
+	 * @return null
+	 */
+	function expire();
+
+	/**
+	 * Returns if this is Document is expired.
+	 * @abstract
+	 * @return bool True or False depending on whether this document is expired
+	 */
+	function isExpired();
+
+	/**
+	 * Hides the document at a specific date, so it does not show up when getByPage($myPage) is called.
+	 * @abstract
+	 * @param $datetime String date time value when this Document should expire
+	 * @return null
+	 */
+	function expireAtDate($datetime);
+
+	/**
+	 * Clears any previously set expiry.
+	 * @abstract
+	 * @return null
+	 */
+	function clearExpiry();
+
+	/*---- FROM HERE ON: optional API features ----*/
+
+	/**
+	 * Returns a DataList of all previous Versions of this document (check the LastEdited date of each
+	 * object to find the correct one)
+	 * @abstract
+	 * @return DataList List of Document objects
+	 */
 	function getVersions();
 
-	function embargo();
-	function embargoUntilDate();
-	function clearEmbargo();
-	function expire();
-	function expireAtDate();
-	function clearExpiry();
 }