Picnik API Documentation » tutorials » packing-a-picnik


Packing A Picnik

The ultimate integration

You've polished your text, you've honed your CSS, and your site is awash in AJAX-y goodness. If this sounds like you, then you're ready for the ultimate Picnik integration: Picnik in a Box.

Picnik In A Box

Picnik In A Box presents the complete Picnik UI integrated right into your existing website. You can float the Picnik UI over your own application and pop it in anywhere it suits you and your users. Although it takes a little more work than the other integration scenarios, it presents the the best experience to your users. They feel like they've never left your website and they still get to experience all of Picnik's photo-editing awesomeness.

To see how cool this is, check out our Edit Gallery Picnik API sample.

The PicnikBox Files

Fortunately for you, we've put together the PicnikBox project to do most of the work of integrating Picnik directly into your site. All you need to do is include a few files, mark which links should launch Picnik, and you're ready to go!

The first step to PicnikBox'ing is to include the PicnikBox files in your project. You'll need these files:

Right-click on each of these links and save them to a suitable place on your web server.

The picnikbox_2_0.css file makes use of the lightbox_overlay.png file to render the semi-transparent overlay for Firefox browsers. You'll need to change the CSS file to point to your local copy of the PNG file. 

.pbox_UsePNGForBackground {
	/* change this path to point to your copy of lightbox_overlay.png */
	background-image: url(lightbox_overlay.png);
}

Next, you'll need to add a tiny amount of HTML to your web pages. Include the PicnikBox files inside your <head> tag like this: 

<head>
<link rel="stylesheet" href="...mypicnikfiles/picnikbox_2_0.css" media="screen" type="text/css" />
<script type="text/javascript" src="...mypicnikfiles/picnikbox_2_0.js"></script>
</head>

...and finally, for every Picnik API link add a class="pbox" attribute.

<p>Click <a href="http://www.picnik.com/service/?_apikey=ABCDetc..." class="pbox">here</a>
to launch Picnik in a Box!

That's it! You've now got Picnik integrated into your website -- although there's still a lot more you can do with PicnikBox. Here is what one of those transformed links looks and acts like:

Open Picnik In A Box 

<a class="pbox" href="http://www.picnik.com/service/?_apikey=YourApiKey&_close_target=http://www.picnik.com/picnikbox/picnikbox_close_2_0.html">Open Picnik In A Box</a>

Handling Close

Picnik-in-a-Box lets you build a fully dynamic web 2.0 application around Picnik, but to enable it you'll need to write some application-specific javascript. One of the places you'll need to add some code is picnikbox_close_2_0.html.

If you load picnikbox_close_2_0.html into a browser, you'll notice that it either immediately closes or redirects to somewhere on the Picnik website. That's because this file's job is to get rid of the Picnik IFRAME when the user is done with Picnik.

You should edit this file in the marked places to provide the functionality you need for your application. In most cases, this file will need to do the following:

  • Handle the results of an exported image. For example, you'll need to save the image that Picnik sends you to your own servers. This is almost always done via server-side scripting, in the language of your choice.
  • Refresh your application's UI. For example, if a user has edited an image, you should probably update the thumbnails to match the new look. This is generally done via javascript calls from the picnik_close_2_0.html page to the parent page.
  • Close the Picnik-in-a-Box iframe. This one is easy, since the PicnikBox code does most of the work for you: just set a timer and call parent.onPicnikClose();
  • In some (fairly rare) cases, Picnik might no longer been contained within your application's frame. For example, if a user has requested authentication from a third-party service (such as Facebook or Flickr) then Picnik will most likely be full-frame and your application's code will no longer be available in the browser. In this case, it's the job of picnik_close_2_0.html to redirect the user to the appropriate page on your site.

Expand and Contract

An optional parameter you can add to your PicnikBox'd links is _expand_button. If set it to "true", then Picnik will display an "Expand" button in its UI. Users can click on this button to toggle the Picnik window larger and smaller.

Here's an example:

Open Picnik In A Box (With An Expand Button) 

<a class="pbox" href="http://www.picnik.com/service/?_apikey=YourApiKey&_expand_button=true&_close_target=http://www.picnik.com/picnikbox/picnikbox_close_2_0.html">Open Picnik In A Box (With An Expand Button)</a>

Margins and Borders

picnikbox_2_0.js includes some functions that help you get the ideal integration by adjusting the position of the Picnik iframe on the screen. You can adjust the following parameters:

  • the distance of the semi-transparent overlay from any edge of the browser window;
  • the distance of the Picnik client from any edge of the semi-transparent overlay;
  • and the color, width, and style of any of the borders of both the overlay and client.

To make changes to the margins and borders, just put a call to the appropriate function(s) inside a script block in your HTML file. For example, most of the examples on this page use a wider-than-default margin around the Picnik client so that you can see more of the underlying page: 

<script type="text/javascript">
	PicnikBox.SetPicnikMargin( 150 );
</script>

Here's the complete list of margins-and-borders functions:

  • PicnikBox.SetOverlayMargin(size): sets all four margins around the overlay to the same value.
  • PicnikBox.SetOverlayMargins(top,right,bottom,left): sets the four margins around the overlay to the given values.
  • PicnikBox.SetPicnikMargin(size): sets all four margins around the Picnik client to the same value.
  • PicnikBox.SetPicnikMargins(top,right,bottom,left): sets the four margins around the Picnik client to the given values.
  • PicnikBox.SetOverlayBorder(size, style, color): sets all four borders around the overlay to the same value.
  • PicnikBox.SetOverlayBorders(top, right, bottom, left, style, color): sets all four borders around the overlay to different widths.
  • PicnikBox.SetPicnikBorder(size, style, color): sets all four borders around the Picnik client to the same value.
  • PicnikBox.SetPicnikBorders(top, right, bottom, left, style, color): sets all four borders around the Picnik client to different widths.

Realtime Adjustments

You can also provide a set of callbacks to picnikbox_2_0.js. Through these callbacks, you can call PicnikBox functions or adjust your own UI just before Picnik gets activated and just after it closes.

Here are the relevant functions:

  • PicnikBox.SetActivateCallback(fnCallback): sets a function to be called just before PicnikBox is activated. The function should have a signature like function( link_element )
  • PicnikBox.SetDeactivateCallback(fnCallback): sets a function to be called just after PicnikBox is deactivated. The function should have a signature like function( link_element )

Here's an example that changes the borders and margins for Picnik-in-a-Box, but only for the the following link:

Open Picnik In A Box (With Callbacks) 

<script type="text/javascript">
	var strOldTitle = document.title;
	function onPicnikActivate( elLink ) {
		// on activate, if it's our special link, change things!
		if (elLink.id == "picnik_activate_sample") {
			// we set the top overlay margin to 300 so that Picnik only covers the bottom
			// portion of the screen.  Also give it some funky borders and change the title.
			PicnikBox.SetOverlayMargins( 300, 0, 0, 0 );
			PicnikBox.SetOverlayBorders( 6, 0, 0, 0, "dotted", "#888" );
			PicnikBox.SetPicnikMargin( 50 );
			PicnikBox.SetPicnikBorder( 6, "inset", "#BCA" );
			document.title = "Picnik is Running!";	// also change the title (just for fun)
		} else {
			// We want to emphasize that the original website is still in the background, 
			// so we set the margins really wide (150).  You'll probably want to leave this  
			// number closer to its default (20).  All the other settings are defaults.
			PicnikBox.SetPicnikMargin(150);
			PicnikBox.SetOverlayMargin( 0 );
			PicnikBox.SetPicnikBorder( 1, "solid", "#ccc" );
			PicnikBox.SetOverlayBorder( 0, "solid", "#ccc" );
		}
	}
	
	function onPicnikDeactivate( elLink ) {		
		document.title = strOldTitle; // restore the title
	}
	
	PicnikBox.SetActivateCallback( onPicnikActivate );
	PicnikBox.SetDeactivateCallback( onPicnikDeactivate )	
</script>

<a id="picnik_activate_sample" class="pbox" href="http://www.picnik.com/service/?_apikey=YourApiKey&_expand_button=true&_close_target=http://www.picnik.com/picnikbox/picnikbox_close_2_0.html">Open Picnik In A Box (With Callbacks)</a>

Building A Better Box

The PicnikBox code is just a starting point; you can use it as inspiration to build even better applications with Picnik. And, as always, we'd love to hear to from you if there's anything we can do to help make your Picnik dreams a reality.

Next Steps

We've got a few tips and tricks you might want to take a look at before you dive in. And of course, you can always go back and take a look at all the tutorials.