diff --git a/code/DMSInterface.php b/code/DMSInterface.php index 9040ade..73d2a87 100644 --- a/code/DMSInterface.php +++ b/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); } \ No newline at end of file diff --git a/code/DocumentInterface.php b/code/DocumentInterface.php index 2f00ae5..cf6d514 100644 --- a/code/DocumentInterface.php +++ b/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(); } \ No newline at end of file