Role

Parse. Role

Represents a Role on the Parse server. Roles represent groupings of Users for the purposes of granting permissions (e.g. specifying an ACL for an Object). Roles are specified by their sets of child users and child roles, all of which are granted any permissions that the parent role has.

Roles must have a name (which cannot be changed after creation of the role), and must specify an ACL.

Constructor

new Role(name, acl)

Parameters:
Name Type Description
name string

The name of the Role to create.
acl Parse.ACL

The ACL for this role. Roles must have an ACL. A Parse.Role is a local representation of a role persisted to the Parse cloud.

Extends

Members

createdAt

The first time this object was saved on the server.

Properties:
Name Type Description
createdAt Date
Overrides:

updatedAt

The last time this object was updated on the server.

Properties:
Name Type Description
updatedAt Date
Overrides:

Methods

_clearPendingOps(keysToClearopt)

Overrides:
Parameters:
Name Type Attributes Description
keysToClear Array.<string> <optional>

if specified, only ops matching these fields will be cleared

_getId() → {string}

Returns a local or server Id used uniquely identify this object

Overrides:
Returns:
Type:
string

_getStateIdentifier() → {Parse.Object|object}

Returns a unique identifier used to pull data from the State Controller.

Overrides:
Returns:
Type:
Parse.Object | object

add(attr, item) → {ParseObject|boolean}

Atomically add an object to the end of the array associated with a given key.

Overrides:
Parameters:
Name Type Description
attr String

The key.
item

The item to add.
Returns:
Type:
ParseObject | boolean

addAll(attr, items) → {ParseObject|boolean}

Atomically add the objects to the end of the array associated with a given key.

Overrides:
Parameters:
Name Type Description
attr String

The key.
items Array.<Object>

The items to add.
Returns:
Type:
ParseObject | boolean

addAllUnique(attr, items) → {ParseObject|boolean}

Atomically add the objects to the array associated with a given key, only if it is not already present in the array. The position of the insert is not guaranteed.

Overrides:
Parameters:
Name Type Description
attr String

The key.
items Array.<Object>

The objects to add.
Returns:
Type:
ParseObject | boolean

addUnique(attr, item) → {ParseObject|boolean}

Atomically add an object to the array associated with a given key, only if it is not already present in the array. The position of the insert is not guaranteed.

Overrides:
Parameters:
Name Type Description
attr String

The key.
item

The object to add.
Returns:
Type:
ParseObject | boolean

clear() → {ParseObject|boolean}

Clears all attributes on a model

Overrides:
Returns:
Type:
ParseObject | boolean

clone() → {Parse.Object}

Creates a new model with identical attributes to this one.

Overrides:
Returns:
Type:
Parse.Object

decrement(attr, amount) → {ParseObject|boolean}

Atomically decrements the value of the given attribute the next time the object is saved. If no amount is specified, 1 is used by default.

Overrides:
Parameters:
Name Type Description
attr String

The key.
amount Number

The amount to decrement by (optional).
Returns:
Type:
ParseObject | boolean

destroy(options) → {Promise}

Destroy this model on the server if it was already persisted.

Overrides:
Parameters:
Name Type Description
options object

Valid options are:

  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
  • context: A dictionary that is accessible in Cloud Code `beforeDelete` and `afterDelete` triggers.
Returns:
Type:
Promise

A promise that is fulfilled when the destroy completes.

(async) destroyEventually(optionsopt) → {Promise}

Deletes this object from the server at some unspecified time in the future, even if Parse is currently inaccessible.

Use this when you may not have a solid network connection, and don't need to know when the delete completes. If there is some problem with the object such that it can't be deleted, the request will be silently discarded.

Delete instructions made with this method will be stored locally in an on-disk cache until they can be transmitted to Parse. They will be sent immediately if possible. Otherwise, they will be sent the next time a network connection is available. Delete requests will persist even after the app is closed, in which case they will be sent the next time the app is opened.

Overrides:
Parameters:
Name Type Attributes Description
options object <optional>

Valid options are:

  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
  • context: A dictionary that is accessible in Cloud Code `beforeDelete` and `afterDelete` triggers.
Returns:
Type:
Promise

A promise that is fulfilled when the destroy completes.

dirty(attr) → {boolean}

Returns true if this object has been modified since its last save/refresh. If an attribute is specified, it returns true only if that particular attribute has been modified since the last save/refresh.

Overrides:
Parameters:
Name Type Description
attr string

An attribute name (optional).
Returns:
Type:
boolean

dirtyKeys() → {Array.<string>}

Returns an array of keys that have been modified since last save/refresh

Overrides:
Returns:
Type:
Array.<string>

equals(other) → {boolean}

Determines whether this ParseObject is equal to another ParseObject

Overrides:
Parameters:
Name Type Description
other object

An other object ot compare
Returns:
Type:
boolean

escape(attr) → {string}

Gets the HTML-escaped value of an attribute.

Overrides:
Parameters:
Name Type Description
attr string

The string name of an attribute.
Returns:
Type:
string

existed() → {boolean}

Returns true if this object was created by the Parse server when the object might have already been there (e.g. in the case of a Facebook login)

Overrides:
Returns:
Type:
boolean

(async) exists(options) → {Promise.<boolean>}

Returns true if this object exists on the Server

Overrides:
Parameters:
Name Type Description
options object

Valid options are:

  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
Returns:
Type:
Promise.<boolean>

A boolean promise that is fulfilled if object exists.

fetch(options) → {Promise}

Fetch the model from the server. If the server's representation of the model differs from its current attributes, they will be overriden.

Overrides:
Parameters:
Name Type Description
options object

Valid options are:

  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
  • include: The name(s) of the key(s) to include. Can be a string, an array of strings, or an array of array of strings.
  • context: A dictionary that is accessible in Cloud Code `beforeFind` trigger.
Returns:
Type:
Promise

A promise that is fulfilled when the fetch completes.

(async) fetchFromLocalDatastore() → {Promise}

Asynchronously loads data from the local datastore into this object.

await object.fetchFromLocalDatastore();

You can create an unfetched pointer with Parse.Object.createWithoutData() and then call fetchFromLocalDatastore() on it.

Overrides:
Returns:
Type:
Promise

A promise that is fulfilled when the fetch completes.

fetchWithInclude(keys, options) → {Promise}

Fetch the model from the server. If the server's representation of the model differs from its current attributes, they will be overriden.

Includes nested Parse.Objects for the provided key. You can use dot notation to specify which fields in the included object are also fetched.

Overrides:
Parameters:
Name Type Description
keys string | Array.<(string|Array.<string>)>

The name(s) of the key(s) to include.
options object

Valid options are:

  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
Returns:
Type:
Promise

A promise that is fulfilled when the fetch completes.

get(attr) → {*}

Gets the value of an attribute.

Overrides:
Parameters:
Name Type Description
attr string

The string name of an attribute.
Returns:
Type:
*

getACL() → {Parse.ACL|null}

Returns the ACL for this object.

Overrides:
See:
Returns:
Type:
Parse.ACL | null

An instance of Parse.ACL.

getName() → {string}

Gets the name of the role. You can alternatively call role.get("name")

Returns:
Type:
string

the name of the role.

getRoles() → {Parse.Relation}

Gets the Parse.Relation for the Parse.Roles that are direct children of this role. These roles' users are granted any privileges that this role has been granted (e.g. read or write access through ACLs). You can add or remove child roles from this role through this relation.

This is equivalent to calling role.relation("roles")

Returns:
Type:
Parse.Relation

the relation for the roles belonging to this role.

getUsers() → {Parse.Relation}

Gets the Parse.Relation for the Parse.Users that are direct children of this role. These users are granted any privileges that this role has been granted (e.g. read or write access through ACLs). You can add or remove users from the role through this relation.

This is equivalent to calling role.relation("users")

Returns:
Type:
Parse.Relation

the relation for the users belonging to this role.

has(attr) → {boolean}

Returns true if the attribute contains a value that is not null or undefined.

Overrides:
Parameters:
Name Type Description
attr string

The string name of the attribute.
Returns:
Type:
boolean

increment(attr, amount) → {ParseObject|boolean}

Atomically increments the value of the given attribute the next time the object is saved. If no amount is specified, 1 is used by default.

Overrides:
Parameters:
Name Type Description
attr String

The key.
amount Number

The amount to increment by (optional).
Returns:
Type:
ParseObject | boolean

isDataAvailable() → {boolean}

Returns true if the object has been fetched.

Overrides:
Returns:
Type:
boolean

isNew() → {boolean}

Returns true if this object has never been saved to Parse.

Overrides:
Returns:
Type:
boolean

(async) isPinned() → {Promise.<boolean>}

Asynchronously returns if the object is pinned

const isPinned = await object.isPinned();
Overrides:
Returns:
Type:
Promise.<boolean>

A boolean promise that is fulfilled if object is pinned.

isValid() → {boolean}

Checks if the model is currently in a valid state.

Overrides:
Returns:
Type:
boolean

newInstance() → {Parse.Object}

Creates a new instance of this object. Not to be confused with clone()

Overrides:
Returns:
Type:
Parse.Object

op(attr) → {Parse.Op|undefined}

Returns an instance of a subclass of Parse.Op describing what kind of modification has been performed on this field since the last time it was saved. For example, after calling object.increment("x"), calling object.op("x") would return an instance of Parse.Op.Increment.

Overrides:
Parameters:
Name Type Description
attr String

The key.
Returns:
Type:
Parse.Op | undefined

The operation, or undefined if none.

pin() → {Promise}

Asynchronously stores the object and every object it points to in the local datastore, recursively, using a default pin name: _default.

If those other objects have not been fetched from Parse, they will not be stored. However, if they have changed data, all the changes will be retained.

await object.pin();

To retrieve object: query.fromLocalDatastore() or query.fromPin()

Overrides:
Returns:
Type:
Promise

A promise that is fulfilled when the pin completes.

pinWithName(name) → {Promise}

Asynchronously stores the objects and every object they point to in the local datastore, recursively.

If those other objects have not been fetched from Parse, they will not be stored. However, if they have changed data, all the changes will be retained.

await object.pinWithName(name);

To retrieve object: query.fromLocalDatastore() or query.fromPinWithName(name)

Overrides:
Parameters:
Name Type Description
name string

Name of Pin.
Returns:
Type:
Promise

A promise that is fulfilled when the pin completes.

relation(attr) → {Parse.Relation}

Gets a relation on the given class for the attribute.

Overrides:
Parameters:
Name Type Description
attr string

The attribute to get the relation for.
Returns:
Type:
Parse.Relation

remove(attr, item) → {ParseObject|boolean}

Atomically remove all instances of an object from the array associated with a given key.

Overrides:
Parameters:
Name Type Description
attr String

The key.
item

The object to remove.
Returns:
Type:
ParseObject | boolean

removeAll(attr, items) → {ParseObject|boolean}

Atomically remove all instances of the objects from the array associated with a given key.

Overrides:
Parameters:
Name Type Description
attr String

The key.
items Array.<Object>

The object to remove.
Returns:
Type:
ParseObject | boolean

revert(…keysopt)

Clears any (or specific) changes to this object made since the last call to save()

Overrides:
Parameters:
Name Type Attributes Description
keys string <optional>
<repeatable>

specify which fields to revert

save(arg1opt, arg2opt, arg3opt) → {Promise}

Set a hash of model attributes, and save the model to the server. updatedAt will be updated when the request returns. You can either call it as:

object.save();
or
object.save(attrs);
or
object.save(null, options);
or
object.save(attrs, options);
or
object.save(key, value);
or
object.save(key, value, options);

Example 1: 

gameTurn.save({
player: "Jake Cutter",
diceRoll: 2
}).then(function(gameTurnAgain) {
// The save was successful.
}, function(error) {
// The save failed.  Error is an instance of Parse.Error.
});

Example 2: 

gameTurn.save("player", "Jake Cutter");

Overrides:
Parameters:
Name Type Attributes Description
arg1 string | object | null <optional>

Valid options are:

  • `Object` - Key/value pairs to update on the object.
  • `String` Key - Key of attribute to update (requires arg2 to also be string)
  • `null` - Passing null for arg1 allows you to save the object with options passed in arg2.
arg2 string | object <optional>
  • `String` Value - If arg1 was passed as a key, arg2 is the value that should be set on that key.
  • `Object` Options - Valid options are:
    • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
    • sessionToken: A valid session token, used for making a request on behalf of a specific user.
    • cascadeSave: If `false`, nested objects will not be saved (default is `true`).
    • context: A dictionary that is accessible in Cloud Code `beforeSave` and `afterSave` triggers.
arg3 object <optional>

Used to pass option parameters to method if arg1 and arg2 were both passed as strings. Valid options are:

  • useMasterKey: In Cloud Code and Node only, causes the Master Key to be used for this request.
  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
  • cascadeSave: If `false`, nested objects will not be saved (default is `true`).
  • context: A dictionary that is accessible in Cloud Code `beforeSave` and `afterSave` triggers.
Returns:
Type:
Promise

A promise that is fulfilled when the save completes.

(async) saveEventually(optionsopt) → {Promise}

Saves this object to the server at some unspecified time in the future, even if Parse is currently inaccessible.

Use this when you may not have a solid network connection, and don't need to know when the save completes. If there is some problem with the object such that it can't be saved, it will be silently discarded.

Objects saved with this method will be stored locally in an on-disk cache until they can be delivered to Parse. They will be sent immediately if possible. Otherwise, they will be sent the next time a network connection is available. Objects saved this way will persist even after the app is closed, in which case they will be sent the next time the app is opened.

Overrides:
Parameters:
Name Type Attributes Description
options object <optional>

Used to pass option parameters to method if arg1 and arg2 were both passed as strings. Valid options are:

  • sessionToken: A valid session token, used for making a request on behalf of a specific user.
  • cascadeSave: If `false`, nested objects will not be saved (default is `true`).
  • context: A dictionary that is accessible in Cloud Code `beforeSave` and `afterSave` triggers.
Returns:
Type:
Promise

A promise that is fulfilled when the save completes.

set(key, value, options) → {ParseObject|boolean}

Sets a hash of model attributes on the object.

You can call it with an object containing keys and values, with one key and value, or dot notation. For example:

  gameTurn.set({
    player: player1,
    diceRoll: 2
  }, {
    error: function(gameTurnAgain, error) {
      // The set failed validation.
    }
  });

game.set("currentPlayer", player2, {
error: function(gameTurnAgain, error) {
// The set failed validation.
}
});


game.set("finished", true);

game.set("player.score", 10);

Overrides:
Parameters:
Name Type Description
key string | object

The key to set.
value string | object

The value to give it.
options object

A set of options for the set. The only supported option is error.
Returns:
Type:
ParseObject | boolean

true if the set succeeded.

setACL(acl, options) → {ParseObject|boolean}

Sets the ACL to be used for this object.

Overrides:
See:
Parameters:
Name Type Description
acl Parse.ACL

An instance of Parse.ACL.
options object
Returns:
Type:
ParseObject | boolean

Whether the set passed validation.

setName(name, options) → {ParseObject|boolean}

Sets the name for a role. This value must be set before the role has been saved to the server, and cannot be set once the role has been saved.

A role's name can only contain alphanumeric characters, _, -, and spaces.

This is equivalent to calling role.set("name", name)

Parameters:
Name Type Description
name string

The name of the role.
options object

Standard options object with success and error callbacks.
Returns:
Type:
ParseObject | boolean

true if the set succeeded.

toJSON(seen, offline) → {object}

Returns a JSON version of the object suitable for saving to Parse.

Overrides:
Parameters:
Name Type Description
seen
offline
Returns:
Type:
object

toOfflinePointer() → {Pointer}

Gets a Pointer referencing this Object.

Overrides:
Returns:
Type:
Pointer

toPointer() → {Pointer}

Gets a Pointer referencing this Object.

Overrides:
Returns:
Type:
Pointer

unPin() → {Promise}

Asynchronously removes the object and every object it points to in the local datastore, recursively, using a default pin name: _default.

await object.unPin();
Overrides:
Returns:
Type:
Promise

A promise that is fulfilled when the unPin completes.

unPinWithName(name) → {Promise}

Asynchronously removes the object and every object it points to in the local datastore, recursively.

await object.unPinWithName(name);
Overrides:
Parameters:
Name Type Description
name string

Name of Pin.
Returns:
Type:
Promise

A promise that is fulfilled when the unPin completes.

unset(attr, options) → {ParseObject|boolean}

Remove an attribute from the model. This is a noop if the attribute doesn't exist.

Overrides:
Parameters:
Name Type Description
attr string

The string name of an attribute.
options
Returns:
Type:
ParseObject | boolean

validate(attrs) → {Parse.Error|boolean}

You should not call this function directly unless you subclass Parse.Object, in which case you can override this method to provide additional validation on set and save. Your implementation should return

Overrides:
See:
Parameters:
Name Type Description
attrs object

The current data to validate.
Returns:
Type:
Parse.Error | boolean

False if the data is valid. An error object otherwise.