In essence, Attachments is an API that can be used to leverage power over attached media in WordPress through PHP functions. It works similar to the way Featured Images do but gives you more access to the metadata of attached media.

What’s It Do?

Attachments add a meta box to the bottom of posts and pages which allow you to attach or associate any kind of media that WordPress accepts that post. Then, you can use some baked in functions to output those attachments in your theme files. The values of these attachments can be customized to include WYSIWYG boxes, drop-down menus, and text. By default, you will be able to attach an image (or document or basically any filetype) along with a title and caption. These attributes can then be called on and returned easily.

If you need to decouple media from the standard body of your post so that they can be output in a unique way (maybe outside the post?) then this can be useful. Or if you want to include links to several attachments. Or if you want authors to easily upload images without having to worry about layout. Or many different things I can’t think of.

Everything with Attachments happens on the back-end, and is up to you, the developer, to integrate into your theme files. It’s very flexible and simple to use and kind of gets out of the way so you can do what you want with it.

How’s It Work?

I’ll start off by saying that the Official Documentation for Attachments is superb and you should go there if you are trying to figure out how to get the most out of it. What follows is more of a basic overview so you can get the idea.

Basically, the Attachments plugin consists of Instances and Output. Instances describe the actual piece of media that will be attached to posts or pages and any metadata that is associated with them. This basically means that this media will be associated with the Post/Page ID. By default, this is simply an image, a title as a text field and a caption with a WYSIWYG editor. However, custom instances can also be set up with any combination of images, text and WYSIWYG boxes, so you are not limited to the default. Output describes the way this data called on in theme files within the WordPress loop just like the_content(); or the_title();. With a few functions you can output the image, the title, the caption or any combination just as you might with, say, custom fields.

So as I said the custom instance includes three parameters. An image, a text field labeled “Title” and a WYSIWYG area labeled “caption.” If you need to include something else in your instances, you can define these in your functions.php file:

function my_attachments( $attachments )
{
  $fields         = array(
    array(
      'name'      => 'My Text Field',                         // unique field name
      'type'      => 'text',                          // registered field type
      'label'     => __( 'Text Field', 'attachments' ),    // label to display
      'default'   => 'Hey there',                         // default value upon selection
    ),
    array(
      'name'      => 'option',                            // unique field name
      'type'      => 'select',                            // registered field type
      'label'     => __( 'Option', 'attachments' ),       // label to display
      'meta'      => array(                               // field-specific meta as defined by field class
                    'allow_null'    => true,            // allow null value? (adds 'empty' <option>)
                    'multiple'      => true,            // multiple <select>?
                    'options'       => array(           // the <option>s to use
                          '1'     => 'Option 1',
                          '2'     => 'Option 2',
                      )
                  ),
  ),
  );

  $args = array(

    // title of the meta box (string)
    'label'         => 'My Attachments',

    // allowed file type(s) (array) (image|video|text|audio|application)
    'filetype'      => null,  // no filetype limit

    // include a note within the meta box (string)
    'note'          => 'Attach files here!',

    // fields array
    'fields'        => $fields,

  );

  $attachments->register( 'my_attachments', $args ); // unique instance name
}

add_action( 'attachments_register', 'my_attachments' );

What we’ve done here is defined a new instance with two separate fields. This will be added as a meta box to the bottom of posts and pages. When a user selects an image as an attachment, they will also be provided with a text field labeled “My Text Field” and an option box labeled “option.” The rest are just some additional settings, like labels and options for the select menu. Then we assign it a unique name with $attachments->register which we will use in our theme files.

Visit any post or page to see this in action. By default, you’ll see a meta box with an “Attach” button in it. If you’ve created a custom instance, you will see a separate meta box with this second instance in addition to the default. When you click on “Attach” the WordPress media uploader will load. You can either upload a new image or select from your media library. After you’ve included this, you will be prompted to enter the associated metadata. Again by default, this is a title and caption. But it can be whatever you want with custom instances.

The next step is to output the attachment and data on your theme. This can be done in your single.php file inside of the WordPress Loop. What you basically have to do is call the attachment associated with the post, and then output however you like. For instance, to output a simple list:

<?php $attachments = new Attachments( 'attachments' ); ?>
<?php if( $attachments->exist() ) : ?>
  <h3>Attachments</h3>
  <p>Total Attachments: <?php echo $attachments->total(); ?></p>
  <ul>
    <?php while( $attachments->get() ) : ?>
      <li>
        ID: <?php echo $attachments->id(); ?><br />
        Type: <?php echo $attachments->type(); ?><br />
        Subtype: <?php echo $attachments->subtype(); ?><br />
        URL: <?php echo $attachments->url(); ?><br />
        Image: <?php echo $attachments->image( 'thumbnail' ); ?><br />
        Source: <?php echo $attachments->src( 'full' ); ?><br />
        Size: <?php echo $attachments->filesize(); ?><br />
        Title Field: <?php echo $attachments->field( 'title' ); ?><br />
        Caption Field: <?php echo $attachments->field( 'caption' ); ?>
      </li>
    <?php endwhile; ?>
  </ul>
<?php endif; ?>

This is really just a list of attributes but should give you an idea about how to retrieve certain kinds of data. You can output the Image or just the Source URL, and you can call individual fields with $attachments->field( 'FieldName' );. How you actually output everything is up to you. Maybe you want to put the image at the top of your posts, or to the side. Just include the relevant function and assign it some HTML markup. The plugin is flexible in that way. It basically works like custom fields, but specifically deals with media and metadata in a fairly accessible way.

There are actually lots more that can be done with the plugin, including outputting the data outside of the Loop, retrieving single attachments by ID and disabling the default instance. There’s also a search function that lets you query attachments for a certain string and then outputs those attachments. It looks like this:

 $attachments->search( 'lorem ipsum', $search_args ); 

To fully explore all that can be done with this plugin, I suggest you visit the Usage section of the documentation. It has lots of examples and more than enough to get you started.

Costs, Caveats, Etc.

Attachments is free and actively maintained to keep up with the pace of WordPress. Its code is hosted on GitHub if you feel as if you want to contribute.

Jonathan Christopher, the plugin’s developer, also made an add-on called “Attachment UI” which gives you a GUI for setting up custom instances and templates for outputting them to your page. It is available to Monday By Noon members.

There is also documentation on GitHub which walks you through all of the steps of the plugin and how to use it. If you are still having a problem after that, you can visit the support forums to ask for help.

Resources

• Documentation
• Support Forums
• GitHub Source