eZ Platform 2.x has evolved a lot - tons of great changes/improvements. But one vital feature is still missing: custom CSS classes and custom attributes. This could prevent a large number of eZ Publish 5.4 sites migrating to the latest eZ Platform version.
That's why we decided to help by submitting a few pull requests. Among them, are:
- EZP-29301: Added support for custom attributes on elements which extends eZ Platform schema and allows for the storage of custom attributes. It was merged in eZ Platform 2.5.1.
- Handled custom attributes when converting XmlText to RichText which allows running migrations from eZ Publish 5.4 to eZ Platform without custom attributes loss. It is going to be merged and released very soon.
So right now is possible to store custom attributes, and it will be possible to migrate them from eZ Publish 5.4 very soon. But there is no way to manage them in eZ Platform. eZ Systems plans to release this feature in upcoming 3.x.
In the meantime, ezplatform-custom-attributes solves this problem. It provides a way to set up custom classes and attributes. And it also brings the new UI to them in the Online Editor:
There is nothing special; you know the drill:
- Require contextualcode/ezplatform-custom-attributes via composer:
- Activate the bundle in app/AppKernel.php:
- Clear the caches:
After the steps above, the installation is complete. You should now see the new "Elements Path" block in the Online Editor. You are able to click on any element in that block; if the clicked element has been defined to be able to have at least one custom class or attribute a new UI will be shown to edit them.
The next step is to configure custom classes and custom attributes.
Custom classes and attributes are set up per each HTML element in the yml configuration file. An example configuration looks like the following:
For custom_classes you just specify an HTML element and the array of its custom CSS classes.
Similarly, for custom_attributes, it is required to define custom attribute settings per each HTML element. There are following options:
- type possible values are: text, textarea, select, checkbox
- default applicable only for text and textarea attributes
- options is used only for select attributes, and it contains an array of possible options
If you are migrating from eZ Publish 5.4 and your content has a lot of custom classes and attributes, it might be very time-consuming to configure all of them. To simplify this task its better to use the ezplatform:generate-custom-attributes-configuration command. This script will generate a configuration based on the content stored in the database. Example usage:
After the custom classes and attributes configuration is done you should see and be able to edit them in the Online Editor. At this point, you might want to make their labels more editor friendly. And it is done via translations.
To set up custom labels start with creating a custom_attributes.<LANGUAGE-CODE>.yaml translation file in your bundle. A good example would be src/AppBundle/Resources/translations/custom_attributes.en.yaml.
Then you need to add the actual labels there. Supported types are:
- Custom class label, its translation message key should follow options.<css-class-name>.label pattern. Examples:
- Options labels (only for select type attributes), its key pattern is options.<option>.label. Examples:
- Custom attribute title, the pattern is attributes.<name>.label. Examples:
Please note, every time after custom attributes translations are changed you need to dump them and run encore:
So now the remaining part would be to handle the custom classes and attributes on the front-end.
There is nothing special about the rendering of custom classes on the front-end. They are set as a class attribute on the corresponding HTML elements.
Custom attributes are rendered as data attributes with an ezattribute- prefix by default. So if for some element max-length is set to 10, on the front-end it will be rendered as data-ezattribute-max-length="10" attribute. It works in most cases, but there are few ways to customize it.
One of the possible ways to implement advanced rendering for custom attributes is to use custom XSL stylesheets. This option is the best for performance, but it requires some extensive knowledge of XSL. Also, you need to be familiar with eZ Platform Rich Text schema. In this case, Rich Text content is modified at the stage when it is transformed from the format it is stored into the database to HTML5. Example implementation:
- Define custom XSL Stylesheet:
- Notify eZ Platform about the custom XSL Stylesheet via ezpublish.system.default.fieldtypes.ezrichtext.output_custom_tags configuration parameter.
Rich Text Converter
Alternatively, you can use Rich Text Converters to implement advanced rendering for custom attributes. In this case, Rich Text content is manipulated in PHP, which makes easier to develop and debug it. Basically you define a new service with a ezpublish.ezrichtext.converter.output.xhtml5 tag, which implements EzSystems\EzPlatformRichText\eZ\RichText\Converter interface. And that's all!
- Create a new Rich Text Converter
- Define it as a service with ezpublish.ezrichtext.converter.output.xhtml5 tag
You can grab a working example of eZ Platform with ezplatform-custom-attributes from https://gitlab.com/contex... . Please check out AppBundle there. It has examples of all possible configurations and customizations in the scope of custom classes and attributes.
There are no reasons why you can't start using ezplatform-custom-attributes right now, and then use the official Custom Attributes feature due to be released in eZ Platform 3.
- First of all, we want to highlight that ezplatform-custom-attributes does not modify the Rich Text schema. This means you don't need to make any changes to your data during your eZ Platform 3 upgrade. And you don't need to run any migration scripts.
- Custom classes and attributes rendering is done by using built-in eZ Platform functionality. So if you implement it now, it should stay the same in eZ Platform 3.
- The only thing that's going to be changed in eZ Platform 3 is the admin UI. An that point you can just disable this bundle and the new UI will be picked up.
- The only part might need to be changed during eZ Platform 3 migrations is custom classes and attributes configurations. That's going to depend on the configuration format for custom classes and Attributes in eZ Platform 3.
So please have a try ezplatform-custom-attributes. We would love to hear your feedback. PRs and comments are very welcome!