Thesis Skin API

Although they are similar to WordPress themes, Thesis Skins are more powerful because of all the functionality they inherit right out of the box.

Like Boxes, Skins are deeply integrated into both WordPress and Thesis, giving you the ability to create admin pages, manage options, and exercise precise control over content.

To tap into the awesome power of the Thesis Skin API, you must first create a Skin.

Connect to the Thesis Skin API

Just like Boxes, Thesis Skins are a classic example of object-oriented programming (OOP). Through the concept of inheritance, every Skin receives basic functionality and access to the awesome Skin API.

class my_skin_class_name extends thesis_skin {
	/* Skin properties and methods go here */
}

In PHP, object inheritance is achieved through the extends keyword, as seen in the above snippet. In this case, thesis_skin is the base Skin object—it contains all the basic Skin functionality coupled with the Skin API, which can be used by the extending object (your Skin).

Now that your Skin is alive and kickin’, let’s take a closer look at the Skin API options.

Thesis Skin Options

Unlike Boxes, all Skin properties and methods are optional. Because of this, your Skin could, in theory, be no more complicated than the example code shown above.

However, if you want your Skin to be dynamic and interesting, you’ll need to add some options. Lucky for you, the Thesis Skin API makes this process both easy and fun.

Let’s take a trip down the rabbit hole, shall we?

construct() — The Constructor Method

The Skin pseudo-constructor runs at the beginning of each page load (both on the admin side and front end). If you need to initialize hooks and/or filters for your Skin, this is the place to do that.

protected function construct() {
	/* initialize 
}

Note: If your Skin contains display options, then you’ll need to place your display filters inside the construct() method.

boxes() — Register Special Skin Boxes

Default Thesis Boxes cover basic website functionality, but some Skins may require custom Box functionality to achieve their purpose. In this case, the developer must do the following:

  1. create a custom Box (or Boxes) using the Thesis Box API
  2. place all custom Skin Boxes in a separate Skin file called box.php
  3. include custom Boxes via the boxes() method

Here’s the general syntax for the boxes() method, which expects you to return an array of custom Box class names:

protected function boxes() {
	return array();
}

Assuming a Skin that has two custom Boxes, my_cool_box and my_sample_box, here’s what your boxes() method would look like:

protected function boxes() {
	return array(
		'my_cool_box',
		'my_sample_box');
}

If you’ve registered your Boxes properly, they’ll either “just work” or appear in the Skin Editor, depending on the particular Box types. There is one special case you should be aware of, though.

If your Skin needs to register a Box that should only appear as a dependent of another Box and never deployed on its own, then you should leave that Box class out of the boxes() method shown above.

Finally, if your Skin only has one Box, and that Box is a dependent Box, then simply include an empty boxes() method in your Skin.

display() — Content Display Options

All Thesis Boxes are equipped with display filters that allow them to be included or omitted from Skin template output on the front end. Skin display options leverage these filters to bring a configurable output experience to the user.

From the perspective of a Skin developer, display options are really cool because they enable users to bring your creation to life in new and unexpected ways.

Like other options structures within Thesis, display options consist of a reserved method and reserved property:

protected function display() {
	return array();
}

/* property reference within Skin class */
$this->display['option_id'];

In the above code, the display() method should return an array in Thesis Options API array format.

By their nature, display options are simple and can be expressed in a binary on/off format—either a Box is set to display, or else it’s suppressed. Because of this, checkboxes are the input element of choice for display options in the Thesis interface.

But there’s one little problem here…

With so many Boxes and potential display options, your Skin’s Content page (Thesis Admin → Skin → Content) can get overwhelming in a hurry.

In the interest of keeping things simple for users, we recommend using a set of option objects to represent your display options.

Using an option object set will minimize the display options interface and enhance clarity for users. For additional insight into creating a display options array, check out the Classic Skin skin.php file.

Using Filters to Finalize Display Options

After setting up your display options array, you’ll need to incorporate filters before your display options will function properly.

Depending on the purpose and output of your Skin, you likely won’t need to use all of the available filters. With that in mind, here is more information on the Thesis Box display filter naming convention.

It is entirely up to you, the Skin developer, to incorporate these filters and to shore up the functionality of your display options. We recommend adding these filters to your construct() method, which was introduced above.

Attention! Supplying a display() method only initiates the display options interface and allows display data to be saved. It is up to the Skin developer to activate Box display filters based on saved data.

design() — Design Options

Because they add customization flexibility, design options can make a Skin far more useful and appealing to a broad range of users.

With Thesis, adding design options to your Skin is easy; simply use the reserved method and property shown below:

protected function design() {
	return array();
}

$this->design['option_id'];

Like other options structures in Thesis, the design() method should return an array in Thesis Options API array format.

Adding a Color Scheme Picker and the Thesis ColorScale

The Skin API contains a turnkey color scheme picker that includes awesome technology known as the Thesis ColorScale. Two aspects of Thesis’ color scheme picker make it superior to all other color scheme pickers out there.

First, the ColorScale can translate your original grayscale input into any color in the color cube. This means users can choose a color they prefer, and your original grayscale will be translated into the color space they’ve chosen.

Second, Thesis includes a complementary color picker that you can use to find just the right “pop” in your color scheme. Using any color as a starting point, Thesis can determine its complements and allow you to choose one that works well with your existing color scheme.

Follow these instructions to add a color picker to your Skin.

Design Options Customization

If your Skin includes design options, Thesis will add a “Design” page to the admin interface. Typically, this functionality is entirely automated, but you can override certain aspects of it with reserved methods and/or the Skin $filters property.

Overriding Default Design Options Functionality

If you want to add functionality to your design options that cannot be achieved through the normal means (maybe you have a crazy new interface idea that you’d like to try…), then you may wish to supply your own admin page.

Important! If you supply your own design options admin page, you’ll also need to handle the saving of your design data, too.

There are two ways to achieve this:

  • Add the reserved design_admin() method to your Skin and have it echo the output of your admin page.
  • Use the $this->filters['design_admin'] property to designate the name of the method you’d like to use for your design options admin page.

In some cases, you may also need to supply your own CSS or JS to make your design options page function as desired. To do this easily, you can use the reserved init_design_admin() method to enqueue your stylesheets or scripts at precisely the right time.

You can also completely turn off automated Thesis design options functionality by supplying your own design options URL.

This is accomplished through the $this->filters['design_url'] parameter, which should only be used if you want your design options admin page to live outside of Thesis.

Making Design Options Work

Design options don’t have any effect on a Skin unless the developer integrates saved design options data in some way.

Typically, design options only affect CSS, and the most efficient way to manipulate CSS is through the use of variables.

Because of this, the Skin API includes a special method that allows you to modify your Skin’s CSS variables based on your design options. Let’s take a closer look, shall we?

css_variables() — Manipulating CSS Variables Based on Design Options

By including the reserved css_variables() method in your Skin, you’ll be able to exercise complete control over not only your CSS variables, but also your entire stylesheet.

public function css_variables() {
	return array(/* 'variable_reference' => 'new value' */);
}

The premise behind the css_variables() method is simple—just return an associative array of CSS variable references and their new values, and then Thesis will generate a stylesheet with this new data.

In practice, there are many things you might wish to do within a css_variables() method, and ultimately, the sky is the limit here.

Leveraging Thesis APIs to Manipulate CSS Variables

To make life easier, you’ll want to use parts of the Thesis API when manipulating CSS variables. Whether you’re substituting font stacks, calculating typography and spacing, or setting CSS properties, the Thesis API will reduce both mistakes and the amount of code needed to get the results you want.

For example, the Classic Skin uses the following parts of the Thesis API:

For a much more in-depth look at CSS variable manipulation, check out the Classic Skin skin.php file and, specifically, the css_variables() method.

header_image() — Header Image Uploader

To add a simple header image uploader to your Skin, simply include a header_image()> method and have it return a suggested header image width (in pixels), like so:

protected function header_image() {
	return 900;
}

Adding the above code to your Skin would trigger a header image admin page with a suggested upload width of 900 pixels.

In reality, you would never simply return a hardcoded value of 900, as shown above. Instead, you’d probably want to perform a width calculation based on the current state of the design options.

Adding a Header Image to Your Skin

As you might have already realized, being able to upload and save a header image is only half the battle—you still need to add the image to your Skin if one is present.

To deal with this process, the Skin API contains a special method, header_image_html(), that you can simply hook into place wherever you want the header image to appear. For example, the Classic Skin contains the following code inside its construct() method:

add_action('hook_bottom_header', array($this, 'header_image_html'));

That bit of code hooks the header image HTML output into place at the bottom (just before the closing tag) of the HTML Container Box with a hook name of header.

One of the best aspects of the header_image_html() method is the fact that you don’t have to set up any conditionals based on whether or not the user has specified a header image. All the conditional logic is contained in the header_image_html() method itself, so simply hooking the method into place is sufficient.

Adding Header Image CSS

In the section above, you learned how to add header image HTML to your Skin output, but that’s only half the battle. In all likelihood, you’ll still need to add some CSS to ensure that header images display perfectly in your Skin.

You can use the Skin filter_css() method for exactly this purpose (and indeed, that’s precisely how the Classic Skin incorporates CSS for header images).

filter_css() — Skin CSS Filter

If you need to add CSS to either the beginning or end of your CSS file, you can accomplish this easily by adding a filter_css() method to your Skin.

It works just like a normal filter, except you don’t have to take the step of adding the filter because Thesis already knows precisely what you want to do with it:

public function filter_css($css) {
	$new = 'my new css';
	return $css. $new;
}

The code in the above snippet would cause my new css to be added to the end of the CSS when the file is written.

This type of structure is perfect for adding things like header image CSS or especially font inclusion declarations for Google Fonts, Adobe Edge Web Fonts, or @font-face rules.

meta_viewport() — Viewport Meta Tag for Responsive Websites

If you’ve built a responsive web design, then you’re familiar with the viewport <meta> tag, which is helpful for achieving predictable results across a variety of devices.

Adding this tag to your Skin is simple—just include a meta_viewport() method, and return the eventual contents of the content="" portion of the <meta> tag. For example, including this in your Skin:

public function meta_viewport() {
	return 'width=device-width';
}

…will result in the following code in your Skin’s document <head>:

<meta name="viewport" content="width=device-width" />

There are quite a few different properties you might wish to include in your viewport meta. In testing, however, we’ve found the above declaration, width=device-width, to provide the most consistent, least wonky experience across the widest array of devices.

admin_ajax() — Admin Ajax

If you need to add an ajax behavior to your Skin, then you need to add an action—a hook, essentially—that fires when your ajax action occurs.

Typically, you’d just include the appropriate action declaration in your construct() method, and you could indeed do that here.

In this case, however, Skins already have quite a few ajax actions in place, so it would be better if you could just add your action to that list.

By using the admin_ajax() method you can add your custom ajax actions to an appropriately bulletproof place in your Skin:

protected function admin_ajax() {
	add_action('wp_ajax_my_custom_action', array($this, 'my_ajax_method'));
}

public function my_ajax_method() {
	global $thesis;
	/* The code you place here will run whenever your ajax action occurs. */
	if ($thesis->environment == 'ajax') die();
}

In the above code, the admin_ajax() method is self-explanatory, but my_ajax_method() requires additional explanation.

Notice the global $thesis and then the if-statement in that method—these are necessary to ensure that Thesis exits the AJAX process properly. You’ll want to include them in your ajax methods just as you see them here.

fonts() — Fonts

If you want to add fonts to your Skin that aren’t supported by the Thesis core, you should add them via the fonts() method.

Simply return an array of your new font(s) in Font API array format, and Thesis will add your font(s) to font <select> elements in the interface and also use your font(s) in typographical calculations, as appropriate.

For example, the following code will add the Adelle font from Typekit to your Skin:

protected function fonts() {
	return array(
		'adelle' => array(
			'name' => 'Adelle',
			'family' => 'Adelle, serif'));
}

Please note that it is still up to you, the Skin developer, to include font-family references in your CSS. The fonts() method is only intended to register your font(s) for use within the Thesis interface and also in typographical calculations.

packages() – Packages

Deprecated! Packages are deprecated in Thesis 2.1 and will be removed from the core in version 2.2.

SCSS/LESS CSS Preprocessors

Incredibly, the Thesis Skin API also contains out-of-the-box support for both the SCSS and LESS CSS preprocessors. You don’t have to install any files or set anything up—simply tell Thesis which CSS preprocessor you want your Skin to use, and BOOM.

CSS preprocessors are enabled via the Skin $filters property, which is a catch-all property that allows you to modify various default Skin behaviors. In this case, the specific code you’ll want to use is:

protected $filters = array(
	'css_preprocessor' => 'scss'); // this is for SCSS; use 'less' for LESS

Note: If you elect to use a CSS preprocessor, Thesis will disable Packages in the Skin Editor.

Also, if you’re using SCSS, make sure your SCSS variable names do not conflict with your Thesis CSS Variable names. Thesis allows you to use both types of Variable references at the same time so you can incorporate Design options and CSS Variable modification while still using SCSS.

The power here is incredible; if you’re accustomed to using SCSS or LESS, using either one with Thesis will blow you away.