Hostinicon
GET HOSTING FROM $3.95/MO PLUS A FREE YEAR ON TUTS+ (RRP $180). HURRY OFFER LIMITED. Check it out
Advertisement

Integrating the Piecemaker 3D Gallery into your WordPress Theme

by
Gift

Get a free year on Tuts+ this month when you purchase a Siteground hosting plan from $3.95/mo

This tutorial will show you how to successfully integrate the Piecemaker 3D Flash image rotator into your WordPress theme. We'll also discuss setting up a custom admin panel which will make it super easy for your users to make customizations to the rotator.

Piecemaker is a gorgeous, open-source, 3D Flash image rotator created by Björn Crüger from Modularweb. You can preview the piecemaker in action on Sansation, the first premium WordPress theme on ThemeForest to incorporate Piecemaker.

Piecemaker

Preview


Brief Overview

All of the files included in the ZIP file are already modified for you. We've also included a folder which has all of the default unmodified Piecemaker files. I recommend that you go check out the Piecemaker site and familiarize yourself with it before proceeding with the tutorial.


Step 1. Modify the ActionScript

The first step is to modify the ActionScript so that it'll play nicely with WordPress. The ActionScript that comes with Piecemaker defines three values that the Piecemaker needs in order to function properly:

  • the XML Source
  • the CSS Source
  • the path to the images folder.

The XML Source defines the Picemaker's various settings and allows you to define images and their descriptions. The CSS file styles the Piecemaker's description panels, and the images directory tells the Piecemaker where to pull the images from.

Open up the FLA file named "piecemakerNoShadow.fla" and open the Actions window. In frame 1 you will see the actions below. Please note that you need Flash CS4 to open the source file.

In order for the Piecemaker to work properly within our WordPress theme, we need to dynamically set these variables. To achieve this, we will be using FlashVars. FlashVars are variables the we'll set within our WordPress page template that will get passed to the flash movie when the page loads. Go ahead and delete the default actions in frame 1 of the flash file, and replace them with the following code:

The above ActionScript first loads in the FlashVars, and then replaces the default Piecemaker values with these new variables. Our Flash file is now all set to go. Publish the SWF and load your FTP client of choice.


Step 2. Upload Files and Folders

The next step is to upload the required files and folders into your WordPress theme's directory. This tutorial assumes that you will be uploading everything directly into your theme's main directory. Here is a list of the required items:

  • piecemakerCSS.css
  • piecemakerNoShadow.swf
  • piecemakerXML.xml
  • 'images' folder (with your images in it)
  • 'swfobject' folder (plus contents)
  • piecemakerXML.php (needde for use with the custom admin panel)

Step 3. Embed the SWF and set the FlashVars

The next step is to embed the SWF movie into your WordPress page template. We'll be using SWFObject 2 to embed the movie, and we'll also define the three FlashVars that we referenced in step one.

You first need to reference swfobject within the head of your page. To do so, open up your theme's "header.php" file in your code editor of choice (mine's BBEdit), and add the following code in the head of your page:

Next, open up the WordPress page template where you'd like the Piecemaker 3D Rotator to display, and paste the following code:

Code Explaination

The bulk of the code is just your standard swfobject code used to embed a flash movie onto any webpage. The important stuff we need to be concerned with are the FlashVars:

Notice that we have named our FlashVars just as we defined them in the ActionScript in step on4. We are also using WordPress' built-in bloginfo() function to reference the exact locations of the three required files.

That's it! Well, Sort of...

The above steps will enable you to successfully deploy the Piecemaker 3D Image Rotator into your WordPress theme, but we're going to take it a step further. In the following steps, we will discuss how to create a custom admin panel that will allow you to customize Piecemaker's settings right from the WordPress back-end.

If you're not interested in setting up the admin panel, you can go over to the Piecemaker website to read the documentation and start making some really kick-awesome animations.


Step 4. Create The Admin Panel

We will not be covering how to create the entire admin panel from scratch. Instead, we'll expand upon an already in-depth tutorial here on Nettuts: How to Create a Better WordPress Panel.

Once you have followed that tutorial and you have your admin panel setup, please proceed to the next step.


Step 5. Define Our New Options Panel

We now need to add additional options to the admin panel you just created in the tutorial. Open your theme's "functions.php" file, and replace the first chunk of code with the following:

The bulk of the above code is identical to the tutorial, but we've added a new array named $tween_types. This array holds all of the various animation effects that are available with PieceMaker. We will use this array to generate a dropdown list of the various animation effects in our custom options panel. You can check out the Tweener Documentation to review a visual representation of the various Piecemaker animation effects.

Still within the functions.php file, add the following array below the ones you've already created in the tutorial.

This will create a new sliding options panel similar to the ones you created in the tutorial. It's a long bit of code, but it follows the same exact logic as the tutorial. We are simply creating variables for all of the different settings that we'll need to define in the Piecemaker's XML file. An important thing to note is that we made sure to define default values for each option (the values in 'std' are the default values). There are a decent amount of settings for the Piecemaker and we don't want to force our users to set up all those options if they don't want to.


Step 6. Update Our Page Template

In this step, we need to slightly modify our WordPress page template from Step three. Instead of pointing our xmlSource to an XML file, we need to point it to a PHP file. By using a PHP file instead of an XML file, we can pull in all of the values that were set by the user in our custom options panel. It's just the one line of code that needs to be replaced:


Step 7. Generate our XML File with PHP

We're almost there! In this step, we'll create the PHP file that we just referenced in the code above. This PHP file will be used to pull in all of the values from our custom options panel and generate the XML file that the Piecemaker needs in order to function properly. The code is somewhat lengthy, so I'll try to break it up into more digestable chunks.

Create a blank PHP file, name it "piecemakerXML.php", and paste the following code at the start of the file:

  • The first line loads WordPress into our PHP file. This allows us to have access to all of the default WordPress functions, as well as any values stored within our database.
  • The rest of the code pulls in the data from our custom options panel and stores those values into variables. We will use these variables to generate the rest of the Piecemaker's settings.
  • Next, we need to set the content-type header so that the browser knows we are going to output XML content rather than the default text/html. We will also include some initial Piecemaker settings tags.

We are now going to output the variables we stored into their correct XML tags, and close out the Piecemaker settings tag.

The final step is to output the images that we want to include in the rotator along with their descriptions, and we'll also close out the Piecemaker XML tag.


Conclusion

I hope you learned something useful in this tutorial. By combining various different technologies, we're able to add powerful functionality to our WordPress themes. More importantly, we made it easy for the average user to make customizations to our theme.

Advertisement