Loupe Widgets

Documentation

How does the widget work?

The widget opens up in an iframe. Javascript is used to trigger the widget and receive a callback. You will receive a response object containing the URL of the collage.

What code do I add?

First, you will need to include this line in your HTML file. This will load the widget, that is, it will instantiate a _loupeWidget object with which you will use to set collage parameters.

<script src='http://www.getloupe.com/js/widget/loupeWidget.js' type='text/javascript'></script>

Next, in your Javascript file, you will need to call init(object) of _loupeWidget

_loupeWidget.init({ 
	"app_id" : "your_app_id_goes_here"
});

The parameter for the init method is a Javascript object that contains a set of key/value pairs that configure the collage widget. The app_id setting is mandatory (but all other settings are optional). You will need to get an app id.

Below are the keys and values of the settings:

app_id (required)
Type: String

The app_id identifies which application is making requests for the widget use. This is the only mandatory setting. You can get an app id here.

preload (optional)
Type: Boolean

You can force the widget to preload its resources, rather than waiting until open is called. Note that the widget is automatically initialized when _loupeWidget.open(function) is called, but we include this initialization in case you want to load the resources earlier, thereby making the widget more responsive when it first opens up.

widget_type (optional)
Type: String

The type of the widget. "collage" is for the collage widget (this is the default). "picker" is for the photo picker widget.

Collage-specific parameters

These are the parameters for the collage widget:

shape_url (optional)
Type: String

Interacting with the widget, the end user is able to select a desired shape using our collage tool. However, if you prefer, a shape can be preset for the collage. To specify a specific shape, set shape_url in settings.

    The shape options include:
  • A URL to an image for a custom shape (black and white images work best)
  • A photo pile, specified by "rect". This places photos in a rectangular space. The number of photos in the collage will be equal to the unique number of photos selected.
  • A grid shape, specified by "grid". In this collage, the photos will be aligned in a grid pattern.
  • A text shape, specified by "text (word)", where (word) is the shape word as a string. The maximum number of characters for (word) is 8. An example is, "text hello"
  • Or one of the shapes below:
heartshape
heart
heart-outlineshape
heart-outline
circleshape
circle
moonshape
moon
star2shape
star2
butterflyshape
butterfly
worldshape
world
pawprintshape
pawprint
catshape
cat
puzzleshape
puzzle
airplane-bigshape
airplane-big
airplane-smallshape
airplane-small
appleshape
apple
atomshape
atom
batmanshape
batman
birdshape
bird
bunnyshape
bunny
carshape
car
manshape
man
womanshape
woman
card-clubshape
card-club
card-diamondshape
card-diamond
card-heartshape
card-heart
card-spadeshape
card-spade
circle-outlineshape
circle-outline
cloudshape
cloud
crossshape
cross
crossed-circleshape
crossed-circle
dogshape
dog
duckshape
duck
elephantshape
elephant
maleshape
male
femaleshape
female
firstaidshape
firstaid
fishshape
fish
flowershape
flower
giraffeshape
giraffe
boyshape
boy
girlshape
girl
horseshape
horse
lionshape
lion
smiling-moonshape
smiling-moon
musicshape
music
nuclearshape
nuclear
rabbitshape
rabbit
recycleshape
recycle
rhinoshape
rhino
star-outlineshape
star-outline
triangleshape
triangle
tuxshape
tux
volleyballshape
volleyball
windowsshape
windows
yinyangshape
yinyang
loveshape
love
doveshape
dove
first-kissshape
first-kiss
heart-tailshape
heart-tail
i-heart-u-tooshape
i-heart-u-too
carefree-doveshape
carefree-dove
i-heart-ushape
i-heart-u
multi-heartsshape
multi-hearts
pishape
pi
clovershape
clover
balloonshape
balloon
cake-sliceshape
cake-slice
candle-newshape
candle-new
party-hatshape
party-hat
party-faceshape
party-face
dancing-girlshape
dancing-girl
wine-glassshape
wine-glass
pandashape
panda
light-bulbshape
light-bulb
globeshape
globe
slipshape
slip
broken-heartshape
broken-heart
smiley-faceshape
smiley-face
easter-bunnyshape
easter-bunny
carrotshape
carrot
egg-fullshape
egg-full
egg-outlineshape
egg-outline
egg-stripeshape
egg-stripe
egg-heartshape
egg-heart
egg-starshape
egg-star
cute-butterflyshape
cute-butterfly
basketshape
basket
tulipshape
tulip
angelshape
angel
bellshape
bell
candleshape
candle
candy-caneshape
candy-cane
double-candy-caneshape
double-candy-cane
gingerbread-manshape
gingerbread-man
hollyshape
holly
presentshape
present
ribbonshape
ribbon
rocking-horseshape
rocking-horse
santashape
santa
sleighshape
sleigh
snowmanshape
snowman
stockingshape
stocking
treeshape
tree
snowflakeshape
snowflake
firefoxshape
firefox
running-foxshape
running-fox
fox-faceshape
fox-face
tankshape
tank
busshape
bus
car-frontshape
car-front
rocketshape
rocket
clothes-hangershape
clothes-hanger
coffee-cupshape
coffee-cup
cogshape
cog
command-signshape
command-sign
eyeshape
eye
facebookshape
facebook
flagshape
flag
wrenchshape
wrench
thumb-upshape
thumb-up
leafshape
leaf
magnifying-glassshape
magnifying-glass
paint-brushshape
paint-brush
scissorsshape
scissors
paperclipshape
paperclip
planetshape
planet
puzzle-pieceshape
puzzle-piece
chess-horseshape
chess-horse
rotateshape
rotate
telephoneshape
telephone
shieldshape
shield
smiley-invertedshape
smiley-inverted
tagshape
tag
top-hatshape
top-hat
infinityshape
infinity
round-wine-glassshape
round-wine-glass
ubuntushape
ubuntu
seahorseshape
seahorse
houseshape
house
boatshape
boat
twittershape
twitter
nike-swooshshape
nike-swoosh
googleshape
google
mcdonaldsshape
mcdonalds
mickey-mouseshape
mickey-mouse
supermanshape
superman
grad-capshape
grad-cap
diamondshape
diamond
olympic-logoshape
olympic-logo
reindeershape
reindeer
skateshape
skate
skiershape
skier
snowboardershape
snowboarder
shooting-starshape
shooting-star
hanging-stockingshape
hanging-stocking
evergreen-treeshape
evergreen-tree
rounded-snowflakeshape
rounded-snowflake
butterfly-heartshape
butterfly-heart
cupidshape
cupid
double-heartshape
double-heart
love-dovesshape
love-doves
wide-heartshape
wide-heart
roseshape
rose
teddyshape
teddy
skinny-heartshape
skinny-heart
nyan-catshape
nyan-cat
minionshape
minion
bananashape
banana

photos (optional)
Type: Array

You can specify a particular set of photos to use in the collage widget. To do so, set photos in settings. The parameter is an array of objects, each of which are composed of "url" (the URL to the image) and "link" (an optional URL that is associated with the image). Note that calling this function will set up the widget to bring the user to the Add Photos dialog with your preselected images immediately displayed. Here is an example photos object.

[{ 
	"url" : "http://a.webutation.net/a/1/getloupe.com.jpg",
	"link" : "http://www.getloupe.com/"
}, {
	"url" : "http://www.gearthblog.com/images/images509/disneyparis.jpg",
	"link" : "http://www.disney.com/"
}]

num_photos (optional)
Type: Number

You can specify the number of photos for a collage. By default, an appropriate number of photos is used to fill each shape in the collage widget (this default changes depending on the shape). However, you can specify the number of photos to use for a collage using num_photos in settings. The value is an integer indicating the number of photos to use for the collage. The minimum number of photos is 1 and maximum is 200.

start_state (optional)
Type: String

You can specify the stage of the widget. The string value is either: "default" (default behaviour), or "edit" (the collage starts in the edit phase of the collage process, but you must also be sure to specify photos in the settings), or "upload" (where the splash screen is skipped and the user is taken to the Upload screen of the Add Photos dialog immediately).

photo_spacing (optional)
Type: Number

The spacing between photos in the collage, in percentage, relative to the size of the photos. Default is 75.

background_color (optional)
Type: String

You can specify the a default color for the collage background. The value is hexadecimal notation for the combination of red, green, and blue color values. The hex values are written as 3 double digit numbers, concatenated to form a string. The default color is "FFFFFF" (white).

border_color (optional)
Type: String

You can specify the a default color for borders around photos. The value is hexadecimal notation for the combination of red, green, and blue color values. The hex values are written as 3 double digit numbers, concatenated to form a string. The default color is "F3F3F3" (a light gray).

tier (optional)
Type: Number

The tier is the upper limit of the collage's width and height in pixels. You can specify the tier as an integer indicating the maximum number of pixels for the collage. Available options are: 500 or 1000. To generate a collage a higher resolution collage, use this method.

watermark (optional)
Type: Boolean

Specify false to have no watermark on the collage, or true (default) to have a watermark. For this parameter to work, you must also specify a tier.

products (optional)
Type: Array

The user can choose from the list of products in the collage app. This is achieved via the Sizing button in the side bar of the collage app. Clicking this button opens a modal window that includes a drop down menu listing the available products. There are some default options available for the user. However, it is best to specify your own products depending on your needs. When you specify you own products, the default options are replaced by your own specifications.

To specify your own products, you can provide a custom parameter, called products, when launching the widget. Products is essentially a list of available options describing the final collage that the user wants to generate.

Each product should have an ID (optional), name, size, and default (optional). The ID can be any string that allows you to uniquely identify the product. The name parameter should be a string that is understandable by the user, for example 8" x 10" ($5.00). The size is an array of integers consisting of the expected width and height of the product. You can specify an automatic size for the collage by using the string "auto". You can have one of your products be selected by default by setting the default setting to true.

If you specify products, the widget will return via the callback a string, selected_product, representing the user-selected product.

This is the format of the objects in the product array:

[{
	id: "Product identifier", (optional)
	name: "Product name",
	size: [width, height],
	default: true (optional)
}]
	

To see an example, go here.

Picker-specific parameters

These are the parameters for the photo picker widget:

selection_limit (optional)
Type: Number

The number of photos that the user can keep in the photo drawer.

multiple_selection (optional)
Type: Boolean

Whether the user can select multiple photos (true) or one at a time (false).

exclude (optional)
Type: String

To exclude a particular feature. There is only one available option at the moment, "upload" which removes the upload button and disallows photos from being dragged and dropped into the widget for uploading.

start_state (optional)
Type: String

You can specify the stage of the picker. The string value is either: "default" (default behaviour), or "upload" (where the splash screen is skipped and the user is taken to the Upload screen immediately).

How do I launch the widget?

You can launch the widget by calling _loupeWidget.open(function). The optional parameter is a function that will be called when the widget is done. The callback will be called with a response parameter that will contain the collage url. Here is an example:

_loupeWidget.open(function(response) {
	if (response && 'collage_url' in response) {
		// do something with the resulting collage image
		var logo = document.getElementById('collage');
		logo.src = response.collage_url;
	}
});

Sample response

The response object is provided in the callback.

{
	"collage_url" : "http://collages.shapecollage.com/shape-collage-ti0r7o7k.jpg",
	"cid" : "ti0r7o7k", 
	"width" : 313, 
	"height" : 720
}

Basic example code

<html>
	<head>
	
		<script src='http://www.getloupe.com/js/widget/loupeWidget.js' type='text/javascript'></script>	
			
		<script type='text/javascript'>

			_loupeWidget.init({ 
				'app_id' : 'your_app_id_goes_here'
			});

			// function for opening the collage widget
			function openCollageWidget() {
				_loupeWidget.open(function(response) {
					// the function that the collage widget will call once it is complete
					if (response && 'collage_url' in response) {				
						// do something with the resulting collage image
						var logo = document.getElementById('collage');
						logo.src = response.collage_url;
					}
				});
			}
		</script>
		
	</head>
	
	<body>
		<input id='btn' type='submit' value='Loupe Collage Widget' style='vertical-align: top;' 
			onclick='openCollageWidget()' />
		<img id='collage' />
	</body>
</html>

Example code with presets

<html>
	<head>

		<script src='http://www.getloupe.com/js/widget/loupeWidget.js' type='text/javascript'></script>	
			
		<script type='text/javascript'>		

			_loupeWidget.init({ 
				'app_id' : 'your_app_id_goes_here', 
				'shape_url' : 'heart',
				'start_state' : 'default',
				'photos' : [{
					'url' : 'http://a.webutation.net/a/1/getloupe.com.jpg',
					'link' : 'http://www.getloupe.com/'
				}, {
					'url' : 'http://www.gearthblog.com/images/images509/disneyparis.jpg',
					'link' : 'http://www.disney.com/'
				}],
				'num_photos' : 100
			});
			

			// function for opening the collage widget
			function openCollageWidget() {
				_loupeWidget.open(function(response) {
					// the function that the collage widget will call once it is complete
					if (response && 'collage_url' in response) {				
						// do something with the resulting collage image
						var logo = document.getElementById('collage');
						logo.src = response.collage_url;
					}
				});
			}
		</script>

	</head>
	
	<body>
		<input id='btn' type='submit' value='Loupe Collage Widget' style='vertical-align: top;' 
			onclick='openCollageWidget()' />
		<img id='collage' />
	</body>
</html>

Example code with products

<html>
	<head>

		<script src='http://www.getloupe.com/js/widget/loupeWidget.js' type='text/javascript'></script>	
			
		<script type='text/javascript'>		

			_loupeWidget.init({ 
				'app_id' : 'your_app_id_goes_here', 
				'shape_url' : 'heart',
				'start_state' : 'default',
				'photos' : [{
					'url' : 'http://a.webutation.net/a/1/getloupe.com.jpg',
					'link' : 'http://www.getloupe.com/'
				}, {
					'url' : 'http://www.gearthblog.com/images/images509/disneyparis.jpg',
					'link' : 'http://www.disney.com/'
				}],
				'num_photos' : 100,

						
				'products' : [{
					id: 'Portrait',
					name: 'Canvas Portrait $70',
					size: [2400, 2000],
					default: true // this is optional
				}, {
					id: 'Lanscape',
					name: 'Canvas Landscape $70',
					size: [2000, 2400],
				}, {
					id: 'Square',
					name: 'Postcard Square $100',
					size: [3000, 3000],
				}]	
				
			});

			// function for opening the collage widget
			function openCollageWidget() {
				_loupeWidget.open(function(response) {
					// the function that the collage widget will call once it is complete
					if (response && 'collage_url' in response) {				
						// do something with the resulting collage image
						var logo = document.getElementById('collage');
						logo.src = response.collage_url;
					}
				});
			}
		</script>

	</head>
	
	<body>
		<input id='btn' type='submit' value='Loupe Collage Widget' style='vertical-align: top;' 
			onclick='openCollageWidget()' />
		<img id='collage' />
	</body>
</html>

Generating higher resolution collage after using the widget

Typically, the 500 and 1000 pixel collages generated from the widget are meant as previews for the user before they confirm purchasing the final product. Once the user confirms the order, you can generate the high resolution collage, up to 12000 pixels. For the time being, we support up to and including 3000 pixel collages. However, if you need higher resolution, please contact us and we will enable our system to support greater resolutions.

In order to get different resolutions of the collage after they are generated from the widget, you will need to construct a link to request the collage using a particular tier, the collage identifier, and your private key (not your app_id!). Since this link uses your private key, it is important to keep the link secret from your users. The format of the link is below:

http://www.getloupe.com/api/collage/tier/cid?private_key=your_private_key_goes_here

Where

  • cid is the collage ID, a string identifier that is returned by the widget.
  • tier is the numerical upper limit of the collage's width and height in pixels. Valid values are: 500, 1000, 3000, 6000, 9000, and 12000. Please note that the collage will be scaled up no more than the selected products size when the collage was created (see note below). If you plan on using tiers above 3000, contact us to enable it on your account.
  • your_private_key_goes_here is a string that is a secret identifier similar to app_id in that it identifies which application is making the request. This key should not be shared. Note: this is not the same as your app_id!

Note: When generating high resolution collages, please note that the desired collage dimension should be specified in the products parameter for the widget. While the collages generated will be of that selected product size, you would need to choose the tier based on the maximum size you want generated. For example, if your product was square and specified to be 2400x2000, and your tier is set to 3000, the collage generated would be 2400x2000. Alternatively, if you had set the tier to 1000, then the collage generated would be 1000x833.