Configurer Fontawesome dans un site web basé sur Bridgetown

FontAwesome est une bibliothèque d’icônes pouvant être utilisées sur des sites web, dans des applications, et plus. On peut l’importer grâce à leur CDN, hébergée localement, ou intégrée en tant que dépendance via npm ou yarn.

J’utilise yarn et esbuild, qui sont les outils prévus par BridgetownRB, et mon site est configuré pour utiliser ERB et SCSS. (Note : pourquoi ERB ? Parce que j’ai perdu beaucoup trop de temps à utiliser Liquid et Smarty, qui complexifient l’écriture de templates sans apporter aucuns bénéfices dans ma situation).

Première étape - ajouter le paquet

En premier, nous devons ajouter la dépendance aux icônes FontAwesome, et un plugin pour esbuild qui permet de copier les fichiers de polices dans le dossier où sera généré le site :

yarn add @fortawesome/fontawesome-free esbuild-plugin-copy

Deuxième étape - copier les fichiers de polices

Il faut maintenant indiquer à ESbuild que les fichiers de polices doivent être copiées depuis node_modules/@fortawesome/fontawesome-free/webfonts vers le dossier où Bridgetown génère le site compilé.

Ouvrir le fichier esbuild.config.js

Avant

//esbuild.config.js
/**
 * @typedef { import("esbuild").BuildOptions } BuildOptions
 * @type {BuildOptions}
 */
const esbuildOptions = {}

Après

const path = require("path")
const esbuildCopy = require('esbuild-plugin-copy').default

/**
 * @typedef { import("esbuild").BuildOptions } BuildOptions
 * @type {BuildOptions}
 */
const esbuildOptions = {
  plugins: [
    esbuildCopy({
      assets: {
        from: [path.resolve(__dirname, 'node_modules/@fortawesome/fontawesome-free/webfonts/*')],
        to: [path.resolve(__dirname, 'frontend/fonts/')],
      },
      verbose: false
    }),
  ]
}

Troisième - importer les styles de Font-Awesome

Ouvrir maintenant le fichier frontend/styles/index.scss et y ajouter les lignes suivantes :

$fa-font-path: "../fonts";
@import "~@fortawesome/fontawesome-free/scss/fontawesome.scss";
@import "~@fortawesome/fontawesome-free/scss/solid.scss";
@import "~@fortawesome/fontawesome-free/scss/brands.scss";

Note : il se peut que les fichiers SCSS soient compilés avant que les polices aient eu le temps d’être copiées. Dans ce cas, attendre un instant puis relancer la compilation, ou relancer le serveur Bridgetown.

Quatrième étape - simplifier l’intégration des icônes

Créer le fichier suivant : plugins/builders/icon.rb

class Builders::Icon < SiteBuilder
  def build
    helper :icon
    helper :link_icon
  end

  def icon(icon, classes = "", style: :solid, fixed: true, rotate: nil, flip: nil, size: nil, animate: nil, **attributes)
    classes << " fa-" + icon.to_s.gsub("_", "-")
    classes << " fa#{style.to_s[0].downcase}" # Solid/regular/thin/brands
    classes << " fa-fw" if fixed # Fixed-width
    classes << " fa-rotate-#{rotate}" if rotate
    classes << " fa-flip-#{flip}" if flip
    classes << " fa-#{size}" if size
    classes << " fa-#{animate.to_s.gsub("_", "-").downcase}" if animate
    attributes["aria-hidden"] = "true"
    attributes["class"] = classes
    attributes = attributes.collect { |key, value| "#{key}=\"#{value}\"" }
    <<~ICON.strip.html_safe
      <i #{attributes.join(" ")}></i>
    ICON
  end

  def link_icon(icon, name, url, **options)
    icon_attributes = options.delete(:icon) || {}
    icon_class = icon_attributes.delete(:class) || ""
    options[:href] = url
    attributes = options.collect { |key, value| "#{key}=\"#{value.to_s.strip}\"" }
    <<~LINK.strip.html_safe
      <a #{attributes.join(" ")}>
        #{icon(icon, icon_class, **icon_attributes)}
        #{name}
      </a>
    LINK
  end
end

Vous pouvez désormais insérer une icône en saisissant icon :foo dans un fichier de mise en page ou un fragment réutilisable. Et pour les liens, il suffit de remplacer link_to "titre", url par link_icon :foo, "titre", url pour ajouter une icône au texte du lien.

Notes :

• Le deuxième paramètre, facultatif, permet d’ajouter une ou plusieurs classes à l’icône.
• Le style par défaut est solid, pour utiliser le style regular ou brand il suffit de le passer avec le paramètre nommé style. Exemple : style: :regular.
• Pour inverser une icône, passer le paramètre flip: :horizontal # ou :vertical ou :both.
• Pour faire tourner une icône, passer rotate: 90 # ou 180 ou 270
• Pour animer une icône, passer animate: :beat # ou :fade, :beat_fade, :bounce, :flip, :shake, :spin
• Pour changer la taille, passer size: "2xs" # ou :xs, :sm, :lg, :xl, "2xl", "1x", "2x", "3x", "4x", "5x", "6x", "7x", "8x", "9x", "10x". Les tailles commençant par un nombre doivent être passées en tant que chaînes de caractères, les autres peuvent être des symboles.
• Les autres paramètres passés en tant que mots-clés seront automatiquement ajoutés en tant qu’attributs, par exemple : icon :foo, id: "bar" pour générer l’identifiant HTML id="bar"
• L’attribut aria-hidden="true" est automatiquement appliqué pour que les lecteurs d’écrans n’essaient pas de prononcer le contenu de l’icône.

Bonus : automatisation

Il est possible d’automatiser des actions dans Bridgetown, j’ai donc créé un Gist avec les instructions ci-dessus au format attendu par Bridgetown.

Pour l’appliquer, placez-vous dans le répertoire de votre site Bridgetown, et lancer la commande suivante :

bin/bridgetown apply https://gist.github.com/goulvench/5e808f89958655d304dabf039512ab33