Engage Theme for CME

Engage is a Timber-powered WordPress theme for The Center for Media Engagement at the University of Texas at Austin.

Note: This repo includes the entire WordPress installation. However, the only directory you should work on is wp-content/themes/engage-2-x. Avoid making changes to other files as they are tied to live sites.

Installation

Summary

1. Install WP Engine Local App.
2. Connect with the CME WP Engine account.
3. Download mediaengagement.org from Local App.
4. Clone this GitHub repo and fetch.
5. Install npm dependencies.
6. Start development.

For full installation instructions, refer to the development guide.

Local Development

Engage 2.x is forked from the Timber Starter Theme. You can follow the Timber Composer installation guide for additional setup details.

Steps:

1. Clone the repo and navigate to the theme directory:

   cd yourSiteName/app/public/wp-content/themes/engage-2-x

2. Check Node and Yarn versions:

   node -v
   yarn -v

3. Install dependencies:

   yarn

4. Install Timber via Composer:

   composer require timber/timber

5. Activate the engage-2-x theme from WP Admin → Appearance.

6. Run the development server:

   yarn watch

7. Before pushing changes, compile assets for production:

   yarn prod

Debugging Local App Connection

If you encounter issues with the Engage theme:

1. Check the Local App setup:

   • Switch the web server to nginx.
   • Ensure PHP version is 8.2.10 or higher.

2. Switch to a default theme:

   • Rename the engage theme folder to force WordPress to switch to a default theme.
   • Disable all plugins except for ACF.
   • Rename the theme back and reactivate it in WP Admin.

3. Install Timber Dump Extension (if needed):

   composer require hellonico/timber-dump-extension

4. Deactivate the Engaging Quiz Plugin: It is known to cause issues.

Deployment (for project leads only)

Github Actions deploy to each site via public/.github/workflows/*.yml files. See WP Engine Branched Deploys to WP Engine with GitHub Actions for instructions and enp-platform Actions to view workflow processing. Pushing changes to the master branch does not deploy to the dev site.

1. Notify Kat before pushing updates to the live site.

2. Compile production assets:

   yarn prod

3. Merge and push changes to the development site:

   git checkout dev && git merge master && git push

4. Merge and push changes to the staging site:

   git checkout stage && git merge master && git push

5. Notify Kat before pushing to the live site.

6. Merge changes to the production site:

   git checkout stable && git merge master

   :wq + enter

7. Push to the production site:

   git push

Sync Production Database → Development

Only for your Dev environment. This will not touch uploads or code—just the DB.

1. Make sure you’ve set your SSH keys as described in ssh/sync-db.sh.

2. Confirm you have the Yarn script in your package.json:

   {
   	"scripts": {
   		"sync-db": "bash ssh/sync-db.sh"
   	}
   }

3. From the theme root, run:

   Dev Site

   yarn sync-db-dev

   This will:

   • Export the Production database
   • Stream it into Development
   • Search-replace your live URL with the dev URL
   • Flush the WP cache

   Staging Site

   yarn sync-db-staging

   This will:

   • Export the Production database
   • Stream it into Staging
   • Search-replace your live URL with the staging URL
   • Flush the WP cache

4. Verify by spot-checking a few pages and custom post types in your Dev site.

ACF Field Group Syncing

Overview

ACF field groups are automatically synced across environments via JSON files in the acf-json directory.

Steps to Sync:

1. Field group changes are automatically saved as JSON in acf-json when updated in WP Admin.
2. Pull changes from the repo to sync ACF fields on your local environment.
3. Commit and push any changes after updating field groups to share them with the team.

Hiding ACF Admin in Production:

• The ACF admin is hidden on production and non-local environments by checking WP_ENVIRONMENT_TYPE. It is only visible in local environments.

WP-CLI updates

Local users: Run WP-CLI from the Local app’s Site Shell (right‑click the site → “Open site shell” or equivalent). Commands run from your normal terminal can’t reach the database and will fail with “Error establishing a database connection.”

Run the commands below from the WordPress root (e.g. app/public in your local site folder) or use --path:

wp core update
wp plugin update --all
wp theme update --all

To update a single plugin or theme: wp plugin update <slug> or wp theme update <slug>. List what’s outdated with wp plugin list --status=update-available and wp theme list --status=update-available.

Reverting a bad core update

Before running wp core update, note your current version: wp core version. If the site breaks after updating, reinstall the previous version:

wp core update --version=6.4.2

Use the version number you noted (or the last known good release from wordpress.org/support/wordpress-versions).

Additional Information

• Timber Documentation
• Local Development