Documentation Anatomy of a VIP Theme

Anatomy of a VIP Theme

Overview #

This page explains the anatomy and structure of an example theme that might be used on WordPress.com VIP. It complements the Theme Development guidelines 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.

↑ Top ↑

Theme Naming #

Themes in the VIP environment live in WP_CONTENT_DIR . '/themes/vip/'. So if your organization is called Acme Kite Co., for example, your theme path might be /wp-content/themes/vip/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. /wp-content/themes/vip/acmekites-main/ and /wp-content/themes/vip/acmekites-seasonal/.

↑ Top ↑

Plugin Locations #

Each theme should have a dedicated directory for custom plugins:

/wp-content/themes/vip/acmekites-main/plugins/

You can then load a plugin from this directory in your theme’s functions.php file:

require_once( __DIR__ . ‘/acmekites-main/plugins/plugin-name/plugin-name.php’ );

If you are developing plugins that might be used across multiple sites/themes, you can put them in a plugins directory not associated with a specific theme:

/wp-content/themes/vip/acmekites-plugins/

Plugins managed this way will live in a separate SVN repo and loaded using wpcom_vip_load_plugin:

wpcom_vip_load_plugin( ‘plugin-name’, ‘acmekites-plugins’ ); // note this requires a specific naming structure: /plugin-name/plugin-name.php

There is also a directory for plugins shared across all VIP sites, make sure you avoid this directory namespace in your development stucture:

/wp-content/themes/vip/plugins/

Plugins available to all VIP sites can be loaded using wpcom_vip_load_plugin as well:

wpcom_vip_load_plugin( ‘plugin-name’ );

↑ Top ↑

Child Themes #

WordPress.com VIP sites can create and use themes that are child themes of the themes available on WordPress.com. This allows you to build on the great themes already developed and tested for WordPress while incorporating your own custom features and styles. When the parent theme is updated or expanded, your child theme can take advantage of those changes without having to re-incorporate your customizations. Child theming works the same in this case as child theming on self-hosted WordPress sites.

↑ Top ↑

functions.php #

The functions.php file in your theme lays the groundwork for customizing the functionality of your theme.  You can read more about it in Functions File Explained. On WordPress.com VIP sites, the functions.php file must include the vip-init functions.  Here’s a sample VIP functions file for Acme Kites:

<?php

// Set a theme constant for later use
define('AK_DIR',__DIR__);

/**
* Standard VIP configuration
*/
require_once WP_CONTENT_DIR . '/themes/vip/plugins/vip-init.php';

// Site-specific Config
require_once(AK_DIR . '/functions/config.php');

// Custom widgets and sidebars for this site.
require_once(AK_DIR . '/functions/widgets.php');

↑ 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.

↑ Top ↑

See Also #