ModelCore

A Javscript ORM/Active Record to work with angularjs and others. Easy to use and to understand.
4 people use it
Author: F1394acb940b2e4030a4597964fd2df9?d=https%3a%2f%2fidenticons.github.com%2f25d116dc9e29065600cd84782e385de2 klederson

ModelCore

What is?

ModelCore is a very light and simple ActiveRecord and Data Mapper over REST ( with some nice features of course )

The reason i built it was to easly handle lots of data and "Models" from REST api that i already work nowdays. The lack of good tools in this area made me do this in a 24h programming day.

Introduction

This is primary build to be used with AngularJS but will be soon ported to a framework free solution.

This is the very first version of this and was coded (at least until the first version) in 24h ( between understand some ECMACScript stuff, research and angular learn curve + this documentation ).

So be brave and use at your own risk!!!!! =)

Usage

First of all ( and of course ) you need to include it's javascript in your html

The samples here are for AngularJS please keep that in mind for more informations please check their site

Than you need to setup your app to receive ModelCore

And Then we setup our Controller to use our model ( in this case Users )

And … that's all to be honest… =)

Now you have a Fully Functional model in your app… but HEY! Show me the magic!!!

Ok, you can see the sample's source code

ModelCore.instance()

This method help you to create a new instance… for now it's just used at angular factory but soon will be updated to work with pure javascript and than… we provide more info about that. For now… just trust me on this.

model.$settings

When you create the model using ModelCore.instance() you need to provide some basic settings and this are:

urls

Urls define witch url should be used in each REST Method case, example, if you want POST to have one url and GET to have another you just do this:

urls.base is a very important trick because if your REST server follows the correct specifications you only need one url to rule them all and base does that

headers

This will setup your rest call headers

dataField

This is a very special field that will define the container of your response data item(s), for example if your REST Server respond a JSON with an array of items in the field items then you should configure this like many : "items" and when you get a unique item it responds as content then you should setup like one : "content".

I'll give you a example to better explain the idea.

JSON Response from SERVER

One

Many

dataField configuration

by the way this example is the default settings so if is like this you dont need to setup anything

And is basicaly that.

Common Methods & Attributes

model.$type

Define the type of the ModelCore.instance() object to return.

model.$pkField

Define witch will be the pkField to some automatic operations refer to

model.$find()

Perform a call to the server using "GET"

This method return a Promisse so you can handle the calls:

You can also setup a query to complete your request such as filters or anything.

model.$get(id)

This will retreive a given id User. Of course your server must reply following some REST basic patterns such as:

GET /api/users/1 HTTP/1.1

Other important thing: this already performs model.$fetch() so is not needed to call twice

And you can onDemand change the "get" field just providing a second parameter with the model field name to use:

This case bellow your url MUST have the :otherId parameter otherwise will make no sense once it will not be applied anyway.

model.$save()

This will perform a POST (yes, for now we'll not add PUT as default save once we need to save and update automaticaly just like any ORM but in the future this will be configurable )

This operation uses model.$toObject() to understand the changes and once everything is saved it will update your model so the new data will replace the original even in the model so commands like model.$diff() or model.$isChanged() will reply empty and/or false.

model.$delete()

Just like get you can add an id and also change onDemand the idField

model.$fetch()

This is a important stuff because anytime you need to instance a object you need to $fetch() that.

Example

model.next()

This is the man how makes model.$fetch() works

Example

model.prev()

Same as model.$next() but to move the cursor back.

Auxiliar Methods

model.$isChanged()

This returns a Boolean if is or not changed based on the original data ( the REQUEST momentum )

This is cool and can be combined to alert the user about unsaved changes.

And also you can check for only one field

Here is a pratical sample in the html using AngularJS

That sample put in the input the class "unsaved" if the field "fname" is changed ( and will disappear once model.$save() is invoked and of course returns success )

model.$diff()

Display the difference between the original data and the staged data and returns a Object with all ( and only ) changed fields

model.$toObject()

Return a raw object with all STAGED ( not the original, not the saved, the STAGED/CURRENT ) data.

Will return something like as a Javascript Object

model.$original()

Return a raw object with all ORIGINAL data of the model even if there are changes.

Will return something like as a Javascript Object

model.$url()

This return the url to a given method and parameters (optional)

Really Deep Stuff

model.$dataset

This is an array from the MASTER model that contains ALL the child models and of course each item is also a model of the same instance of that master.

model.$mapping

For now this is automatic but in a VERY near future you will be able to setup and map your model and shape it as your will. More details later.

Thanks to

Well, the first version (until the first version of this document) was written as i said in 24 hours and was only possible because some folks:

BreezeJS

Thankyou for be so awesome that made me really want to use your features but also be so complex/burocratic, heavy and so "microsoftized" that i give up before 4h trying to understand and customize a simple model.

That make me realize that i needed to search more and more or even make my own solution

BreezeJS

angular-activerecord (github project)

This is a very nice project and very simple, works well but missed lots of stuff… at the beginning i wanted to do a fork of this and than just improve but ModelCore in my head would be so different that maybe would have dismissed the goal of this very nice project.

Also this gave me the guidlines to start building and also to the ModelCore.instance() code.

Checkout the project at Github

Roadmap

  • Non-relational workflow ( it's almost but need more polish )
  • Pure Javascript (not dependend on AngularJS but fully compatible)
  • qUnit Tests =) (of course)
  • Offline data
  • Query like filters such as .where() .and() .or() ...
  • OAuth

Of course i accept suggestions

comments powered by Disqus
This page was last updated over 3 years ago.