From e20b237da245709719d9baad4f7f19b660b543ae Mon Sep 17 00:00:00 2001 From: Thomas Tanghus Date: Wed, 31 Oct 2012 23:51:11 +0100 Subject: [PATCH] vcategories: Fixed some markup --- developer_manual/vcategories.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/developer_manual/vcategories.rst b/developer_manual/vcategories.rst index 44531ab59..98a6f5a71 100644 --- a/developer_manual/vcategories.rst +++ b/developer_manual/vcategories.rst @@ -3,11 +3,13 @@ Categories API Introduction ------------ -The Categories API is as the name says used for categorizing objects. The visual representation can be different for each app and is totally up to the developer/designer: you can add tags like for example used in .. _github issues: https://github.com/owncloud/core/issues/ , you can show your objects in a (one-level) hierarchy or you can simply use comma-separated strings. +.. sectionauthor:: Thomas Tanghus -The API is mainly designed for objects using .. _vCard: https://en.wikipedia.org/wiki/Vcard or .. _iCalendar: https://en.wikipedia.org/wiki/ICalendar as storage, as they all have a CATEGORIES property from which the categories are extracted, and were they will be saved so that client apps like Apples .. _iCal: https://en.wikipedia.org/wiki/ICal and .. _KDEs Kontact: http://userbase.kde.org/Kontact can use them as well. Currently the API is used in the Calendar, Task and Contacts apps, plus recently the 3rd party Journal app. +The Categories API is as the name says used for categorizing objects. The visual representation can be different for each app and is totally up to the developer/designer: you can add tags like for example used in `github issues `_ , you can show your objects in a (one-level) hierarchy or you can simply use comma-separated strings. -Internally the categories and the object/category relations are stored using the category, the user ID, the object ID and a type identifier to be able uniquely identify where a category "belongs to". The types are similar to the types used in the .. _Share API: http://owncloud.org/dev/apps/share-api/ for example `contact`, `event` or `task`. +The API is mainly designed for objects using `vCard `_ or `iCalendar `_ as storage, as they all have a CATEGORIES property from which the categories are extracted, and were they will be saved so that client apps like Apples `iCal `_ and `KDEs Kontact `_ can use them as well. Currently the API is used in the Calendar, Task and Contacts apps, plus recently the 3rd party Journal app. + +Internally the categories and the object/category relations are stored using the category, the user ID, the object ID and a type identifier to be able uniquely identify where a category "belongs to". The types are similar to the types used in the `Share API `_ for example `contact`, `event` or `task`. Besides being used for categories, the API also supports setting objects as favorites. Favorites are simply a separate category internally, but convenience methods for getting/setting objects as favorites are available. @@ -35,9 +37,9 @@ First check if any categories have been saved for `contact` objects, if not scan } -Here we first create an instance of OC_VCategories and tell it to store categories identified by `contact` type. Then we fetch all the contacts and create and array holding arrays of id/carddata [1]_ pairs. The OC_VCategories object is then told to scan all the vCards `CATEGORIES` property and save the result when done. If it finds any categories it doesn't know already, they will be added to the database (category names are NOT case-sensitive). Additionally it will create relations between the category and the contact object to be used by the contacts app. The `rescan` method also takes a third boolean argument `reset` which will purge any categories and relations for the current user. +Here we first create an instance of OC_VCategories and tell it to store categories identified by ``contact`` type. Then we fetch all the contacts and create and array holding arrays of id/carddata [1]_ pairs. The OC_VCategories object is then told to scan all the vCards ``CATEGORIES`` property and save the result when done. If it finds any categories it doesn't know already, they will be added to the database (category names are NOT case-sensitive). Additionally it will create relations between the category and the contact object to be used by the contacts app. The ``rescan`` method also takes a third boolean argument ``reset`` which will purge any categories and relations for the current user. -This piece of code will in most cases only run once i.e. when the user first opens the Contacts app after upgrade to ownCloud 5. Behind the scene any update or additions will scan for categories using the methods `loadFromVObject(int $id, OC_VObject $vobject)` which scans an already parsed VCALENDAR, VEVENT, VTODO, VJOURNAL or as in this example VCARD (if given a VCALENDAR the class will use the first found of either VEVENT, VTODO or VJOURNAL). Similarly when a contact is deleted the `purgeObject($id)` method will remove any category/object relations. When a user is deleted all entries for that user will automatically be purged from the database as well. +This piece of code will in most cases only run once i.e. when the user first opens the Contacts app after upgrade to ownCloud 5. Behind the scene any update or additions will scan for categories using the methods ``loadFromVObject(int $id, OC_VObject $vobject)`` which scans an already parsed VCALENDAR, VEVENT, VTODO, VJOURNAL or as in this example VCARD (if given a VCALENDAR the class will use the first found of either VEVENT, VTODO or VJOURNAL). Similarly when a contact is deleted the ``purgeObject($id)`` method will remove any category/object relations. When a user is deleted all entries for that user will automatically be purged from the database as well. **Instantiation** @@ -46,10 +48,12 @@ Default values can be given in the constructor: .. code-block:: php + -The second argument being null will use the current user id. After instantiating this way the database will be pre-filled with the default categories for the current user, and any `isEmpty()` calls will of course return **false** ;) +The second argument being null will use the current user id. After instantiating this way the database will be pre-filled with the default categories for the current user, and any ``isEmpty()`` calls will of course return **false** ;) For acting on user input the following methods, which should be mostly self-explanatory, are available: @@ -57,7 +61,7 @@ For acting on user input the following methods, which should be mostly self-expl public function add($name); -Returns the integer id of the new category or false if it already exists. +Returns the integer id of the new category or **false** if it already exists. .. code-block:: php @@ -98,4 +102,6 @@ Favorites Javascript ---------- -To be written... \ No newline at end of file +To be written... + +.. [1] An example of a `vCard `_ version 3.0