GLL Component Library

A Rails engine that renders GLL websites by consuming content from the BOP API, served by gll_central. Built on ViewComponent, it provides a full design system of panels, patterns, and atomic components — all driven by JSON:API responses from BOP.

Prerequisites

Before installing this engine, ensure your Rails application has the following dependencies installed:

Importmap for Rails
This gem requires importmap-rails for JavaScript module management.
bash bundle add importmap-rails ./bin/rails importmap:install
Dart Sass for Rails
This gem requires dartsass-rails for CSS compilation.
bash bundle add dartsass-rails ./bin/rails dartsass:install
BOP API server
Host apps need a running instance of gll_central (aka BOP) to serve content. Start it via the project orchestrator:
bash gll up central

Installation

This README explains how to install the engine into your host application.
For development-specific steps and considerations, refer to the spec/dummy/README.md.

Examining the gem's integration in spec/dummy is the best way to see how to mount and use the engine.

Choose a version
Browse all releases on GitHub tags and note the version you need.
Add the gem
In your Gemfile, add:
ruby gem 'gll_component_library_gem', tag: 'vX.Y.Z', git: 'https://<your-token>@github.com/morsedigital/gll_component_library_gem.git'
Install dependencies
bash gll bundle install
Run the install generator
bash gll rails g gll_component_library:install
This will:
- Create the configuration initializer (see the section on configuration)
- Mount the engine in your routes file
- Add the necessary assets to your application.scss and application.js
- Copy professional error pages (500.html) to your public/ directory
- Copy the default GLL logo to public/images/logo.png for error pages
Check application layout is configured
erb <head> <%= javascript_importmap_tags %> <%# make sure importmap is loaded before the call to yield :head %> <%= yield :head %> </head>

Configuration

All configuration is done in config/initializers/gll_component_library.rb after running the install generator.

BOP API

gll_central, known as BOP (Backend of Platforms), is the backend service that manages content from Contentful and serves it to host apps via JSON:API. The component library fetches all page and content data from BOP at request time — there is no local content database.

Base URL

The BOP base URL is loaded from config/bop.yml via Rails.application.config_for(:bop). Create this file in your host app:

# config/bop.yml
default: &default
  base_url: http://gll_central:3000/api/v1

development:
  <<: *default

test:
  <<: *default

production:
  <<: *default
  base_url: <%= ENV['BOP_BASE_URL'] %>

The default http://gll_central:3000/api/v1 resolves via the Docker network when running through the project orchestrator.

API Key

The API key is loaded from Rails encrypted credentials under bop.api_key:

gll rails credentials:edit

bop:
  api_key: your-bop-api-key

Overriding in the initializer

Both values can also be set directly in the initializer if needed:

GllComponentLibrary.configure_app do |app|
  app.configure_bop do |bop|
    # bop.base_url = 'http://gll_central:3000/api/v1'
    # bop.api_key = ENV['BOP_API_KEY']
  end
end

Basic Settings

GllComponentLibrary.configure_app do |app|
  # Logo path (relative to assets/images directory)
  # Default is 'logo.png' which is preferred for error page compatibility
  # Static error pages require logo.png at public/images/logo.png
  app.logo_path = 'logo.png'  # Default - recommended to keep this

  # Custom header component path
  app.custom_header_content_fpath = 'layouts/partials/_header_custom'

  # Mobile rendering
  app.force_mobile_render = false

  # Configuration validation on startup
  app.validate_on_start = true
end

Feature Toggles

Enable/disable various features:

GllComponentLibrary.configure_app do |app|
  app.enable_diagnostic_info = true  # Shows gem/Rails/Ruby version in development
  app.enable_language_switcher = true
  app.enable_turnstile = true        # Cloudflare bot protection
  app.enable_one_trust = true        # Cookie consent
  app.enable_recite_me = true        # Accessibility widget
  app.enable_gtm = true              # Google Tag Manager
end

Third-Party Integrations

Google Tag Manager

GllComponentLibrary.configure_app do |app|
  app.enable_gtm = true
  app.gtm_id = 'GTM-XXXXXXX'
end

Cloudflare Turnstile (Bot Protection)

GllComponentLibrary.configure_app do |app|
  app.enable_turnstile = true
  app.turnstile_site_key = ENV['TURNSTILE_SITE_KEY']
  app.turnstile_secret_key = ENV['TURNSTILE_SECRET_KEY']
end

OneTrust Cookie Consent

GllComponentLibrary.configure_app do |app|
  app.enable_one_trust = true
  app.one_trust_data_domain = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
end

ReciteMe Accessibility Widget

GllComponentLibrary.configure_app do |app|
  app.enable_recite_me = true
  app.recite_me_url = 'https://api.reciteme.com/asset/js/reciteme-2.0.0.min.js'
  app.recite_me_key = 'your-recite-me-key'
end

Language Support

The locale first in the list is considered the #default_locale for the project. If none are provided en-GB => English is set.

GllComponentLibrary.configure_app do |app|
  app.enable_language_switcher = true
  app.supported_languages_map = {
    "en-GB" => "English",
    "fr-FR" => "Français",
    "es-ES" => "Español"
  }
end

Content Slots (Deprecated)

Content slot configuration is now managed in GLL Central. This option is retained for backwards compatibility but host apps should no longer need to configure it.

GllComponentLibrary.configure_app do |app|
  # app.content_slots = { patterns: %w[SwatchPatternComponent] }
end

Organization Schema (SEO)

Configure structured data for your organization:

GllComponentLibrary.configure_app do |app|
  app.configure_organization_schema do |org|
    org.name = "Your Organization Name"
    org.alternate_name = "Your Alt Name"
    org.url = "https://yourorganization.com"
    org.telephone = "+1234567890"
    org.address_country = "GB"
    org.address_locality = "Your City"
    org.postal_code = "12345"
    org.street_address = "123 Your Street"
    org.same_as = [
      "https://twitter.com/yourorg",
      "https://linkedin.com/company/yourorg"
    ]
  end
end

The logo (configured via app.logo_path) will automatically be included in the schema markup.

Color Palette

Customize the color scheme:

GllComponentLibrary.configure_app do |app|
  app.configure_palette do |palette|
    # Primary colors
    palette.primary_10 = "#E5F3FF"
    palette.primary_60 = "#0087FF"

    # Secondary colors
    palette.secondary_10 = "#FFF4E5"
    palette.secondary_60 = "#FF9100"

    # Accent colors
    palette.accent_10 = "#E5FFF5"
    palette.accent_60 = "#00FF9B"

    # Monochrome colors
    palette.mono_0 = "#FFFFFF"
    palette.mono_100 = "#000000"
  end
end

Architecture

The engine is a stateless API client — it holds no local content database. On each request, it fetches page and content data from BOP via JSON:API and renders it using a ViewComponent design system organized into four tiers:

Documents     Page, Article — top-level document shells
  Panels      Hero, Carousel, Pattern, Breadcrumb — full-width page sections
    Patterns  MediaCard, TextCard, Image, Video — reusable content blocks
      Components  Button, HyperLink, Icon — atomic UI elements

All content modelling and management happens in gll_central / Contentful. The component library is responsible only for presentation.

Design System Documentation

Detailed design system reference docs live in app/components/previews/docs/ and are browsable in Lookbook:

File	Contents
`01_overview.md.erb`	Component hierarchy and composition model
`02_colours.md.erb`	Palette system, colour families, semantic tokens, panel backgrounds
`03_typography.md.erb`	Heading sizes, text utilities, font weights, link styles
`04_spacing.md.erb`	Grid system, breakpoints, panel spacing, padding utilities, flex mixins
`05_adding_components.md.erb`	Step-by-step guide for adding new components with Lookbook previews

Development

All GLL apps are managed via the gllprojectorchestrator. Common commands for the component library (cl):

gll up cl                    # Start the component library (and dependencies including BOP)
gll logs cl                  # View logs
gll exec cl                  # Open a bash session in the container
gll exec cl rails console    # Rails console

Lookbook

The component library includes Lookbook for browsing and interacting with components in isolation. Once the container is running:

URL: http://localhost:3001/lookbook
Previews: Interactive component previews with configurable params — change properties in real time
Documentation: Design system reference pages (colours, typography, spacing, adding components)

Lookbook previews live in app/components/previews/ and documentation pages in app/components/previews/docs/. Lookbook auto-reloads when component or SCSS files change.

Running Tests

Because this is a Rails engine, the Docker container WORKDIR is spec/dummy (the dummy host app). To run the gem's specs, use the --workdir flag to target the gem root:

gll exec cl --workdir /app -- bundle exec rspec spec/lib spec/requests

Important: Do not use bundle exec rspec spec/ — it picks up vendor bundle specs. Always specify spec/lib spec/requests or a specific spec path.

See the orchestrator README for the full command reference.

Release Process

There's a staging server at https://gllcl.morsestaging.com
Staging branch deploys to it automatically on push.