How Ara components work?

There are 2 types of Ara components:

• Components with twig files which load assets when enabled.
• Components without twig files which are meant to be called by other components.

Lets discuss the first type.

Every part and bit in a drupal page (regions, blocks, buttons, textfields ...) is generated with a twig file.

Before we begin you need to be familiar with the general concept of twig file name suggestions, see:

https://www.drupal.org/node/2186401

https://www.drupal.org/node/1906392

https://www.drupal.org/node/2358785

Ara theme will add for each enabled component a new twig file name suggestion pointing to the component twig file and overriding an existing suggestion. When active, the component twig file will load the component library (css/js) responsible for the new styling of the page element.

Lets look at this in more detail using an example:

Assume we want to style all the submit buttons in the page using Lumx framework.

Looking at a submit button html in the page source (with twig debug enabled) we find:

<!-- FILE NAME SUGGESTIONS:
   * input--submit.html.twig
   x input.html.twig
-->

From the above we understand that we want to override "input--submit.html.twig".

We look for an Ara component having a twig file with a name starting with "input--submit". We find "input--submit--lumx-ara.html.twig" in "ara/components/atoms/lumx/inputs/submit".

Note: If we don't find a corresponding component, or the available component does not suit our page styling, we can easily create a new one.

To enable this component we add the following entry in "YOURSUBTHEME/settings/components/enabled-components.yml"

input:
  submit:
    framework: lumx

then we clear the cache (drush command: drush cr).

Ara will now add a new twig file name suggestion: "input--submit--lumx-ara.html.twig" with a priority that is exactly above "input--submit.html.twig".

"input--submit--lumx-ara.html.twig" will load the library defining the needed css/js files responsible for styling the button. This file will also add a class name to the button element "input--submit--lumx-ara".

The next step is to customize the submit buttons using "settings.js.yml" residing in "YOURSUBTHEME/settings/components/atoms/lumx/inputs/submit/".

Refer to http://ui.lumapps.com/components/button for the available settings.

Any setting value preceded by "gs." will be pulled from the global settings you define in "YOURSUBTHEME/settings/settings.js.yml". This will make it easier to have common settings between different components, and have colors and sizes consistent in your page.

Notes: If you have multiple Ara subthemes chained:

• You can enable components in any subtheme.
• Component settings defined in different subthemes will be merged while ensuring priority is given according to subthemes order.