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.