Skip to content

Commit

Permalink
cleanup; working on readme; updated tests
Browse files Browse the repository at this point in the history
  • Loading branch information
@chrisantonellis
chrisantonellis committed Feb 8, 2016
1 parent ee597a5 commit 5f2e118
Show file tree
Hide file tree
Showing 7 changed files with 219 additions and 137 deletions.
166 changes: 103 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,45 @@

freezeframe.js is a script that pauses animated .gifs and enables them to start animation
automatically on mouse hover / mouse click / touch event, or manually with trigger / release
functions. it also supports responsive images.
functions. It supports responsive images and works as a jQuery plugin.

1. [Examples](#examples)
2. [Files & Dependencies](#files_dependencies)
3. [Basic Usage: jQuery Plugin](#basic_usage_jquery_plugin)
4. [Basic Usage: Vanilla JS](#basic_usage_vanilla_js)
5. [Advanced Usage](#advanced_usage)
6. [Options Reference](#options_reference)
7. [Function Reference](#function_reference)

<a name="examples"></a>
## Examples
[http://ctrl-freaks.github.io/freezeframe.js/](http://ctrl-freaks.github.io/freezeframe.js/)

## Basic Usage
<a name="files_dependencies"></a>
## Files & Dependencies

1. Include the js and css from **/build**
1. Include the js and css from **/build/**

```
```html5
<link rel="stylesheet" href="freezeframe_styles.min.css">
<script src="freezeframe.min.js"></script>
```
If you do not use a packaged version the following dependencies are required
( can be found in **/src/js/vendor** ):
* imagesLoaded Packaged v4.0.0 ( [https://github.com/desandro/imagesloaded](https://github.com/desandro/imagesloaded) )
* jQuery
2. If you do not use a **packaged version** the following dependencies are required. These files can be found in **/src/js/vendor/**:
* imagesLoaded Packaged v4.0.0 ( [https://github.com/desandro/imagesloaded](https://github.com/desandro/imagesloaded) )
* jQuery
2. Add **freezeframe** as a class name on the .gifs you want processed
<a name="basic_usage_jquery_plugin"></a>
## Basic Usage: jQuery Plugin
1. Capture the image you want by selector and run the **freezeframe()** function.
```
$('.my_class').freezeframe();
```
<a name="basic_usage_vanilla_js"></a>
## Basic Usage: Vanilla JS
1. Add **freezeframe** as a class name on the .gifs you want processed
```
<img class="freezeframe" src="image.gif" />
```
Expand All @@ -30,110 +49,131 @@ functions. it also supports responsive images.
<img class="freezeframe freezeframe-responsive" src="image.gif" />
```
3. ✨ freeze those frames ✨
2. ✨ freeze those frames ✨
```javascript
$(function() {
ff = new freezeframe().freeze();
})
```
<a name="advanced_usage"></a>
## Advanced Usage
freezeframe.js exposes public methods to allow for more custom integration. These
methods are described in detail in the [Function Reference](#function_reference)
You can manually trigger freezeframe functions to do whatever you want in whatever order you want.
freezeframe.js exposes public methods to allow for more custom integration. You
have the option of manually controlling when freezeframe captures images, adds
support elements, and attaches event handlers. You can also manually trigger
and release animation on one image or a group of images. These methods are
described in detail in the [Function Reference](#function_reference).
You have the option of manually going through the steps with freezeframe to setup, capture images,
process images, attach event handlers, and trigger
Capture and manually trigger / release animation
Capture .gifs and manually trigger / release animation:
```javascript
logo = new freezeframe('#logo'); // setup freezeframe instance with custom selector
logo.capture(); // capture images by selector
logo.setup(); // setup helper elements
logo.process(); // process images so they are paused
logo.setup(); // setup support elements
logo.trigger(); // trigger animation
logo.release(); // release animation
```

<a name="options_reference"></a>
## Options Reference

Options can be passed to a freezeframe instance on creation in the form of an
***object*** or a ***string***. Strings will be interpreted as the ***selector*** option.
**object** or a **string**. Strings will be interpreted as the **selector** option.

```javascript
// object as options
ff = new freezeframe({
// String as selector option
var ff = new freezeframe('.my_class');

// Object as options
var ff = new freezeframe({
'selector': '.my_class',
'animation_play_duration': 3000,
'non_touch_device_trigger_event': 'hover'
})

// string as selector option
ff = new freezeframe('.my_class')
```

```selector``` ***string***
this is something something
show default value
* **selector** *string*
Default: ```".freezeframe"```
The selector freezeframe will use to search for .gifs when the capture()
function is run (if no custom selector is passed to the capture() function).

```animation_play_duration``` ***integer***
this is something something
show default value
* **animation_play_duration** *integer*
Default: ```5000```
The number of milliseconds a .gif will animate for when triggered by click / touch event.

```non_touch_device_trigger_event``` ***string***
this is something something
show default value
* **non_touch_device_trigger_event** *string*
Default: ```"hover"``` Options: ```"hover", "click"```
The trigger event to start animation for non-touch devices.

## Function Reference <a name="function_reference"></a>
<a name="function_reference"></a>
## Function Reference

these are the freezeframe public methods and how you can use them
* **freezeframe(** options **)**
Creates a new freezeframe object instance. Can be passed options.
```javascript
// Default options
var ff = new freezeframe();

* **freezeframe(** selector **)**
creates a new freezeframe object instance with image selection.
can be passed options object or string to act as new selector.
// String as selector option
var ff = new freezeframe('.my_class');

// Object as options
var ff = new freezeframe({
'selector': '.my_class',
'animation_play_duration': 3000,
'non_touch_device_trigger_event': 'hover'
})
```

* **capture(** selector **)**
captures images by jquery reference to be operated on by freezeframe. if run
without selector argument, selector in freezeframe options will be used. can
be run multiple times with different selector to group many images,
unrelated by selector, in one freezeframe instance
Captures images to be paused by freezeframe. If run without selector
argument, selector in freezeframe options will be used. Can be run multiple
times with different selector to group many images, unrelated by selector,
in one freezeframe instance.
```javascript
ff.capture(); // use selector in freezeframe options
ff.trigger('.my_class'); // use custom selector
```

* **setup()**
creates and inserts support elements.
before:
Creates and inserts support elements. Can be filtered by selector.
```javascript
ff.setup(); // all images in freezeframe instance
ff.setup('.my_class'); // filter images by selector
```
HTML image before:

```html
```html5
<img class="freezeframe" src="my_image.gif" />
```

after:
```
...and after:
```html5
<div class="ff-container">
<canvas class="ff-canvas ff-canvas-ready" width="400" height="250"></canvas>
<img class="freezeframe ff-setup ff-image ff-image-ready" src="my_image.gif">
</div>
```

* **attach(** selector **)**
attaches hover / click / touch events based on freezeframe options. can be filtered by selector.

* **process(** selector **)**
attaches imagesloaded event listener to image and processes / pauses image
when ready.
Attaches hover / click / touch events based on freezeframe options.
```javascript
ff.attach(); // all images in freezeframe instance
ff.attach('.my_class'); // filter images by selector
```

* **trigger(** selector **)**
triggers image animation by selector. must be a part of existing image
selection in freezeframe instance.
Triggers (starts) animation. Can be filtered by selector.
```javascript
ff.trigger(); // all images in freezeframe instance
ff.trigger('.my_class'); // filter images by selector
```

* **release(** selector **)**
releases ( stops ) image animation by selector. must be part of existing image selection
in freezeframe instance.

## Development Environment
* use package.json to install npm stuff
* list gulp commands to build the project
* cleanup gulpfile
Releases (stops) animation.
```javascript
ff.release() // all images in freezeframe instance
ff.release('.my_class'); // filter images by selector
```
41 changes: 25 additions & 16 deletions build/js/freezeframe.js
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

// pass references around in a cleaner way
// try to remove jquery dependency !
// remove jquery dependency

var freezeframe = (function($) {

Expand All @@ -23,17 +23,17 @@ var freezeframe = (function($) {
}

// filter captured images by selector and warn if none found
var filter = function(_selector) {
var filter = function(_selector, _images) {
var filtered_images;

if(_selector != undefined && this.images.length > 1) {
filtered_images = this.images.filter( $(_selector) );
if(_selector != undefined && _images.length > 1) {
filtered_images = _images.filter( $(_selector) );
if (filtered_images.length == 0) {
warn("no images found for selector '" + _selector + "'")
return false;
}
} else {
filtered_images = this.images;
filtered_images = _images;
}

return filtered_images;
Expand Down Expand Up @@ -102,7 +102,7 @@ var freezeframe = (function($) {
freezeframe.prototype.capture = function(_selector) {
var selector;

// passed in string or default string
// Passed in string or default string
if(_selector !== undefined) {
selector = _selector;
} else if (this.options.selector !== undefined) {
Expand All @@ -112,22 +112,22 @@ var freezeframe = (function($) {
return false;
}

// empty jquery object to add into
// Empty jQuery object to add into
if(this.images == undefined) {
this.images = $();
}

// add new selection, jquery keeps it non redundant
// Add new selection, jQuery keeps it non redundant
this.images = this.images.add( $('img' + selector) );

// get non gifs outta there
// Get non gifs outta there
for (i = 0; i < this.images.length; i++) {
if (this.images[i].src.split('.').pop().toLowerCase().substring(0, 3) !== 'gif') {
this.images.splice(i, 1);
}
}

// if nothing was found, throw a fit
// If nothing was found, throw a fit
if(this.images.length == 0) {
console.warn('freezeframe : no gifs found for selector "' + selector + '"');
return false;
Expand All @@ -141,7 +141,7 @@ var freezeframe = (function($) {
// Setup Elements //
// //
//////////////////////////////////////////////////////////////////////////////
freezeframe.prototype.setup = function() {
freezeframe.prototype.setup = function(_selector) {
var ff = this,
setup_required = this.images.not('.ff-setup'),
container_classnames = ['ff-container'];
Expand All @@ -154,7 +154,7 @@ var freezeframe = (function($) {
return false;
}

setup_required.each(function(e) {
filter.call(ff, _selector, setup_required).each(function(e) {
var $image = $(this);

$image.addClass('ff-setup ff-image');
Expand Down Expand Up @@ -200,7 +200,7 @@ var freezeframe = (function($) {
return false;
}

filter.call(ff, _selector).each(function(e) {
filter.call(ff, _selector, ff.images).each(function(e) {

var $image = $(this);
var $canvas = $(this).siblings('canvas');
Expand Down Expand Up @@ -274,7 +274,7 @@ var freezeframe = (function($) {
var ff = this,
errors = 0;

filter.call(ff, _selector).each(function(e) {
filter.call(ff, _selector, ff.images).each(function(e) {

if($(this).hasClass('ff-image-ready')) {
$(this).attr('src', $(this)[0].src);
Expand All @@ -298,7 +298,7 @@ var freezeframe = (function($) {
var ff = this,
errors = 0;

filter.call(ff, _selector).each(function(e) {
filter.call(ff, _selector, ff.images).each(function(e) {
if($(this).hasClass('ff-image-ready')) {
$(this).siblings('canvas').removeClass('ff-canvas-active').addClass('ff-canvas-ready');
} else {
Expand All @@ -321,5 +321,14 @@ var freezeframe = (function($) {
}

return freezeframe;
})(jQuery);

})(jQuery);
// jQuery plugin
$.fn.freezeframe = function(_options) {

var ff = new freezeframe(_options);
ff.images = this;
ff.setup().attach();

return this;
};
Loading

0 comments on commit 5f2e118

Please sign in to comment.