documentation.md

Develop

Components

Public packages which are published on NPM registry are located in src/ec/packages. Packages in other folders are private and are for development purposes only.

Each ECL-Twig component is an npm package. Packages are named after components. For example, the EC button component lies in a package named @ecl-twig/ec-component-button. The *-component-* pattern allows for future publishing flexibility.

The Twig template file in each package should be named after the component too. For example, the main template file for the EC button component is named button.html.twig.

The extra (meta) package @ecl-twig/ec-components is used to automatically import all the available Twig components. New components must be added in this package!

Style guide

Each component comes with a Storybook story file *.story.js.

Twig templates are imported and visualized through these stories for demonstrating components' visual design as well as data structures and behaviors.

EC/EU systems

The library was built with two independent systems in mind, EC and EU, but in ECL-Twig only the EC components are defined and two different storybook instances are prepared to render the components with the right style.

Sometimes components diverge in the two systems in terms of content or data for the input that we receive as specs from ECL, if this cannot be handled in a single *.story.js file, two story files can be created, the system will select the right one for the different system: ec-{component}.story.js will be chosen when starting EC and eu-{component}.story.js when starting EU.

Working on the EC system

yarn start:ec

Working on the EU system

yarn start:eu

Automated testing

The following section focuses on testing rendered output of templates.

Snapshots

Regressions are tested by Jest snapshot testing:

yarn jest

Update snapshots when reported changes are desired and are to be committed as a new reference:

yarn jest-update

Linting

Standards for the way of writing templates is ensured with static code analysis.

JavaScript

yarn lint

Twig

The ECL-Twig library is an implementation of the ECL vanilla components using the twig render engine. Since templates are targeting Drupal primarily, ECL-Twig is based on twig 1.x.

No syntax or features from twig 2.x can be used. There are a few utilities for ensuring these standards.

Libraries for sniffing and linting twig (language) templates are based on PHP. The following software packages are required for the following scripts to work:

• PHP 7 or higher
• Composer (following scripts assume global install)

Install dependencies:

composer install --no-scripts

The no-scripts flag prevents Grumphp from overriding existing git hooks from husky (npm toolchain).

To circumvent this issue it's recommended to also run the following script that will enable the pre-commit check by Grumphp.

yarn grump-en

Disable the pre-commit hook:

yarn grump-dis

Manually run the sniffer on all the packages: It uses twigcs

composer twig-cs

Run the sniffer on a specific file:

composer cs /path/to/specific/template/file

Run grumphp on all the packages, one of its tasks is twigcs, the output of this command should be equal to composer run twig-cs.

composer grump-cs

PHP Twig Storybook

If you want test components with PHP rendering, please ensure that you have the required dependencies to work also with the PHP tool-chain, i.e. Composer.

Details are included in the README.md of @ecl-twig/php-storybook.

The following commands are available from the project root: (please ensure data is generated before executing any rendering command)

Get dependencies.

yarn php:install

Remove files and folders from previous builds.

yarn php:clean

Generate data from specification files.

yarn render:dataGen

Generate HTML rendered by Twig PHP:

yarn render:php

Generate HTML rendered by Twing

yarn render:js

All these commands can be executed at once passing the generated files through prettier:

yarn render-php-js (ec|eu)

The whole process of installing the dependencies, generating the needed files, linting them and finally launching a storybook instance is done by:

yarn start:php-ec

yarn start:php-eu

All output files are stored in ./php/packages/ec and ./php/packages/eu folder.

Development tools

(yarn php:install needs to be executed before using the following scripts)

Language-specific rendering

To compare rendering output of a given component in PHP and JavaScript and make a diff comparison between the two language implementations:

yarn check:component (ec/eu) (componentName)

Diff comparison

The commands below rely on the existence of PHP filesystem: yarn render-php-js.

Make a comparison on a system-level:

yarn diff (ec|eu)

Make a comparison of a component rendered in PHP with the ECL version markup.

yarn diff:ecl (ec|eu)

For a full comparison of all components and their variants:

yarn diff:ecl-full (ec|eu)

Using it with no argument it will generate a report in the two systems independently.

Building the project (creating a dist)

Build the dist for the twing-based storybook:

yarn twing:dist

Build the dist for the PHP-based storybook:

yarn php:dist

Build both:

yarn dist

Test the dist:

npx serve build

Libraries update

The task of upgrading the dependencies is executed via the command:

yarn upgrade-interactive --latest --exact

which will retrieve all the possible upgrades marking them in green, yellow or red depending on the changes included in these packages.