DEV Community: Andrea Berardi

BEM, CSS Namespaces and ITCSS

Andrea Berardi — Mon, 21 Mar 2022 02:13:07 +0000

because writing CSS is easy; looking after it is not.

-- csswizardry

Yes, even though currenly there are lots of tools involved in CSS landscape nowadays, it's a pretty easy language to start with, and due to its design (pitfalls ?) it's also pretty easy to find yourself soon wasting time on deciding classes names and struggling to make your code more maintainable and scalable.

Basically HTML and CSS shares classes (and ids) to shape the final UI and reusing classes being sure to do exactly what you want, where you want, without introducing problems in a totally different part of the ui requires you, developer, to be really accurate/diligent.

Methodologies, naming conventions and architectures help you a lot.

This is what is currently helping me a lot.

BEM

Block Element Modifier is a methodolgy, or a naming convention suggestion that helps you giving classes a role, relationship, responsibilities and states in a clear way.

Definitely a way to save time when deciding class names.

Block: the parent, the standalone entity that has a meaning by itself (top level abstraction of your component)
Element: a part of the block, without meaning standalont by itself (a child item)
Modifier: a flag, a variation, a state to a block or element

Here is an example of BEM applied to a button

<a class="button button--big">
    <span class="button__icon"></span>
</a>

.button {
    display: inline-flex;
    justify-content: center;
    align-items: center;
    border-radius: 6px;
    padding: 8px 12px;
}
.button__icon {
    margin-right: 6px;
    font-size: 0.5rem;
}
.button--big {
    padding: 12px 16px;
    font-size: 20px;
}

CSS Namespaces

How many times have you looked at a piece of HTML only to wonder:

which classes do what
which classes are related to each other
which classes are optional
which classes are recyclable
which classes can you delete, and so on?

A lot of times, I bet.

A CSS Namespace will tell you exactly how a class behave in a more global sense.

Again, this methodolgy is meant to be used when deciding class names.

ere are the individual namespaces and a brief description.

Object: o-

A class name that starts with "o-" is an Object, an abstract layout implementation. Used in any number of unrelated contexts: tread carefully.

Eg. o-grid, o-sidebar-left

Component: c-

A class name that starts with "c-" is a Component: this is a concrete, implementation-specific piece of UI.

Eg. c-hero, c-card

Utility: u-

A class name that starts with "u-" is a Utility class. It has a very specific role and it can be reused and is not tied to any specific piece of UI.

Eg. u-color-primary, u-text-center

Theme: t-

A class name that starts with "t-" adds a adds a theme to a view. Overrides default style due to the presence of a theme.

Eg. t-light, t-saint-valentine

State: is- / has-

A class that starts with is- or has- indicates that this piece of UI is currently styled a certain way because of a state or condition. Used everywhere, not tighten to specific UI block

Eg. is-active, has-2-items

Javascript Hooks: js-

A class that starts with - js- indicates that this piece of the DOM has some JavaScript binds onto it.

Eg. js-carousel, js-accordion

ITCSS: Inverted Triangle CSS

It helps us to organize our CSS files to better deal with CSS specifics/issues/pitfalls like:

global namespace
cascade
selectors specificity.

At the end, we split CSS properties based on their level of specificity and importance.

Going from top to bottom symbolizes an increase in specificity, and each subsection of the triangle may be considered a separate file or group of files.

My personal implementation:

1-settings: sass variables: font, colors, spacings
2-tools: mixins and functions: bg-image(), abs-center()
3-base: generic + elements, normalize/reset + base html elements style without classes: body, h1, table (this is the first CSS output)
4-layout: (remember objects?) abstract layouts, unstyles patterns: grid, layout-sidebar, media
5-components: style for a specific piece of UI: c-hero, c-footer
6-modules: aggregation of modules: c-cards-list, c-cards-carousel
7-trumps/utilities: utilities and helper classes with ability to override anything which goes before, all CMS specific stuff like base overrides, views, specific page style

Eleventy (11ty) setup for multilingual component-based flexible pages (aka One Page Websites with i18n)

Andrea Berardi — Sun, 20 Mar 2022 05:32:54 +0000

Intro

Such a huge hype about Eleventy (11ty) in the last year that I wanted to give it a try.

Documentation

The documentations is definitely good, but it's lacking exactly what I was looking for: how to use structure multi-sections pages built using reusable UI components (hero, text, text-image, gallery, etc.).

I was able to find just a couple of devs asking for the same setup, and at the end I figured out that this tool is mainly designed to be used as a data-driven static generator with simple content structure: 1 to 1 relationship between content and template.

Luckily, I found this interesting article, written by Laurence Hughes, that was my starting point for this setup: Reusable code snippets and components in Eleventy

Frontend toolchain and libraries

11ty is not coupled with any kind of frontend library or framework. No Sass compilation in place, no postcss, no babel, no webpack... nothing. No specific tool used by default, no toolchain setup for you: you are free to use whatever you want, but, at the same time, you're going to spend just a bit of time to setup whatever you want.

Configuration file

Even if Eleventy can be used with zero configuration, be comfortable as early as possible with playing with its config file, since you'll need it to define custom collections, filters, basic setup (etc.)

11ty basic concepts

With 11ty, content files are called templates, and what I usually call templates are called layouts.

There are lots of engines available and you can even mix them.
I used Markdown for templates (content files), and Nunjucks for layouts (templates).

Some key points:

by default every template you write automatically generates a final html page
you use Front Matter to drive 11ty behaviours and define custom content you might need inside layouts
you use the layout Front Matter key to indicate which layout has to be used to generate the page
collections are groups of content you can play with using APIs: you can define collections in different ways: tags in Front Matter, tags in directory-specific json file, 11ty configuration

Nunjucks basics

I love component-based development: the idea is that you have a piece of reusable encapsulated UI you can use thoughtout your project, passing the scoped data you want time by time.

With Twig this is typically implemented writing 1 markup file for each components (partial) and then including it using include and the with only keywords, passing the only data required by that component.

Nunjucks is a template language for JavaScript with syntax pretty similar to Twig, supporting template inheritance and partials definitions and includes, but one main difference I found, is that its include doesn't support that so-practical with keywork.

With Nunjucks the best way to write component based templates is to use the macro stratement.

    {% macro field(name, value='', type='text') %}
        <div class="field">
            <input type="{{ type }}" name="{{ name }}" value="{{ value | escape }}" />
        </div>
    {% endmacro %}

Pay attention: include seems to do the job, but actually it's good to be used just for pieces of templates that don't require params. The problem is params scoping: you can try to use the {% set %} statement for "passing data" just before the include statement, but there is no scope: all variables you have set before the include call are visible inside the component.

Structuring the content and layout for multi-sections page

For each page create one directory containing:

one data file configuring 11ty to not generate a page for every file inside ("permalink": false) and create a collection, setting tags for every file inside the directory
one file for each section of the page using a custom "clayout" Front Matter key to indicate the UI component to use
one page file (template) "index.md" with permalink Front Matter key set to the page's URL you want

Nunjucks and UI components

And this is how I structured the layouts part:

1 specific directory containing all reusable UI components markup
1 "macros" file defining all availble UI components using include and macro statements, to be used inside layouts files
1 template logic for/each cycle (DRY principle) to be used when cycling all different page setion files (collections) and rendering the relevant component

Frontend toolchain

Gulp FTW here.

I used Gulp to compile scss files, process JavaScript files with Babel and bundle with rollup, and setup a watch task to process scss and js when there's an update source file.

All processed files (final style.min.css and app.min.js) are saved in a "processed" folder under the src/assets folder, and then 11ty is configured to watch for changes and simply copy those files.

Multilanguage

Another common request is to manage i18n in your project.

As far as I know there's no official plugin for this, and as usual in JavaScript world, there are multiple ways of doing thigs. This is my approach:

Translating page content

Create one directory for each language you want to support ("en", "fr"): it will contain all templates for that language
Set the locale using a custom "lang" Front Matter key in templates: it will be used for getting the right content from multilanguage globals data files (labels, header, footer, navigation, etc...)

{
    ---
    layout: layouts/pages/home-fr.njk
    title: "Homepage FR"
    permalink: /fr/
    lang: fr
    ---
}

Translating global content (static labels, navigations, etc.)

Structure your globals data files with multiple keys (one per language) and code your templates and partials to include the relavanta data only

    {
        "en": {
            "websitename": "Berry is the best",
            "footercopyright": "Foo bar"
        },

        "fr": {
            "websitename": "Berry est la meilleure ",
            "footercopyright": "Foo bar fr"
        }
    }

    {% set navMain = navMain[lang] if lang else navMain['en'] %}

    <nav id="main-nav" class="c-nav-main u-show-on-desktop">
        <ul>
            {% for item in navMain %}
            [...]
        </ul>
    </nav>

Show me the code!

Far from being perfect, here you can find my repo with all these things implemented:

https://github.com/andberry/berry-11ty

var, let, const: declaring variables in JavaScript

Andrea Berardi — Mon, 27 Sep 2021 12:28:52 +0000

In Javascript we can declare variables using var, const and let keywords

var

var is the old way (pre es6/es2015) of declaring variables. It's a "weak" variable declaration because it doesn't help us understanding if binding could change durign execution.

let

We use let to declare bindings that could chage during execution (eg. a loop counter, or a variable used in math).

const

const stands for constant. We use const for bindings that will not change during execution.

Pay attention: this means that identifiers declared with const cannot be re-assigned, but in case of objects we can change its attributes after binding:

const str = "foobar"
str = "barfoo"
Uncaught TypeError: Assignment to constant variable.

const obj = { foo: 'foo', bar: 'bar' }
obj = { foo: 'foo2', bar: 'bar2' }
Uncaught TypeError: Assignment to constant variable.
obj.foo = 'foo3'
obj
{ foo: 'foo3', bar: 'bar' }

Scoping

Variables declared with var are only function-scoped or globally-scoped.

On the other end, the scope of variables declared with const and let is the enclosing block (code between curly braces { } ) and not the whole function.

Global object (window)

Variables declared outside functions (aka in the top level of program) with var become properties of the global object (window), while variables declared with let or const don't.

var foo = "foo";
let bar = "bar";
window.foo
"foo"
window.bar
undefined

Conclusion

I don't use var anymore
I use let only when it's required that binding can change during execution (eg. loop variables)
I use const almost for everything

jQuery $(document).ready() in vanilla JavaScript

Andrea Berardi — Mon, 27 Sep 2021 05:20:31 +0000

jQuery's $(document).ready() method allows us to safely run code only once the DOM is loaded and parsed.

Not to be confused with $( window ).on( "load"), to be used if we want to run code only if the whole page content (DOM, and assets as well) is loaded in the browser.

We can achieve the same result with vanilla js and Web APIs, in particular using:

Window: DOMContentLoaded event
document.readyState

The tricky part is considering that when the browser runs our code it may have already loaded and parsed the DOM, so the best practice is to first check the document.readyState variable.

Here is my complete gist:

How to integrate UIkit in Drupal

Andrea Berardi — Mon, 27 Sep 2021 04:56:16 +0000

UIkit (https://getuikit.com/) is an amazing lightweight and modular front-end framework that can help you, frontend developer, a lot.

Super clean black/white style, it can be seen as a library of components you can integrate in your project.

Components list ranges from a sort of utility classes like "Align" or "Padding" to more complex and js driven building blocks like Accordion, Dropdown, Lightbox, Scrollspy and Slideshow just to cite a few.

1) Using the Drupal theme

The simplest way to start using UIkit in Drupal is to simply install the theme https://www.drupal.org/project/uikit

composer require 'drupal/uikit:^3.15'

You get the all the framework css and js loaded and also a useful bunch of views styles/formatters.

2) Loading it as library from CDN

A second way to integrate UIkit in your theme is to load it from CND defining a library in your theme.
Something like this (pay attention that this file must follow YAML 2 spaces indentation and that uikit library has to be included in .info.yml file):

global-css:
  version: 1.0
  css:
    theme:
      css/style.min.css: { minified: false }
global-js:
  version: 1.0
  js:
    js/app.min.js: {}
uikit:
  js:
    "//cdn.jsdelivr.net/npm/uikit@3.7.3/dist/js/uikit.min.js": { type: external, minified: true }
    "//cdn.jsdelivr.net/npm/uikit@3.7.3/dist/js/uikit-icons.min.js": { type: external, minified: true }
  css:
    base:
      "//cdn.jsdelivr.net/npm/uikit@3.7.3/dist/css/uikit.min.css": { type: external, minified: true }

You get the all the framework css and js loaded in your theme

3) Install with npm and integrate in scss/js

If you have a workflow tool or task runner in place I guess you'll prefer to install UIkit with npm and then integrate the scss and js parts.

Install framework with NPM

npm install -P uikit

CSS/Scss: where to put these code snippets actually depends on how you structured your scss files,
but the concept is that you need first to include variables and mixins (eg. _settings.scss)

@import "uikit/src/scss/variables";
@import "uikit/src/scss/mixins";</pre></code>

and the you can include the CSS for the components you're using (eg. _components.scss):

@import "uikit/src/scss/components/visibility";
@import "uikit/src/scss/components/accordion";
@import "uikit/src/scss/components/animation";

JavaScript: simply import the framework (eg. in app.js)

import UIkit from 'uikit';
import Icons from 'uikit/dist/js/uikit-icons';
UIkit.use(Icons);

This way you load all the JavaScript part of the framework but only the style files you're actually using in your frontend,
and you can easily get the framework css and js files bundles with your codebase (reducing the number of browser requests)

Component-Based Frontend in Drupal

Andrea Berardi — Mon, 27 Sep 2021 04:49:56 +0000

What is Component-Base Frontend Development

First of all, Component-Based is an approach to UI Design and Development.

Shortly, your website is no more designed as a set of pages, but as a list of small and reusable blocks (components).
In other words, your pages become "simply" compositions of these blocks, sorting them in different order.

Components are not tied to specific page or sub-page but should be reused throughout the whole website.

If you're implementing a theme for a CMS, it's up to you to decide to use components to just build a "fixed" set of templates or use them to let the client build pages in a flexible sort-of-composer way:
you can use Paragraphs in Drupal, Matrix field in Craft CMS or Flexible Content field type of WordPress ACF Pro plugin just to cite a few.

This is an example list of UI components:

hero
gallery
card
cards
cards-carousel

The actual names of your components is up to you, designers and developers. They should be as more abstract as possible, but I suggest you to find a good compromise avoiding overthinking.

As I said before, Component-Based approach is not only a dev-tech-code thing, but it first involves designers.
From the design point of view, the best is to have a complete and clear collection of all components involved in the project, and then the actual design of pages.

As a developer you start coding first by building the collection of all components and then you can go on building pages.

In my humble opinion this paradigm is amazing when working with a CMS since it lets you write the frontend code you want detached from the underlying CMS, in a sort of decoupled way: this way CMS becomes more your source of data rather then a magic box where your markup comes from.

Yes, if you're used to just style the HTML coming from the default templates of your CMS, this approach is going ask you to write more html, in some cases lots of templates (Drupal), but you'll have full control over it and it'll be easier to integrate 3rd party frontend libraries/components.

Actual implementation details depend on the CMS you're building the frontend for, but more or less this is path for the win: you first code the abstract components, then you connect dynamic data coming from the CMS to the components params/props, and then you build the page.

Why you should start using it

Switching to a Component-Based Design and Development paradigm means:

more collaboration between designers and developers at the early stages of the project;
developers can concentrate on implementing pieces of UI unchained from the underlying CMS used: your frontend code is less dependant by the CMS, so you're free to use whatever markup/classes/architecture you want;
you can implement a style guide shared between the team that can help a lot in terms of keeping consistency during the project
your client or content editor people will easily get one "flexible" page template rather than a set of prefixed page templates. I guess it's a great value added to the project in the sense that your clients will be able to build whatever kind of page they'd like in the future just using and rearranging the building blocks.

How to implement Component-Based Frontend Development in Drupal

This is my way of implementing Component-Based Frontend Dev in Drupal.

Markup (HTML): components are implemented as Twig files, and live in '/templates/components' folder inside your theme folder.
CSS: a separate scss file for each component (I love ITCSS architecture and I use gulp and sass to build the final compressed css file). BEM methodology drives me for classes names.
JavaScript: when required, JavaScript is implemented as ES6 module and bundled with other modules (using gulp, babel and rollup for the build). Using CSS classes with "js-" namespace is a great way to target blocks from JavaScript (eg. js-carousel)

This is an example of the markup of the hero component:

As you can see this component is expecting to receive just 3 parameters/data/props: image, title and text.
I'm able to use the markup I want with all the classes and methodologies / architectures I want: I'm using BEM, with namespaces and in particular in this case I'm using the 'js-hero' class to target this block from JavaScript.

This is an excerpt of the related Scss file:

Connecting Components to Drupal

And now the most complicated part: passing data coming from Drupal to components as parameters/data/props.

Inside each specific Drupal Twig file I simply go with a Twig include statement passing an object containing relevant data coming from fields:

The "specific Drupal Twig file" depends on how you structured the content, but this can be easily done for:

nodes templates (eg. node--page.html.twig)
views templates (eg. views-view-fields--hero.html.twig)
paragraphs templates (eg. paragraph--card.html.twig)

Often the tricky and time wasting part is to access field plain value.

If you've ever worked with Craft CMS you know that accessing field values with this CMS is straightforward thanks to their amazing Twig API, but in Drupal it's not so easy.

Drupal makes the assumption you usually don't want plain value from a field to be used directly in Twig templates, but you usually want a formatted value or worse a prebuit markup depending on the field formatter and the templates coming from modules and base theme you're using.

So, this is my short list of code snippets to access various fields type data: