Important: If you are a current user of Attachments and have upgraded from version 1.x to version 3.0 please see this note. A failsafe has been put in place allowing you to instantly revert to the latest version of the 1.x branch.
I’ve been enjoying (read: gushing) over the updates to WordPress 3.5. Ever since we got our first look at the Media updates my head has been spinning. When I first saw that post I thought there was no way all that work could be done within a single dot release, but I was proven completely and utterly wrong. The WordPress team has pulled off what I see as the best release to date. Naturally, through these observations I couldn’t help but to think about how this might affect Attachments. My initial thought was that the new Media workflow might in fact remove the need for such a plugin:
Wicked beyond excited to see the new Media workflow in #WordPress 3.5 — hoping it kills Attachments!
— Jonathan Christopher (@jchristopher) July 13, 2012
It might seem odd that I’d make a post hoping for a plugin of mine to become obsolete, but Attachments has a solid place in my heart and if that workflow were to be instantly brought to every user of WordPress, it’d be a good day. After observing the stellar progression of the new Media workflow I noticed that there still is a definite need for Attachments, so I committed.
I’ve been working on Attachments for about three years. It was my first adventure into a decently scoped WordPress plugin and it’s taught me so much about the process and software development in general. I’ve learned a lot since writing the first version and the significance in change to the Media workflow in WordPress 3.5 made an otherwise difficult decision nearly trivial: Attachments was getting a full rewrite.
Presenting Attachments 3.0
Attachments 3.0 brings a lot of great features from Attachments Pro (which I consider to be version 2) but in a completely new way. The biggest new feature is the ability to create multiple instances of Attachments. That is to say you can have multiple meta boxes on post edit screens to house separate groups of Attachments. Further: you can customize the fields per instance. If your implementation doesn’t call for Title and Caption fields, you can take those out and implement any number of fields you’d like to use.
At it’s base, the Attachments workflow is similar to what it was, with simplicity as the goal. Once your instances and fields have been set up, you get a new meta box on applicable edit screens:
Everything from there on out is quite different to say the least. The biggest (and best) update is that Attachments 3.0 utilizes the new Media workflow in WordPress 3.5:
The UI for existing Attachments has also been given a nice update:
You can still drag and drop to reorder Attachments on the fly, and as mentioned earlier you can add as many of these meta boxes as you’d like.
So much has changed under the hood
Attachments 3.0 is a full rewrite from the 1.x codebase. I must admit that I made some poor design decisions when writing that for the first time, and didn’t fully understand how the storage and retrieval of post metadata worked. I implemented a wacky data storage design which has been completely restructured to something more sane. Further, you’ll notice that Attachments no longer has any options in it’s Settings screen. Everything has been moved to the code, and I much prefer it that way.
The only thing the Settings screen is used for at this time is facilitation of the migration process. Since the data storage has changed so much (for the better), you’ll need to utilize the migration functionality included in Attachments 3.0 to convert your Attachments from version 1.x to version 3.x. This is only required if you’ve been using Attachments 1.x and have just upgraded to Attachments 3.0. After upgrading, you’ll see this notice:
Following that link will bring you to the one-step migration process that will convert your old Attachments to the new data format. Your old database entries will be left as-is but no longer utilized, but as with every plugin upgrade it is very important that you back up your database prior to upgrading.
Reverse the upgrade to Attachments 3.0
If you do not want to migrate to Attachments 3.0 and immediately revert back to the last version of 1.x, add the following to your site’s wp-config.php:
define( 'ATTACHMENTS_LEGACY', true ); // force the legacy version of AttachmentsIf, however, you would like to proceed with the migration, there will be a few things you need to update. First you can follow the link to the migration script:
If you’d like a frictionless upgrade to Attachments 3.0 using the same meta box and fields you’re used to, you can use the defaults in the migration process and you’ll be good to go. However if you’d like to customize the instance and fields you’re migrating to, you can do that too! The first step would be to create your new instance. Instance creation is outlined in the Usage section of the documentation. If you’d like to disable the default instance (a single meta box on Post and Page edit screens with a Title and Caption field) you can do that by adding the following to your site’s wp-config.php:
define( 'ATTACHMENTS_DEFAULT_INSTANCE', false );It’s also possible to create your own custom instances.
Creating Attachments instances
I wanted to have a code-based method of registering Attachments instances for a number of reasons. Primarily I like the idea of versioning things like this instead of having the configuration sit as an option in the database. Secondarily I like the idea of being able to easily replicate an instance in a new project in a matter of seconds by copy and paste versus having to recreate it in an admin UI. Instance creation is facilitated by tapping into Attachments’ attachments_register action. You’ll make a call to $attachments->register() and pass in any number of parameters to customize your instance.
The inspiration for this was the way we register Custom Post Types in WordPress itself, and I enjoy that workflow and thought it made a lot of sense in this regard as well. You can find out more by checking out the Usage section of the documentation.
Field types
As indicated in the instance registration snippets, you also define your instance fields at that time. Field declaration must match the format of the snippet, but you’ll notice that there’s a type key for each field. As of Attachments 3.0, the only available field type is text, but I’ve got plans to not only add additional field types but also allow you to define and implement your own custom field types. If you’re ambitious, I’d love some community help in establishing the best way to facilitate this functionality extension. If you check out the project on GitHub can see how the text field has been implemented in prep for extension. I’d love to see some pull requests in this area.
Pulling data to your theme
As with previous versions of Attachments, you’ll need to edit your theme’s template files to retrieve Attachments’ data. The old way wasn’t too bad, but I like the new way quite a bit more. Essentially you instantiate Attachments and pass in the instance name you’d like to retrieve. There’s an optional second parameter that can be populated with a post ID if you’re looking to get Attachments data outside of The Loop. You then loop through the returned Attachments, doing with the data what you’d like.
The syntax is highly influenced by Pods because I like it so much. The call to $attachments->get() in the above example does in fact return the raw Attachment if you’d like to use that directly, but the utility functions should help save you some time. There’s much more information in the documentation for Attachments. Please have a look there for more details.
What about Attachments Pro?
Attachments Pro will continue to live on with it’s current user base. Licenses have been unavailable for the past six months or so and will continue to be unavailable as I’m encouraging users to use Attachments 3.0. A migration script is in the works but is not available quite yet. If you are a current user of Attachments Pro I would love to connect in hopes of getting as much test data as possible for the migration script to be released over the coming weeks. Attachments Pro will continue to work as advertised in WordPress 3.5 because the legacy structure has been left as is in WordPress core. For those of you who have purchased licenses to Attachments Pro: thank you so much. You’ve shown that developers are looking for that workflow and I’m glad the experience I gained from writing that plugin will continue to help you out with this new, free version with the same features.
Attachments 3.0 is cool, but WordPress 3.5 is terrific
I’m so pumped on the rewrite of Attachments, but it pales in comparison to my excitement about the new Media workflow in WordPress 3.5. The team of developers working on that feature are nothing short of impressive and in particular I think we all owe @nacin and @koop a round of applause. The code for the new Media workflow is powered by Underscore.js/Backbone.js and like much of WordPress core, it’s worth studying. The extendability is supremely awesome and it made the rewrite of Attachments exponentially easier.
I really hope you guys enjoy Attachments 3.0 and the new Media stuff as much as I do, but I also want to encourage you to contribute back if you find bugs or optimizations that can be made either in WordPress core itself or Attachments. I’ve got the plugin on GitHub and would really love to see some pull requests.