Download Impel

Version 0.7

Read the API

It’s simple

Download Impel Modules

Transparent Database Syncing

Read the FAQ

Yes, it runs on the iPhone

Impel is a Javascript to HTML 5 Object Relational Mapping Library

It is modeled after the PHP Propel library, but deviates from that API where necessary to support HTML5's asynchronous database interface.

Using Impel

Impel is a ....

Impel makes it easy to ...

Define the model

          var Card = new Class({
                Extends    : ImpelClass,
                peer_class : "CardPeer",
                toString   : function(){
                               return this.getName() + " of " + this.getSuit();
                             }
            });

          var CardPeer = new ImpelPeer({
                 'columns'      : { 'id'    : 'card.id',    'suit' : 'card.suit', 
                                    'value' : 'card.value', 'name' : 'card.name'},
                 'table'        : 'card',
                 'base_object'  : 'Card'
            });

         var Stack = new Class({
              Extends      : ImpelClass,
              peer_class   : "StackPeer",
              toString     : function(){
                               return this.getName();
                             }
            });

          var StackPeer = new ImpelPeer({
                'columns'      : {  'id'        : 'stack.id',         
                                    'name'      : 'stack.name', 
                                    'created_at' : 'stack.created_at', 
                                    'updated_at' : 'stack.updated_at'},
                'table'        : 'stack',
                'base_object'  : 'Stack'
            });

          var CardStack = new Class({
               Extends: ImpelClass,
               peer_class: "CardStackPeer",
               toString: function(){
                 return this.getId() + ":" + this.getCardId() + "-" + this.getStackId();
               }
             });

          var CardStackPeer = new ImpelPeer({
                  'columns'      : {'id'        : 'card_stack.id', 
                                    'stack_id'  : 'card_stack.stack_id', 
                                    'card_id'   : 'card_stack.card_id'},
                  'table'        : 'card_stack',
                  'base_object'  : 'CardStack'
             });
        

Define the relationships between the classes

            CardPeer.hasManyThrough("StackPeer::id", "CardStackPeer::card_id", "CardStackPeer::stack_id");
            StackPeer.hasManyThrough("CardPeer::id", "CardStackPeer::stack_id", "CardStackPeer::card_id");
        

Use the objects in your code

Instantiate the objects as you normally would and use the automatically created get and set methods to access the attributes of the objects.
         var cards  = [];

         cards[0]   = new Card();
           cards[0].setSuit("hearts");
           cards[0].setName("9");
           cards[0].setValue(9);

         cards[1]   = new Card();
           cards[1].setSuit("hearts");
           cards[1].setName("10");
           cards[1].setValue(10);

         cards[2]   = new Card();
           cards[2].setSuit("hearts");
           cards[2].setName("Jack");
           cards[2].setValue(11);

         cards[3]   = new Card();
           cards[3].setSuit("hearts");
           cards[3].setName("Queen");
           cards[3].setValue(12);

         cards[4]   = new Card();
           cards[4].setSuit("hearts");
           cards[4].setName("King");
           cards[4].setValue(13);

         var sFlush   = new Stack();
               sFlush.setName('Straight Flush');
        

Associate objects with one another

Objects that are related to one another through one-to-many and many-to-many relationships use automatically generated add and get methods rather than set and get methods
           sFlush.addCard(cards[0]);
           sFlush.addCard(cards[1]);
           sFlush.addCard(cards[2]);
           sFlush.addCard(cards[3]);
           sFlush.addCard(cards[4]);
        

Persist objects via the HTML 5 database

If objects are associated with one another you only need to call save on one of them. Impel will automatially save any related objects. Impel is also smart enough to figure out when an UPDATE is required instead of an INSERT. The HTML 5 specification requires that the HTML database be asynchronous, so Impel is as well. When you call save on an object nothing will be returned, but a callbacks will be used to signal if the save was successful or not. You can safely call save without a callback if you like.
         sFlush.save(
           function(){ 
             notify.show("Saved "+sFlush.getName() + " with " + sFlush.getCards().length + " cards.");
           },
           function(error){ 
             notify.error("Failed to save "+sFlush.getName() + " with " + 
                                  sFlush.getCards().length + " cards." + error);
           }
         );
        

Retrieve objects from the HTML 5 database

To retrieve specific objects from the database first instantiate a Impel.Criteria object and use it to define exactly which object you want to retrieve. Then use that objects associated ImpelPeer to retrieve it.

         var c = new Impel.Criteria();
            c.add("StackPeer::name","Straight Flush");
         CardPeer.doSelectJoinAll(c, function(cards){ 
                                         cards.each(function(card){
                                             display(card);
                                         });
                                     });
        




Class Index

CritConstants

Creates a global alias for Impel.CritConstants

Defined in impel.Globals


Criteria

Creates a global alias for Impel.Criteria.

Impel

Impel is a Javascript to HTML 5 Object Relational Mapping Library

It is modeled after the PHP Propel library, but deviates from that API where necessary to support HTML5's asynchronous database interface.


Impel.CritConstants

Constants used by the Impel.Criteria and Impel.Criterion classes to construct SQL statements.

Impel.Criteria

A utility class for holding criteria information for an SQL query.

Impel.Criterion

An inner class that describes the different portions of the WHERE clause of an SQL query.

Impel.inTouch

Keep a local HTML5 SQL database in sync with one published by your server.

Impel.ResultSet

A simplified verion of the SQLResultSet class that can be easily turned into an array

ImpelClass

Any class of objects that is to be persisted via Impel must Extend the ImpelClass, contain a 'peer_class' attribute, and be within the scope of window.

ImpelPeer

A utility class for managing interactions between objects and their associated records in the database.

ResultSet

Creates a global alias for Impel.ResultSet

Defined in impel.Globals



blog comments powered by Disqus

Impel takes the pain out of working with HTML5 asynchronous databases.

Statement callbacks? Transaction callbacks? One-to-many and many-to-many relationships? How the heck do I deal with all without my head exploding?

Use Impel; create an object then call object.save(); Now get a cup of coffee.

What’s an ORM

Object Relational Mapping is a programming technique that turns your database, in effect, into a virtual object database.

With an ORM you no longer need to worry about how to save a single object across multiple tables, you just call, "save" on the object.

 
Contact Us | © 2009 Caleb Crane | License