Anatomy of a VIP Theme

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

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

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 with:

wpcom_vip_load_plugin( 'plugin-name', 'theme' );

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 structure:

/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’ );

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. Each child theme is managed in its own SVN repository.

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.  

It is critically important that `vip-init.php` is included very early in `functions.php` – before any VIP constants or functions are used.

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');

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.

See Also

Related Posts

You can take advantage of the WordPress.com Related Posts functionality to return related posts quickly. Enable it by turning on Related Posts in Settings > Reading and you’re done!

If you’d like to programmatically retrieve and display posts within your theme code, you can do so like this:

$posts = Jetpack_RelatedPosts::init_raw()->get_for_post_id( $post_id, $args );

// Returns an associative array in the form of id => $post_id:
/*
array(
    array ('id' => 12345),
    array ('id' => 54321),
)
*/

Related Posts indexing will work regardless of whether your site is marked as “Private.” For self-hosted sites, Related Posts will currently only work for standard post-types; we are working on enabling it for custom post types.

For more information about ways to customize related posts, see http://jetpack.me/support/customize-related-posts/

High Traffic Alert

On WordPress.com, we serve 100+ million pageviews per day without blinking. However, sometimes you may be expecting a high traffic event where you may want to notify the VIP team for additional assistance.

To do so, please open a ticket with us with the following information:

  • Date and time of event:
  • Traffic expected:
  • Heavily trafficked pages:
  • Are there any external services, dependencies, or applications that use or rely on the site (e.g. mobile apps)? If so, how do these services interact with the site?

On VIP, we review every line of code to ensure that your site will perform under high traffic events. When you send in a high traffic alert, we will check through the theme again to ensure that it is performance-ready. Please notify us of the high traffic event as far in advance as possible so that there is enough time to resolve any potential issues.

As always, should you need our team immediately, please open a ticket with the word “urgent” in the subject line.

Creating Good Changesets

Changesets are the heart of any version control system, and making good changesets is vitally important to the maintainability of your code. As all code on WordPress.com VIP is reviewed by a real person, it’s even more important all changesets are well crafted.

Remember always code (and commit) for the maintainer.

A Good Changeset:

Represents one logical change

What comprises a ‘logical change’ is up for interpretation, but only directly related changes are included. Generally, the smaller the changeset, the better.

Good Example: Adding the CSS, JS, HTML, and PHP code for a new UI button.

Bad Example: Adding the new UI button, fixing whitespacing, and tweaking copy in the footer.

Bundles related changes together

It’s much easier to trace refactorings and other changes if related changes are grouped together. Rather than splitting a logical change into many separate commits, related changes should be combined.

Good Example: Refactoring code into a new plugin by moving it to a new file and including that file.

Bad Example: Refactoring code into a new plugin by putting the code removal, addition, and include into separate commits.

Is Atomic

An atomic commit means that the system is always left in a consistent state after the changeset is committed. No one commit would cause the codebase to be in an invalid state. The commit is easily rolled back to a previous valid state, including all related changes, without the need to analyze the potential interdependencies of neighboring commits.

Good Example: Adding a new feature to the homepage by committing the HTML / PHP changes alongside the required CSS / JS changes, so there is never an incomplete state (HTML elements without styling) in the codebase.

Bad Example: Committing the HTML changes and requisite CSS / JS separately. The first commit represents an inconsistent state, as the feature can exist in the DOM without being properly styled.

Is Properly Described

Accurately describing the changes is very important for others (and future you) looking at your code. A good commit message describes the what and why of a change. Please see Writing Good Commit Messages for more information.

User_meta vs User_attributes

User Meta

As you read in our what we look for documentation, we don’t allow the use of user_meta. The reason for this is that WordPress.com is an incredibly large multisite and user_meta is all stored in one cache key. Therefore anything stored in user_meta will be loaded on every page load. Another reason is that as the user_meta grows to over 1MB it can no longer be stored in memcache.

User Attributes

User_attributes are a drop in replacement for user_meta. They perform in exactly the same way with the small exception that you cannot have multiple values for the same user_attribute meta_key. You can find the function declarations in vip/plugins/vip-do-not-include-on-wpcom/wpcom-functions.php. These are functions that imitate the behavior of user_attributes on your local dev environement. This means you can code against them without needing to have the cache or table schema that runs on WordPress.com.

While the code you will see in that file looks just like a layer on top of user_meta on WordPress.com, user_attributes are stored in the cache on an individual basis and not globally. This means that requests to user_attributes by meta_key and user_id are cached individually and not grouped by user_id and loaded all at once per page load.

You can use user_attributes as a drop in replacement for user_meta. That means:

update_user_attribute( $user_id, $meta_key, $meta_value )

get_user_attribute( $user_id, $meta_key )

delete_user_attribute( $user_id, $meta_key, $meta_value = ” )

will all work as expected. Just remember, the meta_key are shared among all of WordPress.com so prefix them. As with user_meta you shouldn’t store large quantities of data (several KB), and lastly, since just like user_meta meta_key or meta_value on user_attributes isn’t indexed you shouldn’t query against them.

Custom Error Pages

We have error pages that are standard and served for all sites on WordPress.com, and as a VIP customer you can override these defaults and specify your own custom error pages instead.

Setting it up is simple: all you need to do is add a custom error page (a simple HTML file) to your theme.

The file needs to be located in a folder called “error-docs” and named “error-page.html”. Note that the file can only contain HTML and basic inline or remote-hosted CSS and Javascript.

I.e., from the root of your theme: ~/error-docs/error-page.html

Once you’ve committed the file to your theme, you’ll need to open a ticket with our team to notify us, so we can make some associated configuration changes on our end.

Editor’s Guide to WordPress.com VIP

Welcome to WordPress.com VIP!

We believe that WordPress.com VIP is a partnership between WordPress.com and some of the most high-profile, innovative and smart WordPress websites out there. We’re excited to have you here.

This page is to help managers and editors onboard their editorial team onto WordPress.com VIP. It includes information and resources to help you train your team. If you have any questions, please don’t hesitate to contact us through the VIP tab in your site dashboard.

Training Resources

Useful Features for Editorial Teams

Useful VIP Plugins for Editorial Teams

Advanced WordPress.com Features for Editors

Learn from WordPress Experts

Developer’s Guide To WordPress.com VIP

Welcome to WordPress.com VIP!

We believe that WordPress.com VIP is a partnership between WordPress.com and some of the most high-profile, innovative and smart WordPress websites out there. We’re excited to have you here.

This page is to help developers prepare their code for WordPress.com VIP. It includes information on how to set up a site on WordPress.com VIP, and how to communicate with the VIP team. As always, if you have any questions, please don’t hesitate to contact us through the VIP tab in your dashboard.

Getting Started

Quick Links

Important Documentation

Helpful Resources

Learn from WordPress Experts

Site Owner’s Guide To WordPress.com VIP

Welcome to WordPress.com VIP!

We believe that WordPress.com VIP is a partnership between WordPress.com and some of the most high-profile, innovative and smart WordPress websites out there. We’re excited to have you here.

This page is to help site owers and project managers navigate the world of WordPress.com VIP. It includes information on how to set up a site on WordPress.com VIP, and how to communicate with the VIP team.

A call with the VIP team kicks off the collaborative process. We review your launch timeline and introduce you to the VIP platform and development tools. We are happy to use this time to consult with you on the best setup, plugins, and tools for your site’s needs.

Next, we set up access to some of the tools and documentation spaces that we use, as well as send out questionnaires covering more detailed technical aspects on your content migration, theme and plugin requirements. This is then followed up with a technical meeting.

At this point developers need to start setting up their development environments which involves setting up your local environment, enabling the VIP code scanner and setting up the development IDE to support WordPress coding conventions. The scanner is an essential tool and will help developers to produce secure and performant code.

Next, you will build your website using one of our themes or alternatively start from scratch most likely using a starter theme. You will also integrate custom plugins or leverage our pre-vetted library of community and partner plugins.

We then review the theme and work with your team on any possible issues. Once any issues have been corrected, the code is submitted to SVN / Git (depending on your platform) and your developers or partner developers are given access. From this point onwards changes to code are made via the deploy queue. On WordPress.com CSS changes are deployed immediately with other changes being deployed after review by one of our developers

Please be aware that the initial theme review can take between ten and fifteen days and it is essential that the code passes the VIP scanner before submitting to us. If there are blockers in the code, theme review will be delayed.

At this stage we should know your user and content migration plans and the requirements for SSL will also need to be figured out. We will also work together to establish your final launch date.

The content migration must be carefully prepared and we will work closely together on making this as clean as possible. Please keep us up to date with changes to the content migration timeline as delays here can threaten the launch date.

On launch day, our team schedule engineers to be around to assist your team in realtime. We usually have a live chat open with your team to help ensure a fast response time for any last-minute questions or needs. We look forward to having a successful launch with you!

Getting Started

Quick Links

Information for Your Team

Learn from WordPress Experts

Cloud Hosting FAQ

Frequently-asked questions about our VIP Cloud Hosting. Have a question that’s not answered here? Get in touch. 

1) We don’t yet have a WordPress theme – how should we get started with WordPress.com VIP Hosting?

If you’re building a theme from scratch, we suggest using the WordPress default themes, Twenty Ten, Twenty Eleven, or Twenty Twelve, as they use the recent APIs, are cleanly coded, and provide a good foundation for your work. You should start your theme as a Child Theme instead of modifying Twenty Ten/Twenty Eleven/Twenty Twelve directly. All WordPress.com public themes are available at https://wpcom-themes.svn.automattic.com/.

2) We already have a theme on a self-hosted WordPress site. Will we be able to use it on VIP Hosting?

Yes, probably! As part of the setup process the VIP team will review your theme for any errors or code that needs to change to make sure it’s a good fit for our environment. We also require the use of GPL-licensed plugins and themes or 100% custom ones. If you’re not sure about what you’re using, just ask!

3) How long does the theme review process take?

Once you have your theme fully built and tested in your local environment, the theme is ready for us to review. We generally need 10-15 business days to do a full theme review. You’ll send it to us in an email as a zipped attachment.

4) Can we use X plugin?

Yes, probably! There are +23k WordPress plugins, and you can use most.  We review each plugin to be sure it’s enterprise quality, secure, and will scale with your site’s traffic.  Legacy methods of modifying database tables and manipulating the file system are also traits of plugins we try to avoid, and will work with you to use modern approaches such as Custom Post Types and in-memory file manipulations. We also have a bunch of popular plugins already pre-installed and ready for use. If you are interested in using a plugin that isn’t available as a pre-approved VIP plugin, we will review it for stability, performance, and security before it can be used on WordPress.com VIP.

We also recommend using existing WordPress functionality whenever possible instead of a plugin. If you are not sure if a function exists, try a quick search of a descriptive keyword/field name or similar on one of the many WordPress code documentation sites such as https://developer.wordpress.org/http://phpdoc.wordpress.org/trunk/, http://wpseek.com/, or http://hitchhackerguide.com/function-filter-action-index/

5) Can we use X caching plugin?

You won’t need any caching plugins on WordPress.com VIP Hosting. WordPress.com employs multiple levels of caching automatically. For cases when you are sure that you cannot use a function that contains caching and need to do something that is resource intensive, you should implement some caching yourself using the WordPress cache.

6) How will we access our code?

All WordPress.com code is managed using the Subversion (SVN) revision control system. SVN is the only way to access and update code on VIP Hosting. After your theme has been reviewed, you will be able to use your WordPress.com username and password to access the code for your theme using Subversion. The VIP team will review and handle all deploys for your site, and your developers will get deploy notifications automatically.

7) How does staging work?

VIP clients for the most part have staging servers in-house. A few clients choose to use one of their VIP-package sites as a pre-production site, but any code must be tested and debugged prior and aligned with our coding standards. Think of this pre-production site as a way to test integrations with WordPress.com features that don’t have WordPress.org equivalents (via Jetpack or other plugins).

8) Can we have custom database tables on WordPress.com?

Themes and plugins should use the existing database tables and structure (no alterations). Custom Post Types, Custom Taxonomies, post meta, etc. are incredibly flexible as an alternative to custom database tables.

9) Can we use plugins or code that modify the filesystem?

For security and performance reasons we do not allow plugins or code that write directly to the filesystem.  We’ll work with you to modify the code to avoid local file system manipulations.

10) How do we register user accounts?

By default, users registered through VIP-hosted websites are created as WordPress.com users, which means that the millions of users logged in to WordPress.com will also be logged in on your domain, making it easier for them to comment on your site. If you’d like to be able to query user data or create custom registration fields you’ll need to use a 3rd-party registration service.

11) Is WordPress.com VIP running stock WordPress, or are there tons of custom modifications?

WordPress.com is running mainly off core WordPress, but uses some alterations and optimizations which are unique to our large-scale environment, including a lot of very cool features built right in for all users. WordPress.com is constantly evolving, which means that VIP clients often have access to the latest features and WordPress releases well before the rest of the world. Easy-to-use shortcodes and other built-in features replace the need for many custom plugins.

Have a question that’s not answered here? Get in touch. 

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.