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.
To get started you need to put jQuery, Embedly jQuery, jquery.preview.js and preview.css. into your page:
<head> <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js" type="text/javascript"></script> <script src="http://cdn.embed.ly/jquery.embedly-3.0.5.min.js" type="text/javascript"></script> <script src="http://cdn.embed.ly/jquery.preview-0.3.2.min.js" type="text/javascript"></script> <link rel="stylesheet" href="http://cdn.embed.ly/jquery.preview-0.3.2.css" /> </head>
Next set up a simple form that allows a user to input link:
<form action="/update" method="POST">
<input id="url" type="text" name="url"/>
<!-- Placeholder that tells Preview where to put the selector-->
<div class="selector-wrapper"></div>
</form>
You then need to tell preview what field to listen to:
<script>
// Set up preview.
$('#url').preview({key:'your_embedly_key'})
// On submit add hidden inputs to the form.
$('form').on('submit', function(){
$(this).addInputs($('#url').data('preview'));
return true;
});
</script>
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.
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:
// On submit add hidden inputs to the form.
$('form').on('submit', function(){
$(this).addInputs($('#url').data('preview'));
return true;
});
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 holds all the logic for calls to Embedly and rendering the selector.
bindBy default preview will bind to
keyup,blurandpasteif 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')});errorCalled 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:
$('#url').preview({ error: function(obj){ alert('The URL you entered was not processed.'); }});successCalled 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:
$('#url').preview({ success : function(obj){ $('button').text('Submit'); } });
render
If you would like to create your own selector, overwrite
renderwith 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); }});
previewManually trigger the input to fetch the URL. This is generally only needed if
bindis set to false:$('a.attach').on('click', function(){$('#url').trigger('preview')});loadingTriggered when the request is being made to the API endpoint:
$('#url').on('loading', function(){$('.loading').show()});loadedTriggered when a response has been returned from the API endpoint:
$('#url').on('loaded', function(){$('.loading').hide()});closeTriggered when the selector should be closed. If you are implementing a custom selector, you must listen for this event:
var render = function(data, options){ // Insert selector $(this).on('close', function(){ //Remove 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.
To create our own selector you just need to pass in a function into the
render option when calling preview:
var render = function(data, options){
// custom render
};
$('#url').preview({render:render});
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.
The simplest version of a custom selector looks like so:
var render = function(data, options){
// Add the title after the input.
$(this).after('<span>'+data.title+'</span>');
// remove the selector
$(this).on('close', function(){
$(this).siblings('span').remove();
});
};
jQuery Preview has no concept of displaying the item in a feed. This should be handled by the developer. This is a simple example from one of the demos:
$('#preview_form').on('submit', function(){
// Preview data.
var preview = $('#id_url').data('preview');
// Close the selector
$('#id_url').trigger('close');
$('#id_url').val('');
// Create a post using mustache, i.e. the nice way.
var template = ['<div class="row">',
'<div class="large-3 columns">',
'<img class="thumb" src="{{thumbnail_url}}"></img>',
'</div>',
'<div class="large-9 column">',
'<a href="{{original_url}}">{{title}}</a>',
'<p>{{description}}</p>',
'</div>',
'</div>'].join('');
html = $(Mustache.to_html(template, preview));
html.data('preview', preview);
html.on('click', function(){
var data = $(this).data('preview');
// Insert the video or rich object.
if (data.media.type === 'video' || data.media.type === 'rich'){
$(this).html(data.media.html);
return false;
}
return true;
});
// Display the item in the feed.
$('#feed').append(html);
return false;
});
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':
<form method="post" action="/update"> <input type="text" class="xlarge" name="url" id="id_url" /> <input id="id_submit" type="submit" class="btn btn-primary" value="Share"/> </form>
We then build a handler to deal with the form data:
class UpdateHandler(tornado.web.RequestHandler):
def post(self):
#Overly verbose
data = {}
for name in ['type', 'original_url', 'url', 'title', 'description',
'favicon_url', 'provider_url', 'provider_display', 'safe',
'html', 'thumbnail_url', 'object_type', 'image_url']:
data[name] = self.get_argument(name, None)
# This also works
# data = dict([(k, v[0]) for k, v in self.request.arguments.items()])
# Save the data off and return the object that we will pass back.
obj = db.save(data)
# Write a json response
self.write(json.dumps(obj))
Once the data is successfully posted the response is passed into the Display object to be rendered and displayed.
To get you going even faster, Embedly hosts all the files you need on scripts.embed.ly. The latest version is available here:
http://cdn.embed.ly/jquery.preview-0.3.2.min.js http://cdn.embed.ly/jquery.preview-0.3.2.css
- Fixed a bug with media types in addInputs
- Fixed a bug with sprintf and added secure images.
- Full rewrite to simplify adding jQuery Preview to a site.
- Added the $.preview so it can be used before the a form is initialized.
- Added
errorandcallbackto the Preview object.