Exports for Experts

Advanced topics in image flow

Picnik offers many tools to help you customize the Picnik experience, make it as seamless for your users as possible, and enable as many cool, interesting applications as you can dream up.

Overwrite Confirmation

If you're letting users edit images on your own website, you can have Picnik put up a dialog asking them to confirm the changes they make before saving. You have a few options controlling how this works.

First, you need to assign an identifier to the image being edited. You can use whatever makes sense for your application such as a numeric ID, or a URL. When you invoke the Picnik API, you'll pass this identifier in the _imageid parameter.

When the user is done making changes and the image is exported back to you, the same identifier that you passed in via _imageid will be sent back to you -- again, via _imageid. You can then use the identifier to find the original image and overwrite it with the new image data.

Sounds easy (and it is!), but we're actually missing one step. The _imageid won't be exported back to you unless you pass in one more parameter with the initial API call: _replace.

_replace lets you control under what circumstances the _imageid is exported back to you, and therefore under what circumstances you'll overwrite the previous image. The behavior of your application is then determined by the presence of an _imageid parameter on export: if Picnik sends it to you, overwrite the old image; if it's not there, create a new image.

The default value for _replace is "no". This means that the _imageid will never be sent back to you and you should always create a new file.

The opposite option for _replace is "yes". In this case the _imageid is always sent back to you and you should always overwrite the old file.

Two other options are more interesting: "ask" and "confirm". Both of these will put up a dialog which asks the user for more information before exporting. But they behave slightly differently from each other:

• In "ask", you're asking the user whether or not to overwrite the image. The user can click either "Replace" or "Save a new copy" (or "Cancel"), and the _imageid will be sent (for "Replace") or not sent (for "Save a new copy").
• In "confirm", you're telling the user that the image will be overwritten. The user's options are "Replace" or "Cancel". If the user clicks "Replace" then the _imageid is sent to you. "Cancel" takes the user back to editing the photo. In this situation, an image will never be exported to you without an attached _imageid — you're giving the user control over whether the export happens as all.

There's one more optional parameter you can use alongside _imageid and _replace. It's called _original_thumb. For its value, pass the URL of a thumbnail of the original image (no bigger than 240x240, please). Then, when the user is asked whether to overwrite the old file, she will be shown both the original and the changed images, side by side, to make sure she really agrees with the changes that were made.

Redirect After Export

By default, Picnik will follow any redirects it receives after exporting, so if you don't want your user to end up looking at the results of your export script after you get the image, you can do something like this:

<?php
	// picnik_export.php
	
	// handle file upload
	include "MyPicnikExportHandler.php"
	MyPicnikExportHandler();
	
	// send the user to the all done page
	header('Location: http://www.example.com/all_done.php');
?>

... and the user will end up on the "all done" page.

You can also control where the user ends up by setting the _redirect parameter when you invoke the API. In that case, Picnik will ignore any redirects sent back from your export script. Instead, the user will be sent to whichever URL you've specified for _redirect.

...And One Cool Little Import Thing

Some applications (particularly desktop applications) can't upload an image via HTTP POST and open up a browser window at the same time. For these kinds of apps, we've created the _returntype parameter. The default value for _returntype is "load" which means the user will be redirected to the main Picnik app right away. But if your application can't handle that redirect automatically, you should specify "text". In this case, your API call will return a text URL. Your desktop app can then launch a browser using that URL.

Next Steps

Perhaps you'd like to customize the Picnik UI? And of course, you can always go back and take a look at all the tutorials.