Anatomy of a VIP Go Theme

Overview #

This page explains the anatomy and structure of an example theme that might be used on VIP Go. It complements the Theme Handbook that apply to regular WordPress theme development. While every client’s themes will have different requirements and constraints, following this general structure will help ensure faster theme reviews and more efficient long term maintenance of your site.

When we create you a new VIP Go site, we will provide a GitHub repository under the wpcomvip GitHub organization. The repository for each VIP Go site has the following directory structure:

  • plugins — for your plugins
  • themes — for your themes
  • vip-config — for custom configuration changes
  • languages – for your translations
  • images – any shared images for all your sites
  • private – for any files which must not be web accessible (e.g. secret keys)
  • client-mu-plugins – for plugins that you want automatically load very early during the WordPress load process

↑ Top ↑

Theme Naming #

Themes in the VIP Go environment live in WP_CONTENT_DIR . '/themes/'. So if your organization is called Acme Kite Co., for example, your theme path might be /themes/acmekites/.

If you anticipate setting up multiple themes for your site or if you are a developer working on different themes for different sites, you might need a naming scheme that further distinguishes themes, e.g. /themes/acmekites-main/ and /themes/acmekites-seasonal/

↑ Top ↑

Plugin Locations #

On VIP Go, there is a dedicated plugin directory in the root of the theme’s Git repository. This directory works similarly to WP_CONTENT_DIR . '/plugins/' in a installation.

The plugins in this directory can be activated and deactivated from the standard Plugins menu in wp-admin. If a plugin is critical for a site to work, they can also be loaded inside the theme’s function.php file using wpcom_vip_load_plugin():

wpcom_vip_load_plugin( 'plugin-name' );
// Note this requires a specific naming structure: /plugin-name/plugin-name.php
// You can also specify a specific root file: wpcom_vip_load_plugin( '/plugin-name/plugin.php' );

When do these plugins run? #

Sometimes plugins may have dependencies on running before specific hooks.  Depending on how the plugin is loaded, it can be run at three different times:

  • /plugins – Before the plugins_loaded hook
  • wpcom_vip_load_plugin( 'plugin-name' ) – Before the mu_plugins_loaded hook
  • require_once( get_template_directory() . '/plugins/plugin-name/plugin.php' ) – Before the after_setup_theme hook

↑ Top ↑

What about Shared Plugins? #

The Shared Plugins on VIP are not available to load the same way on VIP Go.  Instead, these plugins should be added to the Git repository as if it were a custom plugin. Public Git submodules are supported, so it’s possible to add these directly to your Git repository (Example: Automattic/Co-Authors-Plus).

Presence of shared plugins in the mu-plugins directory is a legacy feature which should not be relied upon for future development. Existing sites should take any opportunity to add plugins they are loading from the shared-plugins directory to their /plugins directory (we are happy to assist with this). The wpcom_vip_load_plugin function will load a plugin from the /plugins directory before it references any version in shared-plugins.

↑ Top ↑

client-mu-plugins #

client-mu-plugins are scripts that are automatically loaded very early in the WordPress bootup process and do not need to be explicitly enabled or disabled. For multisite installs, the plugins are loaded on all sites on the network.

On VIP Go, these client-mu-plugins are loaded immediately after the platform-level vip-go-mu-plugins and follow similar behaviours:

  • loaded before the muplugins_loaded hook.
  • loaded in alphabetical order based on the filename.
  • only top-level files are loaded (additional files inside folders can be required by top-level files).

↑ Top ↑

Child Themes #

Child theme-ing works the same in this case as child theming on self-hosted WordPress sites. Just add another theme to your Git repository at /themes.  Because the themes on aren’t available in the Git repository, they will need to be added before they can be used as parent themes.

↑ Top ↑

functions.php #

Unlike VIP, there is no required code in the theme’s functions.php file.

↑ Top ↑

Using /private #

The /private folder in your repo, if used, will provide access to files that are *not* web accessible, but can be accessed by your theme or plugins. For example, if you place a file at /private/sites.json you can access that within your them with;

file_get_contents( '/private/sites.json' );

No visitor will be able to access that file at any URL, unless deliberately exposed via the theme or a plugin.

↑ Top ↑

Use Underscores for a head start #

The Underscores project will generate a starter theme that can be used to get a head start on your theme development. It includes lean, well-commented, modern, HTML5 templates, minimal CSS that’s ready for you to build on, and a variety of tools to help you work efficiently in customizing your theme


Ready to get started?

Tell us about your needs

Let us lead the way. We’ll help you select a top tier development partner. We’ll train your developers, operations, infrastructure, and editorial teams. We’ll coarchitect your deployment processes. We will provide live support for peak events. We’ll help your people avoid dark alleys and blind corners, and reduce wasted cycles.