Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
JavaScript CSS

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
assets
dist
examples
libs
src
test
.gitignore
.gitmodules
.jshintrc
Gruntfile.js
LICENSE-BSD
README.textile
jquery-liveupdate.json
package.json

README.textile

Documentation

Two light-weight plugins for publishing Blogsmith Live Update content

For the premiere, full-featured Liveblog Publisher, check out Joe Bartlett’s Liveblog Publisher.

This is a light-weight adaptation built for use with jQuery 1.5.2 and above.

Live Update is two simple plugins. $.liveUpdateApi fetches liveblog data using a postid and a domain and provides updates via a custom event. $.liveUpdateUi is a simple, example implementation of the UI to respond to these updates that responds to new content, edits, comments, and deletions.

Credit where credit is due: Liveblog Publisher (LbP) was heavily consulted in writing this lighter version. Some patterns were even copied entirely.

How to use Live Update

Requirements

Live Update officially requires jQuery 1.5.2 or higher. (It has been tested to work as low as jQuery 1.4.2, however, but we don’t recommend it.)

The following browsers have been tested with known support, for both the Javascript and CSS:
IE (6+), Chrome (11+), Firefox (3.6+), Safari (3+), Opera (9+)

Files

The plugins’ JS and CSS are hosted as a bundle on AOL’s global origin server.

JS: http://o.aolcdn.com/os/aol/liveupdate/jquery.liveupdate.min.js
CSS: http://o.aolcdn.com/os/aol/liveupdate/aol.liveupdate.css

Include them on your page.

The files are also located in the dist folder in this repo, in both minified and unminified versions. The two plugins are also provided separately here, in case you want to use only the API plugin and implement your own UI.

Instantiation

Instantiate it using code along these lines:

 $(document).ready(function () {
  var $myLiveBlog = $('#myLiveBlog').liveUpdateUi({
    // This is an example post on the Bootcamp blog
    postId: '20317028',
    // This is the URL to the Bootcamp blog
    url: 'http://bootcamp.aol.com/'
  });
});

The element you instantiate $.liveUpdateUI on (here, <div id="#myLiveBlog"></div>) can have content. That content will be displayed until there are actually updates on the live blog post in question and the begin time has passed, if that option has been set. This allows you to have pre-event content. Once the initial conditions have been met, the element in question is emptied and refilled with live blog content.

That’s the quick and dirty. More detailed documentation is provided below.

Blogsmith Setup

Blogsmith blogs have to be set up to have live blog posts.

  1. In the CMS, an owner of the blog in question needs to go to Management >> Settings and change “Live Content Tool” to Live Update Tool (Ver 2).
  2. This line needs to be present in the `.htaccess` file of the blog in question (accessed via the Design tool):
RewriteRule ^live-update/([0-99]+)/([0-99]+)/?$ /index.php?&a=live-update&postid=$1&timestamp=$2 [QSA,L]

Order can affect the way this works, so it needs to be close to the top of your `.htaccess` file.

$.liveUpdateUi(options)

The Live Update UI plugin provides user interface elements for displaying live blog updates. It requires and wraps the API plugin, so if you use it you don’t have to separately instnatiate the API. Also: you may pass options for the API plugin (such as `postId` and `url`) through the UI plugin.

Example Usage

$('#myWidget').liveUpdateUi({
  postId: '20334012',
  url: 'http://liveupdater.aol.com/',
  toolbarEnabled: true,
  begin: new Date('9/21/2012 15:27:00 GMT-0400'),
  end: new Date('9/21/2012 15:30 GMT-0400'),
  height: 700
});

Available Options

Property Type Default Description
Required
url string null The domain of the Blogsmith blog with your live blog post. Ex: http://liveupdater.aol.com
postId number null The id of the live blog post, i.e. 20317028. Can be found in the URL string while editing the post in question.
height number 0 Set the height of the post container. This is required for the UI slider
Optional
toolbarEnabled boolean false Turns on or off toolbar functionality.
timelineEnabled boolean true Turns on or off the timeline slider UI in the toolbar.
tweetButtons boolean true Turns on or off tweet buttons in updates.
linkParams string null URL params to append to all outgoing links within the post text; Ex: ‘icid=aol123’
thumbnails boolean true Whether to show a thumbnail for uploaded images. If set to false, will show the full image instead.
dims boolean true Whether to use DIMS for thumbnails. If false, uses default thumbnails from Blogsmith. Only applicable if thumbnails is true.
thumbnailDimensions object { height:100, width:null } Dimension restrictions for thumbnail images. If dims is true, uses this for resizing; else if thumbnails is false, uses this for setting max-width and max-height CSS.
thumbnailExcludeFilter string null Filter of which files to exclude from thumbnail generation. Should be a comma-separated list of file patterns. Only applicable when thumbnails is true. Ex: ‘.gif’
postLimit number null Display only the recent n posts.
memberSettings object null Set various options for how bloggers are rendered, based on each memberId sent from the server. Ex:
{
‘987654321’: {
profileImage: ‘http://www.gravatar.com/avatar/some-hash.png’,
featured: true
}
}

$.liveUpdateApi(options)

The Live Update API plugin initiates a recurring poll of the Blogsmith Live Updater API. The first time, it receives all updates that currently exist on the live blog post. It begins checking the API every three seconds (or so) and only returns new or edited data. It provides this data to the jQuery object on which it’s initiated as a custom “update” event.

Example usage

// Initiate the Plugin
$('#myLiveBlog').liveUpdateApi({
  postId: 20334012,
  url: 'http://liveupdater.aol.com/'
});

// Output the data to the console
$('#myLiveBlog').bind('update', function (event, data) {
  console.log(data);
});

Methods

Use methods by passing their name as an argument to the plugin.

$('#myLiveBlog').liveUpdateApi('pause');
Method Description
pause Pause updates from the API.
play Resume updates from the API.
reset Resets the API so that the next update will be like the first one, and will return all available data.

Events

These events are triggered on the element used to instantiate the $.liveUpdateApi() plugin. Ex:

$('#myLiveBlog').liveUpdateApi({ options });
$('#myLiveBlog').on('begin', function (event) { ... });
Event Description
begin Fired one time after the first update is received from the API with non-empty data.
end Fired when the API is no longer polling for updates, either because alive is false, or the end option was specified, and that time has passed.
update Fired every time non-empty data is received from the API. Passes the normalized response data object with the event.
status Fired whenever the liveblog status changes. Includes ‘status’ property that is one of: (disabled, notstarted, completed, live)

Available Options

Property Type Default Description
Required
url string null The domain of the Blogsmith blog with your live blog post. Ex: http://liveupdater.aol.com
postId number null The id of the live blog post, i.e. 20317028. Can be found in the URL string while editing the post in question.
Optional
begin Date Object1 null Sets a time for your live blog to begin polling the API for updates.
end Date Object1 null Sets a time for your live blog to stop polling the API for updates.
alive boolean true If set to false, your live blog will only hit the API once to fetch all available data – it will not continue polling the API.
callbackPrefix string ‘LB_U’ The prefix used for the JSONP call. Probably shouldn’t be changed.
pollInterval Number null The delay, in seconds, between calls to the Blogsmith API. For many events, three seconds (what Blogsmith defaults to if this is set to null) is overkill. For ongoing events with infrequent updates, setting the delay to something like 30 seconds tremendously reduces resource usage.
trafficPing boolean true If true, polls the appropriate Blogsmith traffic URL every thirty seconds for analytics.
fetch function null Reference to alternate function to execute the fetch request, useful for simulating different data patterns, or testing the UI, for instance. Signature should be function(state, successCallback(response), errorCallback(response))

1 Here’s an easy tool for creating a valid JS date string.

A Warning About Sandboxes

CMS can not, will not, has never, and will never dynamically update Sandbox’d Sites in Beta mode. Beta Mode is strictly for testing a site with the production level caching layer turned on. It is built this way to discourage people from trying to run production sites from the sandbox.

“If you wish to test a Live Update post, and have it update LIVE. 1. Turn off Beta mode. 2. Point the updater to the production api.

Development

Do you want to contribute to LbL? Or fork it and modify it for your own needs? Awesome. You’ll need a few more things.

If you’ve got these installed, you should be able to build the project from your command line by going to the root directory and typing grunt.

You can use grunt watch-serve to run a watcher that’ll rebuild the project whenever key files are changed and also let you view the project at localhost:8000.

Important note: as of this writing, only Jeremy and Nate have installed the requirements and it was as we were building this. If you’re trying to set yourself up to develop, you may be the first person. Please do us and future developers a favor and tell us about any problems you run into! Don’t just quietly solve them yourself because you’re super smart. We want to make this as easy as possible.

License

Copyright © 2012, AOL Inc. All rights reserved.

https://github.com/aol/jquery-liveupdate/blob/master/LICENSE-BSD

Something went wrong with that request. Please try again.