Skip to content

Commit

Permalink
simplify route building, respect documents (#85)
Browse files Browse the repository at this point in the history 
* simplify route building, respect documents
* fix context doc links
* cleanup route parameter builder
* remove current site cache, fix proxy context document
* do not boot context for links
* do not fully boot sites in route dispatch
* fix sub zone render decision
  • Loading branch information
@solverat
solverat committed Nov 12, 2021
1 parent 146ac26 commit e53a50e
Show file tree
Hide file tree
Showing 30 changed files with 1,153 additions and 687 deletions.
12 changes: 7 additions & 5 deletions README.md
View file
Expand Up @@ -8,7 +8,7 @@
![i18n](https://user-images.githubusercontent.com/700119/27761666-f3ed6746-5e60-11e7-955a-3030453c68ff.jpg)

## Scheme
![i18n scheme](https://user-images.githubusercontent.com/700119/140646548-fcf6433d-1fa0-4323-98e2-9cc49550e5ee.png)
![i18n scheme](https://user-images.githubusercontent.com/700119/141124503-59576527-e5b1-47b3-a38e-d06e51555bde.png)

## Introduction
Pimcore already comes with some great features to build internationalized websites.
Expand Down Expand Up @@ -58,15 +58,17 @@ When using this bundle, you should:
- If you're using the country detection, you need a valid maxmind geo ip [data provider](docs/10_GeoControl.md)

## Further Information
- [I18n Overview Page](./docs/1_I18n.md): Learn all about the i18n principals.
- [Geo IP/Control](docs/10_GeoControl.md): Enable GeoIP Data Provider.
- [Zone Definitions](docs/20_Zones.md): Learn more about i18n zone definitions and how to manage them.
- [Custom I18n Context Look-Up](docs/21_CustomI18nContextLookUp.md)] (🔥 New!)
- [Custom I18n Context Look-Up](docs/21_I18nContext.md)] (🔥 New!)
- [Href-Lang](docs/25_HrefLang.md): Find out more about the href-lang tag generator.
- [Language Configuration](docs/26_Languages.md): Configure languages.
- [Country Configuration](docs/27_Countries.md): Configure countries.
- Dynamic Routing
- [Static Routes](docs/28_StaticRoutes.md): Configure translatable static routes and implement href-lang tags.
- [Symfony Route](docs/29_SymfonyRoutes.md): Configure translatable symfony routes and implement href-lang tags.
- Route and Alternate Links Generation
- [Document Routes](docs/90_DocumentRoutes.md): Build document routes
- [Static Routes](docs/91_StaticRoutes.md): Build translatable static routes and implement href-lang tags.
- [Symfony Route](docs/92_SymfonyRoutes.md): Build translatable symfony routes and implement href-lang tags.
- [Front Page Mapping](docs/30_FrontPageMapping.md): Learn how to map a custom front page.
- [Localized Error Documents](docs/40_LocaleErrorDocument.md): Learn how to create localized error documents.
- [Custom Locale Adapter](docs/50_CustomLocaleAdapter.md): Learn how to create a custom locale adapter.
Expand Down
5 changes: 3 additions & 2 deletions UPGRADE.md
View file
Expand Up @@ -34,7 +34,8 @@ i18n:
### Global Changes
- `$staticRoute->assemble()` is **not** supported anymore, you always need to call `$router->generate()`:
- Every PIMCORE LinkGenerator needs to implement the `I18nLinkGeneratorInterface`
- You need to pass the `_18n => [ type = RouteItemInterface::TYPE, routeParameters => [] ]` block via `$router->generate()`
- You need to pass the `_18n => [ type = RouteItemInterface::TYPE, routeParameters => [] ]` block via `$router->generate()` (Or use `RouteParameterBuilder` for parameter building)
- `url()`, `path()`, `pimcore_url()` twig helper are not supported, use `i18n_entity_route()`, `i18n_static_route()` and `i18n_symfony_route()` instead
- Context Adapter and Manager have been removed (All corresponding information are available via `I18nContextInterface` directly)
- PHP8 return type declarations added: you may have to adjust your extensions accordingly
- `LocaleProviderInterface` changes:
Expand Down Expand Up @@ -79,7 +80,7 @@ i18n:

### Additional new Features
- Check Akamai CDN header [@florian25686](https://github.com/dachcom-digital/pimcore-i18n/pull/76/files)
- Allow different I18nContext look-ups [#70](https://github.com/dachcom-digital/pimcore-i18n/issues/70), read more about it [here](./docs/21_CustomI18nContextLookUp.md)
- Allow different I18nContext look-ups [#70](https://github.com/dachcom-digital/pimcore-i18n/issues/70), read more about it [here](./docs/21_I18nContext.md)
- Allow symfony routes [#65](https://github.com/dachcom-digital/pimcore-i18n/issues/65)

***
Expand Down
136 changes: 21 additions & 115 deletions docs/1_I18n.md
View file
@@ -1,5 +1,5 @@
# I18n Workflow
![i18n scheme](https://user-images.githubusercontent.com/700119/140646548-fcf6433d-1fa0-4323-98e2-9cc49550e5ee.png)
![i18n scheme](https://user-images.githubusercontent.com/700119/141124503-59576527-e5b1-47b3-a38e-d06e51555bde.png)

## I18n Context
I18n will generate a `I18nContextInterface` object at **every request** which is accessible via the resolver
Expand Down Expand Up @@ -136,126 +136,32 @@ my_symfony_route:
matching_route_key: '(%i18n.route.translations.mySymfonyRouteKey%)' ## returns (meine-symfony-route|my-symfony-route)
```

## Command Line
Generating absolute URLs in CL is easy! Let's create a static route (which will dispatch your LinkGenerator):
## Twig|PHP Route Generation
- [Current Request Routes for Documents](./90_DocumentRoutes.md#generating-routes-in-current-request)
- [Current Request Routes for Static Routes](./91_StaticRoutes.md#generating-routes-in-current-request)
- [Current Request Routes for Symfony Routes](./92_SymfonyRoutes.md#generating-routes-in-current-request)

```php
$routeParameters = [
'_i18n' => [
'type' => RouteItemInterface::STATIC_ROUTE,
'entity' => $object,
'routeParameters' => [
'_locale' => 'en'
],
'context' => [
## if you're having sites, you need to define zones
## if you're having zones, you MUST pass the site context parameter
## that's the rule!
'site' => Site::getByDomain('test-domain1.test')
]
]
];

echo $this->router->generate('', $routeParameters, UrlGeneratorInterface::ABSOLUTE_URL);
```

## Twig Helper
Generating a complete headless context object via twig:

```twig
{# SECTION A: simple i18n route generation #}
{# simple url() #}
{{ url('my_symfony_route', {_i18n: { type: 'symfony', routeParameters: {_locale: 'de'}, context: { site: pimcore_site_by_domain('test-domain1.test') }}}) }}
{# simple path() without configured zones #}
{{ path('my_symfony_route', {_i18n: { type: 'symfony', routeParameters: {_locale: 'de'} }}) }}
{# SECTION B: complete i18n context generation #}
{% set object_context = i18n_create_context_by_symfony_route('my_symfony_route', {_locale: 'en'}) %}
{{ dump(object_context) }}
{{ dump(object_context.linkedLanguages) }}
{#
if you're having sites, you need to define zones
if you're having zones, you MUST pass the site context parameter
that's the rule!
#}
{% set route_site = pimcore_site_by_domain('test-domain1.test') %}
{% set zone_aware_object_context = i18n_create_context_by_symfony_route('my_symfony_route', {_locale: 'en'}, route_site) %}
{{ dump(zone_aware_object_context) }}
{{ dump(zone_aware_object_context.linkedLanguages) }}
```
## Command Line Route Generation
Generating absolute URLs in CLI is easy!
- [CLI Routes for Documents](./90_DocumentRoutes.md#generating-routes-in-cli)
- [CLI Routes for Static Routes](./91_StaticRoutes.md#generating-routes-in-cli)
- [CLI Routes for Symfony Routes](./92_SymfonyRoutes.md#generating-routes-in-cli)

## PHP Helper
Generating a complete headless context object via php api. Let's dump some examples:
## Non-I18n Routes
I18n always requires the `_i18n` parameter node in `urlGenerator->generate`.
If this node is not present, the default route generation will be triggered.

```php
dump($router->generate('my_non_i18n_aware_symfony_route', ['_locale' => 'en'], UrlGeneratorInterface::ABSOLUTE_URL));
```

// SECTION A: complete i18n context generation

// $i18nContextManager = [DI] I18nBundle\Manager\I18nContextManager
$routeItemParameters = [
'type' => RouteItemInterface::SYMFONY_ROUTE,
'routeParameters' => [
'_locale' => 'de'
// ... and all your special route params which i18n are not aware off
],
'routeName' => 'my_static_route',
'context' => [
'site' => Site::getByDomain('test-domain1.test')
]
];

// if you want to use the `$i18nContext.getLinkedLanguages()`
// you need to pass the second boolean argument as true to boot the path generator adapter
// this is disabled by default because it is not required when generating default routes
$i18nContext = $i18nContextManager->buildContextByParameters($routeItemParameters, true);

// SECTION B: simple i18n route generation

// $router = [DI] Symfony\Component\Routing\RouterInterface
dump('static route (without entity) and site:' . $router->generate('my_static_route', [
'_i18n' => [
'type' => RouteItemInterface::STATIC_ROUTE,
'routeName' => 'my_static_route'
'routeParameters' => [
'_locale' => 'de'
// ... and all your special route params which i18n are not aware off
],
'context' => [
## if you're having sites, you need to define zones
## if you're having zones, you MUST pass the site context parameter
## that's the rule!
'site' => Site::getByDomain('test-domain1.test')
]
]
], UrlGeneratorInterface::ABSOLUTE_URL));

dump('static route (with entity): ' . $router->generate('', [
'_i18n' => [
'type' => RouteItemInterface::STATIC_ROUTE,
'entity' => $object,
'routeParameters' => [
'_locale' => 'de'
// ... and all your special route params which i18n are not aware off
]
]
], UrlGeneratorInterface::ABSOLUTE_URL));

dump('symfony route: ' . $router->generate('my_symfony_route', [
'_i18n' => [
'type' => RouteItemInterface::SYMFONY_ROUTE,
'routeParameters' => [
'_locale' => 'de'
// ... and all your special route params which i18n are not aware off
]
]
], UrlGeneratorInterface::ABSOLUTE_URL));
## Context
I18n allows you to easily fetch the current context via a given request object.
Read more about it [here](21_I18nContext.md#current-context).

dump('non i18n symfony route: ' . $router->generate('my_non_i18n_aware_symfony_route', ['_locale' => 'en'], UrlGeneratorInterface::ABSOLUTE_URL));
```
## Custom Context Boot
Generating a complete headless context object via twig or php api.
Read more about it [here](21_I18nContext.md#custom-context-look-up).

## Code Examples
Please check out the [code examples](./60_CodeExamples.md) doc section to learn more about accessing zone information.
71 changes: 58 additions & 13 deletions docs/21_CustomI18nContextLookUp.md → docs/21_I18nContext.md
View file
@@ -1,39 +1,82 @@
# Current Context

Fetch the current context to list linked languages for example:

```twig
<h5>i18n Current Context</h5>
{% set i18n_current_context = i18n_current_context() %}
{{ dump(i18n_current_context) }}
{{ dump(i18n_current_context.linkedLanguages) }}
<ul>
{% for link in i18n_current_context.linkedLanguages %}
<li>{{ link.url }}</li>
{% endfor %}
</ul>
```

**PHP**

```php
<?php

use Symfony\Component\HttpFoundation\RequestStack;
use I18nBundle\Http\I18nContextResolverInterface;

class Service
{
public function myAction(RequestStack $requestStack, I18nContextResolverInterface $i18nContextResolver)
{
$i18nContext = $i18nContextResolver->getContext($requestStack->getMainRequest());
$linkedLanguages = $i18nContext->getLinkedLanguages();
}
}
```

# Custom Context Look-Up
In some cases, you want to retrieve all available links for a specific document or object (Generating links via commandline for example).

In some cases, you want to retrieve all available links for a specific document or object.

## Boot Context in TWIG

```twig
<h4>I18n Context Look-Up (document)</h4>
{% set document_context = i18n_create_context_by_entity(pimcore_document(16), { _locale: 'en' }) %}
{{ dump(document_context) }}
{{ dump(document_context.linkedLanguages) }}
<hr>
<h4>I18n Context Look-Up (object [will call correspondig link generator])</h4>
{% set object_context = i18n_create_context_by_entity(pimcore_object(16), { _locale: 'en' }) %}
{{ dump(object_context) }}
{{ dump(object_context.linkedLanguages) }}
<hr>
<h4>I18n Context Look-Up (symfony route)</h4>
{% set object_context = i18n_create_context_by_symfony_route('my_symfony_route, { _locale: 'en' } }) %}
{{ dump(object_context) }}
{{ dump(object_context.linkedLanguages) }}
<hr>
<h4>I18n Context Look-Up (static route)</h4>
{% set object_context = i18n_create_context_by_static_route('my_static_route', { _locale: 'fr', object_id: 16 } }) %}
{{ dump(object_context) }}
{{ dump(object_context.linkedLanguages) }}
## If you're using zones, you NEED to pass the site as context!
{# If you're using zones, you NEED to pass the site as context! #}
<h4>I18n Context Look-Up with Zones (document)</h4>
{% set zone_aware_document_context = i18n_create_context_by_entity(pimcore_document(16), { _locale: 'en' }, pimcore_site_by_domain('my-site.test')) %}
{{ dump(zone_aware_document_context) }}
{{ dump(zone_aware_document_context.linkedLanguages) }}
```

## Boot Context in PHP

```php
<?php

use I18nBundle\Manager\I18nContextManager;
use I18nBundle\Model\RouteItem\RouteItemInterface;

class ExampleService
{
Expand All @@ -44,26 +87,28 @@ class ExampleService
$this->i18nContextManager = $i18nContextManager;
}

public function build(Pimcore\Document $document, array $routeParameter)
public function build(Pimcore\DataObject $object, array $routeParameter)
{
## I. no zones defined
$parameters = [
'routeParameters' => $routeParameter,
'entity' => $document
'entity' => $object
];

$i18nContext = $this->i18nContextManager->buildContextByParameters($parameters, true);

## If you're using zones, you NEED to pass the site as context!
// third argument needs to be true to fully boot context (initialize linked zone sites)
$i18nContext = $this->i18nContextManager->buildContextByParameters(RouteItemInterface::STATIC_ROUTE, $parameters, true);

$zoneAwareParameters = [
## II. zones available
## You MUST pass the site as context!
$zoneAwareParameters = [
'routeParameters' => $routeParameter,
'entity' => $document,
'entity' => $object,
'context' => [
'site' => $site
]
];

$zoneAwareI18nContext = $this->i18nContextManager->buildContextByParameters($zoneAwareParameters, true);
$zoneAwareI18nContext = $this->i18nContextManager->buildContextByParameters(RouteItemInterface::STATIC_ROUTE, $zoneAwareParameters, true);

dump($zoneAwareI18nContext);
}
Expand Down

0 comments on commit e53a50e

Please sign in to comment.