khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-03 02:09:45 +07:00
Code Issues Packages Projects Releases Wiki Activity

added todos for the docs on vcategories

Browse Source
This commit is contained in:
Bernhard Posselt
2013-02-09 15:53:23 +01:00
parent 4c7a0a14d9
commit 1600758d3a
4 changed files with 35 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
developer_manual/app/filesystem.rst
View File

@@ -1,19 +1,20 @@
Filesystem
==========
ownCloud handling of filesystems is very flexible. A variety of local and remote filesystem types are supported, as well as a variety of hooks and optional features such as encryption and version control. It is important that apps use the correct methods for interacting with files in order to maintain this flexibility.
In some cases using PHP’s internal filesystem functions directly will be sufficient, such as unlink() and mkdir(). Most of the time however it is necessary to use one of ownCloud’s filesystem classes. This documentation assumes that you are working with files stored within a user’s directory (as opposed to ownCloud core files), and therefore need to use OC_Filesystem.
In some cases using PHP’s internal filesystem functions directly will be sufficient, such as **unlink()** and **mkdir()**. Most of the time however it is necessary to use one of ownCloud’s filesystem classes. This documentation assumes that you are working with files stored within a user’s directory (as opposed to ownCloud core files), and therefore need to use **OC_Filesystem**.
Using PHP filesystem functions directly
---------------------------------------
An example of when it is approprite to use PHP’s filesystem functions instead of OC_Filesystem is if you are storing temporary files which will not be saved, or whose saving is taken care of by external code. ownCloud’s zip compression class does this (OC_Archive_ZIP), and returns the temporarily stored compressed file so that external code can determine what to do with it. Parts of ownCloud’s installation procedure also fall into this category, as certain files need only be saved temporarily in order to set up more permanent storage options.
An example of when it is approprite to use PHP’s filesystem functions instead of **OC_Filesystem** is if you are storing temporary files which will not be saved, or whose saving is taken care of by external code. ownCloud’s zip compression class does this (**OC_Archive_ZIP**), and returns the temporarily stored compressed file so that external code can determine what to do with it. Parts of ownCloud’s installation procedure also fall into this category, as certain files need only be saved temporarily in order to set up more permanent storage options.
Using ownCloud’s filesystem methods
-----------------------------------
Most filesystem interaction should make use of OC_Filesystem. By using the methods within this class you ensure that non-standard and future ownCloud configurations, as well as other filesystem-related apps, will function correctly with your code. Static methods for performing most filesystem operations are provided, including:
Most filesystem interaction should make use of **OC_Filesystem**. By using the methods within this class you ensure that non-standard and future ownCloud configurations, as well as other filesystem-related apps, will function correctly with your code. Static methods for performing most filesystem operations are provided, including:
.. note:: needs to be reworked into rst class defs
* mkdir( $path )
* rmdir( $path )
@@ -43,14 +44,17 @@ Most filesystem interaction should make use of OC_Filesystem. By using the metho
* free_space( $path )
* search( $query )
OC_Filesystem must be initiated before it can be used using the OC_Filesystem::init() method (the class is follows the `singleton pattern`_). init() takes one argument, which is the root directory to be used within the virtual filesystem that OC_Filesystem will work with.
.. note:: **Do not use singletons inside your code!**. It is an antipattern and makes your code hard to test
OC_Filesystem must be initiated before it can be used using the OC_Filesystem::**init()** method (the class is follows the `singleton pattern`_). **init()** takes one argument, which is the root directory to be used within the virtual filesystem that **OC_Filesystem** will work with.
Example:
.. code-block:: php
OC_Filesystem::init( '/' . $user . '/' . $root );
OC_Filesystem::mkdir( 'test' );
if ( OC_Filesystem::is_dir('test') ) { echo 'OC_Filesystem is being used correctly'; }``
<?php
OC_Filesystem::init( '/' . $user . '/' . $root );
OC_Filesystem::mkdir( 'test' );
if ( OC_Filesystem::is_dir('test') ) { echo 'OC_Filesystem is being used correctly'; }``
.. _singleton pattern: https://en.wikipedia.org/wiki/Singleton_pattern

2
developer_manual/app/hooks.rst
View File

@@ -1,6 +1,8 @@
Hooks
=====
.. todo:: Needs to be reworked
In ownCloud apps, function or methods (event handlers) which are used by the app
and called by ownCloud core hooks, are generally stored in
apps/appname/lib/hooks.php.Hooks are a way of implementing the `observer

4
developer_manual/app/share-api.rst
View File

@@ -1,7 +1,9 @@
Share API
=========
**Warning: The Share API is still under heavy development and testing. Report issues to Michael Gapczynski.**
.. todo:: Needs to be reworked
.. Warning:: **The Share API is not stable** and still under heavy development and testing. Report issues to Michael Gapczynski.
The Share API was introduced in ownCloud 5 as a public API for apps to share content. It is a revision of the original file sharing app with enhancements to increase stability, reduce conflicts, and operate in a generic fashion. At this time it is possible to share content with local ownCloud users, groups, contacts, and email via link. This document is a guide for using the Share API in apps. The Share API is made up of a public class OCP\Share in ``/lib/public/share.php``, an AJAX file ``/core/ajax/share.php``, and a JavaScript file ``/core/js/share.js``. Javadoc style documentation is included in OCP\Share.

21
developer_manual/app/vcategories.rst
View File

@@ -8,9 +8,9 @@ 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.
The API is mainly designed for objects using `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 API is mainly designed for objects using `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.
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`.
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 :doc:`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.
@@ -22,10 +22,14 @@ The API can be used both from PHP and via a simple Javascript object.
PHP
---
.. todo:: Provide an easier example with less text
As example I will use a very simplified version of how it is used in the Contacts app. The real implementation is optimized for speed and low memory consumption, but there's no need to show that here.
First check if any categories have been saved for `contact` objects, if not scan all vCards for categories:
.. todo:: use comments inside the php source to explain the functionality
.. code-block:: php
<?php
@@ -60,6 +64,7 @@ The second argument being null will use the current user id. After instantiating
For acting on user input the following methods, which should be mostly self-explanatory, are available:
.. php:class:: OC_VCategories
.. php:method:: __construct()
@@ -78,9 +83,10 @@ For acting on user input the following methods, which should be mostly self-expl
:param array $objects: If `$objects` is not null it is assumed to be an array of id/data pairs passed by reference.
:returns: the integer id of the new category or **false** if it already exists.
The data is parsed into an OC_VObject and if found the categories will be removed from the CATEGORIES property and the OC_VObject will be serialized back to a string again. It is up to the app to store the data afterwards.
The data is parsed into an **OC_VObject** and if found the categories will be removed from the **CATEGORIES** property and the **OC_VObject** will be serialized back to a string again. It is up to the app to store the data afterwards.
.. todo:: use a proper rst syntax for class definitions
.. code-block:: php
@@ -91,12 +97,16 @@ For acting on user input the following methods, which should be mostly self-expl
`addToCategory()` creates an user/category/object relation. `$category` can be either an integer category id or a string with the category name. If `$type` is null the type provided in the constructor will be used.
.. todo:: use a proper rst syntax for class definitions
.. code-block:: php
public function categories($format = null);
Per default this returns an array of the category names, but given the `$format` argument `OC_VCategories::FORMAT_MAP`, it will return an array of `array('id' => $id, 'name' => $name)` maps.
.. todo:: use a proper rst syntax for class definitions
.. code-block:: php
public function idsForCategory($category);
@@ -105,9 +115,12 @@ Returns an array of integer object ids. `$category` can again be either the inte
Favorites
---------
.. todo:: use a proper rst syntax for class definitions
.. code-block:: php
<?php
public function addToFavorites($objid, $type = null);
public function removeFromFavorites($objid, $type = null);
public function getFavorites($type = null);
@@ -115,6 +128,6 @@ Favorites
Javascript
----------
To be written...
.. todo:: needs to be written
.. [1] An example of a `vCard <https://en.wikipedia.org/wiki/Vcard#vCard_3.0>`_ version 3.0