diff --git a/developer_manual/app/app/routes.rst b/developer_manual/app/app/routes.rst index 8d04579c7..fdb598e68 100644 --- a/developer_manual/app/app/routes.rst +++ b/developer_manual/app/app/routes.rst @@ -10,3 +10,57 @@ Routing connects your URLs with your controller methods and allows you to create ownCloud uses `Symphony Routing `_ Routes are declared in :file:`appinfo/routes.php` + +A simple route would look like this: + +.. code-block:: php + + create('yourappname_routename', '/myurl/{key}')->action( + function($params){ + require __DIR__ . '/../index.php'; + } + ); + + +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. + +.. note:: The identifier should always start with the appid since they are global and you could overwrite a route of a different app + +The second parameter is the URL which should be matched. You can extract values from the URL by using **{key}** in the section that you want to get. That value is then available under **$params['key']**, for the above example it would be **$params['key']**. You can omit the parameter if you dont extract any values from the URL at all. + +If a default value should be used for an URL parameter, it can be set via the **defaults** method: + +.. code-block:: php + + create('yourappname_routename', '/myurl/{key}')->action( + function($params){ + require __DIR__ . '/../index.php'; + } + )->defaults('key' => 'john'); + +The **action** method allows you to register a callback which gets called if the route is matched. You can use this to call a controller or simply include a PHP file. + +Using routes in templates and JavaScript +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To use routes in :php:class:`OC_Template`, use: + +.. code-block:: php + + 1))); + + +In JavaScript you can get the URL for a route like this: + +.. code-block:: javascript + + var params = {key: 1}; + var url = OC.Router.generate('yourappname_routename', params); + console.log(url); // prints /index.php//yourappname/myurl/1 + +.. note:: Be sure to only use the routes generator after the routes are loaded. This can be done by registering a callback with **OC.Router.registerLoadedCallback(callback)** \ No newline at end of file diff --git a/developer_manual/app/appframework/routes.rst b/developer_manual/app/appframework/routes.rst index 708b4e074..30d01789b 100644 --- a/developer_manual/app/appframework/routes.rst +++ b/developer_manual/app/appframework/routes.rst @@ -1,53 +1,11 @@ .. include:: ../app/routes.rst -A simple route would look like this: +Using Controllers +----------------- -.. code-block:: php +To call your controllers the App Framework provides a main method: :php:class:`OCA\\AppFramework\\App`. - create('yourappname_routename', '/myurl/{key}')->action( - function($params){ - App::main('MyController', 'methodName', $params, new DIContainer()); - } - ); - - - -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. - -.. note:: The identifier should always start with the appid since they are global and you could overwrite a route of a different app - -To use it in OC templates, use: - -.. code-block:: php - - 1))); - -In Twig templates you can use the :js:func:`url` function: - -.. code-block:: js - - {{ url('yourappname_routename', {key: '1'}) }} - - -In JavaScript you can get the URL for a route like this: - -.. code-block:: javascript - - var params = {key: 1}; - var url = OC.Router.generate('yourappname_routename', params); - console.log(url); // prints /index.php//yourappname/myurl/1 - -.. note:: Be sure to only use the routes generator after the routes are loaded. This can be done by registering a callback with **OC.Router.registerLoadedCallback(callback)** - -The second parameter is the URL which should be matched. You can extract values from the URL by using **{key}** in the section that you want to get. That value is then available under **$params['key']**, for the above example it would be **$params['key']**. You can omit the parameter if you dont extract any values from the URL at all. - -If a default value should be used for an URL parameter, it can be set via the **defaults** method: +.. note:: If you call a controller directly no security checks will be performed! Security checks are handled by the :php:class:`OCA\\AppFramework\\Middleware\\Security\\SecurityMiddleware` and called inside the :php:meth:`OCA\\AppFramework\\App::main` method! Always use the :php:meth:`OCA\\AppFramework\\App::main` method! .. code-block:: php @@ -61,9 +19,6 @@ If a default value should be used for an URL parameter, it can be set via the ** } )->defaults('key' => '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. @@ -103,3 +58,12 @@ The fourth parameter is an instance of the **DIContaier** (see :doc:`../general/ } ); ?> + +Twig +~~~~ + +The Twig templates also provide a function to create a link from a route :js:func:`url` function: + +.. code-block:: js + + {{ url('yourappname_routename', {key: '1'}) }} \ No newline at end of file