<commit_before>Stamplay JavaScript SDK
===============
[![Build Status](https://travis-ci.org/Stamplay/stamplay-js-sdk.svg?branch=master)](https://travis-ci.org/Stamplay/stamplay-js-sdk)

##Getting Started
Just import the JS SDK in your HTML page and you're ready to go.

```html

<!DOCTYPE html>
<html>
	<head>
	<!-- Nice things here -->
	</head>
	<body>
		<!-- Beautiful DOM elements here -->
		<script src="path/to/stamplay-sdk.js"></script>

		<script type="text/javascript">
			// Initializing the user informations
			var user = new Stamplay.User().Model;
			var tag = new Stamplay.Cobject('tag').Model;
			var tags = new Stamplay.Cobject('tag').Collection;
			
			user.currentUser()
			.then(function(){
				// Reading data
				return tags.fetch()	
			}).then(function(){
				tag.set('name', 'javascript');
				return tag.save();
			}).then(function(){
				tags.add(tag);
			});
		</script>
	</body>
</html>
```

This javascript SDK expose through the Stamplay object the following components:
 
* [User](#user)
* [Custom Object](#custom-object)

Every component can expose two main classes:

* [Model](#model)
* [Collection](#collection)

#Model
Models are the heart of any JavaScript application, a model keeps the application logic and with the Stamplay model you can easily synchronize the data between client and the Stamplay platform.

The following is a contrived example, but it demonstrates defining a User model, setting an attribute, and saving it in the application. 

```javascript
var registrationData = {
	email : '<EMAIL>',
	password: '<PASSWORD>'
};
var newUser = new Stamplay.User;
newUser.signup(registrationData)
.then(function(){
	// User is now registered
	newUser.set('phoneNumber', '020 123 4567' );
	return newUser.save();
}).then(function(){
	// User is saved server side
	var number = newUser.get('phoneNumber'); // number value is 020 123 4567 
})
```

##Methods

  * <a href="#Model.get"> <code>get()</code></a>
  * <a href="#Model.set"><code>set()</code></a>
  * <a href="#Model.unset"><code>unset</code></a>
  * <a href="#Model.fetch"><code>fetch()</code></a>
  * <a href="#Model.destroy"><code>destroy()</code></a>
  * <a href="#Model.save"><code>save()</code></a>
 
-------------------------------------------------------
  
<a name="Model.get"></a>
### get(property)
Returns the value of the property
<a name="Model.set"></a>
### set(property, value)
Sets the value of the property
<a name="Model.unset"></a>
### unset(property)
Delete the property from the object
<a name="Model.fetch"></a>
### fetch(id, queryParameters)
Resets the model's state from the server. Useful if the model has never been populated with data, or if you'd like to ensure that you have the latest server state. 
Refer to the [queryParameters](#query-parameters) documentation. 
<a name="Model.destroy"></a>
###destroy()
Deletes the object from the server by making a DELETE request. If the model is new, false is returned.
<a name="Model.save"></a>
###save(options)
Saves the model to the database. If the model is new a POST request is made, otherwise, unless specified a PUT request is sent.
#### options 
An object with the following properties: 

* patch : default false, if true an HTTP PATCH is sent to the server instead of PUT for updating the model 

##Actions
Some models can expose Action's methods, refer to the [Actions](#action-methods) .

# Collection
Collections are sets of models. You can ```fetch``` the collection from the server and a set of Underscore methods.   

##Methods

  * <a href="#Collection.fetch"> <code>fetch()</code></a>
  * <a href="#Collection.remove"><code>remove()</code></a>
  * <a href="#Collection.get"><code>get()</code></a>
  * <a href="#Collection.at"><code>at()</code></a>
  * <a href="#Collection.pop"><code>pop()</code></a>
  * <a href="#Collection.shift"><code>shift()</code></a>
  * <a href="#Collection.add"><code>add()</code></a> 

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

<a name="Collection.fetch"></a>
### fetch(queryParams)
Populate the collection with all the available models. If no [queryParameters](#query-parameters) are passed the collection is populated with the first 20 models ordered by id. 
<a name="Collection.remove"></a>
### remove(id)
Remove the model with the specified id from the collection. 
You can pass an array of ids to remove from the collection. 
<a name="Collection.get"></a>
### get(id)
Get a model from a collection, specified by an id.
<a name="Collection.at"></a>
### at(index)
Get a model from a collection, specified by index. In this moment collection aren't sorted so **at** will still retrieve models in insertion order.
<a name="Collection.pop"></a>
### pop()
Remove and return the last model from a collection, if collection is empty return false. 
<a name="Collection.shift"></a>
### shift()
Remove and return the first model from a collection, if collection is empty return false.
<a name="Collection.add"></a>
### add(model)
Add a model at the end of the collection.

#Action methods
These methods are a fast way to ```rate```, ```vote``` and ```comment``` a resource. 
Moreover there are two methods for keeping track of the Twitter and Facebook shares.
All these methods return a promise.
     
```javascript
var tag = new Stamplay.Cobject('tag').Model;
tag.rate(4)
.then(function(){
	var actions = tag.get('actions');
	console.log(actions.ratings); // You can see the ratings, the average rate and the users who v
});
```
##Methods

  * <a href="#Action.vote"><code>vote()</code></a>
  * <a href="#Action.rate"><code>rate()</code></a>
  * <a href="#Action.comment"><code>comment()</code></a>
  * <a href="#Action.twitter_share"><code>twitter_share()</code></a>
  * <a href="#Action.facebook_share"><code>facebook_share()</code></a>

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

<a name="Action.vote"></a>
###vote() 
Vote the resource.
<a name="Action.rate"></a>
###rate(rating)
Rate the resource, only integer values as parameter.
<a name="Action.comment"></a>
###comment(text)
Comment the resource with the text.
<a name="Action.twitter_share"></a>
###twitter_share()
Calls the Twitter share endpoint. Note that this method updates the twitter_share counter but it is not responsible for sharing the resource on Twitter.
<a name="Action.facebook_share"></a>  
###facebook_share
Calls the Facebook share endpoint. Note that this method updates the facebook_share counter but it is not responsible for sharing the resource on Facebook.  
#Query parameters
An object representing the parameters that should be added in the request. 

You can use these keys in the object:

* **page** : a number representing the pagination page. Must be used in conjunction with per_page.  default: 1
* **per_page**: the number of results in a single page. Must be used in conjunction with page.   default: 20
* **select**: the attributes that you want to be returned from the server. default: none
* **sort**: the name of the attribute on which you want to sort on. If a ```-``` symbol is present before the attribute name, the sorting is made on descendant order.   
* **n** : the number results to return
 
#User
You can create both Model and Collection of a Stamplay.User.

```javascript
var user = new Stamplay.User().Model;<commit_msg>Updating README<commit_after>Stamplay JavaScript SDK
===============
[![Build Status](https://travis-ci.org/Stamplay/stamplay-js-sdk.svg?branch=master)](https://travis-ci.org/Stamplay/stamplay-js-sdk)

##Getting Started
Just import the JS SDK in your HTML page and you're ready to go.

```javascript
var user = new Stamplay.User().Model;
var tags = new Stamplay.Cobject('tag').Collection;
var tag;

//Gettings 
user.currentUser()
.then(function(){
  // Populating tags collection with all available data
  return tags.fetch();
})
.then(function(){
  tag = new Stamplay.Cobject('tag').Model;
  tag.set('name', 'javascript');
  return tag.save();
 })
.then(function(){
  tags.add(tag);
});
```

##Available components
This JavaScript SDK expose through the Stamplay object the following components:
 
* [User](#user)
* [Custom Object](#custom-object)

Every component can expose two main classes:

* [Model](#model)
* [Collection](#collection)

#Model
Models are the heart of any JavaScript application, a model keeps the application logic and with the Stamplay model you can easily synchronize the data between client and the Stamplay platform.

The following is a contrived example, but it demonstrates defining a User model, setting an attribute, and saving it in the application. 

```javascript
var registrationData = {
	email : '<EMAIL>',
	password: '<PASSWORD>'
};
var newUser = new Stamplay.User;
newUser.signup(registrationData)
.then(function(){
	// User is now registered
	newUser.set('phoneNumber', '020 123 4567' );
	return newUser.save();
}).then(function(){
	// User is saved server side
	var number = newUser.get('phoneNumber'); // number value is 020 123 4567 
})
```

##Model actions
Some components expose the model actions too.
These methods are a fast way to ```rate```, ```vote``` and ```comment``` a resource. 
Moreover there are two methods for keeping track of the Twitter and Facebook shares.
All these methods return a promise.

```javascript
var tag = new Stamplay.Cobject('tag').Model;
tag.rate(4)
.then(function(){
	var actions = tag.get('actions');
	console.log(actions.ratings); // You can see the ratings, the average rate and the users who rate
});
```

##Model methods

  * <a href="#Model.get"> <code>get()</code></a>
  * <a href="#Model.set"><code>set()</code></a>
  * <a href="#Model.unset"><code>unset</code></a>
  * <a href="#Model.fetch"><code>fetch()</code></a>
  * <a href="#Model.destroy"><code>destroy()</code></a>
  * <a href="#Model.save"><code>save()</code></a>
  * <a href="#Action.vote"><code>vote()</code></a>

###Action methods
  * <a href="#Action.rate"><code>rate()</code></a>
  * <a href="#Action.comment"><code>comment()</code></a>
  * <a href="#Action.twitter_share"><code>twitter_share()</code></a>
  * <a href="#Action.facebook_share"><code>facebook_share()</code></a>
 
-------------------------------------------------------
  
<a name="Model.get"></a>
### get(property)
Returns the value of the property
<a name="Model.set"></a>
### set(property, value)
Sets the value of the property
<a name="Model.unset"></a>
### unset(property)
Delete the property from the object
<a name="Model.fetch"></a>
### fetch(id, queryParameters)
Resets the model's state from the server. Useful if the model has never been populated with data, or if you'd like to ensure that you have the latest server state. 
Refer to the [queryParameters](#query-parameters) documentation. 
<a name="Model.destroy"></a>
###destroy()
Deletes the object from the server by making a DELETE request. If the model is new, false is returned.
<a name="Model.save"></a>
###save(options)
Saves the model to the database. If the model is new a POST request is made, otherwise, unless specified a PUT request is sent.
#### options 
An object with the following properties: 

* patch : default false, if true an HTTP PATCH is sent to the server instead of PUT for updating the model 

##Action methods
<a name="Action.vote"></a>
###vote() 
Vote the resource.
<a name="Action.rate"></a>
###rate(rating)
Rate the resource, only integer values as parameter.
<a name="Action.comment"></a>
###comment(text)
Comment the resource with the text.
<a name="Action.twitter_share"></a>
###twitter_share()
Calls the Twitter share endpoint. Note that this method updates the twitter_share counter but it is not responsible for sharing the resource on Twitter.
<a name="Action.facebook_share"></a>  
###facebook_share
Calls the Facebook share endpoint. Note that this method updates the facebook_share counter but it is not responsible for sharing the resource on Facebook.  

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


# Collection
Collections are sets of models. You can ```fetch``` the collection from the server and a set of Underscore methods.   

##Methods

  * <a href="#Collection.fetch"> <code>fetch()</code></a>
  * <a href="#Collection.remove"><code>remove()</code></a>
  * <a href="#Collection.get"><code>get()</code></a>
  * <a href="#Collection.at"><code>at()</code></a>
  * <a href="#Collection.pop"><code>pop()</code></a>
  * <a href="#Collection.shift"><code>shift()</code></a>
  * <a href="#Collection.add"><code>add()</code></a> 

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

<a name="Collection.fetch"></a>
### fetch(queryParams)
Populate the collection with all the available models. If no [queryParameters](#query-parameters) are passed the collection is populated with the first 20 models ordered by id. 
<a name="Collection.remove"></a>
### remove(id)
Remove the model with the specified id from the collection. 
You can pass an array of ids to remove from the collection. 
<a name="Collection.get"></a>
### get(id)
Get a model from a collection, specified by an id.
<a name="Collection.at"></a>
### at(index)
Get a model from a collection, specified by index. In this moment collection aren't sorted so **at** will still retrieve models in insertion order.
<a name="Collection.pop"></a>
### pop()
Remove and return the last model from a collection, if collection is empty return false. 
<a name="Collection.shift"></a>
### shift()
Remove and return the first model from a collection, if collection is empty return false.
<a name="Collection.add"></a>
### add(model)
Add a model at the end of the collection.

#User
You can create both Model and Collection of a Stamplay.User.

```javascript
var user = new Stamplay.User().Model;
{'fraction_non_alphanumeric': 0.1731037009893734, 'fraction_numerical': 0.0035910589959692197, 'mean_word_length': 4.14361100640784, 'pattern_counts': {'":': 0, '<': 236, '<?xml version=': 0, '>': 236, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '388599', 'n_tokens_mistral': 4073, 'n_tokens_neox': 3871, 'n_words': 1484}