From d6711fef79d189b6470ce80e807a0b3e2b6abf6e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 2 Mar 2016 18:09:04 +0100 Subject: [PATCH 1/2] Converted documentation into reStructuredText format --- Resources/doc/compiling.rst | 25 ++++ Resources/doc/index.md | 253 --------------------------------- Resources/doc/index.rst | 13 ++ Resources/doc/installation.rst | 70 +++++++++ Resources/doc/testing.rst | 26 ++++ Resources/doc/usage.rst | 180 +++++++++++++++++++++++ 6 files changed, 314 insertions(+), 253 deletions(-) create mode 100644 Resources/doc/compiling.rst create mode 100644 Resources/doc/index.rst create mode 100644 Resources/doc/installation.rst create mode 100644 Resources/doc/testing.rst create mode 100644 Resources/doc/usage.rst diff --git a/Resources/doc/compiling.rst b/Resources/doc/compiling.rst new file mode 100644 index 00000000..4ba7f27a --- /dev/null +++ b/Resources/doc/compiling.rst @@ -0,0 +1,25 @@ +Compiling the JavaScript files +============================== + +.. note:: + + We already provide a compiled version of the JavaScript; this section is only + relevant if you want to make changes to this script. + +In order to re-compile the JavaScript source files that we ship with this +bundle, you need the Google Closure Tools. You need the `plovr`_ tool, which is +a Java ARchive, so you also need a working Java environment. You can re-compile +the JavaScript with the following command: + +.. code-block:: bash + + $ java -jar plovr.jar build Resources/config/plovr/compile.js + +Alternatively, you can use the JMSGoogleClosureBundle. If you install this +bundle, you can re-compile the JavaScript with the following command: + +.. code-block:: bash + + $ php app/console plovr:build @FOSJsRoutingBundle/compile.js + +.. _`plovr`: http://plovr.com/download.html diff --git a/Resources/doc/index.md b/Resources/doc/index.md index b0824e79..139597f9 100644 --- a/Resources/doc/index.md +++ b/Resources/doc/index.md @@ -1,255 +1,2 @@ -FOSJsRoutingBundle -================== -Port of the incredible plugin -[chCmsExposeRoutingPlugin](https://github.com/themouette/chCmsExposeRoutingPlugin). -* [Installation](#installation) -* [Usage](#usage) - - [Generating URIs](#generating-uris) - - [Commands](#commands) - - [fos:js-routing:dump](#fosjs-routingdump) - - [fos:js-routing:debug](#fosjs-routingdebug) - - [HTTP Caching](#http-caching) -* [Compiling the JavaScript files](#compiling-the-javascript-files) - - -Installation ------------- - -Require [`friendsofsymfony/jsrouting-bundle`](https://packagist.org/packages/friendsofsymfony/jsrouting-bundle) -into your `composer.json` file: - - -``` json -{ - "require": { - "friendsofsymfony/jsrouting-bundle": "@stable" - } -} -``` - -**Protip:** you should browse the -[`friendsofsymfony/jsrouting-bundle`](https://packagist.org/packages/friendsofsymfony/jsrouting-bundle) -page to choose a stable version to use, avoid the `@stable` meta constraint. - -Register the bundle in `app/AppKernel.php`: - -``` php -// app/AppKernel.php -public function registerBundles() -{ - return array( - // ... - new FOS\JsRoutingBundle\FOSJsRoutingBundle(), - ); -} -``` - -Register the routing definition in `app/config/routing.yml`: - -``` yml -# app/config/routing.yml -fos_js_routing: - resource: "@FOSJsRoutingBundle/Resources/config/routing/routing.xml" -``` - -Publish assets: - - $ php app/console assets:install --symlink web - - -Usage ------ - -Add these two lines in your layout: - -``` - - -``` - -**Note:** if you are not using Twig, then it is no problem. What you need is to -add the two JavaScript files above loaded at some point in your web page. - -### Generating URIs - -It's as simple as calling: - -```JavaScript -Routing.generate('route_id', /* your params */) -``` - -Or if you want to generate **absolute URLs**: - -```JavaScript -Routing.generate('route_id', /* your params */, true) -``` - -Assuming some route definitions: - -```yaml -# app/config/routing.yml -my_route_to_expose: - pattern: /foo/{id}/bar - defaults: { _controller: HelloBundle:Hello:index } - options: - expose: true - -my_route_to_expose_with_defaults: - pattern: /blog/{page} - defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 } - options: - expose: true -``` - -Or using annotations: - - # src/Acme/DemoBundle/Controller/DefaultController.php - /** - * @Route("/foo/{id}/bar", name="my_route_to_expose", options={"expose"=true}) - */ - public function exposedAction($foo) - -You can use the `generate()` method that way: - -```JavaScript -Routing.generate('my_route_to_expose', { id: 10 }); -// will result in /foo/10/bar - -Routing.generate('my_route_to_expose', { id: 10, foo: "bar" }); -// will result in /foo/10/bar?foo=bar - -$.get(Routing.generate('my_route_to_expose', { id: 10, foo: "bar" })); -// will call /foo/10/bar?foo=bar - -Routing.generate('my_route_to_expose_with_defaults'); -// will result in /blog/1 - -Routing.generate('my_route_to_expose_with_defaults', { id: 2 }); -// will result in /blog/2 - -Routing.generate('my_route_to_expose_with_defaults', { foo: "bar" }); -// will result in /blog/1?foo=bar - -Routing.generate('my_route_to_expose_with_defaults', { id: 2, foo: "bar" }); -// will result in /blog/2?foo=bar -``` - -Moreover, you can configure a list of routes to expose in `app/config/config.yml`: - -``` yaml -# app/config/config.yml -fos_js_routing: - routes_to_expose: [ route_1, route_2, ... ] -``` - -These routes will be added to the exposed routes. You can use regular expression patterns -if you don't want to list all your routes name by name. - -You can prevent to expose a route by configuring it as below: - -```yml -# app/config/routing.yml -my_very_secret_route: - pattern: /admin - defaults: { _controller: HelloBundle:Admin:index } - options: - expose: false -``` - -### HTTP Caching - -You can enable HTTP caching as below: - -``` -# app/config/config.yml -fos_js_routing: - cache_control: - # All are optional, defaults shown - public: false # can be true (public) or false (private) - maxage: null # integer value, e.g. 300 - smaxage: null # integer value, e.g. 300 - expires: null # anything that can be fed to "new \DateTime($expires)", e.g. "5 minutes" - vary: [] # string or array, e.g. "Cookie" or [ Cookie, Accept ] -``` - -### Commands - -#### fos:js-routing:dump - -This command dumps the route information into a file so that instead of having -the controller generated JavaScript, you can use a normal file. This also allows -to combine the routes with the other JavaScript files in assetic. - - $ php app/console fos:js-routing:dump - -Instead of the line - - - -you now include this as - - - -Or inside assetic, do - - {% javascripts filter='?yui_js' - 'bundles/fosjsrouting/js/router.js' - 'js/fos_js_routes.js' - %} - - {% endjavascripts %} - -**Important:** you should follow the Symfony documentation about generating URLs -in the console: [Configuring The Request Context -Globally](http://symfony.com/doc/current/cookbook/console/sending_emails.html#configuring-the-request-context-globally). - -*Hint*: If you are using JMSI18nRoutingBundle, you need to run the command with -the `--locale` parameter once for each locale you use and adjust your include paths -accordingly. - - -#### fos:js-routing:debug - -This command lists all exposed routes: - - $ php app/console fos:js-routing:debug [name] - - -Compiling the JavaScript files ------------------------------- - -Note: We already provide a compiled version of the JavaScript; this section is only -relevant if you want to make changes to this script. - -In order to re-compile the JavaScript source files that we ship with this bundle, you -need the Google Closure Tools. You need the -[**plovr**](http://plovr.com/download.html) tool, it is a Java ARchive, so you -also need a working Java environment. You can re-compile the JavaScript with the -following command: - - $ java -jar plovr.jar build Resources/config/plovr/compile.js - -Alternatively, you can use the JMSGoogleClosureBundle. If you install this bundle, -you can re-compile the JavaScript with the following command: - - $ php app/console plovr:build @FOSJsRoutingBundle/compile.js - - -Testing -------- - -Setup the test suite using [Composer](http://getcomposer.org/): - - $ composer install --dev - -Run it using PHPUnit: - - $ phpunit - -### JavaScript Test Suite - -You need [PhantomJS](http://phantomjs.org/): - - $ phantomjs Resources/js/run_jsunit.js Resources/js/router_test.html diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst new file mode 100644 index 00000000..b48ce6dc --- /dev/null +++ b/Resources/doc/index.rst @@ -0,0 +1,13 @@ +FOSJsRoutingBundle +================== + +This bundle allows to expose Symfony Routes to JavaScript, so you can generate +relative or absolute URLs in the browser using the same routes as in the backend. + +.. toctree:: + :maxdepth: 1 + + installation + usage + compilling + testing diff --git a/Resources/doc/installation.rst b/Resources/doc/installation.rst new file mode 100644 index 00000000..4c6107aa --- /dev/null +++ b/Resources/doc/installation.rst @@ -0,0 +1,70 @@ +Installation +============ + +Step 1: Download the Bundle +--------------------------- + +Open a command console, enter your project directory and execute the +following command to download the latest stable version of this bundle: + +.. code-block:: bash + + $ composer require friendsofsymfony/jsrouting-bundle + +This command requires you to have Composer installed globally, as explained +in the `installation chapter`_ of the Composer documentation. + +Step 2: Enable the Bundle +------------------------- + +Then, enable the bundle by adding it to the list of registered bundles +in the ``app/AppKernel.php`` file of your project: + +.. code-block:: php + + + + +.. note:: + + If you are not using Twig, then it is no problem. What you need is to add + the two JavaScript files above loaded at some point in your web page. + +Generating URIs +--------------- + +It's as simple as calling: + +.. code-block:: javascript + + Routing.generate('route_id', /* your params */) + +Or if you want to generate **absolute URLs**: + +.. code-block:: javascript + + Routing.generate('route_id', /* your params */, true) + +Assuming some route definitions: + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Acme/DemoBundle/Controller/DefaultController.php + + /** + * @Route("/foo/{id}/bar", name="my_route_to_expose", options={"expose"=true}) + */ + public function exposedAction($foo) + + .. code-block:: yaml + + # app/config/routing.yml + my_route_to_expose: + pattern: /foo/{id}/bar + defaults: { _controller: HelloBundle:Hello:index } + options: + expose: true + + my_route_to_expose_with_defaults: + pattern: /blog/{page} + defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 } + options: + expose: true + +You can use the ``generate()`` method that way: + +.. code-block:: javascript + + Routing.generate('my_route_to_expose', { id: 10 }); + // will result in /foo/10/bar + + Routing.generate('my_route_to_expose', { id: 10, foo: "bar" }); + // will result in /foo/10/bar?foo=bar + + $.get(Routing.generate('my_route_to_expose', { id: 10, foo: "bar" })); + // will call /foo/10/bar?foo=bar + + Routing.generate('my_route_to_expose_with_defaults'); + // will result in /blog/1 + + Routing.generate('my_route_to_expose_with_defaults', { id: 2 }); + // will result in /blog/2 + + Routing.generate('my_route_to_expose_with_defaults', { foo: "bar" }); + // will result in /blog/1?foo=bar + + Routing.generate('my_route_to_expose_with_defaults', { id: 2, foo: "bar" }); + // will result in /blog/2?foo=bar + +Moreover, you can configure a list of routes to expose in ``app/config/config.yml``: + +.. code-block:: yaml + + # app/config/config.yml + fos_js_routing: + routes_to_expose: [ route_1, route_2, ... ] + +These routes will be added to the exposed routes. You can use regular expression +patterns if you don't want to list all your routes name by name. + +You can prevent to expose a route by configuring it as below: + +.. code-block:: yaml + + # app/config/routing.yml + my_very_secret_route: + pattern: /admin + defaults: { _controller: HelloBundle:Admin:index } + options: + expose: false + +HTTP Caching +------------ + +You can enable HTTP caching as below: + +.. code-block:: yaml + + # app/config/config.yml + fos_js_routing: + cache_control: + # All are optional, defaults shown + public: false # can be true (public) or false (private) + maxage: null # integer value, e.g. 300 + smaxage: null # integer value, e.g. 300 + expires: null # anything that can be fed to "new \DateTime($expires)", e.g. "5 minutes" + vary: [] # string or array, e.g. "Cookie" or [ Cookie, Accept ] + +Commands +-------- + +fos:js-routing:dump +~~~~~~~~~~~~~~~~~~~ + +This command dumps the route information into a file so that instead of having +the controller generated JavaScript, you can use a normal file. This also allows +to combine the routes with the other JavaScript files in assetic. + +.. code-block:: bash + + $ php app/console fos:js-routing:dump + +Instead of the line + +.. code-block:: twig + + + +you now include this as + +.. code-block:: html + + + +Or inside assetic, do + +.. code-block:: twig + + {% javascripts filter='?yui_js' + 'bundles/fosjsrouting/js/router.js' + 'js/fos_js_routes.js' + %} + + {% endjavascripts %} + +.. caution:: + + You should follow the Symfony documentation about generating URLs + in the console: `Configuring The Request Context Globally`_. + +.. tip:: + + If you are using JMSI18nRoutingBundle, you need to run the command with the + ``--locale`` parameter once for each locale you use and adjust your include + paths accordingly. + +fos:js-routing:debug +~~~~~~~~~~~~~~~~~~~~ + +This command lists all exposed routes: + +.. code-block:: bash + + $ php app/console fos:js-routing:debug [name] + +.. _`Configuring The Request Context Globally`: http://symfony.com/doc/current/cookbook/console/sending_emails.html#configuring-the-request-context-globally From cb8a2c6e5bbd2cb4c039347c642aeaec06a8dd96 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 2 Mar 2016 19:38:32 +0100 Subject: [PATCH 2/2] Implemented suggestions --- CONTRIBUTING.md | 69 +++++++++++++++++++++----- Resources/doc/commands.rst | 58 ++++++++++++++++++++++ Resources/doc/compiling.rst | 25 ---------- Resources/doc/index.md | 2 - Resources/doc/index.rst | 3 +- Resources/doc/testing.rst | 26 ---------- Resources/doc/usage.rst | 99 +++++++++++-------------------------- 7 files changed, 146 insertions(+), 136 deletions(-) create mode 100644 Resources/doc/commands.rst delete mode 100644 Resources/doc/compiling.rst delete mode 100644 Resources/doc/index.md delete mode 100644 Resources/doc/testing.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3677a2cf..e3549e16 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,19 +3,15 @@ Contributing First of all, **thank you** for contributing, **you are awesome**! -Here are a few rules to follow in order to ease code reviews, and discussions before -maintainers accept and merge your work. +Here are a few rules to follow in order to ease code reviews, and discussions +before maintainers accept and merge your work: -You MUST follow the [PSR-1](http://www.php-fig.org/psr/1/) and -[PSR-2](http://www.php-fig.org/psr/2/). If you don't know about any of them, you -should really read the recommendations. Can't wait? Use the [PHP-CS-Fixer -tool](http://cs.sensiolabs.org/). - -You MUST run the test suite. - -You MUST write (or update) unit tests. - -You SHOULD write documentation. + * You MUST follow the [PSR-1](http://www.php-fig.org/psr/1/) and + [PSR-2](http://www.php-fig.org/psr/2/) recommendations. Use the [PHP-CS-Fixer + tool](http://cs.sensiolabs.org/) to fix the syntax of your code automatically. + * You MUST run the test suite. + * You MUST write (or update) unit tests. + * You SHOULD write documentation. Please, write [commit messages that make sense](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), @@ -31,3 +27,52 @@ Also, while creating your Pull Request on GitHub, you MUST write a description which gives the context and/or explains why you are creating it. Thank you! + +Running tests +------------- + +Before running the test suite, execute the following Composer command to install +the dependencies used by the bundle: + +```bash +$ composer install --dev +``` + +Then, execute the tests executing: + +```bash +$ phpunit +``` + +### JavaScript Test Suite + +First, install [PhantomJS](http://phantomjs.org/) and then, execute this command: + +```bash +$ phantomjs Resources/js/run_jsunit.js Resources/js/router_test.html +``` + +Compiling the JavaScript files +------------------------------ + +> **NOTE** +> +> We already provide a compiled version of the JavaScript; this section is only +> relevant if you want to make changes to this script. + +In order to re-compile the JavaScript source files that we ship with this +bundle, you need the Google Closure Tools. You need the +[plovr](http://plovr.com/download.html) tool, which is a Java ARchive, so you +also need a working Java environment. You can re-compile the JavaScript with the +following command: + +```bash +$ java -jar plovr.jar build Resources/config/plovr/compile.js +``` + +Alternatively, you can use the JMSGoogleClosureBundle. If you install this +bundle, you can re-compile the JavaScript with the following command: + +```bash +$ php app/console plovr:build @FOSJsRoutingBundle/compile.js +``` diff --git a/Resources/doc/commands.rst b/Resources/doc/commands.rst new file mode 100644 index 00000000..8308e56c --- /dev/null +++ b/Resources/doc/commands.rst @@ -0,0 +1,58 @@ +Commands +======== + +fos:js-routing:dump +------------------- + +This command dumps the route information into a file so that instead of having +the controller generated JavaScript, you can use a normal file. This also allows +to combine the routes with the other JavaScript files in assetic. + +.. code-block:: bash + + $ php app/console fos:js-routing:dump + +Instead of the line + +.. code-block:: twig + + + +you now include this as + +.. code-block:: html + + + +Or inside assetic, do + +.. code-block:: twig + + {% javascripts filter='?yui_js' + 'bundles/fosjsrouting/js/router.js' + 'js/fos_js_routes.js' + %} + + {% endjavascripts %} + +.. caution:: + + You should follow the Symfony documentation about generating URLs + in the console: `Configuring The Request Context Globally`_. + +.. tip:: + + If you are using JMSI18nRoutingBundle, you need to run the command with the + ``--locale`` parameter once for each locale you use and adjust your include + paths accordingly. + +fos:js-routing:debug +-------------------- + +This command lists all exposed routes: + +.. code-block:: bash + + $ php app/console fos:js-routing:debug [name] + +.. _`Configuring The Request Context Globally`: http://symfony.com/doc/current/cookbook/console/sending_emails.html#configuring-the-request-context-globally diff --git a/Resources/doc/compiling.rst b/Resources/doc/compiling.rst deleted file mode 100644 index 4ba7f27a..00000000 --- a/Resources/doc/compiling.rst +++ /dev/null @@ -1,25 +0,0 @@ -Compiling the JavaScript files -============================== - -.. note:: - - We already provide a compiled version of the JavaScript; this section is only - relevant if you want to make changes to this script. - -In order to re-compile the JavaScript source files that we ship with this -bundle, you need the Google Closure Tools. You need the `plovr`_ tool, which is -a Java ARchive, so you also need a working Java environment. You can re-compile -the JavaScript with the following command: - -.. code-block:: bash - - $ java -jar plovr.jar build Resources/config/plovr/compile.js - -Alternatively, you can use the JMSGoogleClosureBundle. If you install this -bundle, you can re-compile the JavaScript with the following command: - -.. code-block:: bash - - $ php app/console plovr:build @FOSJsRoutingBundle/compile.js - -.. _`plovr`: http://plovr.com/download.html diff --git a/Resources/doc/index.md b/Resources/doc/index.md deleted file mode 100644 index 139597f9..00000000 --- a/Resources/doc/index.md +++ /dev/null @@ -1,2 +0,0 @@ - - diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst index b48ce6dc..31e4554e 100644 --- a/Resources/doc/index.rst +++ b/Resources/doc/index.rst @@ -9,5 +9,4 @@ relative or absolute URLs in the browser using the same routes as in the backend installation usage - compilling - testing + commands diff --git a/Resources/doc/testing.rst b/Resources/doc/testing.rst deleted file mode 100644 index 9fbd2e06..00000000 --- a/Resources/doc/testing.rst +++ /dev/null @@ -1,26 +0,0 @@ -Testing -======= - -Before running the test suite, execute the following Composer command to install -the dependencies used by the bundle: - -.. code-block:: bash - - $ composer install --dev - -Then, execute the tests executing: - -.. code-block:: bash - - $ phpunit - -JavaScript Test Suite ---------------------- - -First, install `PhantomJS`_ and then, execute this command: - -.. code-block:: bash - - $ phantomjs Resources/js/run_jsunit.js Resources/js/router_test.html - -.. _`PhantomJS`: http://phantomjs.org/ diff --git a/Resources/doc/usage.rst b/Resources/doc/usage.rst index f8cdf0cd..7ad13196 100644 --- a/Resources/doc/usage.rst +++ b/Resources/doc/usage.rst @@ -3,10 +3,17 @@ Usage Add these two lines in your layout: -.. code-block:: twig +.. configuration-block:: + + .. code-block:: html+twig + + + + + .. code-block:: html+php - - + + .. note:: @@ -20,13 +27,13 @@ It's as simple as calling: .. code-block:: javascript - Routing.generate('route_id', /* your params */) + Routing.generate('route_name', /* your params */) Or if you want to generate **absolute URLs**: .. code-block:: javascript - Routing.generate('route_id', /* your params */, true) + Routing.generate('route_name', /* your params */, true) Assuming some route definitions: @@ -34,25 +41,38 @@ Assuming some route definitions: .. code-block:: php-annotations - // src/Acme/DemoBundle/Controller/DefaultController.php + // src/AppBundle/Controller/DefaultController.php /** - * @Route("/foo/{id}/bar", name="my_route_to_expose", options={"expose"=true}) + * @Route("/foo/{id}/bar", options={"expose"=true}, name="my_route_to_expose") */ - public function exposedAction($foo) + public function indexAction($foo) { + // ... + } + + /** + * @Route("/blog/{page}", + * defaults = { "page" = 1 }, + * options = { "expose" = true }, + * name = "my_route_to_expose_with_defaults", + * ) + */ + public function blogAction($page) { + // ... + } .. code-block:: yaml # app/config/routing.yml my_route_to_expose: pattern: /foo/{id}/bar - defaults: { _controller: HelloBundle:Hello:index } + defaults: { _controller: AppBundle:Default:index } options: expose: true my_route_to_expose_with_defaults: pattern: /blog/{page} - defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 } + defaults: { _controller: AppBundle:Default:blog, page: 1 } options: expose: true @@ -119,62 +139,3 @@ You can enable HTTP caching as below: smaxage: null # integer value, e.g. 300 expires: null # anything that can be fed to "new \DateTime($expires)", e.g. "5 minutes" vary: [] # string or array, e.g. "Cookie" or [ Cookie, Accept ] - -Commands --------- - -fos:js-routing:dump -~~~~~~~~~~~~~~~~~~~ - -This command dumps the route information into a file so that instead of having -the controller generated JavaScript, you can use a normal file. This also allows -to combine the routes with the other JavaScript files in assetic. - -.. code-block:: bash - - $ php app/console fos:js-routing:dump - -Instead of the line - -.. code-block:: twig - - - -you now include this as - -.. code-block:: html - - - -Or inside assetic, do - -.. code-block:: twig - - {% javascripts filter='?yui_js' - 'bundles/fosjsrouting/js/router.js' - 'js/fos_js_routes.js' - %} - - {% endjavascripts %} - -.. caution:: - - You should follow the Symfony documentation about generating URLs - in the console: `Configuring The Request Context Globally`_. - -.. tip:: - - If you are using JMSI18nRoutingBundle, you need to run the command with the - ``--locale`` parameter once for each locale you use and adjust your include - paths accordingly. - -fos:js-routing:debug -~~~~~~~~~~~~~~~~~~~~ - -This command lists all exposed routes: - -.. code-block:: bash - - $ php app/console fos:js-routing:debug [name] - -.. _`Configuring The Request Context Globally`: http://symfony.com/doc/current/cookbook/console/sending_emails.html#configuring-the-request-context-globally