Photopick.io documentation

We've tried to make using Photopick.io as easy as possible so you could concentrate on making your web app awesome instead of learning complex API's and stuff.

The integration of Photopick.io is two-phased. First you initialize our plugin on your front-end and then you handle the uploaded material on your back-end.

Initializing the plugin

Initializing the plugin is easy. Just include our initialization script and then call the initialization method. The initialization method takes two parameters:

The element into which to inject the plugin
Object with various options how the plugin should behave

Option name	Default value	Description
apiKey	None Required	The API-key for this domain. You can get this from your dashboard for each of your registered domains. If you register multiple domains be sure to use an API key that matches the domain that the initialization script is called from.
uploadURL	None Required	A relative or absolute URL to your backend endpoint where the plugin should send the uploaded files. If the value does not begin with 'http://' or 'https://', the name is prefixed with the current hostname and if the value does not begin with '/' it is prefixed with the current path.
fileFieldName	"file" Optional	The form field name with which the uploaded files are sent to your backend. Default is "file".
dropTarget	None Optional	If you want your users to be able to just drag and drop files into your application, specify a jQuery-type selector of the element onto which the users can drop files, eg. "#myDropTargetDiv". The plugin will add `photopick-drop-target` class to the element if file dropping is supported. `photopick-drop-target-active` class is added when the user is dragging a file on top of the element and `photopick-drop-target-dropped` class is added when the user drops a file onto the element. The file is then added to the upload queue and `onPhotoAdded` event is triggered. `photopick-drop-target-not-supported` class is added if the browser does not support file dropping.
csrfToken	None Optional	If your backend requires a CSRF-token to prevent cross-site request forgery, retrieve it eg. from a cookie and insert here. See your backend framework documentation for more information about CSRF-tokens.
autostart	false Optional	If set to true, uploading starts automatically after the user has selected files for upload. If false, user must click "start upload" before the actual uploading starts.
preload	false Optional	If set to true, the plugin preloads the selected images before they are uploaded so your web app can utilize the selected photos even before they are uploaded to your server. You can then close the plugin and let it continue the upload on the background. The plugin will fire `onPhotoPreloaded` event for each photo when they are preloaded and ready to use.
language	"en_US" Optional	Localization setting for the plugin. Currently implemented are `en_US` and `fi_FI`. If you set `languageURL`, make sure the value you set here matches the one in your custom translation file.
languageURL	None Optional	If you want, you can translate Photopick.io to your own language. Download our translation template and follow the instructions at angular-gettext about how to translate and compile the template to your language (follow the "Lazy-loading languages" -part). Then place the resulting translation file in a publicly available location and pass the URL to the file here.
stylesheet	None Optional	If you want to customize the outlook of the plugin, you can embed your custom stylesheet into the plugin. Enter the ABSOLUTE URL of your custom stylesheet (ie. an URL starting with 'http://' or 'https://')
theme	None Optional	By default the plugin uses the default Bootstrap theme but you can change that to one of Bootswatch.com themes by entering the theme name here, eg. "cerulean" or "readable".

Events

Event name	Description
onPhotoAdded	Dispatched when the user has added a photo to the upload queue
onPhotoRemoved	Dispatched when the user has removed a photo from the upload queue
onUploadStarting	Dispatched when the uploading queue is about to start due to `autostart` being `true` or the user deliberately clicking "start upload"
onPhotoPreloaded	Dispatched when a user has selected a photo for upload and the plugin has preloaded it
onBeforeUpload	Dispatched just before the upload is started for each photo
onUploadProgress	Dispatched while the upload is progressing
onPhotoUploaded	Dispatched when the upload is complete for each photo
onUploadComplete	Dispatched when the whole upload queue is uploaded
onResetAfterUploadComplete	Dispatched when the whole upload queue is processed and the user clicks 'OK'.
onError	Dispatched if there's an error in the upload queue

<script type="text/javascript" src="//photopick.io/photopick.js?v=2.0">
<script>
var photopick = Photopick.init('#myContainerElement', {
	apiKey: 'my-api-key',
	uploadURL: 'my-backend-url',
	fileFieldName: 'my-upload-field-name',
	dropTarget: null,
	csrfToken: 'my-csrf-token',
	autostart: false,
	preload: false,
	language: 'en_US',
	languageURL: 'my-localization-url',
	stylesheet: 'my-stylesheet-url',
	theme: 'readable',
	onPhotoAdded: function(photo, photos) {
		// Dispatched when user has added a photo to the upload queue
	},
	onPhotoRemoved: function(photo, photos) {
		// Dispatched when user removes a photo from the upload queue
	},
	onPhotoPreloaded: function(photo) {
		// Dispatched when a photo has been selected and it's contents has been read
	},
	onUploadStarting: function(photos) {
		// Dispatched just before the upload queue is about to start
	},
	onBeforeUpload: function(photo) {
		// Dispatched when a single photo is about to be uploaded
	},
	onUploadProgress: function(photo) {
		// Dispatched multiple times as the upload progresses
	},
	onPhotoUploaded: function(photo, response) {
		// Dispatched when a single photo has been uploaded
	},
	onUploadComplete: function(photos) {
		// Dispatched when all selected photos have been uploaded
	},
	onResetAfterUploadComplete: function() {
		// Dispatched when the user resets the view after the upload queue is complete
	},
	onError: function(error) {
		// Dispatched if an error occurs at any point of the process
	}
});

// When the window is resized (or if you display photopick in a modal or
// something like that) you must call the 'refresh'-method so that Photopick
// can reposition it's contents accordingly. If you experience non-functioning
// buttons, this should provide the ultimate fix for all your problems.
$(window).on('resize', function() {
	photopick.refresh();
});

</script>

Handling the uploaded files

Almost only special thing you need to handle at your back-end are the Cross-Domain -requirements for POSTing data. Just copy the relevant code from the sample scripts below and you should be all set.

You can handle the uploaded files at your back-end however you want and return whatever you want. The responses are relayed to the handling functions you define when initializing the plugin at the front-end.

See these sample scripts for how to receive the uploaded photos. The photos are received differently depending whether they are actually uploaded or retrieved from an external web service such as Facebook or Instagram.

When a photo is uploaded, the whole photo file is included in the request. When files are selected from an external web service, only the URL's of the files are included in the request data.

import express = require('express');

var router = express.Router();

router.options('/', function(req, res, next) {
	if (req.headers['origin'].match('photopick\.io$')) {
		res.setHeader('Access-Control-Allow-Origin', req.headers['origin']);
		res.setHeader('Access-Control-Allow-Headers', req.headers['access-control-request-headers']);
	}
	res.end();
});

router.post('/', function(req, res, next) {
	if (req.headers['origin'].match('photopick\.io$')) {
		res.setHeader('Access-Control-Allow-Origin', req.headers['origin']);
	}
	res.end();
});

export = router;

import re, json, requests, cStringIO
from django.http.response import HttpResponse

def handle_upload(request):
	if request.method == 'OPTIONS':
		origin = request.META.get('HTTP_ORIGIN')
		response = HttpResponse()
		if origin and origin.endswith('photopick.io'):
			response['Access-Control-Allow-Origin'] = origin
			response['Access-Control-Allow-Headers'] = 'x-requested-with, content-type, accept, origin, authorization, x-csrftoken, user-agent, accept-encoding'
		return response
	elif request.method == 'POST':
		data = json.loads(request.body)
		photo_data = data.get('photo')
		photo_origin = photo_data['source']
		if photo_data['source'] == 'device':
			uploaded_file = request.FILES['my-upload-field-name']
		else:
			photo_url = photo_data['originalURL']
			photo_response = requests.get(photo_url, headers=headers)
			photo_file_data = cStringIO.StringIO(photo_response.content)
			uploaded_file = ContentFile(photo_file_data.getvalue(), photo_data['name'])
		################################################################
		# Do what you want with uploaded_file
		################################################################

Got questions about implementing the plugin? Contact us through the contact form!