Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tmeasday/edifice-widgets

Widgets + Traits done the edifice way
https://github.com/tmeasday/edifice-widgets

Last synced: 30 days ago
JSON representation

Widgets + Traits done the edifice way

Awesome Lists containing this project

README 

        
Edifice Widgets + Traits

========================



Edifice-widgets is a companion gem to [edifice](/tmeasday/edifice) which allows simple unobtrusive javascript behaviours, allowing you to make pages dynamic, whilst avoiding unnecessary boilerplate.



Note that it does not depend on edifice although it complements it well. Also note that it doesn't depend on rails---the javascript files can be used in isolation if you want. It does depend on jQuery.



Installation

------------



To install, simply add to your Gemfile:



```ruby

gem 'edifice-widgets'

```



To include the javascript, add to your application.js:



```js

/*

 *= require edifice-widgets

 */

```



Traits -- unobtrusive JS behaviours

-----------------------------------



Traits are best explained through example. Suppose you have a input field that you'd like to automatically select all when clicked on (for example github's repository URL field). If we define:



```javascript

$.edifice_traits.always_select_all = function() {

  return this.bind('click select focus focusin', function() {

    this.select();

  });

}

```



Then we can use such a behaviour with:



```html



```



edifice-widgets will ensure that the code is attached to the `input` and everything behaves as you'd expect.



You can define more than one trait for an element (separate them with spaces, as you would CSS classes). For that reason, as a rule, it is best if traits remain very simple, and don't alter the internal HTML structure of the element. Otherwise bugs are bound to happen when you combine them.



Widgets -- unobtrusive specialised elements

-------------------------------------------



If you need something more complex that will significantly alter the HTML, or which requires arguments, it is best to use a widget. For example, suppose you want to create a styled separatelect. Suppose we want to use it all over our website.



Then we want to write the minimum of HTML above what we would to use a vanilla select, and let the JS framework take care of hooking things together. edifice-widgets lets us write simply:



```html



  Australia

  USA



```



To enable this, we can write a `select` widget, which goes something like:



```js

// note this is basically untested psuedo-code, don't use on production please

$.edifice_widgets.select = function() {

  return this.each(function(){

    var $select = $(this).wrap('
'),

      $widget = $select.parent(), $ul = $('
    ').insertBefore($select);

        

        // insert the selected text

        $widget.prepend('' + $select.val() + '');

        

        $select.find('option').each(function() {

          // add a 
  •  to $ul

          var $li = $('
    • 

  • ' + $(this).text() + '
    • ').data('option', $(this));

          $ul.append();

        });

        

        // bind click events on lis to select the li's value and close the select widget

        $widget.delegate('li', 'click', function() {

          $select.val($(this).data('option').val());

          $widget.find('.selected').text($(this).data('option').text());

          $widget.removeClass('open');

          

        // bind click events on the selected value to toggle the open state

        }).delegate('.selected', 'click', function() {

          $widget.toggleClass('open');

        })

      });

    }

    ```
    


    Of course you would also need to define some appropriate styles to make the select look right.
    


    Widgets can take arguments, which are set like so:
    


    ```html
    


    ```
    


    To access the option easily, use the `.read_options` method:
    


    ```js

    var settings = $(this).read_options({

      'open_class': 'open' // <-- this is the default value for settings.open_class

    })

    ```
    


    Use `$edifice_widgets.REQUIRED` to indicate that a setting is required:
    


    ```js

    var settings = $(this).read_options({

      'autosubmit_url': $.edifice_widgets.REQUIRED

    });

    ```
    


    License

    -------
    


    [Edifice](http://edifice-rails.com) is crafted by [Percolate Studio](http://percolatestudio.com) and released under the [MIT license](www.opensource.org/licenses/MIT)