nito v2.0.0

Nito

A jQuery library for building user interfaces.

By establishing a declarative approach with pure updates, Nito's helpers and conventions make jQuery applications modular and maintainable.

Quick Tour

Setting up Nito is as simple as including jQuery:

<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
<script src="https://cdn.rawgit.com/morris/nito/v2.0.0/nito.min.js"></script>

With Nito, HTML is just HTML—no sugar required. Use semantic classes and templates as needed. For example, a todo app's base HTML could look like this:

<div class="todo">
  <h1>Todo</h1>
  <ul class="items">
    <li class="item"> <!-- This <li> is a template used by .nest() -->
      <strong class="title">Example item</strong>
    </li>
  </ul>
</div>

We can now add behavior by defining mount functions. These functions can do anything to setup behavior but should follow a few conventions:

• Minimize state and keep it outside the DOM
• Only do DOM manipulation on an update event
• Make the update handler pure, i.e. independent of prior state and complete
• Change state on application events and trigger updates with .update()

function Todo( $el ) {

  // some state, minimized and outside the DOM
  var items = [
    { title: 'Get Nito', completed: false },
    { title: 'Create something', completed: false }
  ];

  $el.on( 'update', update );
  $el.on( 'todo-toggle', toggle );

  function update() {
    // The "update" event should be the only place with DOM manipulation
    // Repeat item HTML for each item, reusing existing DOM
    $el.find( '.items' ).nest( items );
  }

  function toggle( e, item ) {
    // Modify state and trigger pure update
    item.completed = !item.completed;
    $el.update();
  }

}

function TodoItem( $el ) {

  $el.on( 'update', update );
  $el.on( 'click', toggle );

  function update() {
    // Set title and toggle "completed" class
    // DOM is only manipulated if item has changed since last update
    var item = $el.data( 'item' );
    $el.find( '.title' ).ftext( item.title );
    $el.classes( { completed: item.completed } );
  }

  function toggle() {
    $el.trigger( 'todo-toggle', $el.data( 'item' ) );
  }

}

Note the nest helper which repeats the <li> template for each given item. The classes and ftext helpers apply changes softly, i.e. only if the existing DOM differs.

Also note how the definitions are entirely decoupled from the current document, and don't do anything by themselves. To take effect we have to mount them on elements in the document:

$( 'body' ).mount( '.todo', Todo );
$( 'body' ).mount( '.todo .item', TodoItem );

Mounting is declarative: The above ensures that any elements matching .todo and .todo .item are mounted with Todo and TodoItem exactly once, regardless of how and when they are added to the document.

This is key to make jQuery modules viable. Functionality can be entirely wrapped in mount functions—mounting and updating happens automatically under the hood.

Examples

Todo

A simple client-side todo app with TodoMVC-like features.

Core

At its core, Nito allows to declare the behavior of elements now and in the future. Additionally, using update events for pure UI updates and any DOM manipulation simplifies reasoning about the interface state at any point in time.

$scope.mount( selector, fn )

• Ensure that any element under $scope matching selector is mounted with fn exactly once, now and in the future
• fn is called on each matching element, with $( el ) as its only argument
• This also applies to elements appended in the future
• Mounting may take place immediately or in the next frame
• Return $scope

$els.update()

• Enqueue an update event on each element in $els
• Elements receive at most one update event per frame
• Return $els

$els.dispatch( type, data )

• Trigger an event in the next frame
• Useful in situations where mounting may not be safely finished
• Return $els

Nesting

Efficiently nest elements in any container using nest or nestOne. Use these functions on update, not at mount-time.

$els.nest( items, base )

• Nest a base element for each item
• Populate $el.data( 'item' ) with each respective item
• If base is omitted, cache the first child in the container as base
• $els should only have children generated by nest
• Return $els

$( '<ul></ul>' ).nest( [
  { title: 'Write code', done: true },
  { title: 'Write readme', done: false }
], '<li class="item"></li>' );

$els.nestOne( item, base )

• Same as nest, but for one item
• Pass falsy item to not nest anything
• Return $els

Manipulation

The following methods are helpful and/or speed optimized for usage on update events.

$els.classes( map )

• Set classes on $els softly
• Classes not present in map are not touched
• Function values are computed using each element as this
• Return $els

$( '.form-group' ).classes( {
  'has-success': true,
  'has-error': false
} );

$els.fhtml( html )

• Set inner HTML in $els softly
• Faster than $els.html
• Return $els

$els.ftext( text )

• Set text content in $els softly
• Faster than $els.text
• Return $els

Forms

$els.serializeData()

• Serialize named form controls in $els into an object
• Supports all controls and nested names like object[key], array[index], multiple[]
• Checkboxes are serialized with their value, or 'on' if no value is present
• Return an object containing the values

$els.fill( data )

• Fill named form controls in $els with given data (JSON-like)
• Supports all controls and nested data
• Return $els

$( '[name]' ).fill( {
  title: 'Nito',
  description: '...'
} );

$els.fillDef( data )

• Same as fill but for default values
• Return $els

$els.fval( value )

• Set form control value in $els softly
• User input will be overwritten
• Form defaults are not modified
• Return $els

$els.fdef( value )

• Set default form control value in $els softly
• Modifies DOM attributes like value and selected, not the properties
• Inputs modified by the user will still reflect the user input
• Return $els

$els.reset()

• Reset each form or individual form control in $els (without children)
• Return $els