Introduction

LoadGo is a plugin which provides you a better way to keep your users updated about a loading process. Some use cases may be:

User uploads a file to your server.

System is converting a file to PDF.

Current page is loading.

Important This plugin does not control asynchronous behaviour for your loading process, so you have to do that by yourself in your app.

To do this, LoadGo wraps your image into a div , and add an overlay inside this wrapper. Then, it will change overlay's dimensions when setting a progress to simulate a loading behaviour.

LoadGo will work only on img elements given by id .

This piece of code is a minimum example:

<div> <img id="logo" src="logo.png" alt="Logo" /> </div> // jQuery $('#logo').loadgo(); // Javascript Loadgo.init(document.getElementById('logo'));

Initialization

LoadGo needs to be initialized in an img element before use.

jQuery $('#logo').loadgo(); Javascript Loadgo.init(document.getElementById('logo'));

Now, you are capable of set progress and simulate any kind of progression. LoadGo have methods and a couple of options which will help you.

LoadGo also applies an empty CSS class to overlay called loadgo-overlay in case that you want to implement your own resize function or some other advanced features.

Options

bgcolor : background overlay color in hexadecimal or RGB. Default is #FFFFFF .

: background overlay color in hexadecimal or RGB. Default is . opacity : overlay transparency. Default is 0.5

: overlay transparency. Default is animated : true if setprogress CSS width transitions are enable, false otherwise. Default is true (remember that Internet Explorer does not support CSS transitions ).

: true if CSS width transitions are enable, false otherwise. Default is (remember that ). image : image url to be used if you want a background image instead of a simple color. This option disables bgcolor option.

: image url to be used if you want a background image instead of a simple color. This option disables option. class : CSS class which will be applied to overlay. Make sure that all looks good because some CSS options could invalidate other LoadGo plugin CSS options. Default is null .

: CSS class which will be applied to overlay. Make sure that all looks good because some CSS options could invalidate other plugin CSS options. Default is . resize : resize function. LoadGo provides a function which automatically resizes LoadGo overlay by default, but you can use your own.

: resize function. provides a function which automatically resizes overlay by default, but you can use your own. direction : animation direction. Possible values: lr (left to right), rl (right to left), bt (bottom to top), tb (top to bottom). Default is lr .

: animation direction. Possible values: (left to right), (right to left), (bottom to top), (top to bottom). Default is . filter: CSS image filter according to CSS filter property. Possible values: blur , grayscale , sepia , hue-rotate , invert , opacity .

Methods

Get / Set options: Get/Set plugin options. When setting options, the parameter must be a JSON object. This is specially useful if element is already initiate, and you want to change properties dynamically based on your app's logic.

// jQuery - Get current options $('#logo').loadgo('options'); // jQuery - Set options $('#logo').loadgo('options', { direction: 'bt' }); // Javascript - Get current options Loadgo.options(document.getElementById('logo')); // Javascript - Set options Loadgo.options(document.getElementById('logo'), { direction: 'bt' });

Set Progress: Set progress number to loading overlay. This number must be between 0 and 100.

// jQuery $('#logo').loadgo('setprogress', 50); // Javascript Loadgo.setprogress(document.getElementById('logo'), 50);

Reset progress: Reset current progress. This is really useful when you are using the same element for multiple loads, and you need to reset all before starting a new one.

// jQuery $('#logo').loadgo('resetprogress'); // Javascript Loadgo.resetprogress(document.getElementById('logo'));

Get progress: Get current progress. This number will be between 0 and 100.

// jQuery $('#logo').loadgo('getprogress'); // Javascript Loadgo.getprogress(document.getElementById('logo'));

Loop: Sets overlay to loop indefinitely until stopped. This is useful for situations where you have no way of measuring the progress. This method accepts a duration (ms) parameter to customize animation speed.

// jQuery $('#logo').loadgo('loop', 10); // Javascript Loadgo.loop(document.getElementById('logo'), 10);

Stop: Stops the loop previously initiated with loop method and shows the full image. Since loops are indefinite we need to use this method to manually stop it.

// jQuery $('#logo').loadgo('stop'); // Javascript Loadgo.stop(document.getElementById('logo'));

Destroy: Removes all plugin properties and restore everything. This method will also removes div elements created ( loadgo-container and loadgo-overlay ), so make sure that you are not using them for anything else before calling destroy .

// jQuery $('#logo').loadgo('destroy'); // Javascript Loadgo.destroy(document.getElementById('logo'));

Real example

In your webpage, you are using a jQuery plugin like Uploadify to give your users a way to upload files to you page (for example: update his/her web avatar). Most of these plugins provide events like onUploadStart , onUploadProgress or onUploadComplete . These events have variables which give you a lot of information about your current load progress (file size, current uploaded bytes, etc).

You can use this information with LoadGo to update logo overlay like this:

// Set LoadGo on your Logo $('#logo').loadgo(); // Set Uploadify on your upload input $('#uploadinput').uploadify({ // init options... onUploadStart: function (event) { // Upload is going to start, so we need to reset loadgo $('#logo').loadgo('resetprogress'); }, onUploadProgress: function (event) { // We receive some bytes on our upload and updates loadgo progress, // but first, we should calculate total uploaded percentage var p = event.bytesLoaded / event.bytesTotal; $('#logo').loadgo('setprogress', p); }, onUploadComplete: function (event) { // Upload complete } });

Current LoadGo examples

To create LoadGo minimum examples, some intervals were set to recreate this effect. Following code is used by CocaCola example at the beginning of this page:

$(document).ready(function () { $('#cocacola').loadgo(); }); // We create an interval which will be removed when progress completes var cocacolaInterval; function mainDemo () { var p = 0; $('#cocacola').loadgo('resetprogress'); // reset progress to start again cocacolaInterval = window.setInterval(function (){ if ($('#cocacola').loadgo('getprogress') == 100) { // When progress completes, we have to clear the interval window.clearInterval(cocacolaInterval); } else { var prog = p*10; $('#cocacola').loadgo('setprogress', prog); p++; } }, 150); };