The Picup JavaScript helper has a few functions that convert file-input fields with buttons to the Picup app. Use this tool to conditionally replace form elements if your visitor is using Mobile Safari. The script can also help generate Picup URLs to request and view local photos.
Picup's callback functionality can greatly improve the integration with your app. It allows you to define how Picup returns information and device control back to your app. Making this handoff as seamless as possible will improve the user experience. For the sake of example, lets assume you're using Picup at the URL http://myapp.com/form.
When http://myapp.com/form loads, give the browser window a name (e.g. window.name = "my_form") and replace any file-input fields with an "upload photo" button using the Picup JavaScript helper.
Define the Picup.callbackHandler function to accept a JavaScript object with key/value callback parameters. For example:
Picup.callbackHandler = function(params){
for(var key in params){
alert(key+' == '+params[key]);
}
}
Launch Picup with a callback URL for a "transaction complete" page, that's hosted in the same domain as the current page.
User selects and uploads photo with Picup.
Picup opens the "transaction complete" callback URL in a new Safari window. It should give the user some feedback regarding the status of the upload.
Return control to the original window with new hash parameters. This can be done using window.open if your callback URL is in the same domain as the original window. The window name should be the same name that you assigned in step 1. Optionally, close the callback window after you return to the original window to reduce clutter. For example:
<a href="javascript:window.open('http://myapp.com/form'+window.location.hash, 'my_form');window.close()">Return to form</a>
If the original window is still open and in-memory, Safari will return focus to it. If the page is no-longer in memory, Safari will open a new window.
Once control has returned to the original window, Picup.callbackHandler() will be called with the callback parameters. These parameters are parsed from the query-string formatted hash. Use these parameters to update your page as necessary. If there is more than one file-upload fields in the form, the field that requested the upload can be referenced by the Picup.activeFileInput variable.
The above callback cycle can be seen in-use on the Scratchpad Demo.
Give your visitors visual feedback that the upload is complete by adding a thumbnail of the photo to your form. This can be done by requesting a thumbnail data:URL from Picup or inserting the uploaded photo into the page using the remote URL.
It's good practice to keep the requested thumbnail sizes down. The larger the image is, the slower the transaction between your app and Picup will be. You can request images up to 100x100 pixels, but it's recommended that you keep them down to less than 50px square.
Picup will store an image locally and return control to your application even if the upload was not complete. This might happen if the user doesn't have an internet connection, or there was an error from the remote server. If you provide a callback URL, Picup will return a "status" parameter which will either be "Complete" or "Incomplete."
If the upload was not complete, the images can still be viewed locally by launching Picup with a "local" URL. This URL will be returned to your app as a parameter. Your app might also store the thumbnail data to use as a visual representation of the image when the user is not online.
It's suggested that your form includes a link to download Picup. If the user doesn't have Picup and they press a button that calls the custom URL (fileupload://), they will get a jarring and ambiguous alert:
When picking your image upload size, keep the images no bigger than they need to be. Larger images prolong file upload process, which can be slow over phone networks.
If the user has multiple windows open in Safari, it's possible that the window that called Picup will no longer be in-memory. If your callback cycle returns control to the original window (see "Suggested Callback Cycle" above) the page should gracefully handle the case where the page is completely reloaded with Picup hash parameters.