Migrating dimension config [v9]
Neos 9.x Content
This is content for the upcoming Neos 9.0 release with the rewritten Content Repository based on Event Sourcing.
We heavily work on these docs right now, so expect rough edges.
Dimensions are configured in Settings.yaml, but are also reflected in the content repository - thus in the database.
As a consequence, if you change dimension configuration in Settings.yaml you need to run some migrations to adjust the content repository. On this page, we explain the different cases and how to run them:
- adding a dimension
- e.g. site without dimensions => site with a
language
dimension - e.g. site with one dimension
language
=> site with dimensionslanguage, market
- e.g. site without dimensions => site with a
- adding a dimension value
- e.g. site with
language:en
dimension value => site withlanguage:en,de
dimension values
- e.g. site with
- adding a dimension value as fallback
- e.g. site with
language:de
dimension value => site withlanguage:de,ch
dimension values; wherede
is the fallback ofch
- e.g. site with
- renaming dimensions / dimension values
- removing dimensions / dimension values
#General process
Adjusting dimension configuration of a running site works in two steps:
- Make sure your users do not have unpublished changes
- adjust dimension configuration in Settings.yaml at key
Neos.ContentRepositoryRegistry.contentRepositories.default.contentDimensions
(or analogous for other content repositories) - described on page Content Repository Configuration. - Also adjust the Site Dimension Routing configuration in Settings.yaml at key
Neos.Neos.sites.*.contentDimensions.resolver
- described in the Routing docs. - Adjust the root node dimensions
by running./flow content:refreshRootNodeDimensions
.
The root node must exist in all configured dimensions - and this command updates its dimension configuration. - run database migrations (through CLI commands)
- flush the cache and test to ensure the updated routing configuration is active.
#Adding a dimension
Adjust dimension configuration
In Settings.yaml
you need to add the market
dimension configuration.
Neos:
ContentRepositoryRegistry:
contentRepositories:
default:
contentDimensions:
'language':
label: 'Language'
values:
'en':
label: English
'de':
label: German
# Newly added:
'market':
label: 'Market'
value:
'b2b':
label: B2B
'b2c':
label: B2C
Also adjust the Site Dimension Routing configuration in Settings.yaml at key Neos.Neos.sites.*.contentDimensions.resolver
- described in the Routing docs, to configure how the dimension should be mapped to URLs.
Adjust the root node dimensions
The root node is, by definition, existing in every DimensionSpacePoint. Thus, if you change dimension configuration, the root node(s) need to be updated as well. This happens with the following command:
./flow content:refreshRootNodeDimensions
Running dimension migrations
When switching from no dimensions to 1 dimension; or from 1 dimension to two dimensions, you need to move all existing DimensionSpacePoints, because they need the additional "axis" defined.
Moving needs to be done for all existing DimensionSpacePoints, because a 1-dimensional DimensionSpacePoint is not reachable if you have two dimensions configured.
# Example: No Dimensions => 1 Dimension
# Source: no dimensions
# Target: a "language" dimension, where the already existing content should appear as "en"
./flow content:moveDimensionSpacePoint '{}' '{"language": "en"}'
# Example: 1 Dimension => 2 Dimensions (additional market dimension)
# For every existing dimension value in "language", movw it to the "b2c" market.
./flow content:moveDimensionSpacePoint '{"language": "en"}' '{"language": "en", "market": "b2c"}'
./flow content:moveDimensionSpacePoint '{"language": "de"}' '{"language": "de", "market": "b2c"}'
Finally, flush the cache, to ensure no cached routes or cached rendered pages still exist. Then, test your changes:
./flow flow:cache:flush
#Adding a dimension value
Adjust dimension configuration
In Settings.yaml
you need to add the new value for the existing content dimension.
Neos:
ContentRepositoryRegistry:
contentRepositories:
default:
contentDimensions:
'language':
label: 'Language'
values:
'en':
label: English
'de':
label: German
# Newly added:
'fr':
label: French
Also adjust the Site Dimension Routing configuration in Settings.yaml at key Neos.Neos.sites.*.contentDimensions.resolver
- described in the Routing docs, to configure how the dimension should be mapped to URLs.
Adjust the root node dimensions
The root node is, by definition, existing in every DimensionSpacePoint. Thus, if you change dimension configuration, the root node(s) need to be updated as well. This happens with the following command:
./flow content:refreshRootNodeDimensions
Running dimension migrations
This is not needed for this scenario.
Finally, flush the cache, to ensure no cached routes or cached rendered pages still exist. Then, test your changes:
./flow flow:cache:flush
Optional: Copy content from existing dimension
You can translate - as usual - in the Neos backend, by using the dimension switcher. Sometimes, however, it is useful to pre-populate content from an existing dimension. This can be done via the ./flow content:createVariantsRecursively
command as shown below:
# copy all content from "en" to "fr"
./flow content:createVariantsRecursively '{"language": "en"}' '{"language": "fr"}'
In case you need this, you could also add the dimension value as a fallback. The difference is:
- When not using fallbacks and copying content, the content is disconnected from the original dimension value. If a node in one dimension changes, it does not in the other.
- When using fallbacks (see below), then a change on the base dimension (e.g.
de
) will be automatically visible in the specialized dimension (e.g.ch
), as long as no specific content has been created for the specialization (e.g.ch
).
#Adding a dimension value as fallback
Adjust dimension configuration
In Settings.yaml
you need to add the new value for the existing content dimension, underneath specializations
of the parent dimension value:
Neos:
ContentRepositoryRegistry:
contentRepositories:
default:
contentDimensions:
'language':
label: 'Language'
values:
'en':
label: English
'de':
label: German
# Newly added:
specializations:
'ch':
label: Swiss
Also adjust the Site Dimension Routing configuration in Settings.yaml at key Neos.Neos.sites.*.contentDimensions.resolver
- described in the Routing docs, to configure how the dimension should be mapped to URLs.
Adjust the root node dimensions
The root node is, by definition, existing in every DimensionSpacePoint. Thus, if you change dimension configuration, the root node(s) need to be updated as well. This happens with the following command:
./flow content:refreshRootNodeDimensions
Running dimension migrations
Dimension shine through in the event-sourced content repository is implemented on the write side. This means that dimension fallbacks are resolved when writing changes. While reading, dimension fallbacks do not matter.
This is why you need to migrate the content to add a dimension shine-through; possible through ./flow content:addDimensionShineThrough
.
# add a shine-through from the german to the swiss language (i.e. all german content will be visible in Switzerland,
# until you create specific swiss content)
./flow content:createVariantsRecursively '{"language": "de"}' '{"language": "ch"}'
Finally, flush the cache, to ensure no cached routes or cached rendered pages still exist. Then, test your changes:
./flow flow:cache:flush