mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-03 18:26:42 +07:00
typos app
This commit is contained in:
@@ -4,7 +4,7 @@ RESTful API
|
||||
|
||||
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
|
||||
|
||||
Offering a RESTful API is not different from creating a :doc:`route <routes>` and :doc:`controllers <controllers>` for the webinterface. It is recommended though to inherit from ApiController and add **@CORS** annotations to the methods so that `also web applications will be able to access the API <https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS>`_.
|
||||
Offering a RESTful API is not different from creating a :doc:`route <routes>` and :doc:`controllers <controllers>` for the web interface. It is recommended though to inherit from ApiController and add **@CORS** annotations to the methods so that `also web applications will be able to access the API <https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS>`_.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -29,7 +29,7 @@ Offering a RESTful API is not different from creating a :doc:`route <routes>` an
|
||||
|
||||
}
|
||||
|
||||
CORS also needs a seperate url for the preflighted **OPTIONS** request that easily be added by adding the following route:
|
||||
CORS also needs a separate URL for the preflighted **OPTIONS** request that easily be added by adding the following route:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -76,4 +76,4 @@ To add an additional method or header or allow less headers, simply pass additio
|
||||
1728000);
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
@@ -34,6 +34,6 @@ Dont forget to configure the cron service on the server by executing::
|
||||
|
||||
sudo crontab -u http -e
|
||||
|
||||
where **http** is your webserver user, and add::
|
||||
where **http** is your web server user, and add::
|
||||
|
||||
*/15 * * * * php -f /srv/http/owncloud/cron.php
|
||||
*/15 * * * * php -f /srv/http/owncloud/cron.php
|
||||
|
||||
@@ -155,11 +155,11 @@ Which classes should be added
|
||||
In general all of the app's controllers need to be registered inside the container. Then following question is: What goes into the constructor of the controller? Pass everything into the controller constructor that is responsible matches one of the following criteria:
|
||||
|
||||
* It does I/O (database, write/read to files)
|
||||
* It is a global (eg. $_POST, etc. This is in the request class btw)
|
||||
* It is a global (e.g. $_POST, etc. This is in the request class by the way)
|
||||
* The output does not depend on the input variables (also called `impure function <http://en.wikipedia.org/wiki/Pure_function>`_), e.g. time, random number generator
|
||||
* It is a service, basically it would make sense to swap it out for a different object
|
||||
|
||||
What not to inject:
|
||||
|
||||
* It is pure data and has methods that only act upon it (arrays, data objects)
|
||||
* It is a `pure function <http://en.wikipedia.org/wiki/Pure_function>`_
|
||||
* It is a `pure function <http://en.wikipedia.org/wiki/Pure_function>`_
|
||||
|
||||
@@ -110,7 +110,7 @@ All those parameters can easily be accessed by adding them to the controller met
|
||||
|
||||
}
|
||||
|
||||
It is also possible to set default parameter values by using PHP default method values so common values can be ommited:
|
||||
It is also possible to set default parameter values by using PHP default method values so common values can be omitted:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -353,7 +353,7 @@ A :doc:`template <templates>` can be rendered by returning a TemplateResponse. A
|
||||
|
||||
$_['key']
|
||||
|
||||
* **renderAs**: defaults to *user*, tells ownCloud if it should include it in the webinterface, or in case *blank* is passed solely render the template
|
||||
* **renderAs**: defaults to *user*, tells ownCloud if it should include it in the web interface, or in case *blank* is passed solely render the template
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -395,7 +395,7 @@ A redirect can be achieved by returning a RedirectResponse:
|
||||
|
||||
Downloads
|
||||
---------
|
||||
A file download can be triggeredby returning a DownloadResponse:
|
||||
A file download can be triggered by returning a DownloadResponse:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -449,7 +449,7 @@ Creating a custom XMLResponse class could look like this:
|
||||
|
||||
Handling errors
|
||||
---------------
|
||||
Sometimes a request should fail, for instance if an author with id 1 is requested but does not exist. In that case use an appropriate `HTTP error code <https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error>`_ to signal the client that an error occured.
|
||||
Sometimes a request should fail, for instance if an author with id 1 is requested but does not exist. In that case use an appropriate `HTTP error code <https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error>`_ to signal the client that an error occurred.
|
||||
|
||||
Each response subclass has access to the **setStatus** method which lets you set an HTTP status code. To return a JSONResponse signaling that the author with id 1 has not been found, use the following code:
|
||||
|
||||
@@ -515,4 +515,4 @@ A controller method that turns of all checks would look like this:
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
@@ -65,7 +65,7 @@ To create a settings area create a div with the id **app-settings** inside the *
|
||||
</div>
|
||||
</div>
|
||||
|
||||
The data attribute **data-apps-slide-toggle** slides up a taret area using a jQuery selector and hides the area if the user clicks outside of it.
|
||||
The data attribute **data-apps-slide-toggle** slides up a target area using a jQuery selector and hides the area if the user clicks outside of it.
|
||||
|
||||
Icons
|
||||
=====
|
||||
|
||||
@@ -165,7 +165,7 @@ Mappers should be registered in the constructor to reuse them inside the applica
|
||||
|
||||
Entities
|
||||
========
|
||||
Entities are data objects that carry all the table's information for one row. Every Entity has an **id** field by default that is set to the integer type. Table rows are mapped from lower case and underscore seperated names to pascal case attributes:
|
||||
Entities are data objects that carry all the table's information for one row. Every Entity has an **id** field by default that is set to the integer type. Table rows are mapped from lower case and underscore separated names to pascal case attributes:
|
||||
|
||||
* **Table column name**: phone_number
|
||||
* **Property name**: phoneNumber
|
||||
@@ -225,7 +225,7 @@ Since all attributes should be private, getters and setters are automatically ge
|
||||
|
||||
Slugs
|
||||
-----
|
||||
Slugs are used to identify resources in the URL by a string rather than integer id. Since the url allows only certain values, the entity baseclass provides a slugify method for it:
|
||||
Slugs are used to identify resources in the URL by a string rather than integer id. Since the URL allows only certain values, the entity baseclass provides a slugify method for it:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -234,4 +234,4 @@ Slugs are used to identify resources in the URL by a string rather than integer
|
||||
$author->setName('Some*thing');
|
||||
$author->slugify('name'); // Some-thing
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ Filesystem classes can be injected from the ServerContainer by calling the metho
|
||||
Writing to a file
|
||||
=================
|
||||
|
||||
All methods return a Folder object on which files and folders can be accessed, or filesystem operatoins can be performed relatively to their root. For instance for writing to file:`owncloud/data/myfile.txt` you should get the root folder and use:
|
||||
All methods return a Folder object on which files and folders can be accessed, or filesystem operations can be performed relatively to their root. For instance for writing to file:`owncloud/data/myfile.txt` you should get the root folder and use:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -108,4 +108,4 @@ Files and folders can also be accessed by id, by calling the **getById** method
|
||||
throw new StorageException('File does not exist');
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -4,7 +4,7 @@ Hooks
|
||||
|
||||
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
|
||||
|
||||
Hooks are used to execute code before or after an event has occured. This is for instance useful to run cleanup code after users, groups or files have been deleted. Hooks should be registered in the :doc:`app.php <init>`:
|
||||
Hooks are used to execute code before or after an event has occurred. This is for instance useful to run cleanup code after users, groups or files have been deleted. Hooks should be registered in the :doc:`app.php <init>`:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -14,7 +14,7 @@ Hooks are used to execute code before or after an event has occured. This is for
|
||||
$app = new Application();
|
||||
$app->getContainer()->query('UserHooks')->register();
|
||||
|
||||
The hook logic should be in a seperate class that is being registered in the :doc:`container`
|
||||
The hook logic should be in a separate class that is being registered in the :doc:`container`
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -159,4 +159,4 @@ Filesystem Scanner
|
||||
Filesystem scanner hooks available in scope **\\OC\\Utils\\Scanner**:
|
||||
|
||||
* **scanFile** (string $absolutePath)
|
||||
* **scanFolder** (string $absolutePath)
|
||||
* **scanFolder** (string $absolutePath)
|
||||
|
||||
@@ -16,7 +16,7 @@ The :file:`appinfo/info.xml` contains metadata about the app:
|
||||
<version>1.0</version>
|
||||
<licence>AGPL</licence>
|
||||
<author>Your Name</author>
|
||||
<require>5</require>
|
||||
<requiremin>5</requiremin>
|
||||
|
||||
<types>
|
||||
<type>filesystem</type>
|
||||
@@ -47,7 +47,7 @@ The :file:`appinfo/info.xml` contains metadata about the app:
|
||||
|
||||
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.
|
||||
**Required**: This field contains the internal app name, and has to be the same as the folder name of the app. This id needs to be unique in ownCloud, meaning no other app should have this id.
|
||||
|
||||
name
|
||||
----
|
||||
@@ -74,7 +74,7 @@ author
|
||||
------
|
||||
**Required**: The name of the app author or authors.
|
||||
|
||||
require
|
||||
requiremin
|
||||
-------
|
||||
**Required**: The minimal version of ownCloud.
|
||||
|
||||
@@ -98,10 +98,10 @@ website
|
||||
-------
|
||||
link to project webpage
|
||||
|
||||
Depcrecated
|
||||
Deprecated
|
||||
===========
|
||||
|
||||
The following sections are just listed for reference and should not be use because
|
||||
The following sections are just listed for reference and should not be used because
|
||||
|
||||
* **public/remote**: Use :doc:`api` instead because you'll have to use :doc:`../core/externalapi` which is known to be buggy (works only properly with GET/POST)
|
||||
* **standalone/default_enable**: They tell core what do on setup, you will not be able to even activate your app if it has those entries. This should be replaced by a config file inside core.
|
||||
|
||||
@@ -8,7 +8,7 @@ ownCloud's translation system is powered by `Transifex <https://www.transifex.co
|
||||
|
||||
PHP
|
||||
===
|
||||
Should it ever be needed to use localized strings on the serverside simply inject the L10N service from the ServerContainer into the needed constructor
|
||||
Should it ever be needed to use localized strings on the server-side, simply inject the L10N service from the ServerContainer into the needed constructor
|
||||
|
||||
|
||||
.. code-block:: php
|
||||
@@ -97,7 +97,7 @@ In every template the global variable **$l** can be used to translate the string
|
||||
|
||||
JavaScript
|
||||
==========
|
||||
There is currently no good way to translate JavaScript strings. One way to still use translated strings in the scripts is to create an invisble HTML element with all the translations in it which can be parsed in the JavaScript code:
|
||||
There is currently no good way to translate JavaScript strings. One way to still use translated strings in the scripts is to create an invisible HTML element with all the translations in it which can be parsed in the JavaScript code:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -119,4 +119,4 @@ If Transifex is not the right choice or the app is not accepted for translation,
|
||||
|
||||
The translation script requires **Locale::PO** and **gettext**, installable via::
|
||||
|
||||
apt-get install liblocale-po-perl gettext
|
||||
apt-get install liblocale-po-perl gettext
|
||||
|
||||
@@ -144,4 +144,4 @@ Now adjust the container to inject the reflector:
|
||||
|
||||
}
|
||||
|
||||
.. note:: An annotation always starts with an uppercase letter
|
||||
.. note:: An annotation always starts with an uppercase letter
|
||||
|
||||
@@ -15,7 +15,7 @@ The following sections will present an overview over how that request is being p
|
||||
|
||||
Front controller
|
||||
================
|
||||
In the beginning, all requests are sent to ownCloud's :file:`index.php` which in turn executes :file:`lib/base.php`. This file inspects the HTTP headers and abstracts away differences between different webservers and initializes the basic classes. Afterwards the basic apps are being loaded in the following order:
|
||||
In the beginning, all requests are sent to ownCloud's :file:`index.php` which in turn executes :file:`lib/base.php`. This file inspects the HTTP headers and abstracts away differences between different web servers and initializes the basic classes. Afterwards the basic apps are being loaded in the following order:
|
||||
|
||||
* Authentication backends
|
||||
* Filesystem
|
||||
|
||||
@@ -54,12 +54,12 @@ The route array contains the following parts:
|
||||
|
||||
}
|
||||
* **method** (Optional, defaults to GET): The HTTP method that should be matched, (e.g. GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH)
|
||||
* **requirements** (Optional): lets you match and extract urls that have slashes in them (see **Matching suburls**)
|
||||
* **requirements** (Optional): lets you match and extract URLs that have slashes in them (see **Matching suburls**)
|
||||
|
||||
Extracting values from the URL
|
||||
==============================
|
||||
|
||||
It is possible to extract values from the URL to allow RESTful url design. To extract a value, you have to wrap it inside curly braces:
|
||||
It is possible to extract values from the URL to allow RESTful URL design. To extract a value, you have to wrap it inside curly braces:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -79,11 +79,11 @@ It is possible to extract values from the URL to allow RESTful url design. To ex
|
||||
|
||||
}
|
||||
|
||||
The identifier used inside the route is being passed into controller method by reflecting the method parameters. So basially if you want to get the value **{id}** in your method, you need to add **$id** to your method parameters.
|
||||
The identifier used inside the route is being passed into controller method by reflecting the method parameters. So basically if you want to get the value **{id}** in your method, you need to add **$id** to your method parameters.
|
||||
|
||||
Matching suburls
|
||||
================
|
||||
Sometimes its needed to match more than one URL fragment. An example would be to match a request for all urls that start with **OPTIONS /index.php/apps/myapp/api**. To do this, use the **requirements** parameter in your route which is an array containing pairs of **'key' => 'regex'**:
|
||||
Sometimes its needed to match more than one URL fragment. An example would be to match a request for all URLs that start with **OPTIONS /index.php/apps/myapp/api**. To do this, use the **requirements** parameter in your route which is an array containing pairs of **'key' => 'regex'**:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -114,7 +114,7 @@ When dealing with resources, writing routes can become quite repetitive since mo
|
||||
* Update an entry
|
||||
* Delete an entry
|
||||
|
||||
To prevent reptition, it's possible define resources. The following routes:
|
||||
To prevent repetition, it's possible define resources. The following routes:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@@ -152,7 +152,7 @@ can be abbreviated by using the **resources** key:
|
||||
|
||||
Using the URLGenerator
|
||||
========================
|
||||
Sometimes its useful to turn a route into a URL to make the code independent from the url design or to generate an URL for an image in **img/**. For that specific usecase the ServerContainer provides a service that can be used in your container:
|
||||
Sometimes its useful to turn a route into a URL to make the code independent from the URL design or to generate an URL for an image in **img/**. For that specific use case, the ServerContainer provides a service that can be used in your container:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ The parent variables will also be available in the included templates, but shoul
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<div>I am included but i can still access the parents variables!</div>
|
||||
<div>I am included, but I can still access the parents variables!</div>
|
||||
<?php p($_['name']); ?>
|
||||
|
||||
<?php print_unescaped($this->inc('other_template', array('variable' => 'value'))); ?>
|
||||
|
||||
@@ -10,7 +10,7 @@ All PHP classes can be tested with `PHPUnit <http://phpunit.de/>`_, JavaScript c
|
||||
|
||||
PHP
|
||||
===
|
||||
The PHP tests go into the **tests/** directory. Unfortunately the classloader in core requires a running server (as in fully configured and setup up with a database connection). This is unfortunately too complicated and slow so a seperate classloader has to be provided. If the app has been generated with the **ocdev startapp** command, the classloader is already present in the the **tests/** directory and PHPUnit can be run with::
|
||||
The PHP tests go into the **tests/** directory. Unfortunately the classloader in core requires a running server (as in fully configured and setup up with a database connection). This is unfortunately too complicated and slow so a separate classloader has to be provided. If the app has been generated with the **ocdev startapp** command, the classloader is already present in the the **tests/** directory and PHPUnit can be run with::
|
||||
|
||||
phpunit tests/
|
||||
|
||||
@@ -83,4 +83,4 @@ would look like this:
|
||||
$this->container['AuthorStorage']->getContent(3);
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user