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

more structured intro with more information

Browse Source
This commit is contained in:
Bernhard Posselt
2013-03-12 13:15:06 +01:00
parent 48a808a337
commit b4eef0af23
11 changed files with 225 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
developer_manual/app/apptutorial.rst
View File

@@ -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

100
developer_manual/app/createapp.rst Normal file
View File

@@ -0,0 +1,100 @@
Create An App
=============
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>
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
<?xml version="1.0"?>
<info>
<id>appname</id>
<name>My App</name>
<description>Simple app that does some computing</description>
<version>1.0</version>
<licence>AGPL</licence>
<author>Your Name</author>
<require>6</require>
</info>
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 <tutorial>`
* :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:

4
developer_manual/app/css.rst
View File

@@ -0,0 +1,4 @@
CSS
===
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>

32
developer_manual/app/gettingstarted.rst
View File

@@ -17,18 +17,26 @@ There are two ways to obtain ownCloud:
Using stable
~~~~~~~~~~~~
`Install the current version of ownCloud <http://doc.owncloud.org/server/5.0/admin_manual/installation.html>`_ and create a new directory in the **apps/** folder.
`Install the current version of ownCloud <http://doc.owncloud.org/server/5.0/admin_manual/installation.html>`_.
Using development version (recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First `set up your webserver and database <http://doc.owncloud.org/server/5.0/admin_manual/installation.html>`_ (**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/

14
developer_manual/app/index.rst
View File

@@ -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

67
developer_manual/app/info.rst
View File

@@ -1,5 +1,8 @@
App Metadata
============
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>
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:
<licence>AGPL</licence>
<author>Your Name</author>
<require>5</require>
<types>
<filesystem/>
<type>filesystem</type>
</types>
<remote>
<file id="caldav">appinfo/caldav.php</file>
</remote>
<public>
<file id="caldav">appinfo/caldav.php</file>
</public>
<standalone />
<default_enable />
<shipped>true</shipped>
</info>
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 <https://owncloud.com/overview/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
* **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

6
developer_manual/app/tutorial.rst Normal file
View File

@@ -0,0 +1,6 @@
App Tutorial
============
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>
This tutorial contains the traditional approach to write an app.

7
developer_manual/appframework/container.rst
View File

@@ -1,5 +1,8 @@
Dependency Injection
====================
Dependency Injection Container
==============================
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>
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 <http://www.youtube.com/watch?v=RlfLCWKxHJ0>`_
The container is configured in :file:`dependencyinjection/dicontainer.php`. By default `Pimple <http://pimple.sensiolabs.org/>`_ is used as dependency injection container. A `tutorial can be found here <http://jtreminio.com/2012/10/an-introduction-to-pimple-and-service-containers/>`_

7
developer_manual/appframework/index.rst
View File

@@ -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

4
developer_manual/appframework/javascript.rst
View File

@@ -0,0 +1,4 @@
JavaScript
==========
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>

76
developer_manual/appframework/appframeworktutorial.rst → developer_manual/appframework/tutorial.rst
View File

@@ -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 <nukeawhale@gmail.com>
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
<?xml version="1.0"?>
<info>
<id>mynotes</id>
<name>My notes app</name>
<description>Simple notes app</description>
<version>1.0</version>
<licence>AGPL</licence>
<author>Your Name</author>
<require>6</require>
</info>
First Page
----------