{"_id":"56a0bda03697d80d002ac5f6","parentDoc":null,"project":"54774d9af3736008009e9e0e","user":"54ad5f42921992210075173e","version":{"_id":"56a0bd9e3697d80d002ac5e7","project":"54774d9af3736008009e9e0e","__v":20,"createdAt":"2016-01-21T11:14:38.131Z","releaseDate":"2016-01-21T11:14:38.131Z","categories":["56a0bd9f3697d80d002ac5e8","56a0bd9f3697d80d002ac5e9","56a0bd9f3697d80d002ac5ea","56a0bd9f3697d80d002ac5eb","56b098a43a5b810d00745e3f","56b098da8f7a4f0d0029dd10","56d5a8ecf612b80b00fb69cd","570989853ab43c0e0072b2d6","571006aa10300c0e007f6133","5735a52431a73b1700887ca0","5744b0529e045c0e00b7a7a2","5744b1d0b56d431700d8a4fb","5744b1fb55d65a0e00b436e1","5744b218f9c7411700ce560e","5744b220f9c7411700ce560f","5744b2259e045c0e00b7a7a7","5744b22cf8b79f0e00de6a2d","5744b23155d65a0e00b436e4","5744b242c758290e00fbc235","5744b2569e045c0e00b7a7a8","5756a3f2bb92962900dafe3d","57ee23e81e42900e0014a42f","581c822c98676e0f00d240ef"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Sockets","version_clean":"1.1.0","version":"1.1"},"__v":23,"category":{"_id":"56a0bd9f3697d80d002ac5e8","pages":["56a0bda03697d80d002ac5f4","56a0bda03697d80d002ac5f5","56a0bda03697d80d002ac5f6","56a0bda03697d80d002ac5f7","56a0bda03697d80d002ac5f8","56a0bda03697d80d002ac5f9","56a0bda03697d80d002ac5fa","56a0bda03697d80d002ac5fb","56a0bda03697d80d002ac5fc","56a0bda03697d80d002ac5fd","56a0bda03697d80d002ac5fe"],"__v":1,"project":"54774d9af3736008009e9e0e","version":"56a0bd9e3697d80d002ac5e7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-11-27T16:46:04.014Z","from_sync":false,"order":8,"slug":"libraries-quick-starts","title":"Libraries Quick Starts"},"updates":["554bc3c6f245703100ddd3cb","576267ccd3c7061700616498"],"next":{"pages":[],"description":""},"createdAt":"2015-02-18T01:05:05.859Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"1. [Overview](#overview)\n2. [Installing the Library](#installing-the-library)\n3. [Using Syncano library](#using-syncano-library)\n4. [Promises](#promises)\n5. [Model instances](#model-instances)\n5. [QuerySet](#queryset)\n6. [Nested models](#nested-models)\n7. [Contributing](#contributing)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nThis guide will walk you through the installation steps of the [Syncano Library](https://github.com/Syncano/syncano-js) for JavaScript as well as give you a couple of usage examples.\n\nIf you don't have a Syncano account yet, you can read about how to create one [here](doc:getting-started-with-syncano).\n\nFor the full JavaScript documentation, view the [syncano-js reference](http://syncano.github.io/syncano-js/index.html).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installing the Library\"\n}\n[/block]\nThere are a couple of ways to get the Syncano Library - through `npm`, `bower` or directly from our GitHub repository.\n\n## npm\nInstall the [npm module](https://www.npmjs.com/package/syncano) using:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"npm install syncano --save\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n## Bower\nInstall the [bower module](https://www.bower.io) using:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bower install syncano\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n##CDN\nWe also provide the `syncano.min.js` file via jsDelivr.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script src=\\\"//cdn.jsdelivr.net/syncanojs/latest/syncano.min.js\\\"></script>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n## GitHub\n\nDownload the latest version [here](https://github.com/Syncano/syncano-js/archive/master.zip) or browse our repo [here](https://github.com/syncano/syncano-js).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Syncano library\"\n}\n[/block]\nTo use Syncano with the client, include the following script tag in your HTML document:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script src=\\\"path/to/bower_components/syncano/dist/syncano.min.js\\\"></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nUsing Syncano with a CommonJS pattern in Node.js, or using Browserify or WebPack, simply `require` Syncano.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var Syncano = require('syncano');\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSyncano utilizes a method chaining pattern to provide a flexible API. To access the API from the most basic level requires instantiating a new object.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Create empty connection\\nvar connection = Syncano();\\n\\n// Create a connection with an account key\\nvar connection = Syncano({ accountKey: 'MY_ACCOUNT_KEY'});\\n\\n// Create a connection with a user key\\nvar connection = Syncano({apiKey: \\\"API_KEY\\\", userKey: \\\"USER_KEY\\\"});\\n\\n// Create a connection with a social token\\nvar connection = Syncano({ userKey: 'SOCIAL_TOKEN'});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Promises\"\n}\n[/block]\nAs a convenience, the Syncano JavaScript library also uses [Bluebird](https://github.com/petkaantonov/bluebird) to provide a promise interface that you can utilize. On a successful call, `success` will return the `serialized response` from the API call, on a failed call it will return the `error` object. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var success = function(instances) {\\n  console.log(instances);\\n};\\nvar error = function(error) {\\n  console.log(error);\\n};\\n\\nconnection.Instance.please().list().then(success).catch(error);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Model instances\"\n}\n[/block]\nThe `connection` you configured in the previous step has a set of factories that make interacting with objects on the platform easier. For example, if you would like to create a new instance object, you can do it like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var instance = connection.Instance({\\n  name: 'INSTANCE_NAME', \\n  description: 'INSTANCE_DESCRIPTION'\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou can later save the instance, by calling its `save` method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"instance.save().then(function(instance) {\\n\\tconsole.log('instance', instance);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"QuerySet\"\n}\n[/block]\nEvery model has a static `please` method that returns a `QuerySet` object allowing you to perform additional queries like listing objects:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"connection.Instance.please().list().then(function(instances) {\\n\\tconsole.log('instances', instances);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Nested models\"\n}\n[/block]\nThe objects (models) are also nested, so if you would like to list the `Data Classes` of an `Instance`, there's an elegant function chain for that:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"connection.Instance({name: 'silent-dawn-3609'}).classes().list().then(function(classes) {\\n\\tconsole.log('data classes', classes);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination\"\n}\n[/block]\nProbably, you store a lot of objects on Syncano. You will not need get all of them in one API call. Syncano return lists some resource with which you get links to the next and previous page. You can also set `pageSize` to your call as below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"connection.DataObject\\n\\t.please()\\n\\t.list({instanceName: \\\"small-bush-8425\\\", className: \\\"books\\\"})\\n\\t.pageSize(5)\\n\\t.then((res) => {\\n\\t\\tconsole.log('first page', res);\\n\\t\\treturn res.next();\\n\\t}).then((res) => {\\n\\t\\tconsole.log('second page', res);\\n\\t\\treturn res.prev();\\n\\t}).then((res) => {\\n\\t\\tconsole.log('previous / first page', res);\\n\\t});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Contributing\"\n}\n[/block]\nThis library is built using [Stampit](https://github.com/stampit-org/stampit). If you find a bug, feel free to submit an [issue](https://github.com/Syncano/syncano-js/issues). If you would like to directly contribute to the library, we are open for [pull requests](https://github.com/Syncano/syncano-js).","excerpt":"Javascript Library Quick Start Guide","slug":"javascript","type":"basic","title":"JavaScript"}

JavaScript

Javascript Library Quick Start Guide

1. [Overview](#overview) 2. [Installing the Library](#installing-the-library) 3. [Using Syncano library](#using-syncano-library) 4. [Promises](#promises) 5. [Model instances](#model-instances) 5. [QuerySet](#queryset) 6. [Nested models](#nested-models) 7. [Contributing](#contributing) [block:api-header] { "type": "basic", "title": "Overview" } [/block] This guide will walk you through the installation steps of the [Syncano Library](https://github.com/Syncano/syncano-js) for JavaScript as well as give you a couple of usage examples. If you don't have a Syncano account yet, you can read about how to create one [here](doc:getting-started-with-syncano). For the full JavaScript documentation, view the [syncano-js reference](http://syncano.github.io/syncano-js/index.html). [block:api-header] { "type": "basic", "title": "Installing the Library" } [/block] There are a couple of ways to get the Syncano Library - through `npm`, `bower` or directly from our GitHub repository. ## npm Install the [npm module](https://www.npmjs.com/package/syncano) using: [block:code] { "codes": [ { "code": "npm install syncano --save", "language": "shell" } ] } [/block] ## Bower Install the [bower module](https://www.bower.io) using: [block:code] { "codes": [ { "code": "bower install syncano", "language": "shell" } ] } [/block] ##CDN We also provide the `syncano.min.js` file via jsDelivr. [block:code] { "codes": [ { "code": "<script src=\"//cdn.jsdelivr.net/syncanojs/latest/syncano.min.js\"></script>", "language": "text" } ] } [/block] ## GitHub Download the latest version [here](https://github.com/Syncano/syncano-js/archive/master.zip) or browse our repo [here](https://github.com/syncano/syncano-js). [block:api-header] { "type": "basic", "title": "Using Syncano library" } [/block] To use Syncano with the client, include the following script tag in your HTML document: [block:code] { "codes": [ { "code": "<script src=\"path/to/bower_components/syncano/dist/syncano.min.js\"></script>", "language": "html" } ] } [/block] Using Syncano with a CommonJS pattern in Node.js, or using Browserify or WebPack, simply `require` Syncano. [block:code] { "codes": [ { "code": "var Syncano = require('syncano');", "language": "javascript" } ] } [/block] Syncano utilizes a method chaining pattern to provide a flexible API. To access the API from the most basic level requires instantiating a new object. [block:code] { "codes": [ { "code": "// Create empty connection\nvar connection = Syncano();\n\n// Create a connection with an account key\nvar connection = Syncano({ accountKey: 'MY_ACCOUNT_KEY'});\n\n// Create a connection with a user key\nvar connection = Syncano({apiKey: \"API_KEY\", userKey: \"USER_KEY\"});\n\n// Create a connection with a social token\nvar connection = Syncano({ userKey: 'SOCIAL_TOKEN'});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Promises" } [/block] As a convenience, the Syncano JavaScript library also uses [Bluebird](https://github.com/petkaantonov/bluebird) to provide a promise interface that you can utilize. On a successful call, `success` will return the `serialized response` from the API call, on a failed call it will return the `error` object. [block:code] { "codes": [ { "code": "var success = function(instances) {\n console.log(instances);\n};\nvar error = function(error) {\n console.log(error);\n};\n\nconnection.Instance.please().list().then(success).catch(error);", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Model instances" } [/block] The `connection` you configured in the previous step has a set of factories that make interacting with objects on the platform easier. For example, if you would like to create a new instance object, you can do it like so: [block:code] { "codes": [ { "code": "var instance = connection.Instance({\n name: 'INSTANCE_NAME', \n description: 'INSTANCE_DESCRIPTION'\n});", "language": "javascript" } ] } [/block] You can later save the instance, by calling its `save` method: [block:code] { "codes": [ { "code": "instance.save().then(function(instance) {\n\tconsole.log('instance', instance);\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "QuerySet" } [/block] Every model has a static `please` method that returns a `QuerySet` object allowing you to perform additional queries like listing objects: [block:code] { "codes": [ { "code": "connection.Instance.please().list().then(function(instances) {\n\tconsole.log('instances', instances);\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Nested models" } [/block] The objects (models) are also nested, so if you would like to list the `Data Classes` of an `Instance`, there's an elegant function chain for that: [block:code] { "codes": [ { "code": "connection.Instance({name: 'silent-dawn-3609'}).classes().list().then(function(classes) {\n\tconsole.log('data classes', classes);\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Pagination" } [/block] Probably, you store a lot of objects on Syncano. You will not need get all of them in one API call. Syncano return lists some resource with which you get links to the next and previous page. You can also set `pageSize` to your call as below: [block:code] { "codes": [ { "code": "connection.DataObject\n\t.please()\n\t.list({instanceName: \"small-bush-8425\", className: \"books\"})\n\t.pageSize(5)\n\t.then((res) => {\n\t\tconsole.log('first page', res);\n\t\treturn res.next();\n\t}).then((res) => {\n\t\tconsole.log('second page', res);\n\t\treturn res.prev();\n\t}).then((res) => {\n\t\tconsole.log('previous / first page', res);\n\t});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Contributing" } [/block] This library is built using [Stampit](https://github.com/stampit-org/stampit). If you find a bug, feel free to submit an [issue](https://github.com/Syncano/syncano-js/issues). If you would like to directly contribute to the library, we are open for [pull requests](https://github.com/Syncano/syncano-js).