Cross-Platform Projector Publishing in Director MX 2004, Part 2

When we last left off, we were knee-deep in the creation of our masterpiece cross-platform Projector in Director MX 2004, one that consists of a single button that launches a PDF file. Exciting stuff, to be sure, but we're only halfway there. Join me as we continue our journey, this time as we venture outside the cozy confines of DMX04 and into the equally exciting world of moving files and manipulating text documents. And with a buildup like that, how could you not be breathless with anticipation?

Step 3: Take a little trip outside Director

As I've more than likely mentioned already, where things really start to get interesting (as it were) in Director MX 2004 is the ability to output cross-platform Projectors from a single authoring platform. Indeed, the title of this article would seem to back up that assertion, so I really should stop wasting valuable words on that particular tangent. Anyway, while cross-platform publishing is definitely something to cheer about, It's not patently obvious how to successfully publish this way when Xtras are involved. As you know from last time, the mini-project we're doing involves launching a PDF file through the use of the Buddy API Xtra (available at http://www.mods.com.au/budapi/), and while it's been possible for a while to include a dedicated Xtras folder alongside your Projector as a means of distributing Xtras, it's always a cleaner user experience to embed the Xtra directly into the Projector itself. But in MX04, doing so requires a little field trip.

The first thing we need to do here is to grab the Buddy API Xtra. Regardless of the platform you plan to author on, you'll need to download both the Mac and the Windows versions (as of this writing, the Mac version is at 1.51, and the Windows version is 3.60). Once you've got those (and, if you're on Windows, a utility such as Stuffit Expander to decode the .hqx archive the Mac Xtra comes packaged up in), we're ready to put the Xtras where they need to go.

On both platforms, Director's application folder houses a directory called Configuration, and it is here that the three items we are interested in reside (fig. 1).

Figure 1: The three parts of Director's Configuration directory that shall concern us today.

The first is the Xtras directory, where you will stash the platform-native version of whichever Xtra you want to install:

Mac users:

• Unarchive the "bm151.hqx" file you downloaded from the Buddy API site.
• Open the resulting "Buddy API 1.51" folder that the archive created.
• Choose the correct folder for your OS (Classic or X), and move the Xtra ("Buddy API Xtra" for Classic, "Buddy API OSX Xtra" for X) into your Director Xtras folder. Considering that Director MX 2004 doesn't even run in Classic, I suspect most of you will be needing the X version.
• If you're on OS X, which, again, you probably are, rename "Buddy API OSX Xtra" to simply "Buddy API Xtra." Why you're doing this will become clear a little later.

Windows users:

• Unarchive the "bx360.zip" file you downloaded from the Buddy API site.
• Open the resulting "bx360" folder that the archive created.
• Move the Xtra ("budapi.x32") into your Director Xtras folder.

A quick note: Buddy API is a very thoroughly authored Xtra, and as such the developer has included dummy Xtras for the opposite program in each platform-specific version. However, since we did our homework last time and know that the full Buddy API Xtra for each platform will suffice, we can ignore all the other Xtras included in the distribution for this project. Now, with that out of the way, let's take a look at the other two areas of interest in Director's Configuration folder.

The Cross Platform Resources folder is where you stash the other platform's version of the Xtra you're planning to include. On the Mac, this folder includes not only a Windows directory, but also a Classic Mac OS directory as well (fig. 2). For you Windows users, your Cross Platform Resources folder only includes a generic Macintosh directory. While I'll say a little more about this later, Windows users can only produce Mac OS X Projectors and not Classic Projectors. Anyway, it's in these respective folders into which you're going to place the other platform's version of the Xtra. So, as before, let's break this down by platform:

Figure 2: Mac users, the Classic Mac OS lives. Windows users, not so much.

Mac users:

• Unarchive the "bx360.zip" file you downloaded from the Buddy API site.
• Open the resulting "bx360" folder that the archive created.
• Move the Windows Xtra ("budapi.x32") into your Cross Platform Resources:Windows:Xtras folder.

Mac users who are planning on a Classic version:

• Unarchive the "bm151.hqx" file you downloaded from the Buddy API site.
• Open the resulting "Buddy API 1.51" folder that the archive created.
• Move the Classic Mac Xtra into your Cross Platform Resources:Classic MacOS:Xtras folder.
• IMPORTANT: Make sure that this Xtra and the native OS X Xtra (the one you placed in your regular Xtras folder previously) are named identically, or else the Xtra might not get packaged up properly, if at all. That's why we renamed "Buddy API OSX Xtra" to "Buddy API Xtra" a little while ago.

Windows users:

• Unarchive the "bm151.hqx" file you downloaded from the Buddy API site.
• Open the resulting "Buddy API 1.51" folder that the archive created.
• Because of the way the Mac handles some files (with a resource fork and a data fork), you have to move two files ("Buddy API OSX Xtra.data" and "Buddy API OSX Xtra.rsrc") into your Cross Platform Resources\Macintosh\Xtras folder. Director will recombine these files into a single file when it publishes your Mac Projector.

As I mentioned, the developer of Buddy API has pretty much covered everything, so we're in good shape as far as having the split data/rsrc version of the Xtra provided in this particular case. In the future, if you come across Xtras that are distributed with these files missing, be sure to contact the developer and see what's up.

The last element in our Cross Platform Resources folder trinity of items is the Xtrainfo.txt file. In order to "tell" Director of the presence of a specific Xtra, we're going to have to open 'er up and insert a wee bit o' text to make all the magic happen. The process and syntax is identical on both Mac and Windows, so a single description should suffice for everyone. In your favorite text editor, open up the Xtrainfo.txt file, which (once you scroll down a bit) will reveal a lovely jumble of what may very well appear to be garbage on your screen (fig. 3).

Figure 3: Oh, joy...a mess of text.

Once you get over the shock, however, it doesn't take long to figure out that there's a relatively simple syntax at work: Mac names, Windows names, download locations, commenting, etc. What we'll need to do is to just grab what we need and make a couple of tweaks for our purposes. A simple copy and paste of the last heading and entry at the very bottom of the file will give us a block that looks like this:

;----------------------------------------------------------------------
;System
;----------------------------------------------------------------------
[#namePPC:"UIHelper PPC Xtra", #nameW32:"UIHelper.x32"]

Let's just fill in a few things differently, and we should be good to go:

;----------------------------------------------------------------------
;User Added
;----------------------------------------------------------------------
[#namePPC:"Buddy API Xtra", #nameW32:"budapi.x32"]

Now, note that on Windows, the #namePPC value would actually be Buddy API OSX Xtra in this case, which is everything in the name before either the .data and .rsrc extensions. Basically, the names just have to match up to what you have in your various folders, and you'll be set. And again, if you plan on a Classic Mac version, remember to have your OS X and Classic Xtras named identically. Anyway, you've now got your Xtrainfo.txt file set up easily add whatever Xtras come down the pipe, so adding Xtras in the future via this process shouldn't be quite as daunting.

Step 4: Publish

Even though we're now done with all the heavy lifting, we've still got a couple of minor tasks left, so hang with me here. The first is to embed the Xtra into our Director movie (you know, the one left over from last time that we haven't even touched in this installment). Fire up Director and open up the aforementioned PDF-launching-via-Buddy API movie we made previously, and then select Modify:Movie:Xtras to bring up the Movie Xtras dialog box. Click the Add button, and a list of unused Xtras will pop up (fig. 4). Select Buddy API (which should show up as "Buddy API Xtra" on the Mac and "budapi.x32" on Windows, as per their respective names in the Xtras folder), Click OK, and then make sure the "Embed in Movie" option is checked. Click OK again to close the Movie Xtras box. That's it! The Buddy API Xtra is now embedded in your movie, and will be packaged into whatever kind of Projector you make regardless of platform (thanks to the Xtrainfo.txt file telling it to).

Figure 4: Embedding Xtras is easy. The hard part is remembering to actually do it.

Now, if it looks like you're going to use Buddy API (or any other non-standard Xtra, for that matter) in every movie you make in Director for time eternal, you can skip the embedding step entirely by tweaking the Xtrainfo.txt file just a bit more. Simply add #type:#default after the Mac and Windows names in an entry, and the Xtra in question will be automatically embedded into any future movie you make (unless you manually remove it). So for example, the Buddy API entry in your Xtrainfo.txt file would look like this:

[#namePPC:"Buddy API Xtra", #nameW32:"budapi.x32", #type:#default]

Now it's time to publish. Open up the Publish Settings (File:Publish Settings...), and go nuts with whatever settings you want here, because I'm really only interested in what's going on in the Formats tab for today (fig. 5). The only thing I'll really mention here is that while Director , by default, will try and append ".osx" and ".classic" to your OS X and Classic Mac OS Projectors, respectively, I've tried to get into the habit of using ".app" extensions for OS X Projectors and no extension for Classic Projectors, as is pretty much the convention on the Mac anyway. And while Windows users don't even have a Classic Mac OS option, it's still not a bad idea to tack ".app" onto Mac Projector names regardless. Once you've got the Projectors set up how you want them, go ahead and click the Publish button. Mac users can then just copy the Windows .exe Projector directly to Windows, while Windows users can move the Mac Projector , which is bundled inside a .hqx archive, over to the Mac and unpack it using Stuffit Expander. Viola!

Figure 5: Tweaking the default Mac Projector names is a good idea here, if for no other reason than to be consistent with other Mac programs.

Step 5: Test, foo'!

This is the shortest step of the bunch, but please, for the sake of all that is good and right in the world, try and test your Projectors as thoroughly as possible. Just because publishing all manner of Projectors is possible from a single authoring platform doesn't relieve you of your responsibility to make sure everything works. And, if you've followed along from the beginning, you'll see that our simple click-to-launch PDF opener program works great no matter where it's running (fig. 6). Yay!

Figure 6: Opens on the Mac, opens on Windows. And how exciting it is!

Gotcha!

As a public service before we skee-daddle out of here for today, there are a couple of bummers that go along with cross-platform publishing. (Cue sad music.) Unfortunately, regardless of the platform you choose to author on, you'll find missing features. For one, you can't embed a custom icon into a Windows Projector from a Mac, so you're stuck with the generic Director icon for your Windows movies. I can't even begin to fathom why this might be so, because I can't think of a single technical reason why Director on the Mac can't package in an .ico file while it's busy doing everything else to make the Windows code executable.

And, as I already mentioned, if you're authoring on Windows, you have no option for creating pre- OS X Mac Projectors. Again, I'm not at all sure why this is so, because Director 's sibling Flash has no issue making Carbon-based Projectors that run on Classic as well as OS X , so I'm again left scratching my head. Maybe it's an insidious plot to ensure that folks keep buying two copies of Director in order to have access to absolutely everything. Or maybe it's just because that's the way it goes. In any case, the gotchas are small, but they're there. Overall, though, what minor issues exist aren't enough to really spoil the cross-platform party.

Well, as much as a pain as this exercise might have been to do, what with all the text editing and Xtra copying and what-not, the good news is that getting Director MX 2004 ready for cross-platform publishing can be more or less a one-shot deal. Get all your Xtras together, make one massive edit to the Xtrainfo.txt file, and you can be done with it. And with that, dear reader, go forth and publish!

Filed under: Tutorial on June 20th, 2004

^ Top of Page

Got Feedback? to send an email. I'll do my best to answer. Really.