Readme: Clean up of code formatting, some grammar fixes, added UsergridQuery
diff --git a/README.md b/README.md
index 3a7e640..efc0ce2 100644
--- a/README.md
+++ b/README.md
@@ -53,172 +53,190 @@
1. The singleton pattern is both convenient and enables the developer to use a globally available and always-initialized shared instance of Usergrid.
- var Usergrid = require('usergrid')
- Usergrid.init({
- orgId: '<org-id>',
- appId: '<app-id>'
- })
+ ```js
+ var Usergrid = require('usergrid')
+ Usergrid.init({
+ orgId: '<org-id>',
+ appId: '<app-id>'
+ })
- // or you can load from a config file; see config.sample.json
+ // or you can load from a config file; see config.sample.json
- var Usergrid = require('usergrid')
- Usergrid.init() // defaults to use config.json
+ var Usergrid = require('usergrid')
+ Usergrid.init() // defaults to use config.json
+ ```
2. The instance pattern enables the developer to manage instances of the Usergrid client independently and in an isolated fashion. The primary use-case for this is when an application connects to multiple Usergrid targets.
- var UsergridClient = require('./node_modules/usergrid/lib/client')
- var client = new UsergridClient(config)
+ ```js
+ var UsergridClient = require('./node_modules/usergrid/lib/client')
+ var client = new UsergridClient(config)
+ ```
_**Note:** Examples in this readme assume you are using the `Usergrid` shared instance. If you've implemented the instance pattern instead, simply replace `Usergrid` with your client instance variable. See `/tests` for additional examples._
## RESTful operations
-When making any RESTful call, a `type` parameter (or `path`) is always required. Whether you specify this as an argument or in an object as a parameter is up to you.
+When making any RESTful call, a `type` parameter (or `path`) is always required. Whether you specify this as an argument, in an object as a parameter, or as part of a `UsergridQuery` object is up to you.
### GET()
-**GET entities in a collection**
+To get entities in a collection:
- Usergrid.GET('collection', function(error, usergridResponse, entities) {
- // entities is an array of UsergridEntity objects
- })
+```js
+Usergrid.GET('collection', function(error, usergridResponse, entities) {
+ // entities is an array of UsergridEntity objects
+})
+```
-**GET a specific entity in a collection by uuid or name**
+To get a specific entity in a collection by uuid or name:
- Usergrid.GET('collection', '<uuid-or-name>', function(error, usergridResponse, entity) {
- // entity, if found, is a UsergridEntity object
- })
+```js
+Usergrid.GET('collection', '<uuid-or-name>', function(error, usergridResponse, entity) {
+ // entity, if found, is a UsergridEntity object
+})
+```
-**GET specific entities in a collection by passing a UsergridQuery object**
+To get specific entities in a collection by passing a UsergridQuery object:
- var query = new UsergridQuery('cats')
- .gt('weight', 2.4)
- .contains('color', 'bl*')
- .not
- .eq('color', 'blue')
- .or
- .eq('color', 'orange')
-
- // this will build out the following query:
- // select * where weight > 2.4 and color contains 'bl*' and not color = 'blue' or color = 'orange'
+```js
+var query = new UsergridQuery('cats')
+ .gt('weight', 2.4)
+ .contains('color', 'bl*')
+ .not
+ .eq('color', 'blue')
+ .or
+ .eq('color', 'orange')
+
+// this will build out the following query:
+// select * where weight > 2.4 and color contains 'bl*' and not color = 'blue' or color = 'orange'
- Usergrid.GET(query, function(error, usergridResponse) {
- // entities is an array of UsergridEntity objects matching the specified query
- })
+Usergrid.GET(query, function(error, usergridResponse) {
+ // entities is an array of UsergridEntity objects matching the specified query
+})
+```
### POST() and PUT()
POST and PUT requests both require a JSON body payload. You can pass either a standard JavaScript object or a `UsergridEntity` instance. While the former works in principle, best practise is to use a `UsergridEntity` wherever practical. When an entity has a uuid or name property and already exists on the server, use a PUT request to update it. If it does not, use POST to create it.
-**POST (create) a new entity in a collection**
+To create a new entity in a collection (POST):
- var entity = new UsergridEntity({
+```js
+var entity = new UsergridEntity({
+ type: 'restaurant',
+ restaurant: 'Dino's Deep Dish,
+ cuisine: 'pizza'
+})
+
+// or
+
+var entity = {
+ type: 'restaurant',
+ restaurant: 'Dino's Deep Dish,
+ cuisine: 'pizza'
+}
+
+Usergrid.POST(entity, function(error, usergridResponse, entity) {
+ // entity should now have a uuid property and be created
+})
+
+// you can also POST an array of entities:
+
+var entities = [
+ new UsergridEntity({
type: 'restaurant',
restaurant: 'Dino's Deep Dish,
cuisine: 'pizza'
- })
-
- // or
-
- var entity = {
- type: 'restaurant',
- restaurant: 'Dino's Deep Dish,
- cuisine: 'pizza'
- }
-
- Usergrid.POST(entity, function(error, usergridResponse, entity) {
- // entity should now have a uuid property and be created
- })
-
- // you can also POST an array of entities:
-
- var entities = [
- new UsergridEntity({
- type: 'restaurant',
- restaurant: 'Dino's Deep Dish,
- cuisine: 'pizza'
- }),
- new UsergridEntity({
- type: 'restaurant',
- restaurant: 'Pizza da Napoli',
- cuisine: 'pizza'
- })
- ]
-
- Usergrid.POST(entities, function(error, usergridResponse, entities) {
- //
- })
-
-**PUT (update) an entity in a collection**
-
- var entity = new UsergridEntity({
+ }),
+ new UsergridEntity({
type: 'restaurant',
restaurant: 'Pizza da Napoli',
cuisine: 'pizza'
})
+]
- Usergrid.POST(entity, function(error, usergridResponse, entity) {
- entity.owner = 'Mia Carrara'
- Usergrid.PUT(entity, function(error, usergridResponse, entity) {
- // entity now has the property 'owner'
- })
+Usergrid.POST(entities, function(error, usergridResponse, entities) {
+ //
+})
+```
+
+To update an entity in a collection (PUT request):
+
+```js
+var entity = new UsergridEntity({
+ type: 'restaurant',
+ restaurant: 'Pizza da Napoli',
+ cuisine: 'pizza'
+})
+
+Usergrid.POST(entity, function(error, usergridResponse, entity) {
+ entity.owner = 'Mia Carrara'
+ Usergrid.PUT(entity, function(error, usergridResponse, entity) {
+ // entity now has the property 'owner'
})
+})
- // or update a set of entities by passing a UsergridQuery object
+// or update a set of entities by passing a UsergridQuery object
- var query = new UsergridQuery('restaurants')
- .eq('cuisine', 'italian')
-
- // this will build out the following query:
- // select * where cuisine = 'italian'
+var query = new UsergridQuery('restaurants')
+ .eq('cuisine', 'italian')
+
+// this will build out the following query:
+// select * where cuisine = 'italian'
- Usergrid.PUT(query, { keywords: ['pasta'] }, function(error, usergridResponse) {
- /* the first 10 entities matching this query criteria will be updated:
- e.g.:
- [
- {
- "type": "restaurant",
- "restaurant": "Il Tarazzo",
- "cuisine": "italian",
- "keywords": [
- "pasta"
- ]
- },
- {
- "type": "restaurant",
- "restaurant": "Cono Sur Pizza & Pasta",
- "cuisine": "italian",
- "keywords": [
- "pasta"
- ]
- }
- ]
- /*
- })
+Usergrid.PUT(query, { keywords: ['pasta'] }, function(error, usergridResponse) {
+ /* the first 10 entities matching this query criteria will be updated:
+ e.g.:
+ [
+ {
+ "type": "restaurant",
+ "restaurant": "Il Tarazzo",
+ "cuisine": "italian",
+ "keywords": [
+ "pasta"
+ ]
+ },
+ {
+ "type": "restaurant",
+ "restaurant": "Cono Sur Pizza & Pasta",
+ "cuisine": "italian",
+ "keywords": [
+ "pasta"
+ ]
+ }
+ ]
+ /*
+})
+```
### DELETE()
DELETE requests require either a specific entity or a `UsergridQuery` object to be passed as an argument.
-**DELETE a specific entity in a collection by uuid or name**
+To delete a specific entity in a collection by uuid or name:
- Usergrid.DELETE('collection', '<uuid-or-name>', function(error, usergridResponse) {
- // if successful, entity will now be deleted
- })
+```js
+Usergrid.DELETE('collection', '<uuid-or-name>', function(error, usergridResponse) {
+ // if successful, entity will now be deleted
+})
+```
-**DELETE specific entities in a collection by passing a UsergridQuery object**
+To specific entities in a collection by passing a `UsergridQuery` object:
- var query = new UsergridQuery('cats')
- .eq('color', 'black')
- .or
- .eq('color', 'white')
-
- // this will build out the following query:
- // select * where color = 'black' or color = 'white'
+```js
+var query = new UsergridQuery('cats')
+ .eq('color', 'black')
+ .or
+ .eq('color', 'white')
+
+// this will build out the following query:
+// select * where color = 'black' or color = 'white'
- Usergrid.DELETE(query, function(error, usergridResponse) {
- // the first 10 entities matching this query criteria will be deleted
- })
+Usergrid.DELETE(query, function(error, usergridResponse) {
+ // the first 10 entities matching this query criteria will be deleted
+})
+```
## Entity operations and convenience methods
@@ -226,22 +244,34 @@
### reload()
- entity.reload(function(error, usergridResponse) {
- // entity is now reloaded from the server
- })
+Reloads the entity from the server
+
+```js
+entity.reload(function(error, usergridResponse) {
+ // entity is now reloaded from the server
+})
+```
### save()
- entity.aNewProperty = 'A new value'
- entity.save(function(error, usergridResponse) {
- // entity is now updated on the server
- })
+Saves (or creates) the entity on the server
+
+```js
+entity.aNewProperty = 'A new value'
+entity.save(function(error, usergridResponse) {
+ // entity is now updated on the server
+})
+```
### remove()
- entity.remove(function(error, usergridResponse) {
- // entity is now deleted on the server and the local instance should be destroyed
- })
+Deletes the entity from the server
+
+```js
+entity.remove(function(error, usergridResponse) {
+ // entity is now deleted on the server and the local instance should be destroyed
+})
+```
## Authentication, current user, and auth-fallback
@@ -249,10 +279,12 @@
`Usergrid` can use the app client ID and secret that were passed upon initialization and automatically retrieve an app-level token for these credentials.
- Usergrid.setAppAuth('<client-id>', '<client-secret>')
- Usergrid.authenticateApp(function(error, usergridResponse, token) {
- // Usergrid.appAuth is created automatically when this call is successful
- })
+```js
+Usergrid.setAppAuth('<client-id>', '<client-secret>')
+Usergrid.authenticateApp(function(error, usergridResponse, token) {
+ // Usergrid.appAuth is created automatically when this call is successful
+})
+```
### authFallback
@@ -262,36 +294,42 @@
At times it is desireable to have complete, granular control over the authentication context of an API call. To facilitate this, the passthrough function `.usingAuth()` allows you to pre-define the auth context of the next API call.
- // assume Usergrid.authFallback = UsergridAuth.AUTH_FALLBACK_NONE
+```js
+// assume Usergrid.authFallback = UsergridAuth.AUTH_FALLBACK_NONE
- Usergrid.usingAuth(Usergrid.appAuth).POST('roles/guest/permissions', {
- permission: "get,post,put,delete:/**"
- }, function(error, usergridResponse) {
- // here we've temporarily used the client credentials to modify permissions
- // subsequent calls will not use this auth context
- })
+Usergrid.usingAuth(Usergrid.appAuth).POST('roles/guest/permissions', {
+ permission: "get,post,put,delete:/**"
+}, function(error, usergridResponse) {
+ // here we've temporarily used the client credentials to modify permissions
+ // subsequent calls will not use this auth context
+})
+```
### currentUser and authenticateUser()
`Usergrid` has a special `currentUser` property. By default, when calling `authenticateUser()`, `.currentUser` will be set to this user if the authentication flow is successful.
- Usergrid.authenticateUser({
- username: '<username>',
- email: '<email-address>', // either username or email is required
- password: '<password>'
- }, function(error, usergridResponse, token) {
- // Usergrid.currentUser is set to the authenticated user and the token is stored within that context
- })
+```js
+Usergrid.authenticateUser({
+ username: '<username>',
+ email: '<email-address>', // either username or email is required
+ password: '<password>'
+}, function(error, usergridResponse, token) {
+ // Usergrid.currentUser is set to the authenticated user and the token is stored within that context
+})
+```
If you want to utilize authenticateUser without setting as the current user, simply pass a `false` boolean value as the second parameter:
- Usergrid.authenticateUser({
- username: '<username>',
- email: '<email-address>', // either username or email is required
- password: '<password>'
- }, false, function(error, usergridResponse, token) {
+```js
+Usergrid.authenticateUser({
+ username: '<username>',
+ email: '<email-address>', // either username or email is required
+ password: '<password>'
+}, false, function(error, usergridResponse, token) {
- })
+})
+```
## User operations and convenience methods
@@ -301,78 +339,258 @@
Creating a new user:
- var user = new UsergridUser({
- username: 'username',
- password: 'password'
- })
+```js
+var user = new UsergridUser({
+ username: 'username',
+ password: 'password'
+})
- user.create(function(error, usergridResponse, user) {
- // user has now been created and should have a valid uuid
- })
+user.create(function(error, usergridResponse, user) {
+ // user has now been created and should have a valid uuid
+})
+```
### login()
A simpler means of retrieving a user-level token:
- var user = new UsergridUser({
- username: 'username',
- password: 'password'
- })
+```js
+var user = new UsergridUser({
+ username: 'username',
+ password: 'password'
+})
- user.login(function(error, usergridResponse, token) {
- // user is now logged in
- })
+user.login(function(error, usergridResponse, token) {
+ // user is now logged in
+})
+```
### logout()
Logs out the selected user. You can also use this convenience method on `Usergrid.currentUser`.
- user.logout(function(error, usergridResponse) {
- // user is now logged out
- })
+```js
+user.logout(function(error, usergridResponse) {
+ // user is now logged out
+})
+```
### logoutAllSessions()
Logs out all sessions for the selected user and destroys all active tokens. You can also use this convenience method on `Usergrid.currentUser`.
- user.logoutAllSessions(function(error, usergridResponse) {
- // user is now logged out from everywhere
- })
+```js
+user.logoutAllSessions(function(error, usergridResponse) {
+ // user is now logged out from everywhere
+})
+```
### resetPassword()
Resets the password for the selected user.
- user.resetPassword({
- oldPassword: '2cool4u',
- newPassword: 'correct-horse-battery-staple',
- }, function(error, response, success) {
- // if it was done correctly, the new password will be changed
- // 'success' is a boolean value that indicates whether it was changed successfully
- })
+```js
+user.resetPassword({
+ oldPassword: '2cool4u',
+ newPassword: 'correct-horse-battery-staple',
+}, function(error, response, success) {
+ // if it was done correctly, the new password will be changed
+ // 'success' is a boolean value that indicates whether it was changed successfully
+})
+```
### UsergridUser.CheckAvailable()
This is a class (static) method that allows you to check whether a username or email address is available or not.
- UsergridUser.CheckAvailable(client, {
- email: 'email'
- }, function(err, response, exists) {
- // 'exists' is a boolean value that indicates whether a user already exists
- })
+```js
+UsergridUser.CheckAvailable(client, {
+ email: 'email'
+}, function(err, response, exists) {
+ // 'exists' is a boolean value that indicates whether a user already exists
+})
- UsergridUser.CheckAvailable(client, {
- username: 'username'
- }, function(err, response, exists) {
-
- })
+UsergridUser.CheckAvailable(client, {
+ username: 'username'
+}, function(err, response, exists) {
+
+})
- UsergridUser.CheckAvailable(client, {
- email: 'email',
- username: 'username', // checks both email and username
- }, function(err, response, exists) {
- // 'exists' returns true if either username or email exist
- })
+UsergridUser.CheckAvailable(client, {
+ email: 'email',
+ username: 'username', // checks both email and username
+}, function(err, response, exists) {
+ // 'exists' returns true if either username or email exist
+})
+```
+
+## Querying and filtering data
+
+### UsergridQuery initialization
+
+The `UsergridQuery` class allows you to build out complex query filters using the Usergrid [query syntax](http://docs.apigee.com/app-services/content/querying-your-data).
+
+The first parameter of the `UsergridQuery` builder pattern should be the collection (or type) you intend to query. You can either pass this as an argument, or as the first builder object:
+
+```js
+var query = new UsergridQuery('cats')
+// or
+var query = new UsergridQuery().type('cats')
+var query = new UsergridQuery().collection('cats')
+```
+
+You then can layer on additional queries:
+
+```js
+var query = new UsergridQuery('cats')
+ .gt('weight', 2.4)
+ .contains('color', 'bl*')
+ .not
+ .eq('color', 'white')
+ .or
+ .eq('color', 'orange')
+```
+
+You can also adjust the number of results returned:
+
+```js
+var query = new UsergridQuery('cats').eq('color', 'black').limit(100)
+// returns a maximum of 100 entiteis
+```
+
+And sort the results:
+
+```js
+var query = new UsergridQuery('cats').eq('color', 'black').asc('name')
+// sorts by 'name', ascending
+```
+
+And you can do geo-location queries:
+
+```js
+var query = new UsergridQuery('devices').locationWithin(<distanceInMeters>, <latitude>, <longitude>)
+```
+
+### Using a query in a request
+
+Queries can be passed as parameters to GET, PUT, and DELETE requests:
+
+```js
+Usergrid.GET(query, function(error, usergridResponse, entities) {
+ //
+})
+
+Usergrid.PUT(query, { aNewProperty: "A new value" }, function(error, usergridResponse, entities) {
+ //
+})
+
+Usergrid.DELETE(query, function(error, usergridResponse, entities) {
+ //
+})
+```
+
+While not a typical use case, sometimes it is useful to be able to create a query that works on multiple collections. Therefore, in each one of these RESTful calls, you can optionally pass a 'type' string as the first argument:
+
+```js
+Usergrid.GET('cats', query, function(error, usergridResponse, entities) {
+ //
+})
+```
+
+### List of query builder objects
+
+`type('string')`
+
+> The collection name to query
+
+`collection('string')`
+
+> An alias for `type`
+
+`eq('key', 'value')` or `equal('key', 'value')`
+
+> Equal to (e.g. `where color = 'black'`)
+
+`contains('key', 'value')`
+
+> Contains a string (e.g.` where color contains 'bl*'`)
+
+`gt('key', 'value')` or `greaterThan('key', 'value')`
+
+> Greater than (e.g. `where weight > 2.4`)
+
+`gte('key', 'value')` or `greaterThanOrEqual('key', 'value')`
+
+> Greater than or equal to (e.g. `where weight >= 2.4`)
+
+`lt('key', 'value')` or `lessThan('key', 'value')`
+
+> Less than (e.g. `where weight < 2.4`)
+
+`lte('key', 'value')` or `lessThanOrEqual('key', 'value')`
+
+> Less than or equal to (e.g. `where weight <= 2.4`)
+
+`not`
+
+> Negates the next block in the builder pattern, e.g.:
+
+```js
+var query = new UsergridQuery('cats').not.eq('color', 'black')
+// select * from cats where not color = 'black'
+```
+
+`and`
+
+> Joins two queries by requiring both of them. `and` is also implied when joining two queries _without_ an operator. E.g.:
+
+```js
+var query = new UsergridQuery('cats').eq('color', 'black').eq('fur', 'longHair')
+// is identical to:
+var query = new UsergridQuery('cats').eq('color', 'black').and.eq('fur', 'longHair')
+```
+
+`or`
+
+> Joins two queries by requiring only one of them. `or` is never implied. E.g.:
+
+```js
+var query = new UsergridQuery('cats').eq('color', 'black').or.eq('color', 'white')
+```
+
+> When using `or` and `and` operators, `and` joins will take precedence over `or` joins. You can read more about query operators and precedence [here](http://docs.apigee.com/api-baas/content/supported-query-operators-data-types).
+
+`locationWithin(distanceInMeters, latitude, longitude)`
+
+> Returns entities which have a location within the specified radius. Arguments can be `float` or `int`.
+
+`asc('key')`
+
+> Sorts the results by the specified property, ascending
+
+`desc('key')`
+
+> Sorts the results by the specified property, descending
+
+`sort('key', 'order')`
+
+> Sorts the results by the specified property, in the specified order (`asc` or `desc`).
+
+`limit(int)`
+
+> The maximum number of entities to return
+
+`cursor('string')`
+
+> A pagination cursor string
+
+`fromString('query string')`
+
+> A special builder property that allows you to input a pre-defined query string. All other builder properties will be ignored when this property is defined. For example:
+
+```js
+var query = new UsergridQuery().fromString("select * where color = 'black' order by name asc")
+```
## UsergridResponse object
@@ -382,11 +600,13 @@
You can check `usergridResponse.ok`, a `bool` value, to see if the response was successful. Any status code < 400 returns true.
- Usergrid.GET('collection', function(error, usergridResponse, entities) {
- if (usergridResponse.ok) {
- // woo!
- }
- })
+```js
+Usergrid.GET('collection', function(error, usergridResponse, entities) {
+ if (usergridResponse.ok) {
+ // woo!
+ }
+})
+```
### entity, entities, user, users, first, last
@@ -400,36 +620,38 @@
Examples:
- Usergrid.GET('collection', function(error, usergridResponse, entities) {
- // third param is an array of entities because no specific entity was referenced
- // you can also access:
- // usergridResponse.entities
- // usergridResponse.first
- // usergridResponse.entity (the first entity)
- // usergridResponse.last
- })
+```js
+Usergrid.GET('collection', function(error, usergridResponse, entities) {
+ // third param is an array of entities because no specific entity was referenced
+ // you can also access:
+ // usergridResponse.entities
+ // usergridResponse.first
+ // usergridResponse.entity (the first entity)
+ // usergridResponse.last
+})
- Usergrid.GET('collection', '<uuid or name>', function(error, usergridResponse, entity) {
- // third param is a single entity object
- // you can also access:
- // usergridResponse.entity
- // usergridResponse.first
- // usergridResponse.last
- })
+Usergrid.GET('collection', '<uuid or name>', function(error, usergridResponse, entity) {
+ // third param is a single entity object
+ // you can also access:
+ // usergridResponse.entity
+ // usergridResponse.first
+ // usergridResponse.last
+})
- Usergrid.GET('users', function(error, usergridResponse, users) {
- // third param is an array of users because no specific user was referenced
- // you can also access:
- // usergridResponse.users
- // usergridResponse.user (the first user)
- // usergridResponse.last
- })
+Usergrid.GET('users', function(error, usergridResponse, users) {
+ // third param is an array of users because no specific user was referenced
+ // you can also access:
+ // usergridResponse.users
+ // usergridResponse.user (the first user)
+ // usergridResponse.last
+})
- Usergrid.GET('users', '<uuid, username, or email>', function(error, usergridResponse, user) {
- // third param is a single user object
- // you can also access:
- // usergridResponse.user
- })
+Usergrid.GET('users', '<uuid, username, or email>', function(error, usergridResponse, user) {
+ // third param is a single user object
+ // you can also access:
+ // usergridResponse.user
+})
+```
## Connections
@@ -437,35 +659,42 @@
### connect
-**Create a connection between two entities**
+Create a connection between two entities:
- Usergrid.connect(entity1, 'relationship', entity2, function(error, usergridResponse) {
- // entity1 now has an outbound connection to entity2
- })
+```js
+Usergrid.connect(entity1, 'relationship', entity2, function(error, usergridResponse) {
+ // entity1 now has an outbound connection to entity2
+})
+```
### getConnections
-**Retrieve outbound connections**
+Retrieve outbound connections:
- client.getConnections(UsergridClient.Connections.DIRECTION_OUT, entity1, 'relationship', function(error, usergridResponse, entities) {
- // entities is an array of entities that entity1 is connected to via 'relationship'
- // in this case, we'll see entity2 in the array
- })
+```js
+client.getConnections(UsergridClient.Connections.DIRECTION_OUT, entity1, 'relationship', function(error, usergridResponse, entities) {
+ // entities is an array of entities that entity1 is connected to via 'relationship'
+ // in this case, we'll see entity2 in the array
+})
+```
-**Retrieve inbound connections**
+Retrieve inbound connections:
- client.getConnections(UsergridClient.Connections.DIRECTION_IN, entity2, 'relationship', function(error, usergridResponse, entities) {
- // entities is an array of entities that connect to entity2 via 'relationship'
- // in this case, we'll see entity1 in the array
- })
+```js
+client.getConnections(UsergridClient.Connections.DIRECTION_IN, entity2, 'relationship', function(error, usergridResponse, entities) {
+ // entities is an array of entities that connect to entity2 via 'relationship'
+ // in this case, we'll see entity1 in the array
+})```
### disconnect
-**Delete a connection between two entities**
+Delete a connection between two entities:
- Usergrid.disconnect(entity1, 'relationship', entity2, function(error, usergridResponse) {
- // entity1's outbound connection to entity2 has been destroyed
- })
+```js
+Usergrid.disconnect(entity1, 'relationship', entity2, function(error, usergridResponse) {
+ // entity1's outbound connection to entity2 has been destroyed
+})
+```
## Assets
@@ -473,59 +702,70 @@
### UsergridAsset init
-**Loading a file system image via `fs.readFile()`**
+Loading a file system image via `fs.readFile()`:
- var asset = new UsergridAsset('myImage')
- fs.readFile(_dirname + '/image.jpg', function(error, data) {
- asset.data = data
- })
+```js
+var asset = new UsergridAsset('myImage')
+fs.readFile(_dirname + '/image.jpg', function(error, data) {
+ asset.data = data
+})
+```
-**Loading a file system image from a read stream (`fs.createReadStream()`)**
+Loading a file system image from a read stream (`fs.createReadStream()`):
- var asset = new UsergridAsset('myImage')
- fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
- // now contains Buffer stream at asset.data
- })
+```js
+var asset = new UsergridAsset('myImage')
+fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
+ // now contains Buffer stream at asset.data
+})
+```
You can also access `asset.contentType` and `asset.contentLength` once data has been loaded into a `UsergridAsset`.
### .POST and .PUT
-**POST binary data to a collection by creating a new entity**
+POST binary data to a collection by creating a new entity:
- var asset = new UsergridAsset('myImage')
- fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
- client.POST('collection', asset, function(error, assetResponse, entityWithAsset) {
- // asset is now uploaded to Usergrid
- })
+```js
+var asset = new UsergridAsset('myImage')
+fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
+ client.POST('collection', asset, function(error, assetResponse, entityWithAsset) {
+ // asset is now uploaded to Usergrid
})
+})
+```
-**PUT binary data to an existing entity via attachAsset()**
+PUT binary data to an existing entity via attachAsset():
- var asset = new UsergridAsset('myImage')
- fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
- // assume entity already exists; attach it to the entity:
- entity.attachAsset(asset)
- client.PUT(entity, asset, function(error, assetResponse, entityWithAsset) {
- // asset is now uploaded to Usergrid
- })
+```js
+var asset = new UsergridAsset('myImage')
+fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
+ // assume entity already exists; attach it to the entity:
+ entity.attachAsset(asset)
+ client.PUT(entity, asset, function(error, assetResponse, entityWithAsset) {
+ // asset is now uploaded to Usergrid
})
+})
+```
### UsergridEntity convenience methods
-**entity.uploadAsset() is a much simpler means of uploading an asset**
+`entity.uploadAsset()` is a convenient way to upload an asset that is attached to an entity:
- var asset = new UsergridAsset('myImage')
- fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
- // assume entity already exists; attach it to the entity:
- entity.attachAsset(asset)
- entity.uploadAsset(function(error, assetResponse, entityWithAsset) {
- // asset is now uploaded to Usergrid
- })
- })
-
-**entity.downloadAsset() allows you to download a binary asset**
-
+```js
+var asset = new UsergridAsset('myImage')
+fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() {
+ // assume entity already exists; attach it to the entity:
+ entity.attachAsset(asset)
entity.uploadAsset(function(error, assetResponse, entityWithAsset) {
- // access the asset via entityWithAsset.asset
+ // asset is now uploaded to Usergrid
})
+})
+```
+
+`entity.downloadAsset()` allows you to download a binary asset:
+
+```js
+entity.uploadAsset(function(error, assetResponse, entityWithAsset) {
+ // access the asset via entityWithAsset.asset
+})```
