mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-03 02:09:45 +07:00
241 lines
7.3 KiB
ReStructuredText
241 lines
7.3 KiB
ReStructuredText
App Tutorial
|
|
============
|
|
|
|
This will teach you how to get develop your own owncloud app.
|
|
|
|
Before you start, please check if there already is a similar app you could contribute to. Also, feel free to communicate your idea and plans to the `mailing list <https://mail.kde.org/mailman/listinfo/owncloud>`_ so other contributors might join in.
|
|
|
|
|
|
Getting Started
|
|
---------------
|
|
To get started you'll need to clone the basic git repositories into your web directory. Depending on your distro this will either be :file:`/var/www or` :file:`/srv/http`
|
|
|
|
.. code-block:: bash
|
|
|
|
sudo chmod a+rw /var/www # only do this on your dev machine!
|
|
cd /var/www
|
|
git clone https://github.com/owncloud/core.git owncloud
|
|
git clone https://github.com/owncloud/apps.git apps
|
|
git clone https://github.com/owncloud/3rdparty.git 3rdparty
|
|
|
|
Now restart your apache server and get ready to set up owncloud at http://localhost/owncloud
|
|
|
|
|
|
Enable debugging mode
|
|
---------------------
|
|
To disable caching of JavaScript and CSS you'll have to turn on debugging in the :file:`/var/www/owncloud/config/config.php` by adding this to the end of the file::
|
|
|
|
DEFINE('DEBUG', true);
|
|
|
|
|
|
Create your app
|
|
---------------
|
|
The best way to create your application is to simply use and modify the app template.
|
|
|
|
To do that execute:
|
|
|
|
.. code-block:: bash
|
|
|
|
cd /var/www/apps
|
|
sudo cp -r apptemplate yourappname
|
|
sudo chown -R youruser:yourgroup yourappname
|
|
|
|
To enable your app, simply link it into the apps directory:
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
ln -s /var/www/apps/yourappname /var/www/owncloud/apps/yourappname
|
|
|
|
or set the apps directory in your :file:`/var/www/owncloud/config.php` (see :doc:`configfile`)
|
|
|
|
**Don't forget to enable it on the apps settings page!**
|
|
|
|
Now change into your app directory::
|
|
|
|
cd /var/www/apps/yourappname
|
|
|
|
|
|
Remove/Replace apptemplate specific things
|
|
------------------------------------------
|
|
Certain things are still apptemplate specific that you will have to replace for your app.
|
|
|
|
.. todo::
|
|
|
|
Provide some sed commands for simple transformation
|
|
|
|
The following things will need to be changed:
|
|
|
|
* AGPL Headers and copyright
|
|
* **\\OC_App::getAppPath('apptemplate')** to **\\OC_App::getAppPath('yourappname')**
|
|
* **namespace OCA\\AppTemplate** to **namespace OCA\\YourAppName**
|
|
* The Classpaths in :file:`appinfo/bootstrap.php`
|
|
|
|
|
|
App information
|
|
---------------
|
|
You will want to set certain metainformation for your application. To do that open the :file:`appinfo/app.php` and adjust it to look like this
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
|
|
require_once \OC_App::getAppPath('yourappname') . '/appinfo/bootstrap.php';
|
|
|
|
\OCP\App::addNavigationEntry( array(
|
|
|
|
// the string under which your app will be referenced
|
|
// in owncloud, for instance: \OC_App::getAppPath('APP_ID')
|
|
'id' => 'yourappname',
|
|
|
|
// sorting weight for the navigation. The higher the number, the higher
|
|
// will it be listed in the navigation
|
|
'order' => 74,
|
|
|
|
// the route that will be shown on startup
|
|
'href' => \OC_Helper::linkToRoute('apptemplate_index'),
|
|
|
|
// the icon that will be shown in the navigation
|
|
'icon' => \OCP\Util::imagePath('yourappname', 'example.png' ),
|
|
|
|
// the title of your application. This will be used in the
|
|
// navigation or on the settings page of your app
|
|
'name' => \OC_L10N::get('yourappname')->t('Your App')
|
|
|
|
));
|
|
|
|
?>
|
|
|
|
|
|
Classloader
|
|
-----------
|
|
The classloader is configured in :file:`appinfo/bootstrap.php`. The classloader frees you from requiring your classes when you use them. If a class is used and its not yet available, the loader will automatically require the given file.
|
|
|
|
To add a class to the classloader, simply use something like this:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
// loads the class MyClass from the file folder/myclass.php
|
|
\OC::$CLASSPATH['OCA\YourAppName\MyClass'] = 'apps/yourappname/folder/myclass.php';
|
|
?>
|
|
|
|
|
|
Dependency Injection
|
|
--------------------
|
|
Dependency Injection helps you to create testable code. A good overview 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:`appinfo/bootstrap.php`. We use Pimple for the container. The documentation on how to use it can be seen on the `Pimple Homepage <http://pimple.sensiolabs.org/>`_
|
|
|
|
To add your own class simply add a new line inside the **createDIContainer** function:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
|
|
$container['MyClass'] = function($c){
|
|
return new MyClass($c['SomeOtherClass']);
|
|
};
|
|
|
|
?>
|
|
|
|
|
|
|
|
Controllers
|
|
-----------
|
|
The App Template provides a simple baseclass for adding controllers. Controllers connect your view (templates) with your database and is connected to one or more routes.
|
|
|
|
The apptemplate comes with several different Controllers. A simple controller would look like:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
|
|
namespace OCA\YourApp;
|
|
|
|
|
|
class MyController extends Controller {
|
|
|
|
|
|
/**
|
|
* @param Request $request: an instance of the request
|
|
* @param API $api: an api wrapper instance
|
|
*/
|
|
public function __construct($api, $request){
|
|
parent::__construct($api, $request);
|
|
}
|
|
|
|
|
|
/**
|
|
* @brief sets a global system value
|
|
* @param array $urlParams: an array with the values, which were matched in
|
|
* the routes file
|
|
*/
|
|
public function myControllerMethod($urlParams=array()){
|
|
$value = $this->params('somesetting');
|
|
|
|
$response = new JSONResponse($this->appName);
|
|
$response->setParams(array('value' => $value));
|
|
return $response;
|
|
}
|
|
|
|
}
|
|
|
|
?>
|
|
|
|
An instance of the api is passed via dependency injection, the same goes for a request instance. POST and GET parameters are abstracted by the Request class and can be accessed via **$this->params('myPostOrGetKey')** in the controller. This has been done to make the app better testable.
|
|
|
|
If a POST and GET value exist with the same key, the POST value is preferred. You should avoid to have both values with the same key though.
|
|
|
|
Every controller method has to return a response. All possible reponses can be found in :file:`lib/response.php`. The file contains wrappers for Ownclouds internal template engine and JSON response and is used to create a uniform response object which is testable.
|
|
|
|
Don't forget to add your controller to the dependency container in :file:`appinfo/bootstrap.php`
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
|
|
// in the createDIContainer function
|
|
|
|
$container['MyController'] = function($c){
|
|
return new MyController($c['API'], $c['Request']);
|
|
};
|
|
|
|
?>
|
|
|
|
and to the classloader
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
\OC::$CLASSPATH['OCA\YourAppName\MyController'] = 'apps/yourappname/controllers/my.controller.php';
|
|
?>
|
|
|
|
|
|
Database Access
|
|
---------------
|
|
TBD
|
|
|
|
Routes
|
|
------
|
|
|
|
See also :doc:`routing`
|
|
|
|
API abstraction layer
|
|
---------------------
|
|
Owncloud currently has a ton of static methods which is a very bad thing concerning testability. Therefore the app template comes with an api abstraction layer which is located at :file:`lib/api.php`.
|
|
|
|
If you find yourself in need to use an Owncloud internal static method, add it to the api layer by simply creating a new method like:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
|
|
// inside the API class
|
|
|
|
public function methodName($someParam){
|
|
\OCP\Util::methodName($this->appName, $someParam);
|
|
}
|
|
?>
|
|
|
|
That way you can easily create unittests with a simple API class mock if you dont want to call Owncloud internal stuff. |