Merge pull request #4892 from owncloud/vcategories_public

OC_VCategories => OC\Tags. Public interface and getter in server container

3 files changed, 220 insertions, 0 deletions

diff --git a/lib/public/iservercontainer.php b/lib/public/iservercontainer.php
index 6d291321957..f4045faefef 100644
--- a/lib/public/iservercontainer.php
+++ b/lib/public/iservercontainer.php
@@ -56,6 +56,14 @@ interface IServerContainer {
 	function getPreviewManager();
 
 	/**
+	 * Returns the tag manager which can get and set tags for different object types
+	 *
+	 * @see \OCP\ITagManager::load()
+	 * @return \OCP\ITagManager
+	 */
+	function getTagManager();
+
+	/**
 	 * Returns the root folder of ownCloud's data directory
 	 *
 	 * @return \OCP\Files\Folder
diff --git a/lib/public/itagmanager.php b/lib/public/itagmanager.php
new file mode 100644
index 00000000000..07e1d12fc0f
--- /dev/null
+++ b/lib/public/itagmanager.php
@@ -0,0 +1,48 @@
+<?php
+/**
+* ownCloud
+*
+* @author Thomas Tanghus
+* @copyright 2013 Thomas Tanghus <thomas@tanghus.net>
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the License, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+*
+*/
+
+/**
+ * Factory class creating instances of \OCP\ITags
+ *
+ * A tag can be e.g. 'Family', 'Work', 'Chore', 'Special Occation' or
+ * anything else that is either parsed from a vobject or that the user chooses
+ * to add.
+ * Tag names are not case-sensitive, but will be saved with the case they
+ * are entered in. If a user already has a tag 'family' for a type, and
+ * tries to add a tag named 'Family' it will be silently ignored.
+ */
+
+namespace OCP;
+
+interface ITagManager {
+
+	/**
+	* Create a new \OCP\ITags instance and load tags from db.
+	*
+	* @see \OCP\ITags
+	* @param string $type The type identifier e.g. 'contact' or 'event'.
+	* @param array $defaultTags An array of default tags to be used if none are stored.
+	* @return \OCP\ITags
+	*/
+	public function load($type, $defaultTags=array());
+
+}
\ No newline at end of file
diff --git a/lib/public/itags.php b/lib/public/itags.php
new file mode 100644
index 00000000000..5b1ebd189da
--- /dev/null
+++ b/lib/public/itags.php
@@ -0,0 +1,164 @@
+<?php
+/**
+* ownCloud
+*
+* @author Thomas Tanghus
+* @copyright 2013 Thomas Tanghus <thomas@tanghus.net>
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the License, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.  If not, see <http://www.gnu.org/licenses/>.
+*
+*/
+
+namespace OCP;
+
+// FIXME: Where should I put this? Or should it be implemented as a Listener?
+\OC_Hook::connect('OC_User', 'post_deleteUser', 'OC\Tags', 'post_deleteUser');
+
+/**
+ * Class for easily tagging objects by their id
+ *
+ * A tag can be e.g. 'Family', 'Work', 'Chore', 'Special Occation' or
+ * anything else that is either parsed from a vobject or that the user chooses
+ * to add.
+ * Tag names are not case-sensitive, but will be saved with the case they
+ * are entered in. If a user already has a tag 'family' for a type, and
+ * tries to add a tag named 'Family' it will be silently ignored.
+ */
+
+interface ITags {
+
+	/**
+	* Check if any tags are saved for this type and user.
+	*
+	* @return boolean.
+	*/
+	public function isEmpty();
+
+	/**
+	* Get the tags for a specific user.
+	*
+	* This returns an array with id/name maps:
+	* [
+	* 	['id' => 0, 'name' = 'First tag'],
+	* 	['id' => 1, 'name' = 'Second tag'],
+	* ]
+	*
+	* @returns array
+	*/
+	public function getTags();
+
+	/**
+	* Get the a list if items tagged with $tag.
+	*
+	* Throws an exception if the tag could not be found.
+	*
+	* @param string|integer $tag Tag id or name.
+	* @return array An array of object ids or false on error.
+	*/
+	public function getIdsForTag($tag);
+
+	/**
+	* Checks whether a tag is already saved.
+	*
+	* @param string $name The name to check for.
+	* @return bool
+	*/
+	public function hasTag($name);
+
+	/**
+	* Add a new tag.
+	*
+	* @param string $name A string with a name of the tag
+	* @return int the id of the added tag or false if it already exists.
+	*/
+	public function add($name);
+
+	/**
+	* Rename tag.
+	*
+	* @param string $from The name of the existing tag
+	* @param string $to The new name of the tag.
+	* @return bool
+	*/
+	public function rename($from, $to);
+
+	/**
+	* Add a list of new tags.
+	*
+	* @param string[] $names A string with a name or an array of strings containing
+	* the name(s) of the to add.
+	* @param bool $sync When true, save the tags
+	* @param int|null $id int Optional object id to add to this|these tag(s)
+	* @return bool Returns false on error.
+	*/
+	public function addMultiple($names, $sync=false, $id = null);
+
+	/**
+	* Delete tag/object relations from the db
+	*
+	* @param array $ids The ids of the objects
+	* @return boolean Returns false on error.
+	*/
+	public function purgeObjects(array $ids);
+
+	/**
+	* Get favorites for an object type
+	*
+	* @return array An array of object ids.
+	*/
+	public function getFavorites();
+
+	/**
+	* Add an object to favorites
+	*
+	* @param int $objid The id of the object
+	* @return boolean
+	*/
+	public function addToFavorites($objid);
+
+	/**
+	* Remove an object from favorites
+	*
+	* @param int $objid The id of the object
+	* @return boolean
+	*/
+	public function removeFromFavorites($objid);
+
+	/**
+	* Creates a tag/object relation.
+	*
+	* @param int $objid The id of the object
+	* @param int|string $tag The id or name of the tag
+	* @return boolean Returns false on database error.
+	*/
+	public function tagAs($objid, $tag);
+
+	/**
+	* Delete single tag/object relation from the db
+	*
+	* @param int $objid The id of the object
+	* @param int|string $tag The id or name of the tag
+	* @return boolean
+	*/
+	public function unTag($objid, $tag);
+
+	/**
+	* Delete tags from the
+	*
+	* @param string[] $names An array of tags to delete
+	* @return bool Returns false on error
+	*/
+	public function delete($names);
+
+}
\ No newline at end of file