Overview

This article will try to explain the structure & logic of our WordPress theme, located in src/theme.

We use WordPress as our CMS, so please read the WordPress docs first.

Quick Start

Development

Setup your .env file. The local database credentials are set up there - if you skip this step, you will run into database connection issues.
Start Lando via lando start. That will setup and start a local WordPress environment.
Run npm run dev:theme. This will compile all assets and starts watching for changes.

Build

Run npm run build:theme. This will compile/copy all necessary files to app/wordpress/wp-content/themes/letters-from-tartu.

Guidelines

Third-party dependencies

WordPress and plugins that the project uses should be installed via Composer. This means that updating WordPress and plugins should also be done via Composer, not via WordPress admin. This helps to ensure that all developers use the same versions of WordPress and plugins.

In order to install some commercial plugins, you need to define some environment variables in .env and auth.json files in the root of the project. If you don’t have those files, create them from .env.example and auth.json.example.

Commercial plugins can also be installed via Composer. Supported commercial plugins are:

Advanced Custom Fields Pro

To install ACF Pro via composer, define WP_PLUGIN_ACF_KEY in .env. Then run composer require advanced-custom-fields/advanced-custom-fields-pro.
WP Rocket

To install WP Rocket via composer, define WP_PLUGIN_WP_ROCKET_EMAIL and WP_PLUGIN_WP_ROCKET_KEY in .env. Add a post-install script to your composer.json:
```
"scripts": {
  "post-install-cmd": [
    "cd app/wordpress/wp-content/plugins/wp-rocket && composer install --no-dev"
  ]
 }
```
Then run composer require wp-media/wp-rocket.
Gravity Forms

To install Gravity Forms via composer, define WP_PLUGIN_GF_KEY in .env. Then run composer require gravityforms/gravityforms.
WP Migrate DB Pro

To install WP Migrate DB Pro via composer, add your username and password to auth.json. Then run composer require deliciousbrains-plugin/wp-migrate-db-pro.
WPML

To install WPML via composer, define WP_PLUGIN_WPML_USER and WP_PLUGIN_WPML_KEY in .env. Then run composer require wpml/wpml-multilingual-cms. If you need additional WPML plugins, add the package definitions to composer.json and install similarly.

Structure

The file structure can be visualized like this:

theme/
├── acf/
├── gotoAndCore/
├── gotoAndPlay/
├── inc/
├── vendor/
├── 404.php
├── archive.php
├── author.php
├── footer.php
├── functions.php
├── header.php
├── index.php
├── screenshot.png
├── single.php
└── style.css

First read about WordPress template logic and then let’s go through the list:

theme/acf directory includes all ACF custom field configuration files.
theme/gotoAndCore directory includes all core theme files.

You should never need to change these files.

If you need to change these files, contact our core team first.
theme/gotoAndPlay directory includes all files for theme logic. See more below.
theme/inc directory includes all assets from styleguide. Never change files here, since they are automatically generated by npm run dev:theme.
theme/vendor includes all third-party plugin files installed via composer. Never change files here, since the folder is not in VCS and will be overwritten by the next install.
404.php is error 404 template file.
archive.php is archive template file.
author.php is author template file.
footer.php is global footer file. Includes logic from Timber plugin, you should not need to change this file.
functions.php is global functions file. A theme does not work without it.

Our theme is initialized in this file.

Here you can define global constants that will be used in the theme.
header.php is global header file. Includes logic from Timber plugin, you should not need to change this file.
index.php is index template.
screenshot.png screenshot displayed in the WordPress admin theme selection.

This file should be changed before going live.

Ask the designer or project manager for a new screenshot.
single.php is the default template for all post types.
style.css style css for WordPress theme information.

This file is automatically generated, you do not have to change it.

gotoAndPlay folder

This is the main folder that will be manipulated during the development process.

Folder is divided into:

gotoAndPlay/
├── Models/
├── Plugins/
├── Shortcodes/
├── Templates/
├── Traits/
└── Theme.php

Let’s go through the list:

Models Folder for models. Read more about models.
Plugins Folder for plugins. Read more about plugins.
Shortcodes Folder for shortcodes. Read more about shortcodes.
Templates Folder for templates. Read more about templates.
Traits Optional folder used for traits. Read more about php traits.

PHP only supports single inheritance: a child class can inherit only from one single parent. Traits are the solution for this problem and are used to declare methods that can be used in multiple classes. Traits can have methods and abstract methods that can be used in multiple classes, and the methods can have any access modifier (public, private, or protected).
Theme.php This file is an entry point to our theme.

The Theme class constructor will initialize all necessary plugins, shortcodes, register our post types, enable required theme support for WordPress functionality, register nav menus and build javascript data object that is passed to the frontend.

Copy environment