Integrating the Piecemaker 3D Gallery into your WordPress Theme

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.

Preview

• Demo
• Download Source

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:

stage.scaleMode = StageScaleMode.NO_SCALE;

// Pull in the Flashvars
var allFlashVars:Object = LoaderInfo(this.root.loaderInfo).parameters;

// Set the required variables for piecemaker
piecemaker.xmlSource = String(allFlashVars.xmlSource);
piecemaker.cssSource = String(allFlashVars.cssSource);
piecemaker.imageSource = String(allFlashVars.imageSource);
piecemaker.dispatchEvent(new Event("properties"));

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:

<script type="text/javascript" src="<?php bloginfo('template_url'); ?>/swfobject/swfobject.js"></script>

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

<div id="flashcontent">
<p>You need to <a href="http://www.adobe.com/products/flashplayer/" target="_blank">upgrade your Flash Player</a> to version 10 or newer.</p>
</div><!-- end flashcontent -->

<script type="text/javascript">
		var flashvars = {};
		flashvars.xmlSource = "<?php bloginfo('template_url'); ?>/piecemakerXML.xml";
		flashvars.cssSource = "<?php bloginfo('template_url'); ?>/piecemakerCSS.css";
		flashvars.imageSource = "<?php bloginfo('template_url'); ?>/images";
		var attributes = {};
		attributes.wmode = "transparent";
		swfobject.embedSWF("<?php bloginfo('template_url'); ?>/piecemakerNoShadow.swf", "flashcontent", "960", "610", "10", "<?php bloginfo('template_url'); ?>/swfobject/expressInstall.swf", flashvars, attributes);
</script>

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:

flashvars.xmlSource = "<?php bloginfo('template_url'); ?>/piecemakerXML.xml";
flashvars.cssSource = "<?php bloginfo('template_url'); ?>/piecemakerCSS.css";
flashvars.imageSource = "<?php bloginfo('template_url'); ?>/images";

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:

<?php
$themename = "Nettuts";
$shortname = "nt";

$categories = get_categories('hide_empty=0&orderby=name');
$wp_cats = array();
foreach ($categories as $category_list ) {
       $wp_cats[$category_list->cat_ID] = $category_list->cat_name;
}
array_unshift($wp_cats, "Choose a category"); 
$tween_types = array("linear","easeInSine","easeOutSine", "easeInOutSine", "easeInCubic", "easeOutCubic", "easeInOutCubic", "easeOutInCubic", "easeInQuint", "easeOutQuint", "easeInOutQuint", "easeOutInQuint", "easeInCirc", "easeOutCirc", "easeInOutCirc", "easeOutInCirc", "easeInBack", "easeOutBack", "easeInOutBack", "easeOutInBack", "easeInQuad", "easeOutQuad", "easeInOutQuad", "easeOutInQuad", "easeInQuart", "easeOutQuart", "easeInOutQuart", "easeOutInQuart", "easeInExpo", "easeOutExpo", "easeInOutExpo", "easeOutInExpo", "easeInElastic", "easeOutElastic", "easeInOutElastic", "easeOutInElastic", "easeInBounce", "easeOutBounce", "easeInOutBounce", "easeOutInBounce");

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.

array( "name" => "3D Rotator Options",
"type" => "section"),
array( "type" => "open"),

array( "name" => "Segments",
"desc" => "Number of segments in which the image will be sliced.",
"id" => $shortname."_segments",
"type" => "text",
"std" => "9"),

array( "name" => "Tween Time",
"desc" => "Number of seconds for each element to be turned.",
"id" => $shortname."_tween_time",
"type" => "text",
"std" => "3"),

array( "name" => "Tween Delay",
"desc" => "Number of seconds from one element starting to turn to the next element starting.",
"id" => $shortname."_tween_delay",
"type" => "text",
"std" => "0.1"),

array( "name" => "Tween Type",
"desc" => "Type of animation transition.",
"id" => $shortname."_tween_type",
"type" => "select",
"options" => $tween_types,
"std" => "Choose a category"),

array( "name" => "Z Distance",
"desc" => "to which extend are the cubes moved on z axis when being tweened. Negative values bring the cube closer to the camera, positive values take it further away. A good range is roughly between -200 and 700.",
"id" => $shortname."_z_distance",
"type" => "text",
"std" => "25"),

array( "name" => "Expand",
"desc" => "To which etxend are the cubes moved away from each other when tweening.",
"id" => $shortname."_expand",
"type" => "text",
"std" => "9"),

array( "name" => "Inner Color",
"desc" => "Color of the sides of the elements in hex values (e.g. 0x000000 for black)",
"id" => $shortname."_inner_color",
"type" => "text",
"std" => "0x000000"),

array( "name" => "Text Background Color",
"desc" => "Color of the description text background in hex values (e.g. 0xFF0000 for red)",
"id" => $shortname."_text_background",
"type" => "text",
"std" => "0x666666"),

array( "name" => "Text Distance",
"desc" => "Distance of the info text to the borders of its background.",
"id" => $shortname."_text_distance",
"type" => "text",
"std" => "25"),

array( "name" => "Shadow Darkness",
"desc" => "To which extend are the sides shadowed, when the elements are tweening and the sided move towards the background. 100 is black, 0 is no darkening.",
"id" => $shortname."_shadow_darkness",
"type" => "text",
"std" => "25"),

array( "name" => "Auto Play",
"desc" => "Number of seconds to the next image when autoplay is on. Set 0, if you don't want autoplay.",
"id" => $shortname."_autoplay",
"type" => "text",
"std" => "2"),

array( "type" => "close"),

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:

flashvars.xmlSource = "<?php bloginfo('template_url'); ?>/piecemakerXML.php";

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:

<?php require_once( '../../../wp-load.php' );
$segments = get_option('nt_segments');
$tweentime = get_option('nt_tween_time');
$tweendelay = get_option('nt_tween_delay');
$tweentype = get_option('nt_tween_type');
$zdistance = get_option('nt_z_distance');
$expand = get_option('nt_expand');
$innercolor = get_option('nt_inner_color');
$textbackground = get_option('nt_text_background');
$textdistance = get_option('nt_text_distance');
$shadow = get_option('nt_shadow_darknent');
$autoplay = get_option('nt_autoplay');
?>

• 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.

<?php
header("Content-type: text/xml");
echo '<?xml version="1.0" encoding="utf-8" ?>
<Piecemaker>
  <Settings>
	<imageWidth>830</imageWidth>
	<imageHeight>360</imageHeight>';

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

echo '<segments>'. $segments . '</segments>';
echo '<tweenTime>'. $tweentime . '</tweenTime>';
echo '<tweenDelay>'. $tweendelay . '</tweenDelay>';
echo '<tweenType>'. $tweentype . '</tweenType>';
echo '<zDistance>'. $zdistance . '</zDistance>';
echo '<expand>'. $expand . '</expand>';
echo '<innerColor>'. $innercolor . '</innerColor>';
echo '<textBackground>'. $textbackground . '</textBackground>';
echo '<textDistance>'. $textdistance . '</textDistance>';
echo '<shadowDarknent>' . $shadow . '</shadowDarknent>';
echo '<autoplay>' . $autoplay .  '</autoplay>'; 
echo '
</Settings>

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.

<Image Filename="image1.jpg">
    <Text>
      <headline>Description Text</headline>
      <break>Ӂ</break>
      <paragraph>Here you can add a description text for every single slide.</paragraph>
      <break>Ӂ</break>
      <inline>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam eu quam dolor, a venenatis nisl. Praesent scelerisque iaculis fringilla. Sed congue placerat eleifend.</inline>
      Ӂ<a href="http://themes.5-squared.com/sansation/?style=cool_blue" target="_blank">hyperlinks</a>
    </Text>
  </Image>
  <Image Filename="image2.jpg">
    <Text>
      <headline>Description Text</headline>
      <break>Ӂ</break>
      <paragraph>Here you can add a description text for every single slide.</paragraph>
      <break>Ӂ</break>
      <inline>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam eu quam dolor, a venenatis nisl. Praesent scelerisque iaculis fringilla. Sed congue placerat eleifend.</inline>
      Ӂ<a href="http://themes.5-squared.com/sansation/?style=cool_blue" target="_blank">hyperlinks</a>
    </Text>
  </Image>
  <Image Filename="image3.jpg">
    <Text>
      <headline>Description Text</headline>
      <break>Ӂ</break>
      <paragraph>Here you can add a description text for every single slide.</paragraph>
      <break>Ӂ</break>
      <inline>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam eu quam dolor, a venenatis nisl. Praesent scelerisque iaculis fringilla. Sed congue placerat eleifend.</inline>
      Ӂ<a href="http://themes.5-squared.com/sansation/?style=cool_blue" target="_blank">hyperlinks</a>
    </Text>
  </Image>
  <Image Filename="image4.jpg">
    <Text>
      <headline>Description Text</headline>
      <break>Ӂ</break>
      <paragraph>Here you can add a description text for every single slide.</paragraph>
      <break>Ӂ</break>
      <inline>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam eu quam dolor, a venenatis nisl. Praesent scelerisque iaculis fringilla. Sed congue placerat eleifend.</inline>
      Ӂ<a href="http://themes.5-squared.com/sansation/?style=cool_blue" target="_blank">hyperlinks</a>
    </Text>
  </Image>
</Piecemaker>';
?>

---

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.