.. highlight:: yaml
.. index::
   pair: plugin; bsRoutingPlugin
.. _bsRoutingPlugin:

bsRoutingPlugin
*********************************************

This plugin contains several bs*Route classes.
Final two classes which should be used in `routing.yml` are bsHyperRoute and bsDoctrineHyperRoute.

These two classes extend all following classes and allows usage of all features.
The extension chain is:

#. `sfRequestRoute`
#. :ref:`bsCallbackRoute`
#. :ref:`bsI18nRoute`
#. :ref:`bsDynamicRoute`
#. :ref:`bsStarRoute`
#. :ref:`bsHyperRoute`

Full featured example::

    dictionary_lemma_list:
      url:           /__dictionary/:page_number/*
      class:         bsHyperRoute
      param:         { module: pcDictionaryLemma, action: list, page_number: 1 }
      requirements:  { page_number: '\d+', sf_method: [get, post] }
      options:
        dynamic:
          dictionary: { i18n: { callback: {function: "PageTable::getAllSlugsByPageRoute", params: [dictionary_lemma_list]}}}
        star:
          unknown_param: ignore # allow, ignore
          groups:
            dictionary_lemma_filter:
              dictionary_language_id: { i18n: ~, values_i18n: { callback: {function: "DictionaryLanguageTable::getAllSlugs"} } }
              reverse: { i18n: ~ , type: boolean}
              sort: { i18n: ~, values_i18n: { new: {en: new, cs: nove}, old: {en: old, cs: stare} } }
              dictionary_part_of_speech_id: { i18n: ~ }
              dictionary_categorys_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryCategoryTable::getAllSlugs"} } }
              dictionary_lessons_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryLessonTable::getAllSlugs"} } }
              dictionary_regions_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryRegionTable::getAllSlugs"} } }

This route is parsed and processed only once and everything is cached in `cache/[app]/[env]/config/config_routing.yml.php`.

Routing classes
=============================================

.. index::
   pair: routing; bsPatternRouting

.. _bsPatternRouting:

bsPatternRouting
---------------------------------------------

This class extends `sfPatternRouting` and is used as default routing class in `factories.yml`.

This class adds all parameters from config key `app_routing_global_url_params` to all route classes.
It is used e.g. in :ref:`bsPersistentUrlParamsFilter` to add popup parameters to url in backend in popup mode.


Route classes
=============================================

.. index::
   pair: routing; bsCallbackRoute

.. _bsCallbackRoute:

bsCallbackRoute
---------------------------------------------

This class replaces all `callback` keys in `options` array with values returned by callback function or method.

For example::

          dictionary: { i18n: { callback: {function: "PageTable::getAllSlugsByPageRoute", params: [dictionary_lemma_list]}}}

will use php function `call_user_func_array('PageTable::getAllSlugsByPageRoute', array('dictionary_lemma_list'))` and the result after the callback can be::

          dictionary: { i18n: { cs: slovnik, en: dictionary }}}


.. index::
   pair: routing; bsI18nRoute

.. _bsI18nRoute:

bsI18nRoute
---------------------------------------------

This class deals with 

#. culture detection from `:sf_culture` parameter or from host
#. generating urls for different cultures
#. i18n of strings in url pattern

It uses options::

      i18n:
        detection: host # url or host
        hosts:
          en: [signs.zcu.cz, signs.zcu.czlocal]
          cs: [znaky.zcu.cz, znaky.zcu.czlocal]

to set how the culture detection or url generation for different cultures should be used.
These options must be set for every route (but can be set for all routes globally in :ref:`bsHyperRoute`).

If `detection` is set to `host` then the `:sf_culture` parameter is not included in url and the culture is detected from hosts specified in `hosts` key.

If `detection` is set to `url` then the `:sf_culture` is automatically prepended to url pattern.
Enabled languages can be limited by `enabled_cultures` option.

This class contains protected method `applyI18n` which handles i18n strings in url. This method is used by other route classes.
Translation catalogue for these strings is handled by :ref:`bsQuickTranslation` class which stores translations in `sfConfig` options, e.g.::

    all:
      quick_translation:
        routing:
          dictionary_lemma_filter:
            dictionary_language_id: { cs: jazyk, en: language }
            reverse: { cs: opacne, en: reverse }
            dictionary_categorys_list: { cs: kategorie, en: kategorie }
            dictionary_regions_list: { cs: region, en: region }

`quick_translation` defines section for catalogue used by bsQuickTranslation,
`routing` is a namespace (bsQuickTranslation can be used not only for routing),
and `dictionary_lemma_filter` is a group name.

If the translation is not found in specified namespace then `bsQuickTranslation` tries to find translation in `default` namespace.

This class doesn't translate strings in url directly but provides methods which are used by other route classes.



.. index::
   pair: routing; bsDynamicRoute

.. _bsDynamicRoute:

bsDynamicRoute
---------------------------------------------

This class uses :ref:`bsI18nRoute` to translate "dynamic" url parts prefixed by `__`, e.g.::

      url:           /__dictionary/:page_number/*
      options:
        dynamic:
          dictionary: { i18n: { cs: slovnik, sk: slovnik }}

This segment `__dictionary` in the url pattern will be replaced by a string which is defined in corresponding `dynamic` option in `i18n` section.
If no translation is found then the prefix `__` is removed and `dictionary` is used in url as a default.




.. index::
   pair: routing; bsStarRoute

.. _bsStarRoute:

bsStarRoute
---------------------------------------------

This class handles "star" parameters, e.g.::

    dictionary_lemma_list:
      url:           /__dictionary/:page_number/*
      options:
        star:
          unknown_param: ignore # allow, ignore
          groups:
            dictionary_lemma_filter:
              dictionary_language_id: { i18n: ~, values_i18n: { callback: {function: "DictionaryLanguageTable::getAllSlugs"} } }
              reverse: { i18n: ~ , type: boolean}
              dictionary_part_of_speech_id: { i18n: ~ }
              dictionary_categorys_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryCategoryTable::getAllSlugs"} } }

If `unknown_param` is set to `ignore` then all parameters passed to `url_for()` which are not specified in options are ignored.
If set to `allow` then all parameters which are not specified in options are added to url by symfony without any processing.

The parameters are divided into named groups (here e.g. `dictionary_lemma_filter`).
They have no influence for resulting url.

Star parameters can be of type `boolean` or default one.
Boolean star parameters have no value, they are in url (then the value is `true`) or not (then the value is `false`).
In example see `reverse` parameter.

Other star parameters (non-boolean) consist of key and value (as in symfony).
The keys can be translated (see `i18n` options, which are empty here, but this i18n array will be populated later by default values).
The values can be translated too (see `values_i18n` in example, where translations are populated by a callback).


.. index::
   pair: routing; bsHyperRoute

.. _bsHyperRoute:

bsHyperRoute
---------------------------------------------

This is final class which should be used in `routing.yml`.

It adds only handling of default options, which are specified in `sfConfig` for every app::

  routing:
    default_options_frontend:
      i18n:
        detection: host # url or host
        hosts:
          en: [signs.zcu.cz, signs.zcu.czlocal]
          cs: [znaky.zcu.cz, znaky.zcu.czlocal]
    default_options_backend:
      i18n:
        detection: url # url or host
        enabled_cultures: [cs, en]

These options from `sfConfig` are merged to route options.
Because of this it's not necessary to repeat these "global" options for every route.

This functionality is similar as in :ref:`bsPatternRouting` but there the options are processed just-in-time,
here these options are compiled and cached for every route.