Skip to content

Latest commit

 

History

History
220 lines (142 loc) · 9.36 KB

README.md

File metadata and controls

220 lines (142 loc) · 9.36 KB
Raw

What is LoadGo?

LoadGo is a Javascript plugin that allows you to create a progress bar by using your own images.

  • Perfect for logo image animation when user is waiting for something to be loaded (a website, retrieving information, updating status, etc.)

  • It creates an overlay above your desire DOM element and simulates a loading process using width calculations.

  • Tested in IE 9, IE 10, IE Edge, Google Chrome and Mozilla Firefox.

(02-May-2016) I'm currently working in a Wordpress version using PACE. I will release it in a couple of weeks with admin options and a lot of customize features.

I setup my Chrome Dev tools to simulate a 2Mb/s connection and added some useless scripts to increase webpage size, so Loadgo effect can be seen. If you want to know more, check this video: https://youtu.be/VjSE7KzZU60

LoadGo for Wordpress

(05-May-2016) I've just uploaded LoadGo for WP, a Wordpress plugin which uses PACE and LoadGo. With LoadGo for WP you can use your own logo as a page loader in your Wordpress website.

Official Wordpress link: https://wordpress.org/plugins/loadgo-for-wp/

Github: https://github.com/franverona/LoadGo-for-WP

Changelog

2.1 - Latest release (12-04-2016)

  • Fix bug with LoadGo jQuery version where 'left to right' direction was not working.
  • Added some examples.

2.0 (02-04-2016)

  • Pure Javascript version release: now you can use LoadGo plugin without jQuery.
  • Fix overlay reposition bug when resizing window.

1.0.1 (02-11-2015)

  • Fix for 'undefined' errors with newer jQuery versions.

1.0 (15-10-2015)

  • First release.

How to use LoadGo

If you are using jQuery, remember that you have to include it BEFORE using this plugin. I tested it with jQuery v1.11.2, and it works well.

If you are not using jQuery, just include LoadGo script and start using it. Easy as hell.

Production environment (CDN)

(17-Oct-2015) LoadGo is now hosted on cdnjs, so you can link it directly. Thanks so much to cdnjs team for their quickly response! (issue#5927)

<!-- If you use jQuery -->
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/LoadGo/2.1/loadgo.min.js"></script>

<!-- If you don't use jQuery -->
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/LoadGo/2.1/loadgo-nojquery.min.js"></script>

Development environment

1. Download LoadGo from this link or clone it from GitHub

2. Uncompress it (if zipped) and copy LoadGo folder into your JS scripts.

3. Insert the following code in your webpage:

<!-- If you use jQuery -->
<script type="text/javascript" src="loadgo/loadgo.js"></script>

<!-- If you don't use jQuery -->
<script type="text/javascript" src="loadgo/loadgo-nojquery.js"></script>

You can also use the minified version:

<!-- If you use jQuery -->
<script type="text/javascript" src="loadgo/loadgo.min.js"></script>

<!-- If you don't use jQuery -->
<script type="text/javascript" src="loadgo/loadgo-nojquery.min.js"></script>

Important: LoadGo needs images fully loaded in order to read its dimensions correctly. If you are not sure when this is going to happen, you can use this piece of code with each image:

// jQuery
$("#my-image").load(function() {
  $('#my-image').loadgo();
}).each(function() {
  if(this.complete) $(this).load();
});

// Javascript
var image = document.getElementById("my-image");
image.onload = function () {
  Loadgo.init(this);
};

Examples

You can check for examples following this link: [http://franverona.com/loadgo/] (http://franverona.com/loadgo/) or in the examples folder.

Documentation

Introduction

LoadGo is a plugin which provides you a better way to keep your users update about loading process that take some time to be completed. For example:

  • Users upload a file to your server.
  • System is converting a file to PDF.
  • Current page is loading.
  • Etc.

This plugin won't control asynchronous behaviour for your loading process, so you have to do that by yourself in your app.

In order to do this, LoadGo creates an overlay on top of your image, and playing with its width simulates a loading behaviour. This overlay is set by using position: absolute CSS property, so your DOM element needs to be inside a DIV element or things won't look good.

This piece of code is a minimum example:

// HTML
<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 a DOM 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 three 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.
  • opacity: overlay transparency. Default is 0.5
  • animated: true if setprogress CSS width transitions are enable, false otherwise. Default is true (NOTE: Internet Explorer does not support CSS transitions).
  • image: image url to bet use if want a background image instead of a simple color. This option disables bgcolor option.
  • class: CSS class which will be applied to overlay. By using this option you should assure that all looks good because some CSS options for class could invalidate other LoadGo plugin CSS options. Default is none.
  • resize: resize function. LoadGo provides a function which automatically resizes LoadGo 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'.
  • filter: CSS image filter according to [CSS filter property] (https://developer.mozilla.org/en-US/docs/Web/CSS/filter). Possible values: 'blur', 'grayscale', 'sepia', 'hue-rotate', 'invert', 'opacity'.

Methods

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

// jQuery
$('#logo').loadgo('setprogress', 50);

// Javascript
Loadgo.setprogress(document.getElementById('logo'), 50);

Reset progress: set progress to zero automatically. 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: return current progress. This number will be between 0 and 100 (percentage).

// 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 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'));

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 update 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
  }
});

LoadGo is under MIT License. Feel free to download, modify and adapt it to your own purposes. If you find any bug, send a pull request or write an issue.