Cambridge Tailwind Theme

## Description

This repository contains the Cambridge theme for Drupal 10 implementations.

This theme was initially generated from Drupal's starterkit_theme. Additional information on generating themes can be found in the Starterkit documentation.

Styles are based on the tailwind CSS framework.

It also includes twig templates to be implemented as drupal single directory components with the above theme. These are documented using Storybook.

## Developer guide

Requirements

Local development requires this repo to be used as part of the Cambridge D10+Developer starter repo. The starter repo provides a full local Drupal installation. This Drupal install is required to process Twig based Storybook stories and to render Twig components in Storybook via the Drupal renderer: https://gitlab.developers.cam.ac.uk/uis/devops/webcms/2023-platform/cambridge-initial-composer-file

You must have the following installed to run the pre-commit hooks:

• node globally
• npm globally
• pre-commit globally

Setup

To install all local dependencies, run:

ddev npm install

To install all pre-commit hooks, run:

pre-commit install

This will perform checks defined in .pre-commit-config.yaml before committing, including:

• Running prettier & eslint for code formatting and linting
• Consistent file endings / no trailing whitespace
• Consistent formatting of yaml and json files
• etc.

To run these checks manually, run pre-commit run -a.

It is recommended you install the eslint, prettier and typescript VSCode extensions. These will read in our configuration, warn in your editor when you are breaking rules, and auto-format on save.

### Developing changes locally

Local development with Gitflow

Local development of this repository uses gitflow.

Setup and usage can be found here: https://danielkummer.github.io/git-flow-cheatsheet/

Note that all defaults should be uses during setup, so that (for example), git flow feature start AM-123 results in a local branch named git flow feature start feature/AM-123

#### Components

Build stories

ddev drush storybook:generate-all-stories

This generates: components/**/*.stories.json

Start Storybook server and watch Twig changes with:

ddev npm run watch

This will run storybook on http://cam.ddev.site:6006/

Changes made to components will live update. Components must have a components/**/*.stories.twig file defining them in order to appear in storybook.

Quickstart

Run:

ddev npm run dev

To start the watchers for Tailwind and TypeScript changes.

JavaScript & TypeScript

We use TypeScript to develop our code in a type-safe environment and write more reliable code. TypeScript compiles to JavaScript.

We use bundler to compile type-safe TypeScript code, broken down into separate modules where required, into minified JavaScript files that are imported into the browser.

To develop Typescript changes, run:

ddev npm run dev:ts

Note this will be running already if you run ddev npm run dev.

This will start bundler in watch mode, and will recompile the .js files.

You may need to open your browser's developer tools and disable cacheing when making script changes in order to see changes reflected in storybook on refresh.

Theme

Tailwind is configured to produced as minified CSS as possible, it is configured to scan our Twig and JS files to detect classes we are using, and only produce CSS for the those we use. You therefore may need to recompile the theme to see additional classes apply styles.

To develop changes against the tailwind theme, and to have Tailwind generate CSS for classes you've just started using, run:

ddev npm run dev:css

Note this will be running already if you run ddev npm run dev.

This is configured to watch for changes.

Working with Storybook test images

Any files placed in .storybook/assets/ will be copied to the Drupal filesystem when using the local development environment command ddev init and ddev refresh-drupal

You can also run ddev storybook-setup to just reinstall the npm dependencies and copy the assets.

Once the assets are in place, images can be passed through to supporting components using the stream wrapper format: public://my-asset-filename.jpg

Formatting and linting

To independently test for any linting errors eslint has found, run:

ddev npm run test:lint

To independently test for any code formatting errors prettier has found, run:

ddev npm run test:format

And to manually format the whole repo, run:

ddev npm run format

Debugging

You can add {{ dump(_context) }} into a twig component to print out a block containing all the props being passed through and variables set.

Working in this repo when composer has pulled it over HTTPS can cause Git to want to connect to Gitlab via HTTPS. To reset this to consistently go over SSH, and be able to push up to the repo again, run:

git remote set-url origin git@gitlab.developers.cam.ac.uk:uis/devops/webcms/2023-platform/cambridge_tailwind.git

### Testing

There is currently no test coverage on this repository.

### Deployment

The Drupal 10 platform that utilises this theme is still in development and has not yet been deployed to production.

#### Releases

A release candidate has not yet been published.

Using in Drupal instances

The version of this theme pulled in to Drupal 10 instances is defined in composer.json in the intial composer file repo.

Related links

• Drupal 10 Cambridge Profile - the Drupal profile that contains our drupal configuration and implementations of components.
• Cambridge initial composer file - the composer configuration that pulls together this theme with the drupal profile.