Permalink
Browse files

Added / Updated Documentation

  • Loading branch information...
1 parent 9f4a2de commit a4f2a702616375876004783681775d219b8953c9 @lunetics committed Oct 25, 2012
Showing with 139 additions and 20 deletions.
  1. +2 −1 README.md
  2. +9 −2 Resources/doc/guesser.md
  3. +23 −17 Resources/doc/index.markdown
  4. +105 −0 Resources/doc/switcher.md
View
@@ -9,13 +9,14 @@ This bundle allows you to guess the Locale from different parameters in your Sym
The locale can be guessed from different parameters in your applications :
+* In the `Query` parameter
* In the `Route` parameters
* In the `Browser` preferences
* In a `Cookie` or the `Session` if the locale has already been identified
## Documentation
-[Read the Documentation for master](LocaleBundle/blob/master/Resources/doc/index.markdown)
+[Read the Documentation for master](https://github.com/lunetics/LocaleBundle/blob/master/Resources/doc/index.markdown)
[Read the Documentation for 2.1](https://github.com/lunetics/LocaleBundle/blob/2.1/Resources/doc/index.markdown)
View
@@ -4,7 +4,7 @@ If you want to implement your own locale guesser, you need the following steps:
1. Define the guesser class in the config
-----------------------------------------
-Add the following configuration to `app/config/config.yml`:
+Add the following configuration to `app/config/guesser.yml`:
``` yaml
lunetics_locale:
@@ -15,8 +15,12 @@ lunetics_locale:
2. Add the guesser as service
------------------
It is important that you add exactly this tag name.
+
+Also be sure to inject the metavalidator, which checks if the locale is valid and allowed by configuration.
+
``` xml
<service id="lunetics_locale.acme_guesser" class="%lunetics_locale.acme_guesser.class%">
+ <argument type="service" id="lunetics_locale.validator.meta" />
<tag name="lunetics_locale.guesser" alias="acme" />
</service>
```
@@ -35,15 +39,18 @@ namespace Acme\AcmeBundle\LocaleGuesser;
use Symfony\Component\HttpFoundation\Request;
use Lunetics\LocaleBundle\LocaleGuesser\LocaleGuesserInterface;
+use Lunetics\LocaleBundle\Validator\MetaValidator
class AcmeLocaleGuesser implements LocaleGuesserInterface
{
private $identifiedLocale;
+ private $metaValidator;
+
public function guessLocale(Request $request)
{
// Code to identify the locale, if found:
- if($foundLocale) {
+ if($this->metaValidator->isAllowed($foundLocale) {
$this->identifiedLocale = $foundLocale;
return $this->identifiedLocale;
}
@@ -4,7 +4,7 @@
``` yaml
"require": {
- "lunetics/locale-bundle": "2.1.x-dev",
+ "lunetics/locale-bundle": "dev-master",
....
},
```
@@ -46,9 +46,10 @@ lunetics_locale:
lunetics_locale:
strict_mode: true # defaults to false
```
-You can set a **'strict_mode'**, where only EXACTLY! the allowed locales will be tested. For example:
-* If your user has a browser locale with `de_DE` and `de`, the locale `de` will be chosen!
-* If your user has a browser locale with `de` and you only explicit allow `de_DE`, no locale will be detected!
+You can enable `strict_mode`, where only the **exact** allowed locales will be matched. For example:
+
+* If your user has a browser locale with `de_DE` and `de`, and you only explicitly allow `de`, the locale `de` will be chosen.
+* If your user has a browser locale with `de` and you only explicitly allow `de_DE`, no locale will be detected.
We encourage you to use the non-strict mode, that'll also choose the best region locale for your user.
@@ -61,12 +62,25 @@ lunetics_locale:
guessing_order:
- session
- cookie
- - router
- browser
+ - query
+ - router
```
With the example above, the guessers will be called in the order you defined as 1. session 2. cookie 2. router 3. browser.
-Note that the session and cookie guessers only retrieve previously identified and saved locales by the router or browser guesser
+Note that the session and cookie guessers only retrieve previously identified and saved locales by the router or browser guesser.
+
+If you use the _locale parameter as attribute/parameter in your routes, you should use the query and router guesser first.
+
+``` yaml
+lunetics_locale:
+ guessing_order:
+ - query
+ - router
+ - session
+ - cookie
+ - browser
+```
### Locale Cookies / Session
@@ -86,13 +100,13 @@ This is most useful for unregistered and returning visitors.
#### Session
-The session guesser will automatically save a previously identified locale into the session and retrieve it from the session. It should be best on the first place on the guessing_order.
+The session guesser will automatically save a previously identified locale into the session and retrieve it from the session. This guesser should always be first in your `guessing_order` configuration if you don't use the router guesser.
### Custom Guessers
Read more about creating your own guesser here:
-[Custom Locale Guesser](guesser.md)
+[Read the full documentation for creating a custom Locale Guesser](guesser.md)
### Switch to another locale
@@ -102,12 +116,4 @@ You can render a default locale switcher, simply by calling the twig function in
{{ locale_switcher() }}
```
-#### Using your own template
-
-You can define your own template in the configuration :
-
-``` yaml
-lunetics_locale:
- switcher:
- template: AcmeDemoBundle:MyBundle:mytemplate.html.twig
-```
+[Read the full documentation for the switcher](switcher.md)
View
@@ -0,0 +1,105 @@
+Locale Switcher
+==============
+The locale switcher gives you different options for your twig template to change the locale.
+
+1. Use the switcher in a Twig Template
+-----------------------------------------
+Add the following twig method to your template:
+``` html
+{{ locale_switcher() }}
+```
+This will give you a basic switcher.
+
+2. Configuration Options
+------------------------
+It's possible to change the behaviour and the template of the switcher.
+
+### 2.1 Use another template
+
+There are two ways to override the default template:
+
+#### By bundle inheritance
+To override the default template, create a template in your own src directory at the following location: `src/Lunetics/LocaleBundle/Resources/views/Switcher/switcher_links.html.twig`
+
+#### By configuration
+Define your own template in the configuration :
+``` yaml
+lunetics_locale:
+ switcher:
+ template: AcmeDemoBundle:MyBundle:mytemplate.html.twig
+```
+
+### 2.1 Show current locale
+You can set if the current locale should be shown in the template. Defaults to false.
+``` yaml
+lunetics_locale:
+ switcher:
+ show_current_locale: false
+```
+
+3. Define the actor
+-------------------
+There are 3 actors to change the locale. **newLocale** stands for the generated link locale, e.g. **de** or **en**, based on your configuration.
+
+* **default actor:** Change locale via _locale Request attribute (?_locale=newLocale OR /newLocale/about)
+* **controller actor:** Change locale via controller and redirect (/changeLocale/newLocale)
+* **route actor:** Define route in the method locale_switcher (generates custom route)
+
+### 3.1 Default actor
+
+By default, the `TargetInformationBuilder` generates the switcher links to the same route by using the _locale attribute.
+
+If your route has the following config:
+
+``` yaml
+my_route:
+ pattern: /{_locale}/about
+ defaults:
+ _controller: my_controller:myAction
+ _locale: %locale%
+```
+
+Then the switcher will generate links to all your allowed locales. If you have enabled **de** and **en**, it would generate links to:
+* /de/about
+* /en/about
+
+If your route doesn't use a _locale parameter, it will use a query parameter (default symfony behaviour):
+* /about?_locale=de
+* /about?_locale=en
+
+You should use the query guesser and/or route guesser to set the locale.
+If you also use the session guesser or cookie guesser, the locale will be saved in the session / cookie.
+
+### 3.2 Controller actor
+
+You should use the controller actor if you don't use the _locale attribute and want to rely on sessions / cookies only.
+
+The controller actor redirects to the `/changeLocale/**newLocale**` url, sets the new locale into the session / cookie and :
+* redirects back to the origin if the `use_referrer` config var is set to **true**
+* redirect to the route given in the `redirect_to_route` config var
+
+**You MUST set the `redirect_to_route` config var, which will used if you don't want to use the referrer. It's also used as fallback if no referrer could be identified**
+
+These are the current options for the **Controller** actor:
+``` yaml
+lunetics_locale:
+ switcher:
+ use_controller: true # Must be set to true if you want to use the controller. Defaults to false
+ use_referrer: true # Redirect to the origin url from where the switcher was used. Defaults to true
+ redirect_to_route: fallback_route # This parameter MUST be set. Fallback route if no referrer could be found.
+ redirect_statuscode: 302 # Redirect HTTP status code. Options: 300, 301, 302, 303, 307. Defaults to 302
+```
+
+### 3.3 Route actor
+You can override the default / controller actor, if you give a route to the twig switcher method, for example:
+
+``` html
+{{ locale_switcher('my_route') }}
+```
+
+The route actor will then generate the routes to your custom route with the _locale parameter, this can be either the locale in the url or as query parameter **(see default actor)**
+
+It's also possible to add additional parameters/attributes that can be used for route generation:
+ ``` html
+{{ locale_switcher('my_route', {'parameter1':'value1'}) }}
+```

0 comments on commit a4f2a70

Please sign in to comment.