The AudioTheme framework was specifically built to extend WordPress and provide unique functionality for music-oriented websites without changing the way themes are created. If you’re already familiar with building WordPress themes, you will only need to learn how the framework and its APIs work to use it in a custom theme.

Framework Structure

The major features in the framework have been broken out by classification into separate subdirectories within the plugin. Discography, gigs, and videos each have their own subdirectory with related functionality.

Within each subdirectory, a post-template.php file is included containing the template tags available for retrieving or displaying data within themes.

When building themes, it’s a good idea to keep in mind that the framework was built in such a way to create as little friction as possible for end-users, so most information may be considered optional. Themes should take this into consideration.

Discography

The discography feature consists of two custom post types:

• audiotheme_record
• audiotheme_track

Records can be thought of as any song or collection of songs that will be promoted, so albums and singles (radio singles, digital singles, etc) would both be added as records. Tracks are the individual songs in a record. Tracks should always have a record as a parent.

Records can be assigned an audiotheme_record_type taxonomy.

Gigs & Venues

The gigs feature consists of two custom post types:

• audiotheme_gig
• audiotheme_venue

The relationship between gigs and venues is managed using the excellent Posts 2 Posts core. Venues don’t have a permalink or templates and will typically only be displayed as metadata for gigs. Storing them as CPTs allows for reuse and provides administrative capabilities for end-users.

The default gig archive template will show all upcoming gigs.

If a custom loop is needed aside from the built in templates or widgets, a wrapper for WP_Query() has been provided to make it easier to retrieve gig and venue data in a consistent way without needing to account for the relationship. Use AudioTheme_Gig_Query() the same way you would use WP_Query().

Date and Time

Users may not know the time of some gigs when they’re initially saved, therefore, the time may be left blank until it is known. The framework takes this into consideration by storing the time metadata separately under the _audiotheme_gig_time key.

Use get_audiotheme_gig_time() when displaying any date or time values to take this into account and allow for a fallback value, such as “TBD”, if the time is empty.

Feeds

There are a few default feeds built in for gig listings to make it easy for visitors and services alike to consume the gig data. Built-in formats include RSS, iCal, and JSON.

These feeds can be accessed at their corresponding gig archive or permalink endpoints. For instance:

• The upcoming gigs RSS feed can be accessed at: /{{slug}}/feed/
• A JSON feed for gigs in 2012 can be accessed at: /{{slug}}/2012/json/
• An iCal feed for a specific gig can be accessed at: /{{slug}}/{{postname}}/ical/

Videos

The videos feature consists of a single custom post type and a few template tags to make embedding videos from third parties easier:

• audiotheme_video

Archives

Each CPT with an archive has a corresponding audiotheme_archive CPT to give end-users the ability to customize archive properties from within the dashboard. By default, this allows for updating the title, adding an introduction or description, and even changing the CPT slug using the standard interface for editing permalinks. In addition, it gives users a new meta box on the Appearance → Menus screen in order to easily add archives and keep them updated if the permalink structure is changed.

For the most part, nothing special needs to be taken into consideration aside from being aware that this new data can be incorporated into a theme.

Also, since the archives have a corresponding CPT, you can take advantage of this fact to add new meta boxes for further customization of archive screens. For instance, you can allow users to change the number of posts that display on a particular archive, or if your archive is a grid, allow the number of columns to be modified.

Template Structure

Theme Templates

The template structure is based on the WordPress template hierarchy, with a couple of minor changes. The templates specific to AudioTheme custom post types should be included in an /audiotheme/ subdirectory within your theme. The following templates can be used:

• archive-gig.php
• archive-record.php
• archive-video.php
• single-gig.php
• single-record.php
• single-track.php
• single-video.php

Why a plugin?

The framework was built as a plugin to ensure the functionality and data created through the framework is portable. This means the theme isn’t responsible for registering custom post types (CPTs), taxonomies, and saving metadata in an esoteric format that other themes aren’t aware of. Ultimately, this gives end-users the freedom to switch between compatible themes without worrying about losing their data, and provides a consistent experience no matter the theme.

The plugin approach proved to offer the most flexibility in terms of extensibility and maintenance and is really a best practice in the WordPress environment, despite any confusion that might arise from users needing to install a plugin *and* a theme.

We felt it provided the greatest amount of freedom and control for end-users and developers alike.

Notes

Naming Conventions

Anything in the framework that could potentially conflict with other plugins should be prefixed with audiotheme. Custom post types (CPTs), taxonomies, function names, metadata keys, etc. all follow this convention.

Public theme template tags and API functions deviate slightly from the standard approach and lead with a verb, followed by the prefix. This approach was taken to improve readability and help differentiate between functions meant for public use and those that are for internal use. For instance:

• get_audiotheme_gig() instead of audiotheme_get_gig()
• enqueue_audiotheme_tracks() instead of audiotheme_enqueue_tracks()
• the_audiotheme_video() instead of audiotheme_the_video()
• is_audiotheme_post_type_archive() instead of audiotheme_is_post_type_archive()
• Not all public functions lead with a verb, but the majority do.

Take the audiotheme_save_venue() function name — it can be difficult to tell if it’s a function that should be called directly, or if it’s a hook attached to the save_post action. By using the adopted naming convention, you can be pretty sure that it’s a hook that you shouldn’t call directly. Instead, there might be a function called save_audiotheme_venue() for public use.

To further differentiate, hooks that could be mistaken as an API will generally be suffixed with _hook. In this case it would be audiotheme_save_venue_hook() so that you know to not call it directly.

Preventing Errors and Notices

If you don’t want the theme to generate errors and notices if the framework isn’t active, then try to restrict usage of framework functionality to AudioTheme-specific templates.