Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

simplify route building, respect documents #85

Merged
merged 7 commits into from Nov 12, 2021
Merged

simplify route building, respect documents #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
072a6ff
simplify route building, respect documents
solverat Nov 11, 2021
8f472b6
fix context doc links
solverat Nov 11, 2021
a7ab441
cleanup route parameter builder
solverat Nov 11, 2021
25dc990
remove current site cache, fix proxy context document
solverat Nov 11, 2021
7d182ff
do not boot context for links
solverat Nov 11, 2021
f2a4248
do not fully boot sites in route dispatch
solverat Nov 12, 2021
0ed684b
fix sub zone render decision
solverat Nov 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
@@ -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
Open in desktop
@@ -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