client photo

Pick and upload user photos.

Dom.onTap !->
	Photo.pick 'camera', 'category:favorite'

This module works in unison with the photo server module.

Picking a photo happens in three steps:

• pick (the photo source and) the photo
• upload the photo
• claim the photo

Picking a photo might temporarily suspend the mobile Happening app. After resuming, uploading will start immediately.

The problem with the suspending app is that the webview may be completely torn down, destroying any transient data such as registered callbacks. This complicated this API design, since a simple onFinished parameter for the pick() function would not work.

Autoclaim

By default, autoclaim is enabled, meaning that once the upload completes, the server-side onPhoto event will fire. Pass false as second argument to pick() to disable autoclaim.

Disabling autoclaim might be useful when you are unsure if you really want the photo, such as when you're giving the user the possibility to crop a photo directly after picking. After the crop operation, you could use the client-side claim() with the crop parameters, which will then be available in the onPhoto event handler.

Also, autoclaim is less useful when the photo is part of some unsubmitted state, such as a creation form. In such a case, you could claim the photo in the backend rpc code using the server-side claim() call.

Example:

client.coffee:
	Dom = require 'dom'
	Photo = require 'photo'
	Ui = requir 'ui'

	Dom.section !->
		Dom.text "API to show, upload or manipulate photos."
		Ui.bigButton "Pick photo", !->
			Photo.pick()
		if photoKey = Db.shared.get('photo')
			(require 'photoview').render
				key: photoKey

server.coffee
Db = require 'db'

exports.onPhoto = (info) !->
	# entrypoint when a photo is uploaded by the plugin
	log 'onPhoto', JSON.stringify(info)
	Db.shared.set 'photo', info.key

Showing unclaimed photos

Often, you'll want to show unclaimed photos as placeholders in your interface. Use unclaimed() to get a (reactive) reference to the unclaimed photo. When there are multiple, use the third parameter of pick as a unique local id.

Dom = require 'dom'
Obs = require 'obs'
Photo = require 'photo'
Ui = requir 'ui'

Dom.section !->
	Dom.text "API to show, upload or manipulate photos."	
	
	Obs.observe !->
		unclaimed = Photo.unclaimed('myPhoto')
		if unclaimed
			Dom.div !->
				Dom.style
					background: "url(" + unclaimed.thumb + ")"
					backgroundSize: '100%'
					height: '200px'
					width: '100%'
			Dom.div !->
				Ui.button 'discard', !->
					unclaimed.discard()
				Ui.button 'keep', !->
					unclaimed.claim() #calls server.onPhoto(info)
		else
			Dom.div !->
				Dom.style Box: 'center'
				Icon.render (data: 'camera', size: 60)
				Dom.onTap !->
					Photo.pick '', undefined, 'myPhoto'

Functions

pick(source?,serverArg?,localId?)

source can be "camera" or "gallery". Anything else will result in a modal asking the user.

When serverArg is set to undefined, pick will not call 'server.onPhoto' yet.

Use localId when autoclaim is disabled to differentiate between the different unclaimed photos.

unclaimed(filter?)

Reactively get object indicating unclaimed photo. filter can be a filter function, or a string that should match the localId parameter. The returned object contains the keys guid, localId, thumb and uri. The returned object also has two functions: claim() to trigger server.onPhoto(info) discard() to remove th photo without triggering anything.

You can use the guid to make your own rpc call.