eZ Platform v2 is out and the UI has been fully redeveloped using Symfony as well as libraries such as React. You'll learn to quickly and simply extend eZ Platform's UI to fit your needs and add your own features to the platform. This session will go through the major extension points in the application and how to integrate your code—be it Twig-based classic web pages or with more modern and more interactive React.js code. We’ll also explain what had changed in the technology stack of eZ Platform 2.x and why.

1. Extending eZ Platform 2.x with Symfony and React
With the eZ Platform 2.x development case

2. Who are we?
Piotr Nalepa
Senior UI Developer @ eZ Systems
@sunpietro
Maciej Kobus
PHP Developer @ eZ Systems

3. The Past
The technology decisions, regarding eZ Platform 1.x
were made at some point between 2013 and 2014

4. Technology stack in eZ Platform 1.x
• PHP 5.6,
• Symfony 2.x,
• YUI3,
• No CSS pre-processors,

5. Developing features in eZ Platform 1.x
• Difficult,
• Slow,
• Lack of programmers resources

6. The biggest problem
Infamous YUI3

7. The goals for eZ Platform 2.x

8. Make editors/developers happy again
• Increase app performance,
• Eliminate the loading spinner headache,
• Make it easy to extend

9. Seeking a right solution

10. The sources of inspirations
• Community,
• Meetups,
• Conferences,
• Our own experience

11. AdminUI backend technology stack
• PHP 7.1,
• PHP Symfony framework 3.x,
• Twig templates,
• Symfony Forms,
• KNP Menu Bundle,
• Translations Bundle

12. AdminUI frontend technology stack
• JavaScript ES6+,
• ReactJS 16.x,
• Bootstrap 4.x,
• SASS,
• Webpack,
• AlloyEditor

13. On the frontend side

14. Why ReactJS?
• Mechanism of quick UI updates,
• Easy way to manage state and data flow,
• Easy to implement event handlers,
• Paradigm of splitting code into smaller components,
• No need to use any extra templating engines, like Handlebars,
• Easy to combine with any other JS library or framework (if needed).

15. Why not Web Components?
• Difficult to extend existing Web Components when ShadowDOM is on,
• Custom Elements are just another way of writing divs with CSS classes,
• Not many good practices for Web Components development,
• Slow to develop new features.

16. Should you avoid using Web Components?
No!

17. Browsers support in theAdminUI
The latest version of the following browsers:
• Mozilla Firefox,
• Google Chrome,
• Microsoft Edge,
• Safari,
• Opera

18. Why only the latest versions of browsers?
• Latest JS features,
• Latest CSS features,
• HTML5 APIs

19. What about mobile devices?
The base Admin UI is mobile adapted.
The Page Builder component is a desktop-first application,
might be adapted later when needed.

20. Extensible UI parts

21. What can you extend in theAdminUI?
Everything in AdminUI can be extended:
• with PHP code (in most cases),
• with JavaScript/ReactJS (in some cases).

22. Extension points for frontend developers

23. ReactJS modules
• Universal Discovery (the only one loaded everywhere),
• Sub-Items List,
• Multi-File Upload

24. Injecting stylesheets and scripts
JS, CSS and Twig files can be injected
by using YAML config and tags

25. UI Component classes on backend
EzSystemsEzPlatformAdminUiComponentTwigComponent
EzSystemsEzPlatformAdminUiComponentScriptComponent
EzSystemsEzPlatformAdminUiComponentLinkComponent

26. Sample tag usage
tags:
- { name: ezplatform.admin_ui.component, group: 'script-head' }

27. Injection points
• stylesheet-head
• script-head
• custom-admin-ui-modules
• custom-admin-ui-config
• stylesheet-body
• script-body
• content-edit-form-before
• content-edit-form-after
• content-create-form-before
• content-create-form-after
• dashboard-blocks

28. Extending Universal Discovery
(function (global, eZ) {
eZ = eZ || {};
eZ.adminUiConfig = eZ.adminUiConfig || {};
eZ.adminUiConfig.universalDiscoveryWidget =
eZ.adminUiConfig.universalDiscoveryWidget || {};
eZ.adminUiConfig.universalDiscoveryWidget.extraTabs =
eZ.adminUiConfig.universalDiscoveryWidget.extraTabs || [];
eZ.adminUiConfig.universalDiscoveryWidget.extraTabs.push({
id: 'tab-identifier',
title: 'tab-title',
iconIdentifier: 'tab-icon-identifier',
panel: CustomTabContentPanel,
attrs: {}
});
})(window, window.eZ);

29. Universal Discovery – result of extension

30. Extending Sub-Items List
ReactDOM.render(React.createElement(eZ.modules.SubItems, {
handleEditItem,
generateLink,
parentLocationId: container.dataset.location,
sortClauses: {[sortField]: sortOrder},
restInfo: {token, siteaccess},
extraActions: [{
component: SomeCustomComponent,
attrs: Object.assign({}, mfuAttrs, {
onPopupClose: doSomethingOnClose,
})
}],
items,
contentTypesMap,
totalCount: subItemsList.ChildrenCount
}), container);

31. Sub-Items List – result of extension

32. Extending Field Type validators – class
class CustomFieldTypeValidator extends global.eZ.BaseFieldValidator {
validateValue(event) {
return {
isError: false,
errorMessage: ''
};
}
}

33. Extending Field Type validators – implementation
const validator = new CustomFieldTypeValidator({
classInvalid: 'is-invalid',
fieldSelector: '.ez-field-edit--custom-field-type',
eventsMap: [
{
selector: '.ez-field-edit--custom-field-type input',
eventName: 'blur',
callback: 'validateValue',
errorNodeSelectors: ['.ez-field-edit__label-wrapper'],
},
],
});
validator.init();
eZ.fieldTypeValidators = eZ.fieldTypeValidators ?
[...eZ.fieldTypeValidators, validator] :
[validator];

34. Extension points for backend developers

35. Field Types
• Content editing is now powered by Symfony Forms,
• Developers have to provide mapping service between repository fieldtype and
Symfony Forms,
• Templating is easier,
• Customizable via EventListeners, DataTransformers, Type Extensions etc.

36. Field Types in YAML
tags:
- { name: ez.fieldFormMapper.definition, fieldType: ezboolean }
- { name: ez.fieldFormMapper.value, fieldType: ezboolean }

37. Field Types in PHP
class PageFormMapper implements FieldValueFormMapperInterface {
public function mapFieldValueForm(FormInterface $fieldForm, FieldData $data) {
$fieldDefinition = $data->fieldDefinition;
$formConfig = $fieldForm->getConfig();
$names = $fieldDefinition->getNames();
$label = $fieldDefinition->getName($formConfig->getOption('mainLanguageCode')) ?:
reset($names);
$fieldForm->add(
$formConfig->getFormFactory()->createBuilder()->create('value',
PageFieldType::class, [
'required' => $fieldDefinition->isRequired,
'label' => $label,
]
)
->setAutoInitialize(false)
->getForm()
);
}
}

38. ExtendingApplication Menu
The extension point is based on KNP Menu bundle.
It uses Event Listeners to extend existing menus.

39. ExtendingApplication Menu
class ConfigureMainMenuListener implements TranslationContainerInterface
{
public function onMenuConfigure(ConfigureMenuEvent $event)
{
$root = $event->getMenu();
$options = $event->getOptions();
// ...
$root->addChild(self::ITEM_PAGE, [
'extras' => [
'icon' => 'content-list',
'translation_domain' => 'ezplatform_page_builder_menu',
'routes' => [
'ezplatform.page_builder.location_preview',
'ezplatform.page_builder.url_preview',
],
],
]);
}
}

40. ExtendingApplication Menu– the result

41. The Location view tabs

42. Adding new tabs – the YAML code
EzSystemsEzPlatformAdminUiTabLocationViewContentTab:
public: true
autowire: true
arguments:
$siteAccessLanguages: '$languages$'
tags:
- { name: ezplatform.tab, group: location-view }

43. Adding new tabs – the Twig code
{{ ez_platform_tabs('location-view', {
'content': content,
'location': location
}, '@EzPlatformAdminUi/parts/tab/locationview.html.twig') }}

44. Other approaches of extendingAdminUI
• Overriding Twig templates,
• Overriding service definitions,
• Compiler passes,
• Bundle's extension class,
• Semantic configuration,
• Event listeners

45. What else?
• Custom Tags in the rich text editor,
• Notifications API

46. Performance comparison – Login page 1.x

47. Performance comparison – Login page 2.x

48. Login page summary
eZ Platform 1.x eZ Platform 2.x
Requests 158 7
Download size 6.5M 608KB
HTML load time 3.5s 681ms
Page ready time 16.13s 715ms

49. The Login page loads almost 23x faster in 2.x!

50. Performance comparison – Location view 1.x

51. Performance comparison – Location view 2.x

52. Location page summary
eZ Platform 1.x eZ Platform 2.x
Requests 190 22
Download size 6.7M 2.2M
HTML load time 24.6s 2.2s
Page ready time 40.99s 2.69s

53. The Location page loads almost 16x faster in 2.x!

54. Who are we?
Piotr Nalepa
Senior UI Developer @ eZ Systems
@sunpietro
Maciej Kobus
PHP Developer @ eZ Systems

55. THANK YOU!