elpong

Elpong for Javascript

If you don't understand the basics of Elpong, please read the first lines of the spec.

Although this is a draft, everything is tested and it should work in most modern browsers.

Getting started

npm install elpong

Using ES6 modules, Typescript or bundlers like Webpack is recommended:

import elpong, { Scheme, Element, Collection } from 'elpong';

const elpong = require('elpong').default;

<script src="/scripts/elpong/dist/elpong.js"></script>
<script>
  elpong = elpong.default;
</script>

// Choose one of these:
elpong.setAjax(window.fetch, 'fetch') // built-in in modern browsers
elpong.setAjax($http, 'angularjs') // if you use AngularJS
elpong.setAjax($.ajax, 'jquery') // if you use jQuery
elpong.setAjax(http, 'angular') // if you use Angular, http: instance of Http or HttpClient

elpong.enableAutoload(); // when using preloading
// or
var scheme = elpong.add(scheme_config); // if you have the scheme in javascript

scheme.setApiUrl('/api');
var pigs = scheme.select('pigs'); // select the pigs collection

var promise = pigs.actions.getAll(); // sends a GET to /api/pigs
promise.then(function(response) {
  for (pig in pigs.array()) {
    alert('Received pig ' + pig.fields.name);
  }
})

Alternatively, you can use the AjaxAdapterType enum in Typescript:

elpong.setAjax(window.fetch, AjaxAdapterType.Fetch);

Schemes

You can create a scheme in two ways:

elpong.add(scheme_config)

or by preloading it, see Preloading

A scheme can be retrieved with elpong.get(scheme_name)

Collections

When a scheme is created, it immediately creates the defined collections.

They can be retrieved with scheme.select(collection_name)

You can get an array of the elements in a collection with collection.array()

Finding a specific object can be done with: collection.find(id) (if id is the selector), or collection.findBy({name: name}). If you want to search for multiple elements with that name, use collection.findBy({name: name}, {multiple: true}).

To load data into the collection, you can use collection.actions.getAll(), or collection.actions.getOne(id). To preload it, see Preloading

If you are using Rails, check out this library.

To make a new element, use collection.build({name: 'Bob'}).
This element will be stored in the new_elements array, and when it is POSTed, and thus gets a selector value (id gets a value), it will end up in the elements object.

You shouldn't access the new_elements and elements attributes directly, just use array() or array({without_new: true}) for that.

Collection actions

You can execute collection actions with the actions key.
The built in ones are getOne and getAll.

Elements

Fields

Fields can be accessed through the fields key.

Example:

pig.fields.name;

Actions

You can execute actions on the actions key. There are four built in ones:

get: Sends a GET and updates the fields, overwriting the original fields.

post: Sends a POST to the collection url. Should only be called if the element is new, because it assigns a selector to the element. (The server should save it in some database, and thus it gets an id)

put: Sends a PUT with the new data, and expects the same data sent back, or otherwise small updates.

delete: Sends a DELETE, which should remove the element from the server, but does not delete the element from the collection on the client side. Use remove to do that.

All actions accept params to be passed in the url.

Example:

var pig = pigs.build();
pig.actions.post(); // saves the pig, pig gets an id
pig.actions.get();
pig.actions.put();
pig.actions.delete();

pig.actions.oink(); // sends a PUT to /api/pigs/8/oink
pig.actions.oink({params: {loud: true}}); // sends a PUT to /api/pigs/8/oink?load=true

Actions and collection actions (e.g. getAll()) return a promise that returns the response object.

Relations

You can find other elements on the relations key.

Example:

human.relations.pigs();
pig.relations.boss();

Other functions

remove: Triggers a delete on the element and removes it from the collection if it is saved. If it is new, it is just removed from the collection on the client side. In both cases, it returns a promise.

isNew: Checks if the element has a selector value.

Embedded collections and elements

Can be accessed through their relations.

Snapshots

Under the snapshots key:

make(tag): Makes a snapshot of the fields and returns a snapshot object, with a tag, time, data and revert key. If you call revert, the element fields will revert themselves to that snapshot.

undo(tag_or_steps):

• When passed in a tag, will revert itself to the last snapshot with that tag. The snapshot with tag creation is made after build. Snapshots with tags before_action and after_action are made after those actions, like before_get and after_put.
• When passed in a number, it will revert itself n steps. No argument equals 0 steps, which reverts itself to the last snapshot.

isPersisted(): Compares fields with the lastPersisted(). Note: when one of the fields is an object, it will return true when changing the keys of that object, because the object reference is the same. The fields are compared with ===. Returns false if the element is new.

lastPersisted(): Gets last snapshot where the tag is after_get, after_post ,after_put or creation.

last(): Gets last snapshot

lastWithTag(tag): Gets last snapshot where the tag matches the tag string or regex.

You can loop through snapshots with the list key.

element.lastPersisted().revert() // reverts the fields to the last persisted snapshot

Merging

If data is received in another way, like with WebSockets, it can be merged with the other data using merge.

Preloading

To preload a scheme, create a meta tag with name="elpong-scheme", scheme=scheme_name and content=scheme.
scheme is the JSON scheme.

To preload data, create a meta tag with name="elpong-collection", scheme=scheme_name, content=elements and collection=collection_name.
elements is the same JSON data the API would return.

To preload a single element, create a meta tag with name="elpong-element", scheme=scheme_name, content=element and collection=collection_name.

Then you can use elpong.load() and collection.load() to load schemes and collections, respectively, or you can use elpong.enableAutoload() and it will take care of it when it reads the scheme. Make sure to put the meta tags above the script tags when you do this. elpong.enableAutoload() might give some problems because it is synchronous.

Examples

Animal Farm

Scheme Usage

Pulser

Scheme Usage

Setting an ajax function

The ajax function expects one argument object with url, method, data and headers keys.
It should return a Promise-like object that catches when the response status is not between 200 and 299, and on other network errors.
The then and catch functions should return a response object with a data key, that holds the parsed JSON object. $http, Http, and jQuery.ajax are supported out of the box.
If you don't work with AngularJS, Angular, or jQuery, you can use window.fetch.

elpong.setAjax(window.fetch, 'fetch') // built-in in modern browsers
elpong.setAjax($http, 'angularjs') // if you use AngularJS
elpong.setAjax($.ajax, 'jquery') // if you use jQuery
elpong.setAjax(http, 'angular') // if you use Angular, http: instance of Http or HttpClient

Contributing

Yes please!

Fork it, then do something like this:

git clone https://github.com/<you>/elpong-js
cd elpong-js
git checkout -b add-a-feature
npm install -g gulp-cli coffeescript typescript
npm install
gulp test

Check the gulpfile.js for other tasks.
Make pull requests when you think your feature should be merged or when you want feedback. Issues are very welcome too!