README.rest

jQuery Preview

jQuery Preview is a plugin by Embedly that allows
developers to create tools that enable users to share links with rich previews
attached. This method of letting users select thumbnails, edit title and
description has been adopted as the norm across the web. This plugin allows
developers to easily implement this functionality without building the entire
infrastructure themselves. Instead relying on on Embedly to generate the
metadata.

We have made this plugin overly verbose and infinitely customizable. Our goal
is not to dictate design, merely give a set of tools to make it easy to create
a custom experience.

And you are done setting up the front end solution for jQuery Preview. The
rest of this document will go into how to customize Preview.

How it Works

The plugin works by listening to the field on paste, keyup, preview
and blur. If a URL is entered a call is made to Embedly's Extract endpoint and the
result is then passed to the render function. render uses sprintf
to create a selector, so the user can pick a thumbnail associated with the
URL.

jQuery Preview just saves all the data and changes associated with the URL on
the input using jQuery's data. It's up to the developer to choose how they want
to deal with that data on submit. jQuery Preview comes with a helper function
addInputs so all the data can be added to the form. This is the code to
enable it:

The developer can then choose how they wish to display the preview in the feed.
We will show some simple examples for handling this in the documentation.

Preview

Preview holds all the logic for calls to Embedly and rendering the selector.

Options

bind

By default preview will bind to keyup, blur and paste if you
wish to define your own bindings you can set this attribute to false:

// Don't bind the listeners
$('#url').preview({bind:false});
// When a use hits Attach, trigger a preview of the link.
$('a.attach').on('click', function(){$('#url').trigger('preview')});

error

Called when the url that the user inputed throws an error somewhere along
the way. Depending on the use case you may want notify the user or hide it
from them. The default behavior is to not notify the user. To notify them
you can use:

Called after a URL has been successfully rendered by the selector. Useful
if you want to change state after the URL has been successfully processed.
For example if you want to change a button from 'Share' to 'Submit' you can
do it like so:

If you would like to create your own selector, overwrite render with
your own function. We will go in more detail, in the writing your own
selector function, but here is the simplest example I could think of:

$('#url').preview({
render: function(obj, options){
// Put the title after the input.
$(this).after(obj.title);
}});

Events

preview

Manually trigger the input to fetch the URL. This is generally only needed
if bind is set to false:

$('a.attach').on('click', function(){$('#url').trigger('preview')});

loading

Triggered when the request is being made to the API endpoint:

$('#url').on('loading', function(){$('.loading').show()});

loaded

Triggered when a response has been returned from the API endpoint:

$('#url').on('loaded', function(){$('.loading').hide()});

close

Triggered when the selector should be closed. If you are implementing a
custom selector, you must listen for this event:

Custom Selector

It's actually recommended that you build a custom selector. While the default
one is pretty good, you are going to want to customize it more than just the
default styles. Here's how you can create your own.

Render

To create our own selector you just need to pass in a function into the
render option when calling preview:

The render function should accept a data argument that is the response from
the extract endpoint. options is also passed in if you would like to
set custom options in preview. this is the HTMLElement of the input. This
will let you listen for events or trigger events on the input.

Server Side

When the user submits the link, we must save it and echo it back to the page
so it can be displayed. The code contains a simple Tornado example of this dance in app.py.
When we set up the form we need to specify where we are going to be making the
the AJAX post. In this case it's '/update':