1. Code
  2. Creative Coding

Sharing the WordPress Love With Non-Image Media Attachments

Scroll to top
Read Time: 9 mins

While WordPress easily displays images attached to your pages and posts (even without an attachment.php file), the other allowed media types (audio, video, document, text, archive, code, interactive) don't get the same love – save a direct link to the attachment file. But, you don't have to resort to uploading your audio, video, or other non-image media attachments elsewhere (like YouTube) in order to display them on your WordPress site. Using the default Twenty Eleven theme as an example, I'll show you WordPress' built-in functions for sharing the love with non-image media attachments.

How WordPress Handles Attachments by Default

Under the hood, media items are just WordPress posts, therefore, they are displayed according to the WordPress template hierarchy. The template loader does a check to see if the post is an attachment and has an attachment template. If an attachment template does not exist, WordPress will fall back to the single post template or the default index.php template (if the single post template does not exist).

Template Check

In the single post or index.php templates, WordPress themes will likely display the content using the_content. This function has a default filter attached to it – prepend_attachment – that will automatically add an attachment link to the page (using the wp_get_attachment_link function) if it determines that this is an attachment post. However, the arguments used here in the call to wp_get_attachment_link will only provide actual display for image attachments – non-image attachment files only get a direct link to the attachment file. (Where's the love?) We could potentially display more than just a link for non-image attachments with a simple change of arguments to wp_get_attachment_link, but unfortunately we don't have a way to change the arguments before the function is called.

Default Image Attachment Display vs. Default Non-Image Attachment Display

So let's take a look at what we can do to show our non-image attachments some love.

Taking Control of Non-Image Media Attachment Display

Step 1 Determine the File Type

The first thing we'll do is determine the file type of the attachment. WordPress allows uploading of several file types, found in the get_allowed_mime_types function shown below.

Default Allowed File Types

Although the Media Library admin screen only shows filters for the three default file types, the Edit page for each media item shows the exact file type. The file type is in the MIME format (MIME is a long-standing standard for classifying file types on the Internet) which has two parts: type and subtype separated by the /. In the image below, the type is "video" and the subtype is "mp4." This knowledge will come in handy for step 2.

Default File Types Shown in Media Library

File Types Shown on Edit Media Page

Built-In WordPress Function

WordPress has a built-in function for determining the file type of an attachment using the attachment post ID.

This function will return the file type in MIME format, just as it's shown on the media item's edit page in the admin.
Now we're ready to take control of displaying non-image attachments in our theme template files.

Step 2 Create Theme Template File

Template Hierarchy

As shown in the image, the WordPress template hierarchy has four possible attachment templates it will look for after it determines that we are displaying an attachment post. We can either handle the display of each file type in the attachment.php file or we can create separate template files for each MIME type and/or MIME subtype. Let's take a look at these options.

Option 1. attachment.php File

We can handle the display of each file type in attachment.php using our handy get_post_mime_type function.

First, we'll get the file type of the attachment (while inside the loop):

Then, we can do a switch statement on the file type to provide the code to display each type:

So if we'd like to display audio (mp3) and video (mp4) attachments, our switch statement would look like this:

Using attachment.php is great if you only have a few file types to display (or your display for each file type will follow the same basic layout) as it allows us to keep our code in one file. If we have several file types and/or you plan to customize the display layout for each file type, you'll want to take a look at option 2.

Option 2. $mimetype.php, $mimesubtype.php, or $mimetype_$mimesubtype.php

attachment.php is actually the fallback template for template files with the name of the MIME type or MIME subtype of the current attachment post. WordPress will look for files with names like $mimetype.php, $mimesubtype.php, or $mimetype_$mimesubtype.php before falling back to attachment.php.

So instead of calling get_post_mime_type and using a switch statement, we can just create a template file with the name of the MIME type or subtype:

  • audio.php
  • mpeg.php
  • audio_mpeg.php

and place the code to display that file type.

Note: The file names are listed in the order in which WordPress will call them. So $mimetype.php first, then fallback to $mimesubtype.php, then fallback to $mimetype_$mimesubtype.php.

Now let's look at some examples.


Displaying Documents

I don't know about you, but I personally dislike having to download a document to my computer just to view it. Let's enlist the help of the embeddable Google Docs Viewer. It can display PDFs, spreadsheets, presentations and many other file types listed in Google Help. There's no requirement for your documents to be hosted on Google Docs as it will embed a viewer right in the page by passing it a file URL and setting the embedded parameter to true.

Here's how we would handle displaying documents using the Google Docs Viewer in attachment.php after getting the file type:

Or, we could create one of the following template files:

  • application.php
  • pdf.php
  • application_pdf.php

and place the following code where you'd like to display the content inside the loop:

Notice that we are passing the URL of the attachment file to the Google Docs viewer using the wp_get_attachment_url function.

Final Result:


To display (play) audio files uploaded to WordPress and provide a consistent cross-browser experience, we're going to enlist the help of the lightweight audio.js library that allows us to use the HTML5 audio tag anywhere, falling back to flash in browsers that don't support HTML5 audio yet.

First, download and place the audio.js files in your theme. Then, in your functions.php file, add the code to enqueue the audio.js javascript on attachment pages only (following best practices). I'm sure there are other ways to do this – including using the recommended wp_enqueue_scripts action and some conditional statements – however, I'm going to illustrate the method in this article: Quick Tip: Including JavaScript and CSS Only On Certain Site Pages

Then, we can add the following code to our attachment.php file:

Here's our full switch statement up to this point:

Or, we could create one of the following template files:

  • audio.php
  • mpeg.php
  • audio_mpeg.php

and add our audio code inside the loop where we'd like to display the content:

Note: If you use file type template files, the JavaScript needs to be enqueued on those pages only.

Final Result:


We can display (play) video files uploaded to WordPress much the same as audio, except we're going to enlist the help of the video.js library that allows us to use the HTML5 video tag anywhere, falling back to flash in browsers that don't support HTML5 video yet.

Just as with audio, we'll download the files, add them to our theme directory, and enqueue the video.js javascript on attachment pages only, save for the addition of a CSS file:

Here's the full functions.php snippet:

Then, we can add the following code to our attachment.php file:

Here's our full switch statement:

Or, we could create one of the following template files:

  • video.php
  • mp4.php
  • video_mp4.php

and add our video code inside the loop where we'd like to display the content:

Remember: When using file type template files instead of attachment.php, you will need to change the name of the filter used to call the function that enqueues your JavaScript.

Final Result:


Non-image media attachments in WordPress need love, too! Using only two WordPress functions, you can keep your media files on your site and customize the display and layout of any of the allowed file types.

Download and/or fork the working code on Github.

References in This Article

WordPress functions

WordPress template files

  • attachment.php
  • index.php
  • single.php
  • $mimetype.php
  • $mimesubtype.php
  • $mimetype_$mimesubtype.php
Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.