Stowers

Craft 4 project for Stowers

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Requirements

Your local environment must meet the following requirements:

• PHP 8.2
• MariaDB 10.11
• Apache web server
• A minimum of 256MB of memory allocated to PHP
• A minimum of 200MB of free disk space
• Composer 2
• npm v16.13.1
• Editor Config plugin installed and enabled in your preferred code editor.

Installation

Setup

• Create a .env file at project root based on .env.dev, adjusting to account for the appropriate values to connect to your local DB (if you use the ddev setup, this will be automatic).
  • NOTE: The source of truth for these .env values is in the "ENV vars" section of the Fortrabbit app. This .env.dev file is just for reference/ease of initial setup, and should be updated should any of these values change or new ones added.

DDEV

Install Colima (or Docker Desktop) and DDEV.

On the command line, navigate to the project directory and start DDEV.

ddev start

Pulling Down a Database

You need to get a copy of the database imported locally, so you can fully run the site. On the production site, you can navigate to Utilities > Backup to download a current backup.

Once you have your backup, you can import it locally.

ddev import-db --file=/path/to/db.sql

Composer Install

Craft uses Composer to fetch software dependencies. Every time we set up a new environment, we need to run composer install. Since we're using DDEV for localhosting, we'll run it right on the container using the ddev exec subcommand.

ddev composer install

Wait for this complete. When it's done, you should have a vendor directory in the root of the project.

Accessing the Site in the Browser

DDEV is already set up to host the site at the following local domain:

https://stowers.ddev.site/

You can also launch the front end or admin CP directly from the command line:

ddev launch
ddev launch admin

Development Setup

• cd to project root and run the following:

npm install
npm start

Gulp's default task will run through processing the development files and watch for changes.

Workflow

Front End

Most of the time, you'll be working in the following directories:

templates/ (html/twig)
ui/ (css, js, img)

Templates are authored in Twig per Craft defaults, and are not processed by gulp (they are watched, however, for live reload on changes). This project uses Tailwind CSS 3.1 and vanilla JavaScript bundled by webpack.

For any changes made to scss or js files, the default gulp task will compile to web/tmp/ for your local server, and files generated from npm run build task will be minified and sent to web/dist/. Staging and Production environments are set to use these minified files, so you'll want to run a build and commit the result before deploying.

Please ensure you have Editor Config installed in your code editor and are respecting the rules set in the .editorconfig file.

Neo Blocks

This project includes a custom Craft module, NeoBlocks, in order to restrict certain Neo blocks in the modules field (under the "Unique Modules" group title) in the CMS from displaying to the author unless an "Enable Unique Modules" field is set to true.

This allows the standard block/module set to stay consolidated for most use cases.

Build

To run a build:

npm run build

NOTE: This task will automatically swap your .env ENVIRONMENT value to 'staging' so you can verify the minified bundles easily on your local server. This will swap back to 'dev' when you run the default start task.

Deployments

This project is hosted on Servd and is using the Servd Assets and Helpers Plugin.

Once you have access to the app, you can download a current database backup from the Servd dashboard, or Craft CMS CP under Utilities > Database Backup. Once your local site is set up, you can use the Servd plugin to download database backups from production at any time:

ddev exec php craft servd-asset-storage/local/pull-database --from=production

Or assets (see below note):

ddev exec php craft servd-asset-storage/local/pull-assets --from=production

Accessing the Site in the Browser

DDEV is already set up to host the site at the following local domain:

https://stowers.ddev.site/

You can also launch the front end or admin CP directly from the command line:

ddev launch
ddev launch admin

Additional Notes

Multi-site entry relations limitation

You may occasionally notice a strange bug with Call to Action fields where selecting the Grad School version of an entry that exists on both sites will return the Institute version on the front end. There is a limitation of Craft at the time of creating this site where site IDs are not included in entry relations. This is currently an open issue and until this gets addressed in core, there really isn't any elegant way around it.

A workaround in the meantime is to just switch to a "Custom Link" type, and insert a relative link to the path you're looking for, like /gradschool/entry-slug. Then, hopefully once this is addressed in core, you can update the link macro and delete this note.

Resources

• Bitbucket Repository

Reference

• Craft 4 Documentation
• Twig Documentation
• Sass Documentation
• Tailwind 3.1 Documentation
• Webpack Documentation

Authors

• R.J. LaCount, Christine Hager, and Nick Katarow via Turnstyle