API Preview tool | The Dojo Toolkit

dojo/data/api/Write.js

Provides:
- dojo.data.api.Write
Requires:
- dojo.data.api.Read in common

dojo.data.api.Write

type
```
Function
```
chains:
- dojo.data.api.Read: (prototype)
- dojo.data.api.Read: (call)

summary

This is an abstract API that data provider implementations conform to.
This file defines function signatures and intentionally leaves all the
functionss unimplemented.

dojo.data.api.Write.getFeatures

summary
```
See dojo.data.api.Read.getFeatures()
```
type
```
Function
```

dojo.data.api.Write.newItem

parameters:

keywordArgs: (typeof Object)

A javascript object defining the initial content of the item as a set of JavaScript 'property name: value' pairs.

parentInfo: (typeof Object)

An optional javascript object defining what item is the parent of this item (in a hierarchical store.  Not all stores do hierarchical items),
and what attribute of that parent to assign the new item to.  If this is present, and the attribute specified
is a multi-valued attribute, it will append this item into the array of values for that attribute.  The structure
of the object is as follows:
{
parent: someItem,
attribute: &quot;attribute-name-string&quot;
}

returns
```
item
```

summary

Returns a newly created item.  Sets the attributes of the new
item based on the *keywordArgs* provided.  In general, the attribute
names in the keywords become the attributes in the new item and as for
the attribute values in keywordArgs, they become the values of the attributes
in the new item.  In addition, for stores that support hierarchical item
creation, an optional second parameter is accepted that defines what item is the parent
of the new item and what attribute of that item should the new item be assigned to.
In general, this will assume that the attribute targetted is multi-valued and a new item
is appended onto the list of values for that attribute.

exceptions

Throws an exception if *keywordArgs* is a string or a number or
anything other than a simple anonymous object.
Throws an exception if the item in parentInfo is not an item from the store
or if the attribute isn't an attribute name string.

example

	var kermit = store.newItem({name: "Kermit", color:[blue, green]});

type
```
Function
```

dojo.data.api.Write.deleteItem

parameters:
- item: (typeof item)
```
The item to delete.
```
returns
```
boolean
```
summary
```
Deletes an item from the store.
```

exceptions

Throws an exception if the argument *item* is not an item
(if store.isItem(item) returns false).

example

	var success = store.deleteItem(kermit);

type
```
Function
```

dojo.data.api.Write.setValue

parameters:

item: (typeof item)
```
The item to modify.
```

attribute: (typeof string)

The attribute of the item to change represented as a string name.

value: (typeof almost)
```
The value to assign to the item.
```

returns
```
boolean
```

summary

Sets the value of an attribute on an item.
Replaces any previous value or values.

exceptions

Throws an exception if *item* is not an item, or if *attribute*
is neither an attribute object or a string.
Throws an exception if *value* is undefined.

example

	var success = store.set(kermit, "color", "green");

type
```
Function
```

dojo.data.api.Write.setValues

parameters:

item: (typeof item)
```
The item to modify.
```

attribute: (typeof string)

The attribute of the item to change represented as a string name.

values: (typeof array)

An array of values to assign to the attribute..

returns
```
boolean
```

summary

Adds each value in the *values* array as a value of the given
attribute on the given item.
Replaces any previous value or values.
Calling store.setValues(x, y, []) (with *values* as an empty array) has
the same effect as calling store.unsetAttribute(x, y).

exceptions

Throws an exception if *values* is not an array, if *item* is not an
item, or if *attribute* is neither an attribute object or a string.

example

	var success = store.setValues(kermit, "color", ["green", "aqua"]);
	success = store.setValues(kermit, "color", []);
	if (success) {assert(!store.hasAttribute(kermit, "color"));}

type
```
Function
```

dojo.data.api.Write.unsetAttribute

parameters:

item: (typeof item)
```
The item to modify.
```

attribute: (typeof string)

The attribute of the item to unset represented as a string.

returns
```
boolean
```

summary

Deletes all the values of an attribute on an item.

exceptions

Throws an exception if *item* is not an item, or if *attribute*
is neither an attribute object or a string.

example

	var success = store.unsetAttribute(kermit, "color");
	if (success) {assert(!store.hasAttribute(kermit, "color"));}

type
```
Function
```

dojo.data.api.Write.save

parameters:

keywordArgs: (typeof object)

{ onComplete: function
onError: function
scope: object
}

The *onComplete* parameter.
function();

If an onComplete callback function is provided, the callback function
will be called just once, after the save has completed.  No parameters
are generally passed to the onComplete.

The *onError* parameter.
function(errorData);

If an onError callback function is provided, the callback function
will be called if there is any sort of error while attempting to
execute the save.  The onError function will be based one parameter, the
error.

The *scope* parameter.
If a scope object is provided, all of the callback function (
onComplete, onError, etc) will be invoked in the context of the scope
object.  In the body of the callback function, the value of the &quot;this&quot;
keyword will be the scope object.   If no scope object is provided,
the callback functions will be called in the context of dojo.global.
For example, onComplete.call(scope) vs.
onComplete.call(dojo.global)

summary

Saves to the server all the changes that have been made locally.
The save operation may take some time and is generally performed
in an asynchronous fashion.  The outcome of the save action is
is passed into the set of supported callbacks for the save.

return_summary

Nothing.  Since the saves are generally asynchronous, there is
no need to return anything.  All results are passed via callbacks.

example

	store.save({onComplete: onSave});
	store.save({scope: fooObj, onComplete: onSave, onError: saveFailed});

type
```
Function
```

dojo.data.api.Write.revert

returns
```
boolean
```
summary
```
Discards any unsaved changes.
```
description
```
Discards any unsaved changes.
```
example
```
	var success = store.revert();
```
type
```
Function
```

dojo.data.api.Write.isDirty

parameters:
- item: (typeof item)
```
The item to check.
```
returns
```
boolean
```

summary

Given an item, isDirty() returns true if the item has been modified
since the last save().  If isDirty() is called with no *item* argument,
then this function returns true if any item has been modified since
the last save().

exceptions

Throws an exception if isDirty() is passed an argument and the
argument is not an item.

example

	var trueOrFalse = store.isDirty(kermit); // true if kermit is dirty
	var trueOrFalse = store.isDirty();       // true if any item is dirty

type
```
Function
```

dojo.data.api
- type
```
Object
```
dojo.data
- type
```
Object
```
dojo
- type
```
Object
```

dojo/data/api/Write.js

Provides:

Requires:

dojo.data.api.Write

dojo.data.api.Write.getFeatures

dojo.data.api.Write.newItem

dojo.data.api.Write.deleteItem

dojo.data.api.Write.setValue

dojo.data.api.Write.setValues

dojo.data.api.Write.unsetAttribute

dojo.data.api.Write.save

dojo.data.api.Write.revert

dojo.data.api.Write.isDirty

dojo.data.api

dojo.data

dojo