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 right on top of your existing website. This
is known as a "lightbox" technique and is becoming pretty common among advanced web applications.
Although it takes a little more work than the other integration scenarios, it presents the
most seamless 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.
Including the PicnikBox Files
The first step to PicnikBox'ing is to include the two PicnikBox files in your HTML:
picnikbox.css and
picnikbox.js.
You probably want to download these files and serve them from your own web server.
Here's what they'd look like at the top of a typical HTML page:
<head>
<link rel="stylesheet" href="mypicnikfiles/picnikbox.css" media="screen" type="text/css" />
<script type="text/javascript" src="mypicnikfiles/picnikbox.js"></script>
</head>
Handling the Close Button
We provide an additional file which you need to put on your server:
close.html
(you should right-click this link and save it to locally).
Picnik will redirect the user to this file when he or she clicks the close button, and this
page will then take care of closing the window properly (or sending the user to the right page,
as appropriate).
This file should be stored on your own web server, and the URL to this file should be
passed as the value of the _close_target parameter.
You need to make one quick change to your local copy of
close.html.
The version we provide will redirect users to Picnik.com in some cases;
you'll want to make a change in the appropriate spot to point to your own website.
Activating Your Links
The next step is to modify your Picnik API links so they'll launch Picnik inside
a floating window.
First, you need to add
a class called "pbox" to each link. This class acts as a marker for
the javascript code you included at the top of your HTML page, and any links that
have it will be automatically transformed into PicnikBox links.
The second step is to make sure each link includes the _close_target
parameter. Without it, there'll be no way to close the Picnik In A Box window and your
users will probably get stuck. You
should set the value of _close_target to be the location of the
close.html file you
downloaded earlier.
Below is what one of those transformed links looks like.
Open Picnik In A Box
<a class="pbox" href="http://www.picnik.com/service/?_apikey=YourApiKey&_close_target=http://www.picnik.com/close.html">Open Picnik In A Box</a>
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/close.html">Open Picnik In A Box (With An Expand Button)</a>
Building A Better Box
The three Picnik-In-A-Box files you've downloaded are just the starting point. You can use
them as samples to build even better applications around Picnik. For example, you don't need
to have Picnik floating over top of your website -- you can build an IFRAME containing Picnik directly
into your UI. This kind of deep integration gives your users the best experience, but is the trickiest
to build.
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.