The dojox.data.FileStore is a lightweight javascript implementation for accessing details about a remote FileSystem. This includes being able to search the filesystem to locate file names, display path information, file sizes, if it’s a directory or not, and if a directory, what children files are contained within it. The dojox.data.FileStore is also an excellent example of how DataStores can do lazy-loading.

The datastore implementation and its example PHP back-end by default do not inflate the child file objects of a DataStore file item. This allows it to quickly return information about a file without having to return everything, while at the same time providing hooks that allow for the extra information to be gathered on-demand.

A deliberately simple client side implementation for use as a reference when implementing other server side stores that wish to provide lazy-loading as defined by the dojo.data.api.Read spec. The client code is deliberately small to make it easy to understand.

The ability to search across a variety of attributes, such as name, path, parentDir, lastModified, etc. It also allows for matching on multiple fields, such as all files with parentDir of ‘foo’, that have filename: ‘bar*.js’.

The datastore can do shallow searching (root dir only), or recursive searching (scan the entire file system for matches across the parameters).

The client store can directly access information about a specific about a file through RESTlike patterns that work well with servlets that allow mapping of a context root to a servlet, and the servlet’s ability to get extra path information. It can also work with back-end services like PHP that do not provide a mechanism to do URL path based queries by converting the path into a query param, ‘path’. This is enabled by setting pathAsQueryParam to true on the store instance.

Support for all normal query options as defined by the dojo.data.api.Read specification. Deep provides recursive tree searching, ignoreCase provides the ability to ignore the case sensitivity of attributes when matching, and so on.

An example implementation of the back end service in PHP. The example is documented cleanly and is less than five hundred lines of code, making it relatively easy to dissect and understand.

All items returned by a query to the FileStore and will generally have the following attributes accessible via FileStore.getValue(item, attribute) and FileStore.getValues(item, attribute):

Attribute

Description

Type

name

The name of the file. This does not include any path information.

string

path

The full path to the file, including its name.
Note: In the context of dojo.data.api.Identity, this is the identifier

string

parentDir

The parent directory name.

string

size

The size of the file, in bytes.

integer

directory

A Boolean value indicating if the file referenced is a directory or not.

boolean

children

If it is a directory, then children is an array of child files contained within the directory. By
default these will be uninflated datastore items. Meaning isItem() returns true, but isItemLoaded()
returns false. To load the item, it is a call to the FileStore.loadItem() api with the appropriate
callbacks. By not inflating child files by default the store performance is greatly improved, as if you
don’t care about its children, you don’t have to load them. Should be accessed by the multivalue
getValues() accessor.

array

modified

An integer indicating the last modified date. This is the file timestamp from the system

The dojox.data.FileStore query structure follows that of dojo.data.ItemFileReadStore. It is an object-based query structure where the store queries for file items using patterns defined for the attributes to be matched. For example a query object of:

{name:"foo*.txt"}

would return all files that have the name foo at the start of the name and end with the extension .txt.

Please note that the store is a hierarchical store and if you wish to query the entire file system (not just the root of it), for a file name, you must set the standard dojo.data.api.Read queryOption 'deep' to the value true.

Using the dojox.dataFileStore is generally simple. The store takes three possible constructor options which can also be declared in markup. These options configure the store and its operating behavior. The options are defined below in a table.

Constructor param

Description

Type

url

The URL of the service that provides the server-side implementation that processes the queries
returns the results. Note that because of the same origin policy of the browser, the service
must reside in the same domain as the loaded page. To access urls outside of the domain, you
must use a proxy. This parameter is required

string

pathAsQueryParam

This parameter alters the behavior of the dojo.data.api.Identity functions. By default it is
false. When it is false, any request for the information of a single file theough a
fetchItemByIdentity call (and internally by loadItem), the url used is restful. This means the
url request will look like:

http://<server>/<service>/some/file.

It is effectively url-pathing to represent the file.

This is convenient for services implemented in a java servlet. For implementations that are
not convenient to work this way, such as php, you would want to set the option to true. When
is set to true, the path to the file becomes a query parameter. An example is:

http://<server>/<service>?path=some/file

boolean

options

This is a comma separated list of options that dojox.data.FileStore will pass to the service as
a JSON encoded string array. These options can be used to configure certain behaviors of the
dojox.data.FileStore. The example PHP implementation provided in demos supports the following

expand: This option instructs the store to inflate all child files of a directory so that
lazy-loading through isItemLoaded() and loadItem() is not necessary. This options is
expensive to use and not recommended. For large file systems, using this option can generate
huge returns. This option is not recommended for use, but is provided as convenience
for small file systems and debug purposes.

showHiddenFiles: This option enables returning information about hidden files. By default
the example implementation does not display hidden files. Note that a hidden file follows UNIX
of starting with a '.' character.

dirsOnly: Only return file entries that are directories. This option is useful for
a directory tree display.

string

urlPreventCache

Flag to denote if preventCache should be appended to underlying xhrGet calls. Default is true
New in Dojo 1.4

boolean

Some usage examples for using the service in code as well as declarative markup attaching it to a widget such as dijit.Tree, dijit.form.ComboBox, and dojox.grid.DataGrid are shown below.

Attaching it as the datastore for a widget works the same as it would for any widget. For example, using it to front a dijit Tree is shown below. In the following example, dijit.Tree is being rooted so that it displays the entire dojo source tree:

The following section is not necessary to fully understand how to just use the existing dojox.data.FileStore back end implementation, it is intended for people who wish to implement their own back end service in another language, such as python or java.