From d04526c49861e38ac2bba22770ecd852beb65c74 Mon Sep 17 00:00:00 2001 From: Daniel Molkentin Date: Thu, 3 Jan 2013 18:12:07 +0100 Subject: [PATCH] dev manual: fix markup, links, style --- developer_manual/access.rst | 2 + developer_manual/compatibility.rst | 6 +- developer_manual/getting_started.rst | 97 ++++++++++++++++++++++------ developer_manual/guidelines.rst | 9 ++- developer_manual/translation.rst | 2 + 5 files changed, 88 insertions(+), 28 deletions(-) diff --git a/developer_manual/access.rst b/developer_manual/access.rst index fe04b83a9..100e61cae 100644 --- a/developer_manual/access.rst +++ b/developer_manual/access.rst @@ -1,3 +1,5 @@ +.. _granting_access: + Granting Access to your App =========================== diff --git a/developer_manual/compatibility.rst b/developer_manual/compatibility.rst index 99a73ee44..e5f5eb215 100644 --- a/developer_manual/compatibility.rst +++ b/developer_manual/compatibility.rst @@ -40,13 +40,13 @@ Example from our source code: public.php and remote.php ~~~~~~~~~~~~~~~~~~~~~~~~~ -We introduced the files public.php and remote.php in ownCloud 4. +We introduced the files ``public.php`` and ``remote.php`` in ownCloud 4. -If you want to know how to use them, you should take a look `here`_. +If you want to know how to use them, you should take a look as the +:ref:`granting_access` section. New public API ~~~~~~~~~~~~~~ We also introduced our new public api. The documentation for this api can be found at http://api.ownCloud.org. -.. _here: http://owncloud.org/dev/apps/public-php-and-remote-php/ diff --git a/developer_manual/getting_started.rst b/developer_manual/getting_started.rst index 8761a74e3..20b245954 100644 --- a/developer_manual/getting_started.rst +++ b/developer_manual/getting_started.rst @@ -1,7 +1,12 @@ +.. _getting_started: + Getting Started =============== -Before you start, please check if there already is a similar app you could contribute to. `On our planning page`_ there are also some app ideas. Also, feel free to communicate your idea and plans to the `mailing list`_ so other contributors might join in. +Before you start, please check if there already is a similar app you could +contribute to. `On our planning page`_ there are also some app ideas. Also, feel +free to communicate your idea and plans to the `mailing list`_ so other +contributors might join in. Develop an app -------------- @@ -11,41 +16,81 @@ We will use the contacts app as an example, you find it under apps/contacts. Folder structure ---------------- -* ajax -* appinfo -* css -* img -* js -* l10n -* lib -* templates +* ajax/ +* appinfo/ +* css/ +* img/ +* js/ +* l10n/ +* lib/ +* templates/ -As you can imagine, templates belong in the template directory, css files in the css directory, images in the img directory and javascript files in the js directory. Renaming these directories is a really bad idea because functions like OC_Helper::linkTo or OC_Helper::imagePath will not work then.The appinfo directory provides everything ownCloud needs to get the app working. The most important file is app.php. ownCloud will call this file everytime it runs, so this is the place where you can register your navigation entries or connect signals and slots. More on this later.The l10n will contain the translations. As soon as the translation detects a l10n folder it knows that this program is translatable.All php scripts that are used to answer AJAX requests are located in ajax. This keeps the root folder clean. Note that ownCloud does not force you to use this folder but it is recommended to use it.If you write a library for your app you can put it into lib. As with the ajax folder this is not a must, but it is recommended. +As you can imagine, templates belong in the template directory, css files in the +css directory, images in the img directory and javascript files in the js +directory. Renaming these directories is a really bad idea because functions +like ``OC_Helper::linkTo`` or ``OC_Helper::imagePath`` will not work then. +The appinfo directory provides everything ownCloud needs to get the app working. + +The most important file is ``app.php``. ownCloud will call this file everytime +it runs, so this is the place where you can register your navigation entries or +connect signals and slots. More on this later. The ``l10n`` folder will contain +the translations. As soon as the translation detects a ``l10n`` folder it knows +that this program is translatable. All PHP scripts that are used to answer AJAX +requests are located in AJAX. This keeps the root folder clean. Note that +ownCloud does not force you to use this folder but it is recommended to use +it. If you write a library for your app you can put it into lib. As with the +ajax folder this is not a must, but it is recommended. The Model: lib/ --------------- -ownCloud uses the MVC principle. The libraries represent the model. Basically all data should be handled here so the php files the user calls only interact with the library. If you have a look at the lib folder in contacts, you will see three files: addressbook.php, hooks.php and connector_sabre.php.addressbook.php contains all methods that are required for handling addresses. We mostly use the classes as namespaces and write static functions, “real” OOP is only used if it is useful.All functions that are called by hooks are in hooks.phpTo use the CardDAV capabilities of SabreDAV we have the library OC_Connector_Sabre_CardDAV in connector_sabre.php. This file is very small and delegates most work to OC_Contacts_Addressbook in addressbook.php. This way you only have one file with all SQL queries. +ownCloud uses the `MVC_` (Model-View-Controller) principle. The libraries +represent the model. Basically all data should be handled here so the PHP files +the user calls only interact with the library. If you have a look at the lib +folder in contacts, you will see three files: ``addressbook.php``, ``hooks.php`` +and ``connector_sabre.php.addressbook.php`` contains all methods that are +required for handling addresses. We mostly use the classes as namespaces and +write static functions, "real" OOP is only used if it is useful. All functions +that are called by hooks are in ``hooks.php``. To use the CardDAV capabilities +of SabreDAV we have the library ``OC_Connector_Sabre_CardDAV`` in +``connector_sabre.php``. This file is very small and delegates most work to +``OC_Contacts_Addressbook`` in ``addressbook.php``. This way you only have one +file with all SQL queries. + +.. _MVC: http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller The View: templates/ -------------------- -ownCloud has its own template system. The templates are php files that are included by OC_Template. Having a look at two files basically shows you everything you need to know.The variables are assigned by using $tmpl->assign(‘name’,'value’);, have a look at the end of /index.php to see how it works. +ownCloud has its own template system. The templates are php files that are +included by ``OC_Template``. Having a look at two files basically shows you +everything you need to know. The variables are assigned by using +``$tmpl->assign(‘name’,'value’);``, have a look at the end of /index.php to see +how it works. The controllers --------------- -In contacts, you find the controllers in the root directory and in ajax/. Controllers are meant to be lean. +In contacts, you find the controllers in the root directory and in ``ajax/``. +Controllers are meant to be lean. Javascripts ----------- -The javascript libraries we use are jQuery and Torch. You can add scripts to your pages using:OC_UTIL::addScript(‘[app name]‘, ‘[script name]‘);Scripts can be added this way in either appinfo/app.php or in your app’s individual PHP scripts. +The javascript libraries we use are jQuery and Torch. You can add scripts to +your pages using:: + + _UTIL::addScript(‘[app name]‘, ‘[script name]‘); + +Scripts can be added this way in either ``appinfo/app.php`` or in your app’s +individual PHP scripts. Tell owncloud of our app: appinfo/ ---------------------------------- -In appinfo are three files. Each app must have app.php and info.xml, database.xml is only needed when the app creates its own tables.app.php is called by owncloud each time it runs. Let us examine this file line by line. +In appinfo are three files. Each app must have ``app.php`` and ``info.xml``, +``database.xml`` is only needed when the app creates its own ``tables.app.php`` +is called by ownCloud each time it runs. Let us examine this file line by line. .. code-block:: php @@ -53,13 +98,19 @@ In appinfo are three files. Each app must have app.php and info.xml, database.xm OC::$CLASSPATH['OC_Contacts_Hooks'] = 'apps/contacts/lib/hooks.php'; OC::$CLASSPATH['OC_Connector_Sabre_CardDAV'] = 'apps/contacts/lib/connector_sabre.php'; -This adds some entries to the OC::$CLASSPATH. This helps the ownCloud autoload function to load classes that are not in /lib. The cool thing about this is that you do not need to include anything else than /lib/base.php. +This adds some entries to the ``OC::$CLASSPATH``. This helps the ownCloud +autoload function to load classes that are not in ``/lib``. The cool thing about +this is that you do not need to include anything else than ``/lib/base.php``. .. code-block:: php OC_HOOK::connect('OC_User', 'post_createUser', 'OC_Contacts_Hooks', 'deleteUser'); -We do not need addressbooks of deleted people. But how do we know when a user is being deleted? For this, we use hooks. As soon as someone deletes a user the OC_Uer class emits the signal post_createUser. We use this signal and connect it with the slot deleteUser in the class OC_Contact_Hooks. For more details, have a look at the documentation of OC_Hook. +We do not need addressbooks of deleted people. But how do we know when a user is +being deleted? For this, we use hooks. As soon as someone deletes a user the +``OC_User`` class emits the signal post_createUser. We use this signal and +connect it with the slot deleteUser in the class ``OC_Contact_Hooks``. For more +details, have a look at the documentation of ``OC_Hook``. .. code-block:: php @@ -79,17 +130,23 @@ Registers the app in ownCloud. 'icon' => OC_Helper::imagePath( 'contacts', 'icon.png' ), 'name' => 'Contacts' )); -This adds the entry to the navigation.info.xml is self-explanatory.database.xml describes the database as required by MDB2. Note that the database name is *dbname* and that each table name needs a *dbprefix* in front of it. +This adds the entry to the navigation. info.xml is self-explanatory. +database.xml describes the database as required by MDB2. Note that the database +name is *dbname* and that each table name needs a *dbprefix* in front of it. App Template ------------ -A template for writing new apps can be found here: https://github.com/owncloud/apps/tree/master/apptemplate +A template for writing new apps can be found here: +https://github.com/owncloud/apps/tree/master/apptemplate Publish your app ---------------- -At http://apps.owncloud.com for other ownCloud users +You can publish your app at the `apps.owncloud.com`_. People with an +unrestricted ownCloud installation will then be able to directly download and +install your app from the admin interface. +.. _apps.owncloud.com: http://apps.owncloud.com .. _On our planning page: http://gitorious.org/owncloud/pages/Home .. _mailing list: http://mail.kde.org/mailman/listinfo/owncloud diff --git a/developer_manual/guidelines.rst b/developer_manual/guidelines.rst index 02d973f4f..8c703e3a9 100644 --- a/developer_manual/guidelines.rst +++ b/developer_manual/guidelines.rst @@ -5,10 +5,11 @@ How you can contribute: ----------------------- * `Report an issue on our bug tracker`_ -* `Translate ownCloud to your language`_ +* :ref:`Translate ownCloud to your language` * Help coding (see below) and check the `Junior Jobs`_ -* `Develop Apps`_, if you're looking for ideas you can check what users reported at the `App Opportunities Page`_. -* Help out with the website and write documentation (contact tpn or deryo in the irc channel) +* :ref:`Develop Apps`, if you're looking for ideas you can + check what users reported at the `App Opportunities Page`_. Help out with the + website and write documentation (contact tpn or deryo in the irc channel) * Spread the word, tell your friends about it, write a blog post! If you have any questions, `we are happy to help you`_. @@ -87,9 +88,7 @@ Coding guidelines .. _Report an issue on our bug tracker: https://github.com/owncloud/core/issues -.. _Translate ownCloud to your language: http://owncloud.org/dev/translation/ .. _Junior Jobs: http://owncloud.org/dev/junior-jobs/ -.. _Develop Apps: http://owncloud.org/dev/apps/getting-started/ .. _App Opportunities Page: http://bugs.owncloud.org/thebuggenie/owncloud/issues/find/saved_search/4/search/1 .. _we are happy to help you: http://owncloud.org/contact/ .. _setup multiple app directories: https://github.com/owncloud/documentation/blob/master/developer_manual/configfile.rst diff --git a/developer_manual/translation.rst b/developer_manual/translation.rst index 576bf0d7c..b7b502d96 100644 --- a/developer_manual/translation.rst +++ b/developer_manual/translation.rst @@ -1,3 +1,5 @@ +.. _translation: + Translation ===========