Documented some more options

Author: wouterj

book/templating.rst

@@ -688,6 +688,8 @@ Controllers are fast to execute and promote good code organization and reuse.
 Of course, like all controllers, they should ideally be "skinny", meaning
 that as much code as possible lives in reusable :doc:`services </book/service_container>`.
 
+.. _book-templating-hinclude:
+
 Asynchronous Content with hinclude.js
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

reference/configuration/framework.rst

@@ -27,7 +27,7 @@ Configuration
 * `test`_
 * `default_locale`_
 * `trusted_hosts`_
-* `form`_
+* :ref:`form <reference-framework-form>`_
     * :ref:`enabled <form.enabled>`
 * `csrf_protection`_
     * :ref:`enabled <form.csrf_protection.enabled>`
@@ -50,15 +50,15 @@ Configuration
         * `ip`_
         * :ref:`path <profiler.matcher.path>`
         * `service`_
-* router
-    * resource
-    * type
-    * http_port
-    * https_port
-    * strict_requirements
+* `router`_
+    * `resource`_
+    * `type`_
+    * `http_port`_
+    * `https_port`_
+    * `strict_requirements`_
 * `session`_
-    * storage_id
-    * handler_id
+    * `storage_id`_
+    * `handler_id`_
     * `name`_
     * `cookie_lifetime`_
     * `cookie_path`_
@@ -72,22 +72,22 @@ Configuration
 * `templating`_
     * `assets_version`_
     * `assets_version_format`_
-    * hinclude_default_template
-    * form
-        * resources
+    * `hinclude_default_template`_
+    * :ref:`form <templating.form>`_
+        * `resources`_
     * `assets_base_urls`_
         * http
         * ssl
-    * cache
-    * engines
-    * loaders
+    * :ref:`cache <templating.cache>`
+    * `engines`_
+    * `loaders`_
     * packages
 * `translator`_
     * :ref:`enabled <translator.enabled>`
     * `fallback`_
 * `validation`_
     * enabled
-    * `cache`_
+    * :ref:`cache <validation.cache>`
     * `enable_annotations`_
     * `translation_domain`_
 * annotations
@@ -601,9 +601,85 @@ service
 
 This setting contains the service id of a custom matcher.
 
+router
+~~~~~~
+
+resource
+........
+
+**type**: ``string`` **required**
+
+Specifies the path to the routes used by the default router.
+
+It becomes the service container parameter called ``router.resource``.
+
+type
+....
+
+**type**: ``string``
+
+The type of the resource to hint the loaders about the format. This isn't
+needed when you use the default routers with the expected file extensions
+(``.xml``, ``.yml`` / ``.yaml``, ``.php``).
+
+http_port
+.........
+
+**type**: ``integer`` **default**: ``80``
+
+The port for normal http requests (this is used when matching the scheme).
+
+It becomes the service container parameter called ``router.resource``.
+
+https_port
+..........
+
+**type**: ``integer`` **default**: ``443``
+
+The port for https requests (this is used when matching the scheme).
+
+strict_requirements
+...................
+
+**type**: ``mixed`` **default**: ``true``
+
+Determines the behaviour when a route matches, but the parameters do not match
+the specified requirements for that route. Can be one of:
+
+``true``
+    Throw an exception when the requirements are not met;
+``false``
+    Disable exceptions when the requirements are not met and return ``null``
+    instead;
+``null``
+    Disable checking the requirements (thus, match the route even when the
+    requirements don't match).
+
+``false`` is recommended in the development environment, while ``false`` or
+``null`` might be preferred in production.
+
 session
 ~~~~~~~
 
+storage_id
+..........
+
+**type**: ``string`` **default**: ``'session.storage.native'``
+
+The service id used for session storage. The ``session.storage`` service alias
+will be set to this service id.
+
+handler_id
+..........
+
+**type**: ``string`` **default**: ``'session.handler.native_file'``
+
+The service id used for session storage. The ``session.handler`` service alias
+will be set to this service id.
+
+You can also set it to ``null``, to default to the handler of your PHP
+installation.
+
 name
 ....
 
@@ -655,6 +731,13 @@ This means that the cookie won't be accessible by scripting languages, such
 as JavaScript. This setting can effectively help to reduce identity theft
 through XSS attacks.
 
+gc_divisor
+..........
+
+**type**: ``integer`` **default**: ``100``
+
+See `gc_probability`_.
+
 gc_probability
 ..............
 
@@ -665,13 +748,6 @@ on every session initialization. The probability is calculated by using
 ``gc_probability`` / ``gc_divisor``, e.g. 1/100 means there is a 1% chance
 that the GC process will start on each request.
 
-gc_divisor
-..........
-
-**type**: ``integer`` **default**: ``100``
-
-See `gc_probability`_.
-
 gc_maxlifetime
 ..............
 
@@ -700,7 +776,7 @@ the value to ``null``:
         # app/config/config.yml
         framework:
             session:
-                save_path: null
+                save_path: ~
 
     .. code-block:: xml
 
@@ -745,31 +821,14 @@ For more details, see :doc:`/cookbook/serializer`.
 templating
 ~~~~~~~~~~
 
-assets_base_urls
-................
-
-**default**: ``{ http: [], ssl: [] }``
-
-This option allows you to define base URLs to be used for assets referenced
-from ``http`` and ``ssl`` (``https``) pages. A string value may be provided in
-lieu of a single-element array. If multiple base URLs are provided, Symfony
-will select one from the collection each time it generates an asset's path.
-
-For your convenience, ``assets_base_urls`` can be set directly with a string or
-array of strings, which will be automatically organized into collections of base
-URLs for ``http`` and ``https`` requests. If a URL starts with ``https://`` or
-is `protocol-relative`_ (i.e. starts with `//`) it will be added to both
-collections. URLs starting with ``http://`` will only be added to the
-``http`` collection.
-
 .. _ref-framework-assets-version:
 
 assets_version
 ..............
 
 **type**: ``string``
 
-This option is used to *bust* the cache on assets by globally adding a query
+This option is used to bust the cache on assets by globally adding a query
 parameter to all rendered asset paths (e.g. ``/images/logo.png?v2``). This
 applies only to assets rendered via the Twig ``asset`` function (or PHP equivalent)
 as well as assets rendered with Assetic.
@@ -829,19 +888,22 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
 this feature, you **must** manually increment the ``assets_version`` value
 before each deployment so that the query parameters change.
 
-You can also control how the query string works via the `assets_version_format`_
-option.
+.. tip::
+
+    As with all settings, you can use a parameter as value for the
+    ``assets_version``. This makes it easier to increment the cache on each
+    deployment.
 
 assets_version_format
 .....................
 
 **type**: ``string`` **default**: ``%%s?%%s``
 
-This specifies a :phpfunction:`sprintf` pattern that will be used with the `assets_version`_
-option to construct an asset's path. By default, the pattern adds the asset's
-version as a query string. For example, if ``assets_version_format`` is set to
-``%%s?version=%%s`` and ``assets_version`` is set to ``5``, the asset's path
-would be ``/images/logo.png?version=5``.
+This specifies a :phpfunction:`sprintf` pattern that will be used with the
+`assets_version`_ option to construct an asset's path. By default, the pattern
+adds the asset's version as a query string. For example, if
+``assets_version_format`` is set to ``%%s?version=%%s`` and ``assets_version``
+is set to ``5``, the asset's path would be ``/images/logo.png?version=5``.
 
 .. note::
 
@@ -867,6 +929,119 @@ would be ``/images/logo.png?version=5``.
     The latter option is useful if you would like older asset versions to remain
     accessible at their original URL.
 
+hinclude_default_template
+.........................
+
+**type**: ``string`` **default**: ``null``
+
+Sets the content shown during the loading of the fragment or when JavaScript is
+disabled. This can be either a template name or the content itself. It becomes
+the service container parameter named ``fragment.renderer.hinclude.global_template``.
+
+.. seealso::
+
+    See :ref:`book-templating-hinclude` for more information about hinclude.
+
+.. _templating.form:
+
+form
+....
+
+resources
+"""""""""
+
+**type**: ``string[]`` **default**: ``[FrameworkBundle:Form]``
+
+A list of all resources for form theming in PHP. If you have custom global form
+themes in ``src/WebsiteBundle/Resources/views/Form``, you can configure this like:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        framework:
+            templating:
+                form:
+                    resources:
+                        - 'WebsiteBundle:Form'
+
+    .. code-block:: xml
+
+        <framework:config>
+            <framework:templating>
+                <framework:form>
+                    <framework:resource>WebsiteBundle:Form</framework:resource>
+                </framework:form>
+            </framework:templating>
+        </framework:config>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('framework', array(
+            'templating' => array(
+                'form' => array(
+                    'resources' => array(
+                        'WebsiteBundle:Form'
+                    ),
+                ),
+            ),
+        ));
+
+.. note::
+
+    The default form templates from ``FrameworkBundle:Form`` will always be
+    included in the form resources.
+
+assets_base_urls
+................
+
+**type**: ``{ http: [], ssl: [] }``
+
+This option allows you to define base URLs to be used for assets referenced
+from ``http`` and ``ssl`` (``https``) pages. A string value may be provided in
+lieu of a single-element array. If multiple base URLs are provided, Symfony2
+will select one from the collection each time it generates an asset's path.
+
+For your convenience, ``assets_base_urls`` can be set directly with a string or
+array of strings, which will be automatically organized into collections of base
+URLs for ``http`` and ``https`` requests. If a URL starts with ``https://`` or
+is `protocol-relative`_ (i.e. starts with ``//``), it will be added to both
+collections. URLs starting with ``http://`` will only be added to the
+``http`` collection.
+
+.. _templating.cache:
+
+cache
+.....
+
+**type**: ``string``
+
+The path to the cache directory for templates. When this is not set, caching is
+disabled. It becomes the service container parameter named
+``templating.loader.cache.path``.
+
+engines
+.......
+
+**type**: ``string[]`` / ``string`` **required**
+
+The Templating Engine to use. This can either be a string (when only one engine
+is configured) or an array of engines. It becomes the service container
+parameter named ``templating.engines``.
+
+At least one engine is required.
+
+loaders
+.......
+
+**type**: ``string[]``
+
+An array (or a string when configuring just one loader) of service ids for
+templating loaders.
+
+packages
+........
+
 translator
 ~~~~~~~~~~
 
@@ -891,6 +1066,8 @@ For more details, see :doc:`/book/translation`.
 validation
 ~~~~~~~~~~
 
+.. _validation.cache:
+
 cache
 .....
 
@@ -916,6 +1093,7 @@ translation_domain
 
 The translation domain that is used when translating validation constraint
 error messages.
+
 .. _`protocol-relative`: http://tools.ietf.org/html/rfc3986#section-4.2
 .. _`PhpStormOpener`: https://github.com/pinepain/PhpStormOpener
 .. _`egulias/email-validator`: https://github.com/egulias/EmailValidator