diff --git a/developer_manual/app/apptutorial.rst b/developer_manual/app/apptutorial.rst deleted file mode 100644 index a5d4231d4..000000000 --- a/developer_manual/app/apptutorial.rst +++ /dev/null @@ -1,15 +0,0 @@ -App Tutorial -============ - -This tutorial contains the traditional approach to write an app. The benefits of this approach are: - -* Not dependant on the App Framework app -* Easy and fast to create an app -* Typical PHP style like - -The disadvantages of this approach are: - -* No automatic security checks: privilege checks have to be included at the top of each file -* No automatic XSS escaping: :php:class:`OC_Template` does require manual escaping of output -* Hard to unittest: Using files instead of Controllers makes it hard to write unittests for the whole application -* Hard to maintain: Using files instead of functions makes the design inflexible diff --git a/developer_manual/app/createapp.rst b/developer_manual/app/createapp.rst new file mode 100644 index 000000000..b0460d3a8 --- /dev/null +++ b/developer_manual/app/createapp.rst @@ -0,0 +1,100 @@ +Create An App +============= + +.. sectionauthor:: Bernhard Posselt + +After the apps were cloned into either + +* **/var/www** +* **/var/www/html** +* **/srv/http** + +Depending on the used distribution change into that directory inside a terminal:: + + cd /var/www/ + +Next create a directory for the app and make it writable:: + + mkdir apps/YOUR_APP + sudo chown -R YOUR_USER:users apps/YOUR_APP + +If you are unsure about your user **whoami** to find out your user:: + + whoami + +Create basic files +------------------ +The following files need to be created: :file:`appinfo/info.xml`, :file:`appinfo/version` and :file:`appinfo/app.php`. To do that change into the directory of your app:: + + cd apps/YOUR_APP + mkdir appinfo + touch appinfo/version appinfo/app.php appinfo/info.xml + +Set app version +--------------- +To set the version of the app, simply write the following into :file:`appinfo/version`:: + + 0.1 + +Create metadata +--------------- +ownCloud has to know what your app is. This information is located inside the :file:`appinfo/info.xml`: + +.. code-block:: xml + + + + appname + My App + Simple app that does some computing + 1.0 + AGPL + Your Name + 6 + + +For more information on the content of :file:`appinfo/info.xml` and what can be set, see: :doc:`info` + +Enable the app +-------------- +The easiest way to enable is to symlink it into the **owncloud/apps** directory:: + + ln -s /var/www/apps/YOUR_APP /var/www/owncloud/apps/ + +This is also how other apps from the **apps** directory have to be enabled. A second way is to tell ownCloud about the directory. Use :doc:`../core/configfile` to set up multiple app directories. + +The app can now be enabled on the ownCloud apps page. + +.. note:: The app does not show up yet in the navigation. This is intended. How to create an entry in the navigation is explained in the following tutorials. + +Start coding +------------ +The basic files are now in place and the app is enabled. There are two ways to create the app: + +* :doc:`Use ownClouds app API ` +* :doc:`Use the App Framework app <../appframework/tutorial>` + ++-----------------+-------------------------+--------------------------------+ +| Criteria | ownCloud app API | App Framework | ++=================+=========================+================================+ +| Difficulty | easy | medium | ++-----------------+-------------------------+--------------------------------+ +| Architecture | none | MVC | ++-----------------+-------------------------+--------------------------------+ +| Testability | hard | easy: built-in :doc:`\ | +| | | ../general/dependencyinjection`| +| | | and `TDD`_ tools | ++-----------------+-------------------------+--------------------------------+ +| Maintainability | hard | medium | ++-----------------+-------------------------+--------------------------------+ +| Templates | :php:class:`OC_Template`| :php:class:`OC_Template` | +| | | and `Twig`_ | ++-----------------+-------------------------+--------------------------------+ +| Security | manual checks | enforces XSS, CSRF and | +| | | Authentication checks by | +| | | default | ++-----------------+-------------------------+--------------------------------+ + +.. _Twig: http://twig.sensiolabs.org +.. _TDD: http://en.wikipedia.org/wiki/Test-driven_development +.. _Dependency Injection: \ No newline at end of file diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index e69de29bb..68b195ec1 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -0,0 +1,4 @@ +CSS +=== + +.. sectionauthor:: Bernhard Posselt \ No newline at end of file diff --git a/developer_manual/app/gettingstarted.rst b/developer_manual/app/gettingstarted.rst index b5d3980e5..7dc7677f6 100644 --- a/developer_manual/app/gettingstarted.rst +++ b/developer_manual/app/gettingstarted.rst @@ -17,18 +17,26 @@ There are two ways to obtain ownCloud: Using stable ~~~~~~~~~~~~ -`Install the current version of ownCloud `_ and create a new directory in the **apps/** folder. +`Install the current version of ownCloud `_. Using development version (recommended) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ First `set up your webserver and database `_ (**Section**: Manual Installation - Prerequisites). -ownCloud uses `GitHub`_ for developing its code. To be able to participate or check out the code You will have to sign up on `GitHub`_ and install Git. -> -If you need help with Git, contact the `GitHub Help Page`_. +ownCloud's source is hosted on `GitHub`_. To be able to participate or check out the code You will have to sign up on `GitHub`_ and install Git. For help on git, contact the `GitHub Help Page`_. -To get started you'll need to clone the basic git repositories into your web directory. Depending on your distro this will either be **/var/www** or **/srv/http** and the apache user and group for the chown command will either be **http**, **www-data** or **apache** +To get started the basic git repositories need to cloned into the webserver's directory. Depending on the distro this will either be + +* **/var/www** +* **/var/www/html** +* **/srv/http** + +and the apache user and group for the **chown** command will either be + +* **http** +* **www-data** +* **apache** .. code-block:: bash @@ -38,23 +46,23 @@ To get started you'll need to clone the basic git repositories into your web dir git clone https://github.com/owncloud/apps.git apps git clone https://github.com/owncloud/3rdparty.git 3rdparty mkdir owncloud/data - sudo chown -R http:http owncloud/config - sudo chown -R http:http owncloud/data - sudo chown -R http:http owncloud/apps + sudo chown -R www-data:www-data owncloud/config + sudo chown -R www-data:www-data owncloud/data + sudo chown -R www-data:www-data owncloud/apps sudo chmod -R o-rw /var/www -Now restart your apache server and get ready to `set up ownCloud`_ at http://localhost/owncloud. +Now restart the apache server and get ready to `set up ownCloud`_ at http://localhost/owncloud. Enable debugging mode --------------------- -.. note:: Do not enable this for production! Only for developement! +.. note:: Do not enable this for production! This can create security problems and is only meant for debugging and development! -To disable JavaScript and CSS caching you'll have to turn on debugging in :file:`owncloud/config/config.php` by adding this to the end of the file:: +To disable JavaScript and CSS caching debugging has to be enabled in :file:`owncloud/config/config.php` by adding this to the end of the file:: DEFINE('DEBUG', true); -.. note:: This is often overwritten after a **git pull** from core. Always check your :file:`owncloud/config/config.php` afterwards. +This is often overwritten after a **git pull** from core. Always check :file:`owncloud/config/config.php` afterwards. .. _GitHub: https://github.com/owncloud .. _GitHub Help Page: https://help.github.com/ diff --git a/developer_manual/app/index.rst b/developer_manual/app/index.rst index 0286e1157..a52c70c2e 100644 --- a/developer_manual/app/index.rst +++ b/developer_manual/app/index.rst @@ -6,18 +6,10 @@ App Developement :maxdepth: 1 gettingstarted - apptutorial - appframeworktutorial - settings + createapp + tutorial classloader - api - routes - controllers - database - templates - static - unittesting - middleware + info externalapi filesystem hooks diff --git a/developer_manual/app/info.rst b/developer_manual/app/info.rst index eb2015408..e07229f53 100644 --- a/developer_manual/app/info.rst +++ b/developer_manual/app/info.rst @@ -1,5 +1,8 @@ App Metadata ============ + +.. sectionauthor:: Bernhard Posselt + The :file:`appinfo/info.xml` contains metadata about the app: .. code-block:: xml @@ -13,41 +16,57 @@ The :file:`appinfo/info.xml` contains metadata about the app: AGPL Your Name 5 + - + filesystem + + + appinfo/caldav.php + + + + appinfo/caldav.php + + + + + + true id -- -This field contains the internal app name, and has to be the same as the foldername of the app. This id needs to be unique in ownCloud, meaning no other app should have this id. +**Required**: This field contains the internal app name, and has to be the same as the foldername of the app. This id needs to be unique in ownCloud, meaning no other app should have this id. name ---- -This is the human-readable name/title of the app that will be displayed in the app overview page. +**Required**: This is the human-readable name/title of the app that will be displayed in the app overview page. description ----------- -This contains the description of the app which will be shown in the apps overview page. +**Required**: This contains the description of the app which will be shown in the apps overview page. version ------- -Contains the version of your app +Contains the version of your app. Please the :file:`appinfo/version` which contains the version. licence ------- -The licence of the app. This licence must be compatible with the AGPL and **must not be proprietary**, for instance: +**Required**: The licence of the app. This licence must be compatible with the AGPL and **must not be proprietary**, for instance: * AGPL 3 (recommended) * MIT If a proprietary/non AGPL compatible licence should be used, the `ownCloud Enterprise Edition `_ must be used. +author +------ +**Required**: The name of the app author or authors. + types ----- -ownCloud allows to specify four kind of "types" in the file:`appinfo/info.xml` of a app. The type doesn't have to be specified if the app doesn't match any of them. - -Currently supported "types": +ownCloud allows to specify four kind of "types". Currently supported "types": * **prelogin**: apps which needs to load on the login page @@ -55,4 +74,32 @@ Currently supported "types": * **authentication**: apps which provided authentication backends -* **logging**: apps which implement a logging system \ No newline at end of file +* **logging**: apps which implement a logging system + +public +------ +Used to provide a public interface (requires no login) for the app. The id is appended to the URL **/owncloud/index.php/public**. Example with id set to 'calendar':: + + /owncloud/index.php/public/calendar + +Also take a look at :doc:`externalapi`. + +remote +------ +Same as public but requires login. The id is appended to the URL **/owncloud/index.php/remote**. Example with id set to 'calendar':: + + /owncloud/index.php/remote/calendar + +Also take a look at :doc:`externalapi`. + +standalone +---------- +Can be set to true to indicate that this app is a webapp. This can be used to tell GNOME Web for instance to treat this like a native application. + +default_enable +-------------- +**Core apps only**: Used to tell ownCloud to enable them after the installation. + +shipped +------- +**Core apps only**: Used to tell ownCloud that the app is in the standard release \ No newline at end of file diff --git a/developer_manual/app/tutorial.rst b/developer_manual/app/tutorial.rst new file mode 100644 index 000000000..0abef7e7c --- /dev/null +++ b/developer_manual/app/tutorial.rst @@ -0,0 +1,6 @@ +App Tutorial +============ + +.. sectionauthor:: Bernhard Posselt + +This tutorial contains the traditional approach to write an app. \ No newline at end of file diff --git a/developer_manual/appframework/container.rst b/developer_manual/appframework/container.rst index edb4c7099..7ad0dabfa 100644 --- a/developer_manual/appframework/container.rst +++ b/developer_manual/appframework/container.rst @@ -1,5 +1,8 @@ -Dependency Injection -==================== +Dependency Injection Container +============================== + +.. sectionauthor:: Bernhard Posselt + Dependency Injection helps you to create testable code. A good overview over how it works and what the benefits are can be seen on `Google's Clean Code Talks `_ The container is configured in :file:`dependencyinjection/dicontainer.php`. By default `Pimple `_ is used as dependency injection container. A `tutorial can be found here `_ diff --git a/developer_manual/appframework/index.rst b/developer_manual/appframework/index.rst index 5f3a19edf..b0aae7bca 100644 --- a/developer_manual/appframework/index.rst +++ b/developer_manual/appframework/index.rst @@ -5,9 +5,9 @@ App Developement Using the App Framework .. toctree:: :maxdepth: 1 - gettingstarted - appframeworktutorial - ../app/info + ../app/gettingstarted + ../app/createapp + tutorial ../app/classloader container api @@ -19,6 +19,7 @@ App Developement Using the App Framework ../app/css unittesting middleware + ../app/info externalapi filesystem hooks diff --git a/developer_manual/appframework/javascript.rst b/developer_manual/appframework/javascript.rst index e69de29bb..8229a3674 100644 --- a/developer_manual/appframework/javascript.rst +++ b/developer_manual/appframework/javascript.rst @@ -0,0 +1,4 @@ +JavaScript +========== + +.. sectionauthor:: Bernhard Posselt \ No newline at end of file diff --git a/developer_manual/appframework/appframeworktutorial.rst b/developer_manual/appframework/tutorial.rst similarity index 54% rename from developer_manual/appframework/appframeworktutorial.rst rename to developer_manual/appframework/tutorial.rst index c7ec6b50a..b077c7296 100644 --- a/developer_manual/appframework/appframeworktutorial.rst +++ b/developer_manual/appframework/tutorial.rst @@ -1,27 +1,13 @@ App Tutorial (App Framework) ============================ -This tutorial contains the MVC approach to write an app. The benefits of this approach are: -* Highest authentication level and security checks are enforced by default and have to explicitely be turned off -* Possiblity to use Twig templates which escape XSS by default -* Easy to test: The App Framework allows to unittest the whole app by using :doc:`../general/dependencyinjection` -* Comes with AngularJS JavaScript code -* MVC style +.. sectionauthor:: Bernhard Posselt -The disadvantages of this approach are: +This tutorial contains the MVC approach to write an app. The goal of this tutorial is a simple notes app. -* App Framework app has to be installed -* Requires to read more documentation - -Goal ----- -The goal of this tutorial is a simple notes app. - -Create basic files ------------------- -First create a new folder inside your apps directry and name it **mynotes**. The name of the folder is important because it will be used for the :doc:`classloader` to include your classes. - -Next create the :file:`appinfo/app.php`. This file will always loaded for every app and can for instance be used to load additional JavaScript for the files app: +Create an app entry +------------------- +Depending on the . This file will always loaded for every app and can for instance be used to load additional JavaScript for the files app: :file:`appinfo/app.php` @@ -34,45 +20,27 @@ Next create the :file:`appinfo/app.php`. This file will always loaded for every $api = new \OCA\AppFramework\Core\API('mynotes'); $api->addNavigationEntry(array( - - // the string under which your app will be referenced in owncloud - 'id' => $api->getAppName(), + + // the string under which your app will be referenced in owncloud + 'id' => $api->getAppName(), - // sorting weight for the navigation. The higher the number, the higher - // will it be listed in the navigation - 'order' => 10, - - // the route that will be shown on startup - 'href' => $api->linkToRoute('mynotes_index'), - - // the icon that will be shown in the navigation - 'icon' => $api->imagePath('example.png' ), - - // the title of your application. This will be used in the - // navigation or on the settings page of your app - 'name' => $api->getTrans()->t('My notes app') - + // sorting weight for the navigation. The higher the number, the higher + // will it be listed in the navigation + 'order' => 10, + + // the route that will be shown on startup + 'href' => $api->linkToRoute('mynotes_index'), + + // the icon that will be shown in the navigation + 'icon' => $api->imagePath('example.png' ), + + // the title of your application. This will be used in the + // navigation or on the settings page of your app + 'name' => $api->getTrans()->t('My notes app') + )); -Next up is the :file:`appinfo/info.xml` where metadata for the app is stored. This will be used to check if the app is compatible with ownCloud (require tag) and to display text on the app info page: - -:file:`appinfo/info.xml` - -.. code-block:: xml - - - - mynotes - My notes app - Simple notes app - 1.0 - AGPL - Your Name - 6 - - - First Page ----------