dojox/data/CsvStore (version 1.10)

Summary

The CsvStore implements the dojo/data/api/Read API and reads data from files in CSV (Comma Separated Values) format. All values are simple string values. References to other items are not supported as attribute values in this datastore.

Example data file: name, color, age, tagline Kermit, green, 12, "Hi, I'm Kermit the Frog." Fozzie Bear, orange, 10, "Wakka Wakka Wakka!" Miss Piggy, pink, 11, "Kermie!"

Note that values containing a comma must be enclosed with quotes ("") Also note that values containing quotes must be escaped with two consecutive quotes (""quoted"")

Usage

var foo = new CsvStore(keywordParameters);
dojox/data/CsvStore
Parameter Type Description
keywordParameters Object
  • url: String
  • data: String
  • label: String: The column label for the column to use for the label returned by getLabel.
  • identifier: String: The column label for the column to use for the identity. Optional. If not set, the identity is the row number.

See the dojox/data/CsvStore reference documentation for more information.

Examples

Example 1

var csvStore = new dojox.data.CsvStore({url:"movies.csv"); var csvStore = new dojox.data.CsvStore({url:"http://example.com/movies.csv");

Property Summary

  • identifierDeclarative hook for setting the identifier.
  • labelDeclarative hook for setting the label attribute.
  • separatorDeclatative and programmatic hook for defining the separator character used in the Csv style file.
  • urlDeclarative hook for setting Csv source url.
  • urlPreventCache

Method Summary

  • _assertIsItem(item) This function tests whether the item passed in is indeed an item in the store.
  • _containsValue(item,attribute,value,regexp) Internal function for looking at the values contained by the item.
  • _createItemFromIdentity(identity) Function for creating a new item from its identifier.
  • _fetchItems(keywordArgs,findCallback,errorCallback) See dojo.data.util.simpleFetch.fetch()
  • _getArrayOfArraysFromCsvFileContents(csvFileContents) Parses a string of CSV records into a nested array structure.
  • _getIndex(item) Internal function to get the internal index to the item data from the item handle
  • _handleQueuedFetches() Internal function to execute delayed request in the store.
  • _processData(data) Function for processing the string data from the server.
  • _splitLines(csvContent) Function to split the CSV file contents into separate lines.
  • close(request) See dojo/data/api/Read.close()
  • containsValue(item,attribute,value) See dojo/data/api/Read.containsValue()
  • errorHandler(errorData,requestObject) The error handler when there is an error fetching items.
  • fetch(request) The simpleFetch mixin is designed to serve as a set of function(s) that can be mixed into other datastore implementations to accelerate their development.
  • fetchHandler(items,requestObject) The handler when items are successfully fetched.
  • fetchItemByIdentity(keywordArgs) See dojo/data/api/Identity.fetchItemByIdentity()
  • getAttributes(item) See dojo/data/api/Read.getAttributes()
  • getFeatures() See dojo/data/api/Read.getFeatures()
  • getIdentity(item) See dojo/data/api/Identity.getIdentity()
  • getIdentityAttributes(item) See dojo/data/api/Identity.getIdentifierAttributes()
  • getLabel(item) See dojo/data/api/Read.getLabel()
  • getLabelAttributes(item) See dojo/data/api/Read.getLabelAttributes()
  • getValue(item,attribute,defaultValue) See dojo/data/api/Read.getValue() Note that for the CsvStore, an empty string value is the same as no value, so the defaultValue would be returned instead of an empty string.
  • getValues(item,attribute) See dojo/data/api/Read.getValues() CSV syntax does not support multi-valued attributes, so this is just a wrapper function for getValue().
  • hasAttribute(item,attribute) See dojo/data/api/Read.hasAttribute() The hasAttribute test is true if attribute has an index number within the item's array length AND if the item has a value for that attribute.
  • isItem(something) See dojo/data/api/Read.isItem()
  • isItemLoaded(something) See dojo/data/api/Read.isItemLoaded() The CsvStore always loads all items, so if it's an item, then it's loaded.
  • loadItem(item) See dojo/data/api/Read.loadItem()

Properties

identifier
Defined by: dojox/data/CsvStore

Declarative hook for setting the identifier.

label
Defined by: dojox/data/CsvStore

Declarative hook for setting the label attribute.

separator
Defined by: dojox/data/CsvStore

Declatative and programmatic hook for defining the separator character used in the Csv style file.

url
Defined by: dojox/data/CsvStore

Declarative hook for setting Csv source url.

urlPreventCache
Defined by: dojox/data/CsvStore

Methods

_assertIsItem(item)
Defined by dojox/data/CsvStore

This function tests whether the item passed in is indeed an item in the store.

Parameter Type Description
item item

The item to test for being contained by the store.

_containsValue(item,attribute,value,regexp)
Defined by dojox/data/CsvStore

Internal function for looking at the values contained by the item.

Internal function for looking at the values contained by the item. This function allows for denoting if the comparison should be case sensitive for strings or not (for handling filtering cases where string case should not matter)

Parameter Type Description
item item

The data item to examine for attribute values.

attribute attribute | attribute-name-string

The attribute to inspect.

value anything

The value to match.

regexp RegExp
Optional

Optional regular expression generated off value if value was of string type to handle wildcarding. If present and attribute values are string, then it can be used for comparison instead of 'value'

Returns:boolean
_createItemFromIdentity(identity)
Defined by dojox/data/CsvStore

Function for creating a new item from its identifier.

Parameter Type Description
identity String

The identity

Returns:object
_fetchItems(keywordArgs,findCallback,errorCallback)
Defined by dojox/data/CsvStore

See dojo.data.util.simpleFetch.fetch()

Parameter Type Description
keywordArgs Object
findCallback Function
errorCallback Function
_getArrayOfArraysFromCsvFileContents(csvFileContents)
Defined by dojox/data/CsvStore

Parses a string of CSV records into a nested array structure.

Given a string containing CSV records, this method parses the string and returns a data structure containing the parsed content. The data structure we return is an array of length R, where R is the number of rows (lines) in the CSV data. The return array contains one sub-array for each CSV line, and each sub-array contains C string values, where C is the number of columns in the CSV data.

Parameter Type Description
csvFileContents string

Examples

Example 1

For example, given this CSV string as input:

"Title, Year, Producer \n Alien, 1979, Ridley Scott \n Blade Runner, 1982, Ridley Scott"

this._dataArray will be set to:

[["Alien", "1979", "Ridley Scott"],
["Blade Runner", "1982", "Ridley Scott"]]

And this._attributes will be set to:

["Title", "Year", "Producer"]

And this._attributeIndexes will be set to:

{ "Title":0, "Year":1, "Producer":2 }
_getIndex(item)
Defined by dojox/data/CsvStore

Internal function to get the internal index to the item data from the item handle

Parameter Type Description
item undefined

The idem handle to get the index for.

Returns:undefined
_handleQueuedFetches()
Defined by dojox/data/CsvStore

Internal function to execute delayed request in the store.

_processData(data)
Defined by dojox/data/CsvStore

Function for processing the string data from the server.

Parameter Type Description
data String

The CSV data.

_splitLines(csvContent)
Defined by dojox/data/CsvStore

Function to split the CSV file contents into separate lines. Since line breaks can occur inside quotes, a Regexp didn't work as well. A quick passover parse should be just as efficient.

Parameter Type Description
csvContent undefined
Returns:Array
close(request)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.close()

Parameter Type Description
request dojo/data/api/Request | Object
Optional
containsValue(item,attribute,value)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.containsValue()

Parameter Type Description
item item
attribute attribute | attribute-name-string
value anything
Returns:undefined
errorHandler(errorData,requestObject)

The error handler when there is an error fetching items. This function should not be called directly and is used by simpleFetch.fetch().

Parameter Type Description
errorData Object
requestObject Object
fetch(request)

The simpleFetch mixin is designed to serve as a set of function(s) that can be mixed into other datastore implementations to accelerate their development.

The simpleFetch mixin should work well for any datastore that can respond to a _fetchItems() call by returning an array of all the found items that matched the query. The simpleFetch mixin is not designed to work for datastores that respond to a fetch() call by incrementally loading items, or sequentially loading partial batches of the result set. For datastores that mixin simpleFetch, simpleFetch implements a fetch method that automatically handles eight of the fetch() arguments -- onBegin, onItem, onComplete, onError, start, count, sort and scope The class mixing in simpleFetch should not implement fetch(), but should instead implement a _fetchItems() method. The _fetchItems() method takes three arguments, the keywordArgs object that was passed to fetch(), a callback function to be called when the result array is available, and an error callback to be called if something goes wrong. The _fetchItems() method should ignore any keywordArgs parameters for start, count, onBegin, onItem, onComplete, onError, sort, and scope. The _fetchItems() method needs to correctly handle any other keywordArgs parameters, including the query parameter and any optional parameters (such as includeChildren). The _fetchItems() method should create an array of result items and pass it to the fetchHandler along with the original request object -- or, the _fetchItems() method may, if it wants to, create an new request object with other specifics about the request that are specific to the datastore and pass that as the request object to the handler.

For more information on this specific function, see dojo/data/api/Read.fetch()

Parameter Type Description
request Object
Optional

The keywordArgs parameter may either be an instance of conforming to dojo/data/api/Request or may be a simple anonymous object that may contain any of the following:

{
    query: query-object or query-string,
    queryOptions: object,
    onBegin: Function,
    onItem: Function,
    onComplete: Function,
    onError: Function,
    scope: object,
    start: int
    count: int
    sort: array
}

All implementations should accept keywordArgs objects with any of

the 9 standard properties: query, onBegin, onItem, onComplete, onError scope, sort, start, and count. Some implementations may accept additional properties in the keywordArgs object as valid parameters, such as {includeOutliers:true}.

The query parameter

The query may be optional in some data store implementations. The dojo/data/api/Read API does not specify the syntax or semantics of the query itself -- each different data store implementation may have its own notion of what a query should look like. However, as of dojo 0.9, 1.0, and 1.1, all the provided datastores in dojo.data and dojox.data support an object structure query, where the object is a set of name/value parameters such as { attrFoo: valueBar, attrFoo1: valueBar1}. Most of the dijit widgets, such as ComboBox assume this to be the case when working with a datastore when they dynamically update the query. Therefore, for maximum compatibility with dijit widgets the recommended query parameter is a key/value object. That does not mean that the the datastore may not take alternative query forms, such as a simple string, a Date, a number, or a mix of such. Ultimately, The dojo/data/api/Read API is agnostic about what the query format.

Further note: In general for query objects that accept strings as attribute value matches, the store should also support basic filtering capability, such as (match any character) and ? (match single character). An example query that is a query object would be like: { attrFoo: "value"}. Which generally means match all items where they have an attribute named attrFoo, with a value that starts with 'value'.

The queryOptions parameter

The queryOptions parameter is an optional parameter used to specify options that may modify the query in some fashion, such as doing a case insensitive search, or doing a deep search where all items in a hierarchical representation of data are scanned instead of just the root items. It currently defines two options that all datastores should attempt to honor if possible:

{
    ignoreCase: boolean, // Whether or not the query should match case sensitively or not.  Default behaviour is false.
    deep: boolean   // Whether or not a fetch should do a deep search of items and all child
                    // items instead of just root-level items in a datastore.  Default is false.
}

The onBegin parameter.

function(size, request); If an onBegin callback function is provided, the callback function will be called just once, before the first onItem callback is called. The onBegin callback function will be passed two arguments, the the total number of items identified and the Request object. If the total number is unknown, then size will be -1. Note that size is not necessarily the size of the collection of items returned from the query, as the request may have specified to return only a subset of the total set of items through the use of the start and count parameters.

The onItem parameter.

function(item, request);

If an onItem callback function is provided, the callback function will be called as each item in the result is received. The callback function will be passed two arguments: the item itself, and the Request object.

The onComplete parameter.

function(items, request);

If an onComplete callback function is provided, the callback function will be called just once, after the last onItem callback is called. Note that if the onItem callback is not present, then onComplete will be passed an array containing all items which matched the query and the request object. If the onItem callback is present, then onComplete is called as: onComplete(null, request).

The onError parameter.

function(errorData, request);

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 query. The onError callback function will be passed two arguments: an Error object and the Request object.

The scope parameter.

If a scope object is provided, all of the callback functions (onItem, onComplete, onError, etc) will be invoked in the context of the scope object. In the body of the callback function, the value of the "this" 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, onItem.call(scope, item, request) vs. onItem.call(dojo.global(), item, request)

The start parameter.

If a start parameter is specified, this is a indication to the datastore to only start returning items once the start number of items have been located and skipped. When this parameter is paired with 'count', the store should be able to page across queries with millions of hits by only returning subsets of the hits for each query

The count parameter.

If a count parameter is specified, this is a indication to the datastore to only return up to that many items. This allows a fetch call that may have millions of item matches to be paired down to something reasonable.

The sort parameter.

If a sort parameter is specified, this is a indication to the datastore to sort the items in some manner before returning the items. The array is an array of javascript objects that must conform to the following format to be applied to the fetching of items:

{
    attribute: attribute || attribute-name-string,
    descending: true|false;   // Optional.  Default is false.
}

Note that when comparing attributes, if an item contains no value for the attribute

(undefined), then it the default ascending sort logic should push it to the bottom of the list. In the descending order case, it such items should appear at the top of the list.

fetchHandler(items,requestObject)

The handler when items are successfully fetched. This function should not be called directly and is used by simpleFetch.fetch().

Parameter Type Description
items Array
requestObject Object
fetchItemByIdentity(keywordArgs)
Defined by dojox/data/CsvStore

See dojo/data/api/Identity.fetchItemByIdentity()

Parameter Type Description
keywordArgs Object
getAttributes(item)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.getAttributes()

Parameter Type Description
item item
Returns:Array
getFeatures()
Defined by dojox/data/CsvStore

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

Returns:undefined
getIdentity(item)
Defined by dojox/data/CsvStore

See dojo/data/api/Identity.getIdentity()

Parameter Type Description
item item
Returns:undefined | null
getIdentityAttributes(item)
Defined by dojox/data/CsvStore

See dojo/data/api/Identity.getIdentifierAttributes()

Parameter Type Description
item item
Returns:Array | null
getLabel(item)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.getLabel()

Parameter Type Description
item item
Returns:undefined
getLabelAttributes(item)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.getLabelAttributes()

Parameter Type Description
item item
Returns:Array | null
getValue(item,attribute,defaultValue)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.getValue() Note that for the CsvStore, an empty string value is the same as no value, so the defaultValue would be returned instead of an empty string.

Parameter Type Description
item item
attribute attribute | attribute-name-string
defaultValue value
Optional
Returns:undefined
getValues(item,attribute)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.getValues() CSV syntax does not support multi-valued attributes, so this is just a wrapper function for getValue().

Parameter Type Description
item item
attribute attribute | attribute-name-string
Returns:Array
hasAttribute(item,attribute)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.hasAttribute() The hasAttribute test is true if attribute has an index number within the item's array length AND if the item has a value for that attribute. Note that for the CsvStore, an empty string value is the same as no value.

Parameter Type Description
item item
attribute attribute-name-string
Returns:boolean
isItem(something)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.isItem()

Parameter Type Description
something anything
Returns:boolean
isItemLoaded(something)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.isItemLoaded() The CsvStore always loads all items, so if it's an item, then it's loaded.

Parameter Type Description
something anything
Returns:undefined
loadItem(item)
Defined by dojox/data/CsvStore

See dojo/data/api/Read.loadItem()

The CsvStore always loads all items, so if it's an item, then it's loaded.

From the dojo/data/api/Read.loadItem docs: 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.

Parameter Type Description
item item
Error in the documentation? Can’t find what you are looking for? Let us know!