evil-blocks-rails 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5be4b6d7fdc3df28a8ad6bc1cd73f4024f6396f6
-  data.tar.gz: 3dfc6a88f8d0da7aa01cd5c93c1ec1363f14e6fa
+  metadata.gz: e3218d628224ba9091d719cc07bc71d08197753f
+  data.tar.gz: b7bf21a51deba749a22b9a11e6f13d1d705d682e
 SHA512:
-  metadata.gz: 771a05c59ed27eaa63d918fcd0b68971c86b7e7afe072d1e07d20406a7b549b5a91438856c1ed257f21fadb3bfceb53f4c6438be9254afb3efb908fc29952c90
-  data.tar.gz: 633c478e433f53c3e431bd0d12f076088b88e177660052ce34d4b08f3030e85e48396dc0566c5b4228bf25bbc39e1847c07d16051559726a73de702ab1db8444
+  metadata.gz: 09eb8985c804ca37642f418375554dd9f0cde07ba7d55d9ef2586becbe6de5af7a25948cd61d1bef365f5d7c3e6553419545774d1e924470543c4cb496b905f9
+  data.tar.gz: 13cc2cd3cce7438aee98f2e66078f7448a9cbed49318e37253b7fed9b3087753cbaa80b8a44351e420a0777abc648a6c89c628af52883e34ad73ff92a01eb1c7

data/ChangeLog.md

@@ -1,3 +1,8 @@
+## 0.6 (Ranger Able, 27th January 1951)
+* Add filters, which process block object before init was called.
+* Most build-in features was moved to filter to be disableable.
+* Listener `load on window` will call immediately, if page was already loaded.
+
 ## 0.5.1
 * Fix block vitalizing, when multiple blocks was binded to same DOM node.
 

data/README.md

@@ -15,7 +15,7 @@ Evil Block is a tiny JS framework for web pages. It is based on 4 ideas:
 
 See also [Evil Front], a pack of helpers for Ruby on Rails and Evil Blocks.
 
-Sponsored by [Evil Martians]. Role aliases was taken from [Role.js].
+Sponsored by [Evil Martians]. Role aliases were taken from [Role.js].
 
 [Role.js]:       https://github.com/kossnocorp/role
 [big price]:     http://staal.io/blog/2014/02/05/2-way-data-binding-under-the-microscope/
@@ -85,7 +85,8 @@ and `data-role` (to define elements inside block).
 ```
 
 Evil Blocks extends Slim and jQuery, so you can use shortcuts for this
-attributes: `@@block` and `@role`:
+attributes: `@@block` and `@role`. For Haml you can use [Role Block Haml] gem
+to use same shortcuts.
 
 ```haml
 @@todo
@@ -106,6 +107,8 @@ and be sure in scripts:
 Of course, Evil Block doesn’t force you to use only this selectors.
 You can any attributes, that you like.
 
+[Role Block Haml]: https://github.com/vladson/role_block_haml
+
 ## Blocks
 
 You should split your interface to independent controls and mark them
@@ -233,6 +236,8 @@ evil.blocks '@@docs',
     @openPage(location.hash)
 ```
 
+Listener `load on window` will execute immediately, if window is already loaded.
+
 [evil-front/links]: https://github.com/ai/evil-front/blob/master/evil-front/lib/assets/javascripts/evil-front/links.js
 
 ## Blocks Communications
@@ -241,7 +246,7 @@ Blocks should communicates by custom jQuery events. You can bind event listener
 to block node by `"on events"` method:
 
 ```coffee
-evil.block '@@slideshow', ->
+evil.block '@@slideshow',
   nextSlide: -> …
 
   'on play': ->
@@ -250,7 +255,7 @@ evil.block '@@slideshow', ->
   'on stop': ->
     clearInterval(@timer)
 
-evil.block '@@video', ->
+evil.block '@@video',
 
   'click on @fullscreenButton': ->
     $('@@slideshow').trigger('stop')
@@ -259,12 +264,12 @@ evil.block '@@video', ->
 If you want to use broadcast messages, you can use custom events on body:
 
 ```coffee
-evil.block '@@callUs', ->
+evil.block '@@callUs',
 
   'change-city on body': (e, city) ->
     @phoneNumber.text(city.phone)
 
-evil.block '@@cityChanger', ->
+evil.block '@@cityChanger',
   getCurrentCity: -> …
 
   'change on @citySelect': ->
@@ -318,6 +323,74 @@ evil.block '@@comment',
 
 [big price]: http://staal.io/blog/2014/02/05/2-way-data-binding-under-the-microscope/
 
+## Debug
+
+Evil Blocks contains debug extension, which log every events inside blocks.
+To enable it, just load `evil-blocks.debug.js`. For example, in Rails:
+
+```haml
+- if Rails.env.development?
+  = javascript_include_tag 'evil-blocks.debug'
+```
+
+## Extensions
+
+Evil Blocks has tiny core. It only finds blocks by selectors, sets `@block`
+property and calls `init` method. Any others features (like event bindings
+or `@$()` method) was created by filters and can be disabled or replaced.
+
+Before calling `init`, Evil Blocks processes object throw the filters list in
+`evil.block.filters`. Filter accepts object as first argument and unique
+class ID as second. It can find some properties in object, work with block
+DOM nodes and add/remove some object properties. If filter will return `false`,
+Evil Blocks will stop block vitalizing and will not call `init` method.
+
+Default filters:
+
+1. **Don’t vitalize same DOM node twice.** It return `false` if block
+   was already initialized with this class ID.
+2. **Add `@$()` method.** It add shortcut find method to object.
+3. **Add shortcuts to `@element`.** It add properties for all children with
+   `data-role` attribute.
+4. **Bind block events.** Find, bind listeners and remove all methods with
+   name like `on event`.
+5. **Smarter window load listener.** Run `load on window` listener immediately,
+   if window is already loaded.
+6. **Bind window and body events.** Find, bind listeners and remove all methods
+   with name like `event on window` or `event on body`.
+7. **Bind elements events.** Find, bind listeners and remove all methods
+   with name like `event on child`.
+
+You can add you own filter to `evil.block.filters`. Most filters should be added
+after first filter to not been called on already initialized blocks.
+
+Let’s write filter, which will initialize blocks only when they become to be
+visible.
+
+```coffee
+filter = (obj) ->
+  if not obj.block.is(':visible')
+    # Check for visibility every 100 ms
+    # and recall vitalizing if block become visible
+    checking = ->
+      evil.block.vitalize(obj.block) if obj.block.is(':visible')
+    setTimeout(checking, 100);
+
+    # Disable block initializing
+    return false
+
+# Add filter to list
+evil.block.filters.splice(0, 0, filter)
+```
+
+With filters you can change Evil Blocks logic, add some new shortcuts or
+features like mixins.
+
+Also you can remove any default filters from `evil.block.filters`. For example,
+you can create properties for `data-role` children only from some white list.
+
+But Filters API is still unstable and you should be careful on major updates.
+
 ## Modules
 
 If your blocks has same behavior, you can create module-block and set
@@ -329,12 +402,12 @@ multiple blocks on same tag:
 ```
 
 ```coffee
-evil.block '@@closable', ->
+evil.block '@@closable',
 
   'click on @closeLink': ->
     @block.trigger('close')
 
-evil.block '@@popup', ->
+evil.block '@@popup',
 
   'on close': ->
     @clock.removeClass('is-open')
@@ -361,16 +434,6 @@ evil.block '@@docs',
     @openInFancybox(@example)
 ```
 
-## Debug
-
-Evil Blocks contains debug extension, which log every events inside blocks.
-To enable it, just load `evil-block.debug.js`. For example, in Rails:
-
-```haml
-- if Rails.env.development?
-  = javascript_include_tag 'evil-block.debug'
-```
-
 ## Install
 
 ### Ruby on Rails
@@ -387,6 +450,9 @@ Load `evil-blocks.js` in your script:
 //= require evil-blocks
 ```
 
+If you use Rails 3 on Heroku, you may need
+[some hack](https://github.com/ai/evil-blocks/issues/17).
+
 ### Ruby
 
 If you use Sinatra or other non-Rails framework you can add Evil Blocks path

data/lib/evil-blocks.debug.js

@@ -13,17 +13,29 @@
         return;
     }
 
-    window.evil.block.eventFilter = function (callback, block, event) {
-        return function () {
-            var params = Array.prototype.slice.call(arguments, 1);
-            var messages = ['Event "' + event + '" on', block.block[0]];
-            if ( params.length > 0 ) {
-                messages.push('with params');
-                messages = messages.concat(params);
+    var logger = function (obj) {
+        for ( var name in obj ) {
+            if ( name.indexOf('on ') == -1 ) continue;
+
+            var parts = name.split('on ');
+            var event = parts[0] ? parts[0] : parts[1];
+
+            var callback = obj[name];
+            obj[name] = function (e) {
+                var source   = e.el ? e.el[0] : this.block[0];
+                var messages = ['Event "' + event + '" on', source];
+
+                var params = Array.prototype.slice.call(arguments, 1);
+                if ( params.length > 0 ) {
+                    messages.push('with params');
+                    messages = messages.concat(params);
+                }
+
+                log.apply(this, messages);
+                callback.apply(this, arguments);
             }
-            log.apply(this, messages);
+        }
+    };
 
-            callback.apply(this, arguments);
-        };
-    }
+    evil.block.filters.splice(2, 0, logger);
 })();

data/lib/evil-blocks.js

@@ -1,6 +1,23 @@
-;(function ($) {
+;(function ($, window) {
     "use strict";
 
+    // Helpers
+    var $window = $(window);
+
+    // Clone object
+    var clone = function (origin) {
+        var cloned = { };
+        for ( var name in origin ) {
+            cloned[name] = origin[name];
+        }
+        return cloned;
+    };
+
+    // Is string ends with substring.
+    var endsWith = function (string, substring) {
+        return string.substr(-substring.length) === substring;
+    };
+
     /*
      * Add `@data-role` alias to jQuery.
      *
@@ -9,9 +26,7 @@
 
     var rewriteSelector = function (context, name, pos) {
         var original = context[name];
-        if ( !original ) {
-            return;
-        }
+        if ( !original ) return;
 
         context[name] = function () {
             arguments[pos] = arguments[pos].replace(
@@ -35,138 +50,47 @@
     if ( !window.evil ) {
         window.evil = { };
     }
+    var evil = window.evil;
 
-    /**
-     * If onready event is already happend.
-     */
-    var ready = false;
-
-    var callbacks = {
-        /**
-         * Create callback wrapper for block listener.
-         */
-        block: function (self, func) {
-            return function (e) {
-                if ( e.currentTarget == e.target ) {
-                    func.apply(self, arguments);
-                }
-            }
-        },
-
-        /**
-         * Create callback wrapper for body/document listener.
-         */
-        global: function (self, func) {
-            return function () {
-                func.apply(self, arguments);
-            }
-        },
-
-        /**
-         * Create callback wrapper for element listener.
-         */
-        elem: function (self, func) {
-            return function () {
-                var event = arguments[0];
-                event.el = $(this);
-                func.apply(self, arguments);
-            }
-        }
-    };
-
-    /**
-     * Execute `callback` on every finded `selector` inside `base`.
-     */
-    var vitalize = function (base, id, selector, klass) {
+    // Find selector inside base DOM node and cretae class for it.
+    var find = function (base, id, selector, klass) {
         var blocks = $().add( base.filter(selector) ).
                          add( base.find(selector) );
 
-        if ( blocks.length == 0 ) {
-            return;
-        }
+        if ( blocks.length == 0 ) return;
 
-        var inits = [];
-
-        for ( var i = 0; i < blocks.length; i++ ) {
-            var block = $(blocks[i]);
+        var objects = [];
 
-            var vitalized = block.data('evil-vitalized');
-            if ( !vitalized ) {
-                vitalized = [];
-            } else if ( vitalized.indexOf(id) != -1 ) {
-                continue;
-            }
-            vitalized.push(id);
-            block.data('evil-vitalized', vitalized);
-
-            var obj = { };
-
-            obj.$ = (function (block) {
-                return function (subselector) {
-                    return $(subselector, block);
-                };
-            })(block);
-
-            var actives = { };
-            block.find('[data-role]').each(function (_, el) {
-                var roles = el.attributes['data-role'].value.split(' ');
-                for ( var i = 0; i < roles.length; i++ ) {
-                    var role = roles[i];
-                    if ( !obj[role] ) {
-                        obj[role] = $();
-                    }
-                    obj[role].push(el);
-                }
-            });
+        blocks.each(function (_, node) {
+            var block = $(node);
 
+            var obj = clone(klass);
             obj.block = block;
 
-            var event = function (type, name, prop) {
-                var result = callbacks[type](obj, prop);
-                if ( window.evil.block.eventFilter ) {
-                    result = window.evil.block.eventFilter(result, obj, name);
-                }
-                return result;
-            };
-
-            for ( var name in klass ) {
-                var prop = klass[name];
-
-                if ( name.indexOf('on ') == -1 ) {
-                    obj[name] = prop;
-                    continue;
-                }
-
-                (function (name, prop) {
-                    var parts = name.split(' on ');
-
-                    if ( parts[1] == 'body' ) {
-                        $('body').on(parts[0], event('global', name, prop));
-
-                    } else if ( parts[1] == 'window' ) {
-                        $(window).on(parts[0], event('global', name, prop));
-
-                    } else if ( parts[1] ) {
-                        block.on(parts[0], parts[1], event('elem', name, prop));
-
-                    } else {
-                        block.on(parts[0], event('block', name, prop));
-                    }
-                })(name, prop);
+            for ( var i = 0; i < evil.block.filters.length; i++ ) {
+                var stop = evil.block.filters[i](obj, id);
+                if ( stop === false ) return;
             }
 
-            inits.push(obj);
-        }
+            objects.push(obj)
+        });
 
-        if ( klass.init ) {
-            return function () {
-                for ( var i = 0; i < inits.length; i++ ) {
-                    klass.init.apply(inits[i]);
-                }
-            };
-        }
+        return function () {
+            objects.forEach(function (obj) {
+                if (obj.init) obj.init();
+            })
+        };
     };
 
+    // If onready event was already happend.
+    var ready = false;
+
+    // If onload event was already happend.
+    var loaded = false;
+    $window.load(function (event) {
+        loaded = event;
+    });
+
     // Latest block ID
     var lastBlock = 0;
 
@@ -205,29 +129,22 @@
      *   evil.block '.block', ->
      *     # init method
      */
-    window.evil.block = function (selector, vitalizer) {
+    evil.block = function (selector, klass) {
         lastBlock += 1;
         var id = lastBlock;
 
-        if ( typeof(vitalizer) == 'function' ) {
-            vitalizer = { init: vitalizer };
+        if ( typeof(klass) == 'function' ) {
+            klass = { init: klass };
         }
 
-        window.evil.block.vitalizers.push([id, selector, vitalizer]);
+        evil.block.defined.push([id, selector, klass]);
 
         if ( ready ) {
-            var init = vitalize($(document), id, selector, vitalizer);
-            if ( init ) {
-                init();
-            }
+            var init = find($(document), id, selector, klass);
+            if ( init ) init();
         }
     };
 
-    /**
-     * Evil blocks list.
-     */
-    window.evil.block.vitalizers = [];
-
     /**
      * Vitalize all current blocks inside base. You must call it on every
      * new content from AJAX.
@@ -236,7 +153,7 @@
      *     $.get '/comments', (comments) =>
      *       evil.block.vitalize $(comments).applyTo(@comments)
      */
-    window.evil.block.vitalize = function (base) {
+    evil.block.vitalize = function (base) {
         if ( base ) {
             base = $(base);
         } else {
@@ -244,26 +161,165 @@
         }
 
         var inits = [];
-        for ( var i = 0; i < window.evil.block.vitalizers.length; i++ ) {
-            var block = window.evil.block.vitalizers[i];
-            inits.push( vitalize(base, block[0], block[1], block[2]) );
-        }
+        evil.block.defined.forEach(function (define) {
+            inits.push( find(base, define[0], define[1], define[2]) );
+        });
 
         for ( var i = 0; i < inits.length; i++ ) {
-            if ( inits[i] ) {
-                inits[i]();
-            }
+            if ( inits[i] ) inits[i]();
         }
     };
 
+    /**
+     * Evil blocks list.
+     */
+    evil.block.defined = [];
+
+    /**
+     * Filters to process block object and add some extra functions
+     * to Evil Blocks. For example, allow to write listeners.
+     *
+     * Filter will receive block object and unique class ID.
+     * If filter return `false`, block will not be created.
+     */
+    evil.block.filters = [];
+
+    var filters = evil.block.filters;
+
+    /**
+     * Don’t vitalize already vitalized block.
+     *
+     * For better perfomance, it should be last filter.
+     */
+    filters.push(function (obj, id) {
+        var ids = obj.block.data('evil-blocks');
+        if ( !ids ) {
+            ids = [];
+        } else if ( ids.indexOf(id) != -1 ) {
+            return false;
+        }
+        ids.push(id);
+        obj.block.data('evil-blocks', ids);
+    });
+
+    /**
+     * Create `this.$()` as alias for `this.block.find()`
+     */
+    filters.push(function (obj) {
+        obj.$ = function (subselector) {
+            return obj.block.find(subselector);
+        };
+    });
+
+    /**
+     * Create properties for each element with `data-role`.
+     */
+    filters.push(function (obj) {
+        obj.block.find('[data-role]').each(function (_, el) {
+            var roles = el.attributes['data-role'].value.split(' ');
+            for ( var i = 0; i < roles.length; i++ ) {
+                var role = roles[i];
+                if ( !obj[role] ) obj[role] = $();
+                if ( obj[role].jquery ) obj[role].push(el);
+            }
+        });
+    });
+
+    /**
+     * Syntax sugar to listen block events.
+     */
+    filters.push(function (obj) {
+        for ( var name in obj ) {
+            if ( name.substr(0, 3) != 'on ' ) continue;
+
+            var events   = name.substr(3);
+            var callback = obj[name];
+            delete obj[name];
+
+            (function (events, callback) {
+                obj.block.on(events, function (e) {
+                    if ( e.currentTarget == e.target ) {
+                        callback.apply(obj, arguments);
+                    }
+                });
+            })(events, callback);
+        }
+    });
+
+    /**
+     * Smart `load on window` listener, which fire immediately
+     * if page was already loaded.
+     */
+    filters.push(function (obj) {
+        var name     = 'load on window';
+        var callback = obj[name];
+
+        if ( !callback ) return;
+        delete obj[name];
+
+        if ( loaded ) {
+            setTimeout(function () {
+                callback.call(obj, loaded);
+            }, 1);
+        } else {
+            $window.load(function (event) {
+                callback.call(obj, event);
+            });
+        }
+    });
+
+    /**
+     * Syntax sugar to listen window and body events.
+     */
+    filters.push(function (obj) {
+        for ( var name in obj ) {
+            var elem = false;
+            if ( endsWith(name, 'on body') ) {
+                elem = $('body');
+            } else if ( endsWith(name, 'on window') ) {
+                elem = $window;
+            }
+
+            if ( !elem ) continue;
+
+            var event    = name.split(' on ')[0];
+            var callback = obj[name];
+            delete obj[name];
+
+            (function (elem, event, callback) {
+                elem.on(event, function () {
+                    callback.apply(obj, arguments);
+                });
+            })(elem, event, callback);
+        }
+    });
+
+    /**
+     * Syntax sugar to listen element events.
+     */
+    filters.push(function (obj) {
+        for ( var name in obj ) {
+            var parts = name.split(' on ');
+            if ( !parts[1] ) continue;
+
+            var callback = obj[name];
+            delete obj[name];
+
+            (function (parts, callback) {
+                obj.block.on(parts[0], parts[1], function (e) {
+                    e.el = $(this);
+                    callback.apply(obj, arguments);
+                });
+            })(parts, callback);
+        }
+    });
+
     /*
      * Run all blocks on load.
      */
     $(document).ready(function () {
-        setTimeout(function () {
-            ready = true;
-            evil.block.vitalize();
-        }, 1);
+        ready = true;
+        evil.block.vitalize();
     });
 
-})(jQuery);
+})(jQuery, window);

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evil-blocks-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Andrey Sitnik
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-05 00:00:00.000000000 Z
+date: 2014-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sprockets