feature #5159 Added an article explaining how to use Bower in Symfony…

… (WouterJ) This PR was merged into the 2.3 branch. Discussion ---------- Added an article explaining how to use Bower in Symfony | Q | A | --- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | - The documentation was only documenting Assetic to manage assets. I feel like the community is moving away from Assetic and is starting to use tools like Bower, Gulp, Grunt, etc. This first article starts at documenting how to work with these tools within your Symfony application. Commits ------- d34b772 Created Bower article
symfony · May 23, 2015 · 9940c65 · 9940c65
2 parents 12ed2e6 + d34b772
commit 9940c65
Show file tree

Hide file tree

Showing 4 changed files with 129 additions and 0 deletions.
diff --git a/cookbook/frontend/bower.rst b/cookbook/frontend/bower.rst
@@ -0,0 +1,117 @@
+.. index::
+    single: Front-end; Bower
+
+Using Bower with Symfony
+========================
+
+Symfony and all its packages are perfectly managed by Composer. Bower is a
+dependency management tool for front-end dependencies, like Bootstrap or
+jQuery. As Symfony is purely a back-end framework, it can't help you much with
+Bower. Fortunately, it is very easy to use!
+
+Installing Bower
+----------------
+
+Bower_ is built on top of `Node.js`_. Make sure you have that installed and
+then run:
+
+.. code-block:: bash
+
+    $ npm install -g bower
+
+After this command succeeded, run ``bower`` in your terminal to find out if
+it's installed correctly.
+
+.. tip::
+
+    If you don't want to have NodeJS on your computer, you can also use
+    BowerPHP_ (an unofficial PHP port of Bower). Beware that this is still in
+    an alpha state. If you're using BowerPHP, use ``bowerphp`` instead of
+    ``bower`` in the examples.
+
+Configuring Bower in your Project
+---------------------------------
+
+Normally, Bower downloads everything into a ``bower_components/`` directory. In
+Symfony, only files in the ``web/`` directory are publicly accessible, so you
+need to configure Bower to download things there instead. To do that, just
+create a ``.bowerrc`` file with a new destination (like ``web/assets/vendor``):
+
+.. code-block:: json
+
+    {
+        "directory": "web/assets/vendor/"
+    }
+
+An Example: Installing Bootstrap
+--------------------------------
+
+Believe it or not, but you're now ready to use Bower in your Symfony
+application. As an example, you'll now install Bootstrap in your project and
+include it in your layout.
+
+Installing the Dependency
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To create a ``bower.json`` file, just run ``bower init``. Now you're ready to
+start adding things to your project. For example, to add Bootstrap_ to your
+``bower.json`` and download it, just run:
+
+.. code-block:: bash
+
+    $ bower install --save bootstrap
+
+This will install Bootstrap and its dependencies in ``web/assets/vendor/`` (or
+whatever directory you configured in ``.bowerrc``).
+
+.. seealso::
+
+    For more details on how to use Bower, check out `Bower documentation`_.
+
+Including the Dependency in your Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that the dependencies are installed, you can include bootstrap in your
+template like normal CSS/JS:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {# app/Resources/views/layout.html.twig #}
+        <!doctype html>
+        <html>
+            <head>
+                {# ... #}
+
+                <link rel="stylesheet"
+                    href="{{ asset('assets/vendor/bootstrap/dist/css/bootstrap.min.css') }}">
+            </head>
+
+            {# ... #}
+        </html>
+
+    .. code-block:: html+php
+
+        <!-- app/Resources/views/layout.html.php -->
+        <!doctype html>
+        <html>
+            <head>
+                {# ... #}
+
+                <link rel="stylesheet" href="<?php echo $view['assets']->getUrl(
+                    'assets/vendor/bootstrap/dist/css/bootstrap.min.css'
+                ) ?>">
+            </head>
+
+            {# ... #}
+        </html>
+
+Great job! Your site is now using Bootstrap. You can now easily upgrade
+bootstrap to the latest version and manage other front-end dependencies too.
+
+.. _Bower: http://bower.io
+.. _`Node.js`: https://nodejs.org
+.. _BowerPHP: http://bowerphp.org/
+.. _`Bower documentation`: http://bower.io/
+.. _Bootstrap: http://getbootstrap.com/
diff --git a/cookbook/frontend/index.rst b/cookbook/frontend/index.rst
@@ -0,0 +1,7 @@
+Front-end
+=========
+
+.. toctree::
+    :maxdepth: 2
+
+    bower
diff --git a/cookbook/index.rst b/cookbook/index.rst
@@ -17,6 +17,7 @@ The Cookbook
     email/index
     event_dispatcher/index
     form/index
+    frontend/index
     logging/index
     profiler/index
     request/index

diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -107,6 +107,10 @@
   * (validation) :doc:`/cookbook/validation/custom_constraint`
   * (doctrine) :doc:`/cookbook/doctrine/file_uploads`
 
+* :doc:`/cookbook/frontend/index`
+
+  * :doc:`/cookbook/frontend/bower`
+
 * :doc:`/cookbook/logging/index`
 
   * :doc:`/cookbook/logging/monolog`