Threespot WordPress Sandbox

About

This is a repository to try out custom plugins, custom Gutenberg blocks, etc. Get wild, but not too wild.

Child Theme

The twentytwenty-child directory is a child theme based off the WP Twentytwenty. Use this to test simple custimizations.

Hosting

This site is hosted on Pantheon on the Basic plan (details). It's running on WordPress 5 on PHP 7.1. Redis cache is not available to sites on the Basic plan.

Local Development

In order to more easily recreate the production environment locally, Lando is used for local development. We also use Pantheon’s CLI, Terminus, to sync files and databases.

Prerequisites

1. Install git

   • Windows installer
   • macOS
     • Check if already installed with $ git --version
     • If not already installed, you will be prompted to install it.

2. Install Lando (Windows, macOS)

3. Install Terminus, Pantheon’s CLI tool

4. Install Composer

   • Windows instructions
   • macOS
     • Install Homebrew
     • Run $ brew install composer

5. Install NodeJS 8.x (Windows, macOS)

   • Note: We recommend asdf for managing multiple versions of Node

6. Install Yarn (Windows, macOS)

   • Note: Yarn is a faster alternative to npm install

   Add ENV File

Create a .env file. Update it so that it looks something like the following:

DB_NAME=wordpress
DB_USER=wordpress
DB_PASSWORD=wordpress

# Optional variables
DB_HOST=database
# DB_PREFIX=wp_

WP_ENV=development
WP_HOME=http://APP_NAME.lndo.site
WP_SITEURL=${WP_HOME}/wp

# Generate your keys here: https://roots.io/salts.html
AUTH_KEY='generateme'
SECURE_AUTH_KEY='generateme'
LOGGED_IN_KEY='generateme'
NONCE_KEY='generateme'
AUTH_SALT='generateme'
SECURE_AUTH_SALT='generateme'
LOGGED_IN_SALT='generateme'
NONCE_SALT='generateme'

#plugin keys
ACF_PRO_KEY=`pluginkey`

Starting local server

1. Clone this repo

   $ git clone git@github.com:Threespot/threespot-wp-sandbox.git

2. Open threespot-wp-sandbox folder in the terminal and install Composer dependencies

   $ composer install

3. Start the local server

   $ lando start

   1. If everything was successful, you should see something like this:

      Your app has started up correctly.
      Here are some vitals:
      
       NAME                  threespot-wp-sandbox
       LOCATION              /Users/yourUserName/Sites/threespot-wp-sandbox
       SERVICES              appserver_nginx, appserver, database, cache, edge, edge_ssl, index
       APPSERVER_NGINX URLS  https://localhost:32774
                             http://localhost:32775
       EDGE URLS             http://localhost:32776
                             https://threespot-wp-sandbox.lndo.site/:8000
                             https://threespot-wp-sandbox.lndo.site/
       EDGE_SSL URLS         https://localhost:32777
      

4. Clone the database and files from Pantheon

   $ lando pull

   1. Use the arrow keys to select “none” for the code, since we pulled the code from GitHub:

      ? Pull code from?
        live
        dev
        test
      ❯ none
      

   2. Select “live” for the database:

      ? Pull database from?
      ❯ live
        dev
        test
        none
      

   3. Select “live” for the files (NOTE: ALDF has ~4,000 images, so if this takes too long you can select “none” to skip this but you will not see any images locally)

      ? Pull files from?
      ❯ live
        dev
        test
        none
      

5. You should now be able to view the site at https://threespot-wp-sandbox.lndo.site/

   1. Your browser may warn you that the site is not secure, this is expected. Click though the warning message to proceed.

      

6. You should be able to login to the admin at https://threespot-wp-sandbox.lndo.site/wp/wp-admin/

Troubleshooting

If the site fails to load, try the following:

• Restart the server

  $ lando restart

• Rebuild the app

  $ lando rebuild

• Destroy and recreate the app

  $ lando destroy && lando start

• Check current version of Lando to see if there’s an update available

  $ lando version

Starting Webpack with live reload

If you plan to make CSS or JS updates, you must run Webpack to recompile and inject the CSS and JS.

1. In a new terminal window, navigate to the threespot-wp-sandbox project folder again

2. Navigate to the theme folder

   $ cd /web/wp-content/themes/threespot-wp-sandbox

3. Install npm dependencies using Yarn

   $ yarn install

4. Start Webpack

   $ yarn start

   1. You should see the following:

      [HTML Injector] Running...
      [Browsersync] Proxying: https://threespot-wp-sandbox.lndo.site
      [Browsersync] Access URLs:
       -----------------------------------
             Local: https://localhost:3000
          External: https://10.0.5.35:3000
       -----------------------------------
                UI: http://localhost:3001
       UI External: http://localhost:3001
       -----------------------------------
      [Browsersync] Watching files...
      

5. You should now be able to view the site locally at https://localhost:3000

6. To stop the server, press Control + C

Troubleshooting

1. If the server won’t start or gets caught in an endless loop, try stopping and restarting it.
2. If the server starts but the site doesn’t appear at https://localhost:3000, check that devUrl in config.json matches the URL generated by Lando (e.g. https://threespot-wp-sandbox.lndo.site)

Updating Dependencies

To update WordPress or any free plugins to the latest version, run $ composer update and push the updated composer.lock file to GitHub. To update any paid plugins, you will need to manually update the files and commit.

To update the Node dependencies, run $ yarn upgrade-interactive from the theme folder (threespot-wp-sandbox/web/wp-content/themes/threespot-wp-sandbox) and select the packages to update. Once installed, push the updated yarn.lock file to GitHub.

It is technically possible to install plugins via the WordPress admin with Pantheon (docs) but this isn’t recommended since it makes it difficult for multiple developers to stay in sync.

Deployment

Every time code is pushed to GitHub, CircleCI will build and deploy the files to Pantheon’s dev environment. You can tell CircleCI not run by adding [skip ci] to the commit message.

Once code has been deployed to the dev environment, you can switch to the “Test” tab and click the “Deploy Code from Development to Test Environment” button to deploy to http://test-threespot-wp-sandbox.pantheonsite.io.

After the updates have been tested, you can deploy to the live site by following the same process on the “Live” tab.

Tech Stack

Back End

• Bedrock framework
  • Places core WordPress code in a separate folder (required for Pantheon)
  • Composer integration
  • Environment variable support
  • Supports autoloading regular and must-use plugins
• Sage theme framework (docs) with Soil plugin
  • Supports Laravel’s Blade templating engine
  • Supports controllers (docs) to keep views DRY
  • Includes Webpack for processing front-end assets (config)
    • Sass linting, compilation, browser prefixing, and minification
    • JavaScript linting, transpilation (i.e. converting ES6 to ES5), bundling, and minification
    • Image compression (config)
    • Live reload with BrowserSync
• Community support for both frameworks can be found at https://discourse.roots.io

CSS

• Threespot’s CSS reset
• Threespot’s Sass library (docs)
  • Most often used functions and mixins:
    • fs-rem—Helper function converts pixels to rems
    • fs-color—Helper for retrieving a color from the $fs-colors map
    • fs-min-width/fs-max-width—Media query helpers to convert fixed pixels to rems
    • fs-media—Media query helper that supports any condition, and multiple conditions
    • fs-scale—Allows for smoothly scaling values from one viewport width to another
    • fs-attention—Helper mixin adds :hover, :focus, and :active states
    • fs-svg—Function to export URL-escaped inline SVG for use in background-image (SVGs are stored in $fs-svg-icons map)
• SUIT CSS class naming convention, e.g. .ComponentName-child--variation

JavaScript

• Modernizr used for CSS grid and object-fit feature detection

• External JS dependencies are listed in the dependencies section of package.json:

  View dependencies

  • @threespot/expand-toggle

  • @threespot/fluid-iframe

  • @threespot/fluid-svg-polyfill

  • @threespot/freeze-scroll

  • @threespot/mailto

  • @threespot/object-fit-image

  • @threespot/unorphanize

  • console-polyfill

  • flickity-fullscreen

  • fontfaceobserver

  • lodash

  • mdn-polyfills

  • picturefill

  • what-input

  • Custom JS modules can be found in the /resources/assets/scripts folder

The site JS is split into three files:

• critical.js—Contains code that needs to run before content is displayed in the browser to prevent a FOUC (e.g. check is JS is enabled, check if fonts have previously loaded)
  • NOTE: This code must be manually minified and copied to critical-js.blade.php (easier than setting up a custom build script since this code won’t change often)
• main.js—Contains all other site JS, with the exception of image galleries; loaded at the bottom the <body> tag