Accessing Files and Images
The MasterPress API offers dedicated classes to represent files and images throughout your site, making it much easier to manipulate them in your WordPress themes. Files and images can be quickly loaded from your theme, content and uploads folders as a WOOF_File and WOOF_Image object respectively, and the same objects are used for the MasterPress File Upload and Image Upload field types to provide a consistent developer interface.
The WOOF_File class provides the basics for working with files, with highly convenient methods to output file date, type, file size and other properties, generate HTML links pointing to them, and the ability to delete (unlink) files (if permitted). The WOOF_Image class extends WOOF_File to provide resizing, cropping, image filters and processing via PHP’s GD component, and HTML image tag generation.
Accessing files and images from your theme folder
The WOOF class provides a plethora of convenience methods to load a file or load an image object representing the equivalent file in your theme folder. The class reference covers all of these in detail, but we’ll run through a few examples to see the general patterns we use. First though, let’s look at the way we typically bring images into our templates with standard WordPress code.
Suppose we have a file called “logo.png” inside an “images” folder in our theme folder. After a bit of time on Google, we find that we might create an image tag for the logo like this:
Example 1: The WordPress way to output an image from our theme folder
Okay, so it’s one line of code, and it seems to work – but it’s a little bit clumsy if we have to do this a lot, and personally I’ve never been able to memorise all of the bloginfo parameters. But suppose we have remembered it, or we’ve thrown it in some kind of snippet tool on our PC or Mac. Now sometime down the track, we start another WordPress theme, and decide to use a child theme since all the cool kids are doing that these days. We pull out our trusty code snippet and …. what? it doesn’t work! A bit more time on Google and in the codex, and we find that template_directory is only for the parent theme, and we should be doing this instead:
Example 2: THE WordPress way to output an image from our theme folder, version 2
Okay that works, but it took a little bit too much time to work out! Now let’s look at the MasterPress way:
Example 3: The MasterPress way to load a theme image
Much better. There’s a few things to note about this:
- We’re echoing a WOOF_Image directly – this is possible because this class implements PHP5’s __toString method to output an HTML tag pointing at the image, complete with width and height attributes.
- How did the call know that we stored our image in the “images” directory? WOOF::theme_image has a $base_dir parameter to take care of this, which is “images” by default. If you store your images somewhere else, We’ve also provided a preset method WOOF::theme_img to load images from the “img” directory instead, for the HTML5 boilerplate lovers out there.
Getting files from your WordPress themes is a similar process, with the difference being that there’s no way to “display” a file in HTML really, so we wouldn’t echo it directly. Let’s take a look at how to link to a file, in this case a photoshop version of our logo, stored in the “files” directory:
Example 4: Linking to a PSD version of our file
In WOOF_File we override __toString() to output a link to our file using the name of the file as the link text by default. Note that files don’t tend to have any particular conventional folder to store them in, so our theme_file method doesn’t have a default base directory, we just provide the path we need relative to the theme directory.
Automatic fallback from parent to child theme
The WOOF::theme_image and WOOF::theme_file methods have another argument $parent which is set to be “auto” by default. This setting allows these methods to handle child and parent themes in the most intelligent way – if our current theme is a child theme, the method will look for the file or image in the child theme folder first but will fallback to the parent folder if the child theme doesn’t contain the file. This is a nice behaviour, since it would allow you to, for example, make use of a default logo in a parent theme, but then drop in a replacement logo later on to automatically update the logo to the child version in your child theme.
Note that you can also set the $parent argument to true to force the parent theme folder to be used, or false to force the child folder to be used instead.
Checking if an image or file exists
To provide a developer interface consistent with the patterns around silent failure the WOOF_File class provides an exists method to flag if the file exists or not. Using this is simple:
Example 5: Checking if a file exists
Accessing files and images from your content and uploads folders
The WOOF class also has methods to access file and image objects for items in your wordpress content folder (usually “wp-content”) and uploads folder (which is usually at “wp-content/uploads”. Let’s look at an example showing a few of the different methods we can use:
Example 6: Accessing files from our content folder
Automatic fallback from blogs.dir to wp-content for WordPress multi-site
The WOOF::content_image and WOOF::content_file methods have another argument $main which is set to be “auto” by default. This setting allows these methods to deal with the multiple storage locations WordPress multisite uses for your assets – wp-content and wp-content/blogs.dir/SITE_ID – in the most intelligent way. The method will look for the file or image in the wp-content/blogs.dir/SITE_ID folder first but will fallback to the main wp-content folder if it wasn’t found in the site-specific folder. When WordPress is not running in multisite, these methods simply look for the file using wp-content as a base.
Accessing post attachments as files and images
Attachments are a built-in post type WordPress uses to store media attached to your post via the media library. There are a number of ways to access attachments in the MasterPress API. You can access attachments for a specific post using the WOOF_Post::attachments method, or you can query attachments using the WOOF::attachments method, both shown in the example below:
Example 7: Accessing attachments
Now that we have our attachment objects, how do we access the WOOF_File or WOOF_Image objects representing the files they encapsulate? Well, we don’t have to do anything really, since WOOF_File is a delegate class for non-image attachments, and WOOF_Image is a delegate for image attachments. The attachment object will decide which delegate is appropriate, based on whether the attachment is an image.
This means that we can, for example, call our WOOF_Image methods on image attachments easily:
Example 8: Easy thumbnails of image attachments
MasterPress Custom File and Image Fields
The MasterPress File Upload and Image Upload offer the methods of the WOOF_File and WOOF_Image classes through the class delegation mechanism. Specifically MPFT_File delegates to a WOOF_File object, and MPFT_Image delegates to a WOOF_Image object.
In short, this means that image and file fields are able to access the methods of these classes quite simply: