API Documentation

Choose a stylesheet:

dojo.data.api.Write

Object » dojo.data.api.Read » dojo.data.api.Write

dojo.require("dojo.data.api.Write");

defined in dojo/data/api/Write.js

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

FunctionsBack to top

close(request: dojo.data.api.Request)

Defined by dojo.data.api.Read

The close() method is intended for instructing the store to 'close' out any information associated with a particular request.

containsValue(item: item, attribute: attribute-name-string, value: anything): Boolean

Defined by dojo.data.api.Read

Returns true if the given *value* is one of the values that getValues() would return.

deleteItem(item: item): Boolean

Overrides

Deletes an item from the store.

fetch(keywordArgs: Object): an object conforming to the dojo.data.api.Request API

Defined by dojo.data.api.Read

Given a query and set of defined options, such as a start and count of items to return, this method executes the query and makes the results available as data items. The format and expectations of stores is that they operate in a generally asynchronous manner, therefore callbacks are always used to return items located by the fetch parameters.

getAttributes(item: item): Array

Defined by dojo.data.api.Read

Returns an array with all the attributes that this item has. This method will always return an array; if the item has no attributes at all, getAttributes() will return an empty array: [].

getFeatures()

Overrides dojo.data.api.Read,

See dojo.data.api.Read.getFeatures()

getLabel(item: item)

Defined by dojo.data.api.Read

Method to inspect the item and return a user-readable 'label' for the item that provides a general/adequate description of what the item is.

getLabelAttributes(item: item)

Defined by dojo.data.api.Read

Method to inspect the item and return an array of what attributes of the item were used to generate its label, if any.

getValue(item: item, attribute: attribute-name-string, defaultValue: value?): a literal, an item, null, or undefined (never an array)

Defined by dojo.data.api.Read

Returns a single attribute value. Returns defaultValue if and only if *item* does not have a value for *attribute*. Returns null if and only if null was explicitly set as the attribute value. Returns undefined if and only if the item does not have a value for the given attribute (which is the same as saying the item does not have the attribute).

getValues(item: item, attribute: attribute-name-string): an array that may contain literals and items

Defined by dojo.data.api.Read

This getValues() method works just like the getValue() method, but getValues() always returns an array rather than a single attribute value. The array may be empty, may contain a single attribute value, or may contain many attribute values. If the item does not have a value for the given attribute, then getValues() will return an empty array: []. (So, if store.hasAttribute(item, attribute) has a return of false, then store.getValues(item, attribute) will return [].)

hasAttribute(item: item, attribute: attribute-name-string): Boolean

Defined by dojo.data.api.Read

Returns true if the given *item* has a value for the given *attribute*.

isDirty(item: item?): Boolean

Overrides

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().

isItem(something: anything): Boolean

Defined by dojo.data.api.Read

Returns true if *something* is an item and came from the store instance. Returns false if *something* is a literal, an item from another store instance, or is any object other than an item.

isItemLoaded(something: anything): Boolean

Defined by dojo.data.api.Read

Returns false if isItem(something) is false. Returns false if if isItem(something) is true but the the item is not yet loaded in local memory (for example, if the item has not yet been read from the server).

loadItem(keywordArgs: Object)

Defined by dojo.data.api.Read

Given an item, this method loads the item so that a subsequent call to store.isItemLoaded(item) will return true. If a call to isItemLoaded() returns true before loadItem() is even called, then loadItem() need not do any work at all and will not even invoke the callback handlers. So, before invoking this method, check that the item has not already been loaded.

newItem(keywordArgs: Object?, parentInfo: Object?): item

Overrides

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.

revert(): Boolean

Overrides

Discards any unsaved changes.

save(keywordArgs: Object)

Overrides

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.

setValue(item: item, attribute: String, value: almost): Boolean

Overrides

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

setValues(item: item, attribute: String, values: Array): Boolean

Overrides

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).

unsetAttribute(item: item, attribute: String): Boolean

Overrides

Deletes all the values of an attribute on an item.

Navigating the Dojo API Tool

There are several different methods of navigating through the object structure of the Dojo Toolkit:

Use the namespace list (to the left). The simplest method would be to use the list of namespaces defined by the Dojo Toolkit, on the left side of every page.
Drill-down from where you are. The API Tool was designed to give you as much information via drill-down as possible. Everything defined in an object can be clicked on, for more information.
Use the search. At the top of the namespace list to the left is a search box; type in the terms you are looking for, and you will be taken to a result page that spans the entire toolkit.

In addition, objects with large numbers of contained types have a simple way of jumping to sections on a page; simply look at the right side of any heading, and you will see a set of quick navigation icons. Clicking a type icon will take you to that section; clicking the up arrow icon will return you to the top of the page.

Inherited and private members

The Dojo API Tool will show the full ancestry of an object's members (including how that member was defined and whether or not it overrides an original). By default, all members of an object that are inherited are shown with the object's API listing, and all private members are hidden.

To toggle either inherited or private members, look just beneath the breadcrumb bar (above the name of the object you are viewing) and click the appropriate link.

Switching styles

The Dojo API Tool was designed with several themes in mind; we know that some people prefer light on dark, while others might prefer dark on light. With this in mind, two themes (Noir and Blanc) are currently available, with more on the way.

To switch visual styles, click on the theme you want to use, near the top right corner of the page. The API Tool will remember which style you prefer and automatically load that theme on subsequent visits.

Key/Legend

Namespaces

A namespace in Dojo parlance is an object/property bag that can contain almost anything: constructors, methods, properties, etc. Usually is expressly defined to serve a particular purpose; for example, dojo.date.locale is a namespace defined to deal with locale-specific date handling.

Constructors

A constructor is a function designed to create instances of objects. With the Dojo Toolkit, there are two ways of creating constructors: the "old school" way (i.e. defining a function with the this keyword in the body) or using dojo.declare.

Singletons

A singleton is a constructor that is defined and then immediately executed so that only one instance may ever exist during an application's lifetime. Usually this is done to capture some information in the environment, or to ensure a set of private variables that cannot be accessed from outside of the declaration. Examples include dojox.encoding.crypto.Blowfish.

Data Types

Array

Arrays are ordered lists, native to Javascript.

Boolean

Native data type representing a simple "true/false" value.

Date

Native Javascript data type to handle common date and time representations.

Node

An object that represents any kind of element being referenced/used by Javascript code. Note that the type of element is not dictated by this data type; only that it is a node of some sort.

Error

A special, native Javascript object used to indicate an error in code. Can be subclassed and used in conjunction with the throw statement, i.e. throw new MySubError(...);

Function

Functions/methods are pieces of invocable code; in JavaScript, they are also considered data and can be passed around like any other object.

Number

A Number object is used to represent any kind of numeric value; note that Javascript does not guarentee the actual underlying datatype (though the most common is a 64-bit float).

Object

Objects are the base data type of Javascript. With the Dojo API Tool, a type that cannot be determined is usually marked with this icon, in addition to straight objects.

RegExp (Regular Expression)

A regular expression is an object used for fast string search and parsing.

String

A string is any sequence of characters.

Input formats

Filtered HTML:
- Web page addresses and e-mail addresses turn into links automatically.
- Allowed HTML tags: <a> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
 
 This site allows HTML content. While learning all of HTML may feel intimidating, learning how to use a very small number of the most basic HTML "tags" is very easy.
 
 For more information see W3C's HTML Specifications or use your favorite search engine to find other sites that explain HTML.
 
 Most unusual characters can be directly entered without any problems.
 
 If you do encounter problems, try using HTML character entities. A common example looks like & for an ampersand & character. For a full list of entities see HTML's entities page.
- Lines and paragraphs are automatically recognized. The line break, paragraph and close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.
PHP code:
- Using custom PHP code
  
  If you know how to script in PHP, Drupal gives you the power to embed any script you like. It will be executed when the page is viewed and dynamically embedded into the page. This gives you amazing flexibility and power, but of course with that comes danger and insecurity if you do not write good code. If you are not familiar with PHP, SQL or with the site engine, avoid experimenting with PHP because you can corrupt your database or render your site insecure or even unusable! If you do not plan to do fancy stuff with your content then you are probably better off with straight HTML.
  
  Remember that the code within each PHP item must be valid PHP code - including things like correctly terminating statements with a semicolon. It is highly recommended that you develop your code separately using a simple test script on top of a test database before migrating to your production environment.
  
  Notes:
  - You can use global variables, such as configuration parameters, within the scope of your PHP code but remember that global variables which have been given values in your code will retain these values in the engine afterwards.
  - register_globals is now set to off by default. If you need form information you need to get it from the "superglobals" $_POST, $_GET, etc.
  - You can either use the print or return statement to output the actual content for your item.
  A basic example:
  You want to have a box with the title "Welcome" that you use to greet your visitors. The content for this box could be created by going:
```
print t("Welcome visitor, ... welcome message goes here ...");
								
```
  If we are however dealing with a registered user, we can customize the message by using:
```
global $user;
if ($user->uid) {
	print t("Welcome $user->name, ... welcome message goes here ...");
}
else {
	print t("Welcome visitor, ... welcome message goes here ...");
}
								
```
  For more in-depth examples, we recommend that you check the existing Drupal code and use it as a starting point, especially for sidebar boxes.
Full HTML:
- Web page addresses and e-mail addresses turn into links automatically.
- Lines and paragraphs are automatically recognized. The line break, paragraph and close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.
Markdown:
- Quick Tips:
  - Two or more spaces at a line's end = Line break
  - Double returns = Paragraph
  - *Single asterisks* or _single underscores_ = Emphasis
  - **Double** or __double__ = Strong
  - This is [a link](http://the.link.com "The optional title text")
  For complete details on the Markdown syntax, see the Markdown documentation.

dojo.data.api.Write

FunctionsBack to top

Navigating the Dojo API Tool

Inherited and private members

Switching styles

Key/Legend

Data Types

Input formats

Using custom PHP code