Skip to content
Snippets Groups Projects
Commit c27b1ff3 authored by Wolfgang Ziegler's avatar Wolfgang Ziegler
Browse files

Issue #3443424 by fago: Simplify 3.x update documentation.

parent 16f6e5b3
No related branches found
No related tags found
No related merge requests found
Pipeline #507279 passed with warnings
......@@ -139,14 +139,26 @@ rendered in "Automatic processing" mode (using the "Auto" formatter).
## Upgrade from 2.x
Generally, the core module and its API remain unchanged. However, with the
addition of configuration based rendering, the default output of an entity
rendered as custom element changed. Besides that some small API changes /
simplifications have been applied.
## Overview
Please take a list of change records for details:
3.x introduced configuration based rendering based upon Custom Elements Entity
Displays, which is now the primary way render an entity into custom elements.
However, there is the option to enable "Automatic Processing" in the config,
what makes rendering basically work as in 2.x again.
https://www.drupal.org/list-changes/custom_elements
For upgrading, it's a good idea to add custom-elements configuration for your
entity view modes as necessary and to enable "Automatic Processing". Once that
works, it's possible to disable and move to regular formatter-based config any
time.
### Important changes
* Custom Elements Displays with automatic processing enabled don't provide
perfect backward compatibility, check change notices. For example
[the "type" attribute is removed](https://www.drupal.org/node/3474724).
* Any view mode that uses Layout Builder to build custom elements, now
requires a Custom Elements Display that enables this option.
### Submodules
......@@ -156,9 +168,6 @@ https://www.drupal.org/list-changes/custom_elements
Instead, simply enable "force custom elements rendering" for all view
modes as desired. This can be done in the corresponding "Manage display"
tab in the UI.
In terms of configuration: in each applicable
core.entity_view_display.TYPE.BUNDLE.VIEWMODE configuration entity, set
third_party_settings.custom_elements.enabled = true.
* custom_elements_thunder:
Version 2.x implements a couple of example processors for the thunder
......@@ -167,128 +176,13 @@ https://www.drupal.org/list-changes/custom_elements
See [the module's README.md](modules/custom_elements_thunder/README.md)
for further details.
### Updating from 3.0.0-alpha1
Version 3.0.0-alpha1 had a different structure for 'entity_ce_display' config
entities. For converting existing entities saved in this version (in either
configuration files or active storage), update to 3.0.0-alpha2 first, and see
https://www.drupal.org/node/3455435.
### Plan your custom update path
The update introduces breaking changes in the way entities are rendered, and
there is no automatic update path. (The only thing that is done automatically,
is enabling the Custom Elements UI submodule.) Reasons:
* Creating 'version 2 compatible' Custom Elements Displays (i.e. with
automatic processing enabled) for every entity type + bundle may be
detrimental in the longer term, because
* Your Drupal installation will contain a lot of unused configuration.
* Especially when entities are built using the default entity processor in
version 2, this is likely to produce the same output with new version 3
defaults for a Custom Elements Display. These defaults do not need a
display to be pre-created, and also provide more flexibility for future
configuration through the UI than having "automatic processing" enabled.
* Custom Elements Displays with automatic processing enabled still don't provide
perfect backward compatibility, e.g. [the "type" attribute is removed](https://www.drupal.org/node/3474724).
* Any view mode that uses Layout Builder to build custom elements, now
requires a Custom Elements Display that enables this option. However, it is
not easy to automatically detect whether Layout Builder is used: in version 2,
this not only depends on configuration, but also on whether entities are built
by a custom processor (in another module). See below code comments for more
detailed info.
Example code is provided below, that could create Custom Elements Displays with
automatic processing enabled. Please weigh the following options, from 'worst'
to 'best' in terms of future flexibility:
* During the upgrade, create Custom Elements Displays that enable automatic
processing everywhere, per below code.
* Make a list of which exact bundles + view modes you use for rendering custom
elements, and only create Custom Elements Displays with automatic
processing for those.
* Make the same list, and test if your output is the same when using Custom
Elements Displays with default settings (which do not need to be precreated
and saved in active configuration), and/or if you can tweak Custom Elements
Displays slightly to get a desired result.
Regardless of your choice: if you are using Layout Builder then some Custom
Elements Displays will need to be precreated, and some things will need to be
checked. Below code does this / outputs notices.
```php
// Version 3 must be installed already.
//
// FALSE creates only CE displays with "Layout Builder" enabled (which are
// required), and skips creating CE displays with just "automatic processing".
$create_auto_ce_displays = FALSE;
/** @var \Drupal\Core\Entity\EntityDisplayRepositoryInterface $core_display_repo */
$core_display_repo = \Drupal::service('entity_display.repository');
$ce_storage = \Drupal::entityTypeManager()->getStorage('entity_ce_display');
$logger = class_exists('Drush\Drush') ? \Drush\Drush::logger() : \Drupal::logger('custom_elements');
foreach ($ALL_APPROPRIATE_ENTITY_TYPES as $entity_type_id) {
$view_modes = $core_display_repo->getViewModes($entity_type_id);
$bundles = \Drupal::service('entity_type.bundle.info')->getBundleInfo($entity_type_id);
foreach (array_keys($bundles) as $bundle_key) {
$core_display = $core_display_repo->getViewDisplay($entity_type_id, $bundle_key);
$layout_builder_default = $core_display->getThirdPartySetting('layout_builder', 'enabled') && $core_display->status();
// Skip already existing CE displays.
if (!$ce_storage->load("$entity_type_id.$bundle_key.default")) {
// Create CE display; remove default components/fields, to signify
// these are not used. (Unfortunately, at least in v3.0.1 the UI still
// initializes and displays new components when it finds an empty list.)
$ce_display = EntityCeDisplay::create(['mode' => 'default', 'targetEntityType' => $entity_type_id, 'bundle' => $bundle_key]);
foreach (array_keys($ce_display->getComponents()) as $name) {
$ce_display->removeComponent($name);
}
// If Layout Builder is enabled on default Core display, then enable it
// here too; otherwise enable automatic processing.
if ($layout_builder_default) {
$ce_display->setUseLayoutBuilder(TRUE);
// In v2, a non-default view mode would use a Layout,
// * IF it does not have its own (Core) Entity View Display, or if
// its own Entity View Display has Layout Builder enabled,
// * AND IF it is not handled by a custom processor that does not
// extend DefaultContentEntityProcessor.
// It is hard to decide whether it makes more sense
// 1. whether to enable Layout Builder on the default CE display, and
// then also create CE displays with layout builder explicitly
// disabled for any view mode that needs it,
// 2. or to keep Layout Builder disabled on the default CE display,
// and CE displays with layout builder enabled for any view mode
// that needs it,
// ...because it is unknown whether entities are ever built using
// the "default" view mode explicitly. (If so, then only the first
// option is possible.) Leave it up to the user.
$logger->notice("$entity_type_id.$bundle_key has Layout Builder enabled for the 'default' view mode. Please reconsider if you:
1) want building custom elements in any view mode to default to using Layout Builder; in this case, a CE display must be added for any view mode which has its own Core Display (that doesn't use Layout Builder), OR which uses a custom processor (that does not extend DefaultContentEntityProcessor);
2) prefer building custom elements to not default to using Layout Builder; in this case, the \"Use Layout Builder\" option must be disabled on the default CE display and a CE display must be added for any view mode which should use Layout Builder.");
}
$ce_display->setForceAutoProcessing(TRUE);
if ($layout_builder_default || $create_auto_ce_displays) {
$ce_display->save();
}
}
if (!$layout_builder_default) {
// Loop through non-default view modes; see if Layout Builder is enabled.
// Note: if not enabled, the display doesn't necessarily exist in config.
foreach (array_keys($view_modes) as $view_mode_key) {
$core_display = $core_display_repo->getViewDisplay($entity_type_id, $bundle_key, $view_mode_key);
$layout_builder = $core_display->getThirdPartySetting('layout_builder', 'enabled') && $core_display->status();
if ($layout_builder && !$ce_storage->load("$entity_type_id.$bundle_key.$view_mode_key")) {
// Inverse of above: if the view mode is handled by a custom
// processor, then Layout Builder was likely not used in version 2,
// and we are likely fine. If it is handled by
// DefaultContentEntityProcessor or a custom processor that extends
// it, we need a CE display with Layout Builder explicitly enabled.
$logger->notice("$entity_type_id.$bundle_key has Layout Builder enabled for the '$view_mode_key' view mode. If NO custom processor is used, a CE display must still be added, with 'Layout builder' enabled. If a custom processor is using a Layout for building: check https://www.drupal.org/node/3485395.");
}
}
}
}
}
```
### API changes
Generally, the core module and its API remain unchanged. Besides that some small API changes /
simplifications have been applied. Please take a list of change records for details:
https://www.drupal.org/list-changes/custom_elements
## Credits
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment