Scald Migration: From Drupal Images to Scald Media Management

ArticleJanuary 9, 2014


Scald Media Management is a Drupal media management module that can replace Drupal’s default images and allows you to curate and reuse media as entities across your whole site. Scald is for more than just images though, you can use Scald to effectively manage videos (including YouTube, Vimeo, and DailyMotion), audio, images, and Flash files out to the box. On top of that, Scald has an API that will allow you to add even your own media capabilities. I’ve begun to recommend Scald as a great solution for sites, small and large, that have to curate media content beyond anything but the simplest use cases.

To use Scald effectively, you do have to embrace the Scald way of things. That is, Scald has a nomenclature of its own and the installation process of getting media on a node and presenting it well is more involved than what we’re used to out-of-the-box with Drupal. That said, Scald is well conceived, easy for the end user to use, and an elegant solution to a common problem. I’ve put together a glossary at the bottom of this post which tries to break down how Scald works and the terms it uses.

This post is a technical one about migrating a site from utilizing Drupal’s Image module to using Scald to manage those resources and more, but I hope that you’ll also be able to use it to write your own migrations for the Media module and other solutions that may have hit their limitations on your site.


I decided to write a migration module for a client who came to Elevated Third wanting a better way to manage a number of images. The site had a number of photo galleries which pulled from a couple hundred images that were in fields scattered throughout the site. They had seen Scald in use on another project of theirs and really appreciated its simple UI. Besides those, there were a few images that were used for banner slides and other miscellany around the site.

For a site of this size , I think it was right at the point where doing it by hand would be just as much effort as it would be to write some code. As a dev, I’ll take code over point-and-click any day. Other advantages to this approach were that I could be sure I hadn’t accidentally missed a node here or there and I could quickly and completely migrate their dev site without messing with production until everything was fully approved. Then, I could rerun the migration on production and have that done in under 30 minutes. I would definitely go the migration route again and would be willing to take on even smaller sites now that the grunt work is done.

What You’ll Need

  • Views Bulk Operations
  • Scald
    • Enable Scald Core Sub-module
    • Enable Scald Image Sub-module
    • Enable Atom Reference Sub-module
  • Entity API
  • Experience writing a custom module/Willingness to learn and basic understanding of Drupal’s hook system.

The Process

This post goes in tandem with an example module I’ve made available on GitHub. You probably can’t read just this or just the module alone. Feel free to fork it, use it, correct it, or do whatever you want with it. It’s licensed under the WTFPL. I only ask that if you make it better, please submit a pull request for others’ benefit. You can find the module here:

Before you dig in to manipulating the above module, you’ll need to gather some basic info about your site and the migration you intend to run.

First, we need to know where all the image fields are on all our nodes. You can find a list of all fields on the site at Go ahead and take note of all the fields of type ‘Image (module: Image)’. My fields had name like field_thumbnail, and field_banner_image. Also, take note of the “Used On” category, this tells you all the nodes on which you have image fields. Next, go to and get the machine name of each of the content types you just collected from the last page. These will be all lower case and will often have underscores instead of spaces.

Now that we have that information, you can go ahead and go into each of those content types and make a sister field of type ‘Atom Reference’ for each of the image fields you collected info for above. I typically just call them all ‘Image (Atom)’ as you’ll be able to reuse that field for every other content type and simply change the context (kind of like an Image Style, but more versatile (see my glossary at the bottom of thie post) as necessary later on.

When you’re confident you’ve got your fields set up the way you want them, we can start coding.

In order to activate the migration for each node, I’ll be using hook_node_update($node). This will be triggered every time a node is resaved. There are caveats to this method of course, on a live site where you might not be in control of all node updates during the migration, you probably wouldn’t want to use this hook as other users might fire off a migration unknowingly, but on a small site where I’m not too worried about that, I can use Views Bulk Operation to resave nodes in bulk.

At this point much of what needs to be explained is the code itself. I’ve thoroughly documented an example module here on GitHub which will walk you through every step of code and explain what each line does.

Again, feel free to submit a pull request. Please just try to follow Drupal coding standards and the git-flow model (here’s a helpful toolkit). I hope that you’ll consider using Scald on your sites and give it a try, it really is worth it.


Scald has a lot of funky terminology and it can be a little overwhelming, but this complexity is well-intentioned and makes Scald really flexible. It arises from the fact that Scald tries to strip away as many assumptions as it can and provide a versatile way to interact with the media it helps manage. That lack of assumptions means you’ll have to put things together for yourself though. I’ve tried to break down what you need to know here, but there’s a more detailed and verbose breakdown of Scald on the site.

  • Scald - Scald is Content, Attribution, Licensing, and Distribution
  • Scald Core
    • Scald Core is the heart of the module, but provides little in the way of UI. It porvides the API that other modules use to perform CRUD actions on Scald Atoms (see below). Scald core abstracts away the type of media that it’s dealing with and makes no differentiation between images, videos, code, etc.
  • Providers
    • Those ‘other modules’ mentioned above are called providers. They provide the implementation the IS media specific. Allowing you to add an image or a video and making the assumptions you need that Scald didn’t make for you. I.e. The Scald Image provider (which comes with Scald) assumes that you need to know a file location, a height and width, etc. while Scald Youtube (also included) doesn’t need to store a file location, but just the URL of the video. It also provides the code that creates the necessary markup for a YouTube video as opposed to a local image file.
  • Library
    • Scald uses a drag and drop feature to add media atoms to nodes. To enable this user interface, you need to enable the dnd modules that Scald ships with.
  • Scald Atoms
    • Scald Atoms are Drupal entities. This means they are manageble by Drupal and entirely ‘fieldable’, e.g. you can attach a text field to and Image Atom to act as a caption. They also can have their own pages and displays.
    • The provider module, see above, define Atom types like Image and Video. They add the necessary fields for each media type to the Drupal entity and a few standard ones like an Authors taxonomy and Tags taxonomy.
  • Contexts
    • You’ll often want to display media differently based on the the context it is presented in. For example, in a media browser or node edit form, you may not want to show an image the size of your screen, but just a thumbnail of it; so for every Atom type, you can define different contexts which determine how that media will be presented.
    • At first glance, you’ll want to think of these as synonymous with Drupal’s image styles that we’re used to. In a way you’d be right, often these contexts will use image styles, but how do you apply an image style to an audio file? You can’t, and for this reason, what Contexts really are is a set of standard transformations Scald should perform on media before it is presented, based one where it is being displayed or played. They call what transforms the media, a transcoder (see below). Finally, contexts also allow you to choose a player, i.e. you might have two different ways that you want to play a local video file, maybe HTML5 or Flash.
  • Transcoder
    • For images, this might just be Drupal’s image styles. For audio, maybe you’ll write a transcoder that clips out a 30 second sample of a song as a preview before a purchase.
  • Player
    • The last step of presenting the media. As mentioned above this might be a choice between HTML5 markup vs a Flash player.