Skip to content

Commit d6711fe

Browse files
javiereguiluzjaviereguiluz
committed
Converted documentation into reStructuredText format
1 parent 0abe584 commit d6711fe

File tree

6 files changed

+314
-253
lines changed

6 files changed

+314
-253
lines changed

‎Resources/doc/compiling.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
Compiling the JavaScript files
2+
==============================
3+
4+
.. note::
5+
6+
We already provide a compiled version of the JavaScript; this section is only
7+
relevant if you want to make changes to this script.
8+
9+
In order to re-compile the JavaScript source files that we ship with this
10+
bundle, you need the Google Closure Tools. You need the `plovr`_ tool, which is
11+
a Java ARchive, so you also need a working Java environment. You can re-compile
12+
the JavaScript with the following command:
13+
14+
.. code-block:: bash
15+
16+
$ java -jar plovr.jar build Resources/config/plovr/compile.js
17+
18+
Alternatively, you can use the JMSGoogleClosureBundle. If you install this
19+
bundle, you can re-compile the JavaScript with the following command:
20+
21+
.. code-block:: bash
22+
23+
$ php app/console plovr:build @FOSJsRoutingBundle/compile.js
24+
25+
.. _`plovr`: http://plovr.com/download.html

‎Resources/doc/index.md‎

Lines changed: 0 additions & 253 deletions
Original file line numberDiff line numberDiff line change
@@ -1,255 +1,2 @@
1-
FOSJsRoutingBundle
2-
==================
31

4-
Port of the incredible plugin
5-
[chCmsExposeRoutingPlugin](https://github.com/themouette/chCmsExposeRoutingPlugin).
62

7-
* [Installation](#installation)
8-
* [Usage](#usage)
9-
- [Generating URIs](#generating-uris)
10-
- [Commands](#commands)
11-
- [fos:js-routing:dump](#fosjs-routingdump)
12-
- [fos:js-routing:debug](#fosjs-routingdebug)
13-
- [HTTP Caching](#http-caching)
14-
* [Compiling the JavaScript files](#compiling-the-javascript-files)
15-
16-
17-
Installation
18-
------------
19-
20-
Require [`friendsofsymfony/jsrouting-bundle`](https://packagist.org/packages/friendsofsymfony/jsrouting-bundle)
21-
into your `composer.json` file:
22-
23-
24-
``` json
25-
{
26-
"require": {
27-
"friendsofsymfony/jsrouting-bundle": "@stable"
28-
}
29-
}
30-
```
31-
32-
**Protip:** you should browse the
33-
[`friendsofsymfony/jsrouting-bundle`](https://packagist.org/packages/friendsofsymfony/jsrouting-bundle)
34-
page to choose a stable version to use, avoid the `@stable` meta constraint.
35-
36-
Register the bundle in `app/AppKernel.php`:
37-
38-
``` php
39-
// app/AppKernel.php
40-
public function registerBundles()
41-
{
42-
return array(
43-
// ...
44-
new FOS\JsRoutingBundle\FOSJsRoutingBundle(),
45-
);
46-
}
47-
```
48-
49-
Register the routing definition in `app/config/routing.yml`:
50-
51-
``` yml
52-
# app/config/routing.yml
53-
fos_js_routing:
54-
resource: "@FOSJsRoutingBundle/Resources/config/routing/routing.xml"
55-
```
56-
57-
Publish assets:
58-
59-
$ php app/console assets:install --symlink web
60-
61-
62-
Usage
63-
-----
64-
65-
Add these two lines in your layout:
66-
67-
```
68-
<script src="{{ asset('bundles/fosjsrouting/js/router.js') }}"></script>
69-
<script src="{{ path('fos_js_routing_js', {"callback": "fos.Router.setData"}) }}"></script>
70-
```
71-
72-
**Note:** if you are not using Twig, then it is no problem. What you need is to
73-
add the two JavaScript files above loaded at some point in your web page.
74-
75-
### Generating URIs
76-
77-
It's as simple as calling:
78-
79-
```JavaScript
80-
Routing.generate('route_id', /* your params */)
81-
```
82-
83-
Or if you want to generate **absolute URLs**:
84-
85-
```JavaScript
86-
Routing.generate('route_id', /* your params */, true)
87-
```
88-
89-
Assuming some route definitions:
90-
91-
```yaml
92-
# app/config/routing.yml
93-
my_route_to_expose:
94-
pattern: /foo/{id}/bar
95-
defaults: { _controller: HelloBundle:Hello:index }
96-
options:
97-
expose: true
98-
99-
my_route_to_expose_with_defaults:
100-
pattern: /blog/{page}
101-
defaults: { _controller: AcmeBlogBundle:Blog:index, page: 1 }
102-
options:
103-
expose: true
104-
```
105-
106-
Or using annotations:
107-
108-
# src/Acme/DemoBundle/Controller/DefaultController.php
109-
/**
110-
* @Route("/foo/{id}/bar", name="my_route_to_expose", options={"expose"=true})
111-
*/
112-
public function exposedAction($foo)
113-
114-
You can use the `generate()` method that way:
115-
116-
```JavaScript
117-
Routing.generate('my_route_to_expose', { id: 10 });
118-
// will result in /foo/10/bar
119-
120-
Routing.generate('my_route_to_expose', { id: 10, foo: "bar" });
121-
// will result in /foo/10/bar?foo=bar
122-
123-
$.get(Routing.generate('my_route_to_expose', { id: 10, foo: "bar" }));
124-
// will call /foo/10/bar?foo=bar
125-
126-
Routing.generate('my_route_to_expose_with_defaults');
127-
// will result in /blog/1
128-
129-
Routing.generate('my_route_to_expose_with_defaults', { id: 2 });
130-
// will result in /blog/2
131-
132-
Routing.generate('my_route_to_expose_with_defaults', { foo: "bar" });
133-
// will result in /blog/1?foo=bar
134-
135-
Routing.generate('my_route_to_expose_with_defaults', { id: 2, foo: "bar" });
136-
// will result in /blog/2?foo=bar
137-
```
138-
139-
Moreover, you can configure a list of routes to expose in `app/config/config.yml`:
140-
141-
``` yaml
142-
# app/config/config.yml
143-
fos_js_routing:
144-
routes_to_expose: [ route_1, route_2, ... ]
145-
```
146-
147-
These routes will be added to the exposed routes. You can use regular expression patterns
148-
if you don't want to list all your routes name by name.
149-
150-
You can prevent to expose a route by configuring it as below:
151-
152-
```yml
153-
# app/config/routing.yml
154-
my_very_secret_route:
155-
pattern: /admin
156-
defaults: { _controller: HelloBundle:Admin:index }
157-
options:
158-
expose: false
159-
```
160-
161-
### HTTP Caching
162-
163-
You can enable HTTP caching as below:
164-
165-
```
166-
# app/config/config.yml
167-
fos_js_routing:
168-
cache_control:
169-
# All are optional, defaults shown
170-
public: false # can be true (public) or false (private)
171-
maxage: null # integer value, e.g. 300
172-
smaxage: null # integer value, e.g. 300
173-
expires: null # anything that can be fed to "new \DateTime($expires)", e.g. "5 minutes"
174-
vary: [] # string or array, e.g. "Cookie" or [ Cookie, Accept ]
175-
```
176-
177-
### Commands
178-
179-
#### fos:js-routing:dump
180-
181-
This command dumps the route information into a file so that instead of having
182-
the controller generated JavaScript, you can use a normal file. This also allows
183-
to combine the routes with the other JavaScript files in assetic.
184-
185-
$ php app/console fos:js-routing:dump
186-
187-
Instead of the line
188-
189-
<script src="{{ path('fos_js_routing_js', {"callback": "fos.Router.setData"}) }}"></script>
190-
191-
you now include this as
192-
193-
<script src="/js/fos_js_routes.js"></script>
194-
195-
Or inside assetic, do
196-
197-
{% javascripts filter='?yui_js'
198-
'bundles/fosjsrouting/js/router.js'
199-
'js/fos_js_routes.js'
200-
%}
201-
<script src="{{ asset_url }}"></script>
202-
{% endjavascripts %}
203-
204-
**Important:** you should follow the Symfony documentation about generating URLs
205-
in the console: [Configuring The Request Context
206-
Globally](http://symfony.com/doc/current/cookbook/console/sending_emails.html#configuring-the-request-context-globally).
207-
208-
*Hint*: If you are using JMSI18nRoutingBundle, you need to run the command with
209-
the `--locale` parameter once for each locale you use and adjust your include paths
210-
accordingly.
211-
212-
213-
#### fos:js-routing:debug
214-
215-
This command lists all exposed routes:
216-
217-
$ php app/console fos:js-routing:debug [name]
218-
219-
220-
Compiling the JavaScript files
221-
------------------------------
222-
223-
Note: We already provide a compiled version of the JavaScript; this section is only
224-
relevant if you want to make changes to this script.
225-
226-
In order to re-compile the JavaScript source files that we ship with this bundle, you
227-
need the Google Closure Tools. You need the
228-
[**plovr**](http://plovr.com/download.html) tool, it is a Java ARchive, so you
229-
also need a working Java environment. You can re-compile the JavaScript with the
230-
following command:
231-
232-
$ java -jar plovr.jar build Resources/config/plovr/compile.js
233-
234-
Alternatively, you can use the JMSGoogleClosureBundle. If you install this bundle,
235-
you can re-compile the JavaScript with the following command:
236-
237-
$ php app/console plovr:build @FOSJsRoutingBundle/compile.js
238-
239-
240-
Testing
241-
-------
242-
243-
Setup the test suite using [Composer](http://getcomposer.org/):
244-
245-
$ composer install --dev
246-
247-
Run it using PHPUnit:
248-
249-
$ phpunit
250-
251-
### JavaScript Test Suite
252-
253-
You need [PhantomJS](http://phantomjs.org/):
254-
255-
$ phantomjs Resources/js/run_jsunit.js Resources/js/router_test.html

‎Resources/doc/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
FOSJsRoutingBundle
2+
==================
3+
4+
This bundle allows to expose Symfony Routes to JavaScript, so you can generate
5+
relative or absolute URLs in the browser using the same routes as in the backend.
6+
7+
.. toctree::
8+
:maxdepth: 1
9+
10+
installation
11+
usage
12+
compilling
13+
testing

‎Resources/doc/installation.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Installation
2+
============
3+
4+
Step 1: Download the Bundle
5+
---------------------------
6+
7+
Open a command console, enter your project directory and execute the
8+
following command to download the latest stable version of this bundle:
9+
10+
.. code-block:: bash
11+
12+
$ composer require friendsofsymfony/jsrouting-bundle
13+
14+
This command requires you to have Composer installed globally, as explained
15+
in the `installation chapter`_ of the Composer documentation.
16+
17+
Step 2: Enable the Bundle
18+
-------------------------
19+
20+
Then, enable the bundle by adding it to the list of registered bundles
21+
in the ``app/AppKernel.php`` file of your project:
22+
23+
.. code-block:: php
24+
25+
<?php
26+
// app/AppKernel.php
27+
28+
// ...
29+
class AppKernel extends Kernel
30+
{
31+
public function registerBundles()
32+
{
33+
$bundles = array(
34+
// ...
35+
36+
new FOS\JsRoutingBundle\FOSJsRoutingBundle(),
37+
);
38+
39+
// ...
40+
}
41+
42+
// ...
43+
}
44+
45+
Step 3: Register the Routes
46+
---------------------------
47+
48+
Load the bundle's routing definition in the application (usually in the
49+
``app/config/routing.yml`` file):
50+
51+
.. code-block:: yaml
52+
53+
# app/config/routing.yml
54+
fos_js_routing:
55+
resource: "@FOSJsRoutingBundle/Resources/config/routing/routing.xml"
56+
57+
Step 4: Publish the Assets
58+
--------------------------
59+
60+
Execute the following command to publish the assets required by the bundle:
61+
62+
.. code-block:: bash
63+
64+
# Symfony 2
65+
$ php app/console assets:install --symlink web
66+
67+
# Symfony 3
68+
$ php bin/console assets:install --symlink web
69+
70+
.. _`installation chapter`: https://getcomposer.org/doc/00-intro.md

‎Resources/doc/testing.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
Testing
2+
=======
3+
4+
Before running the test suite, execute the following Composer command to install
5+
the dependencies used by the bundle:
6+
7+
.. code-block:: bash
8+
9+
$ composer install --dev
10+
11+
Then, execute the tests executing:
12+
13+
.. code-block:: bash
14+
15+
$ phpunit
16+
17+
JavaScript Test Suite
18+
---------------------
19+
20+
First, install `PhantomJS`_ and then, execute this command:
21+
22+
.. code-block:: bash
23+
24+
$ phantomjs Resources/js/run_jsunit.js Resources/js/router_test.html
25+
26+
.. _`PhantomJS`: http://phantomjs.org/

0 commit comments

Comments
 (0)