From 4609ff0397bf8a21da33e03f3ab7ff550384a00a Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Sat, 26 Jan 2013 17:14:51 +0100 Subject: [PATCH] wired appframework classes into app doc --- developer_manual/app/api.rst | 4 ++-- developer_manual/app/classloader.rst | 2 +- developer_manual/app/controllers.rst | 20 +++++++++----------- developer_manual/app/gettingstarted.rst | 4 ++-- developer_manual/app/middleware.rst | 7 ++----- developer_manual/app/routes.rst | 7 ++++++- developer_manual/app/settings.rst | 2 +- developer_manual/app/templates.rst | 12 ++++++------ developer_manual/app/unittesting.rst | 6 +++--- 9 files changed, 32 insertions(+), 32 deletions(-) diff --git a/developer_manual/app/api.rst b/developer_manual/app/api.rst index 81eded84c..1c868e1c8 100644 --- a/developer_manual/app/api.rst +++ b/developer_manual/app/api.rst @@ -3,9 +3,9 @@ API abstraction layer .. sectionauthor:: Bernhard Posselt -ownCloud currently has a ton of static methods which is a very bad thing concerning testability. Therefore the appframework comes with an :php:class:`OCA\\AppFramework\\Core\\API` abstraction layer (basically a `facade `_) which is located in the appframework app at :file:`core/api.php`. +ownCloud currently has a ton of static methods which is a very bad thing concerning testability. Therefore the App Framework comes with an :php:class:`OCA\\AppFramework\\Core\\API` abstraction layer (basically a `facade `_) which is located in the App Framework app at :file:`core/api.php`. -If you find yourself in need to use more ownCloud internal static methods, add them to the API class in the appframework directory, like: +If you find yourself in need to use more ownCloud internal static methods, add them to the API class in the **appframework/** directory, like: .. code-block:: php diff --git a/developer_manual/app/classloader.rst b/developer_manual/app/classloader.rst index 77e824239..2d67078c5 100644 --- a/developer_manual/app/classloader.rst +++ b/developer_manual/app/classloader.rst @@ -33,4 +33,4 @@ The classloader works like this: require '/apps/apptemplateadvanced/db/itemmapper.php'; -Remember : for it to be autoloaded, the itemmapper.php file needs to either be stored in the /apps/apptemplateadvanced/db/ folder, or adjust its namespace according to the folder it's stored in. \ No newline at end of file +Remember : for it to be autoloaded, the :file:`itemmapper.php` needs to either be stored in the **/apps/apptemplateadvanced/db/** folder, or adjust its namespace according to the folder it's stored in. \ No newline at end of file diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index 0c0c6257b..b8ccbb263 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -3,7 +3,7 @@ Controllers .. sectionauthor:: Bernhard Posselt -The appframework app provides a simple baseclass for adding controllers: :php:class:`OCA\\AppFramework\\Controller\\Controller`. Controllers connect your view (templates) with your database. Controllers themselves are connected to one or more routes. Controllers go into the :file:`controller` directory. +The App Framework provides a simple baseclass for adding controllers: :php:class:`OCA\\AppFramework\\Controller\\Controller`. Controllers connect your view (templates) with your database. Controllers themselves are connected to one or more routes. Controllers go into the **controller/** directory. A controller should be created for each resource. Think of it as an URL scheme:: @@ -61,19 +61,17 @@ An instance of the API is passed via dependency injection, the same goes for a R .. note:: If an URL Parameter, POST or GET value exist with the same key, the URL Parameter is preferred over the POST parameter and the POST parameter is preferred over the GET parameter. You should avoid this scenario though. -Every controller method has to return a Response object. The currently available Responses from the appframework include: +Every controller method has to return a Response object. The currently available Responses from the App Framework include: -* **\\OCA\\AppFramework\\Http\\Response**: response for sending headers only -* **\\OCA\\AppFramework\\Http\\JSONResponse**: sends JSON to the client -* **\\OCA\\AppFramework\\Http\\TemplateResponse**: renders a template -* **\\OCA\\AppFramework\\Http\\RedirectResponse**: redirects to a new URL -* **\\OCA\\AppFramework\\Http\\TextDownloadResponse**: prompts the user to download a text file containing a passed string -* **\\OCA\\AppFramework\\Http\\TextResponse**: for printing text like XML +* :php:class:`OCA\\AppFramework\\Http\\Response`: response for sending headers only +* :php:class:`OCA\\AppFramework\\Http\\JSONResponse`: sends JSON to the client +* :php:class:`OCA\\AppFramework\\Http\\TemplateResponse`: renders a template +* :php:class:`OCA\\AppFramework\\Http\\RedirectResponse`: redirects to a new URL +* :php:class:`OCA\\AppFramework\\Http\\TextDownloadResponse`: prompts the user to download a text file containing a passed string +* :php:class:`OCA\\AppFramework\\Http\\TextResponse`: for printing text like XML -.. note:: For more responses, please look into the appframework :file:`http/`. If you create an additional response, be sure to create a pull request so that more people can profit from it! - -Should you require to set additional headers, you can use the **addHeader()** method that every Response has. +Should you require to set additional headers, you can use the :php:meth:`OCA\\AppFramework\\Http\\Response::addHeader` method that every Response has. Because TemplateResponse and JSONResponse are so common, the controller provides a shortcut method for both of them, namely **$this->render** and **$this->renderJSON**. diff --git a/developer_manual/app/gettingstarted.rst b/developer_manual/app/gettingstarted.rst index 8676ed4a6..5a0c39317 100644 --- a/developer_manual/app/gettingstarted.rst +++ b/developer_manual/app/gettingstarted.rst @@ -5,7 +5,7 @@ Getting Started 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 `_ so other contributors might join in. -This tutorial uses the appframework app, a small framework that makes developing apps easier. To use it, it has to be enabled on the apps settings page. +This tutorial uses the App Framework app, a small framework that makes developing apps easier. To use it, it has to be enabled on the apps settings page. Getting Started @@ -59,7 +59,7 @@ To enable your app, simply link it into the apps directory: or create a second apps directory in your :file:`/var/www/owncloud/config/config.php` (see :doc:`../core/configfile`) -.. note:: Don't forget to enable your app and the appframework app on the apps settings page! +.. note:: Don't forget to enable your app and the App Framework app on the apps settings page! Now change into your app directory:: diff --git a/developer_manual/app/middleware.rst b/developer_manual/app/middleware.rst index 0d247fc37..a17288c77 100644 --- a/developer_manual/app/middleware.rst +++ b/developer_manual/app/middleware.rst @@ -11,10 +11,7 @@ Middleware is logic that is run before and after each request. It offers the fol * **afterController**: This is being run after a successful controllermethod call and allows the manipulation of a Response object. The middleware is run in reverse order * **beforeOutput**: This is being run after the response object has been rendered and allows the manipulation of the outputted text. The middleware is run in reverse order -To generate your own middleware, simply inherit from the Middleware class and overwrite the methods that you want to use. - -.. note:: Some hooks need to return a result, for instance the beforeOutput hook needs to return the text that is printed to the page. Check the Middleware class documentation in the appframework :file:`middleware/middleware.php` for more information - +To generate your own middleware, simply inherit from the Middleware class :php:class:`OCA\\AppFramework\\Middleware\\Middleware`: and overwrite the methods that you want to use. .. code-block:: php @@ -45,7 +42,7 @@ To generate your own middleware, simply inherit from the Middleware class and ov } -To activate the middleware, you have to overwrite the parent MiddlewareDispatcher and wire your middleware into the DIContainer constructor: +To activate the middleware, you have to overwrite the :php:class:`OCA\\AppFramework\\Middleware\\MiddlewareDispatcher`: in the DIContainer constructor: .. note:: If you ship your own middleware, be sure to also enable the existing ones if you overwrite the MiddlewareDispatcher in the Dependency Injection Container! diff --git a/developer_manual/app/routes.rst b/developer_manual/app/routes.rst index f831c49dc..69268adeb 100644 --- a/developer_manual/app/routes.rst +++ b/developer_manual/app/routes.rst @@ -25,7 +25,6 @@ A simple route would look like this: ); -:php:class:`OCA\\AppFramework\\App` The first argument is the name of your route. This is used as an identifier to get the URL of the route and is a nice way to generate the URL in your templates or JavaScript for certain links since it does not force you to hardcode your URLs. To use it in OC templates, use: @@ -63,6 +62,12 @@ If a default value should be used for an URL parameter, it can be set via the ** )->defaults('value' => 'john'); +To call your controllers the App Framework provides a main method: :php:class:`OCA\\AppFramework\\App`. + +The first parameter is the name under which the controller was defined in the :file:`dependencyinjection/dicontainer.php`. + +The second parameter is the name of the method that should be called on the controller. + The third parameter is the $params array which is passed to the controller and available by using **$this->params($KEY)** in the controller method. In the following example, the parameter in the URL would be accessible by using: **$this->params('value')** You can also limit the route to GET or POST requests by simply adding **->post()** or **->get()** before the action method like: diff --git a/developer_manual/app/settings.rst b/developer_manual/app/settings.rst index cfe551859..e912ffbfd 100644 --- a/developer_manual/app/settings.rst +++ b/developer_manual/app/settings.rst @@ -93,6 +93,6 @@ To add your own classes simply open the :file:`dependencyinjection/dicontainer.p ?> -You can also overwrite already existing items from the appframework simply by redefining them. +You can also overwrite already existing items from the App Framework simply by redefining them. **See also** :doc:`../general/dependencyinjection` \ No newline at end of file diff --git a/developer_manual/app/templates.rst b/developer_manual/app/templates.rst index f09c7473f..6a7c55e55 100644 --- a/developer_manual/app/templates.rst +++ b/developer_manual/app/templates.rst @@ -3,9 +3,9 @@ Templates .. sectionauthor:: Bernhard Posselt -ownCloud provides its own templating system. The appframework also provides the option of using `Twig Templates `_ which can optionally be enabled. Templates reside in the **templates/** folder. +ownCloud provides its own templating system. The App Framework also provides the option of using `Twig Templates `_ which can optionally be enabled. Templates reside in the **templates/** folder. -Templates are abstracted by the TemplateResponse object and used and returned inside the controller method. Variables can be assigned to the Template by using the **setParams()** method: +Templates are abstracted by the TemplateResponse object and used and returned inside the controller method. Variables can be assigned to the Template by using the :php:class:`OCA\\AppFramework\\Http\\TemplateResponse::setParams` method: .. code-block:: php @@ -29,7 +29,7 @@ Templates are abstracted by the TemplateResponse object and used and returned in Twig Templates (recommended) ---------------------------- -ownCloud templates do a bad job at preventing `XSS `_. Therefore the apptemplate comes with a second option: the `Twig Templating Language `_. +ownCloud templates do a bad job at preventing `XSS `_. Therefore the App Framework comes with a second option: the `Twig Templating Language `_. Twig Templates are enabled by using the Twig Middleware. If a Twig template directory is set in the :file:`dependencyinjection/dicontainer.php`, the middleware gets loaded automatically. If no directory is set, theres no additional overhead. @@ -71,7 +71,7 @@ After adding the above lines, Angular will use **[[]]** for evaluation variables ownCloud Templates ------------------ -In every template file you can easily access the template functions listed in :doc:`templates`. To access the assigned variables in the template, use the **$_[]** array. The variable will be availabe under the key that you defined (e.g. $_['key']). +In every template file you can easily access the template functions listed in :doc:`../classes/core/templates`. To access the assigned variables in the template, use the **$_[]** array. The variable will be availabe under the key that you defined (e.g. $_['key']). :file:`templates/main.php` @@ -89,7 +89,7 @@ In every template file you can easily access the template functions listed in :d .. warning:: .. versionchanged:: 5.0 - To prevent XSS the following PHP **functions for printing are forbidden: echo, print() and inc('templateName')** method. Use this if you find yourself repeating a lot of the same HTML constructs. The parent variables will also be available in the included templates, but should you require it, you can also pass new variables to it by using the second optional parameter for $this->inc. @@ -103,4 +103,4 @@ Templates can also include other templates by using the **$this->inc('templateNa -**For more info, see** :doc:`templates` \ No newline at end of file +**For more info, see** :doc:`../classes/core/templates` \ No newline at end of file diff --git a/developer_manual/app/unittesting.rst b/developer_manual/app/unittesting.rst index 3792f88d1..400e6d5aa 100644 --- a/developer_manual/app/unittesting.rst +++ b/developer_manual/app/unittesting.rst @@ -3,7 +3,7 @@ Unittests .. sectionauthor:: Bernhard Posselt -.. note:: App Unittests should **not depend on a running ownCloud instance**! They should be able to run in isolation. To achieve that, abstract the ownCloud core functions and static methods in the appframework :file:`core/api.php` and use a mock for testing. If a class is not static, you can simply add it in the :file:`dependencyinjection/dicontainer.php` +.. note:: App Unittests should **not depend on a running ownCloud instance**! They should be able to run in isolation. To achieve that, abstract the ownCloud core functions and static methods in the App Framework :file:`core/api.php` and use a mock for testing. If a class is not static, you can simply add it in the :file:`dependencyinjection/dicontainer.php` .. note:: Also use your app's namespace in your test classes to avoid possible conflicts when the test is run on the buildserver @@ -13,7 +13,7 @@ Owncloud uses `PHPUnit `_ Because of Dependency Injection, unittesting has become very easy: you can easily substitute complex classes with `mocks `_ by simply passing a different object to the constructor. -Also using a container like Pimple frees us from doing complex instantiation and object passing in our application by hand. +Also using a container like `Pimple `_ frees us from doing complex instantiation and object passing in our application by hand. A simple test for a controller would look like this: @@ -75,7 +75,7 @@ You can now execute the test by running this in your app directory:: The apptemplateadvanced provides an own classloader :file:`tests/classloader.php` that loads the the classes. -.. note:: The classloader in the **tests/** directory assumes that the appframework folder is in the same directory as the yourapp. If you run your app in a different apps folder, you will need to link the appframework into the same folder where your app folder resides. +.. note:: The classloader in the **tests/** directory assumes that the **appframework/** folder is in the same directory as the yourapp. If you run your app in a different apps folder, you will need to link the App Framework into the same folder where your app folder resides. More examples for testing controllers are in the :file:`tests/controller/ItemControllerTest.php`