JavaScript API Class: Data
The Data class is used to store and retrieve arbitrary text data by key. This allows EditMe applications that store non-page data, such as form submissions, etc. The "data" implicit variable is a special instance of this class that does not represent an actual data entry, but can be used to manage other data entries. Data entries are also instances of this class and share the same static functions as the implicit object.
Properties
| Name | Type | Access |
Description |
| keys | Array of Strings |
read |
Returns an array of all the keys existing for the entire site. Only 1000 keys can be returned at a time. See the getKeys(Number) function defined below for dealing with larger sets of keys. |
| key |
String | read/write |
Returns or sets the key for this data object. This is an instance property and cannot be called on the implicit "data" variable. |
| lines |
Array of Strings | read |
Returns an array of the lines in this data object's value. This is a shortcut for mydata.value.split('\n'); This is an instance property and cannot be called on the implicit "data" variable. |
| MAX_KEYS |
Number | read |
Returns the maximum number of keys that will be returned by a single call to getKeys(..). Currently, it returns 1000. This constant should be used to protect your code from possible changes to this number. |
| MAX_ENTRIES |
Number |
read |
Returns the maximum number of entries that will be returned by a single call to getEntries(..). Currently, it returns 500. This constant should be used to protect your code from possible changes to this number. |
| xml |
DOM4J Document | read/write |
Attempts to parse the value of this data object as XML and, if successful, returns a DOM4J Document object. If unsuccessful, a JavaScript error is thrown. This is an instance property and cannot be called on the implicit "data" variable. |
| value |
String |
read/write |
Gets or sets the value for this data object. This is an instance property and cannot be called on the implicit "data" variable. |
| id |
Number |
read |
This is the internal ID number used to store this data object. If 0, the data object does not exist. This is an instance property and cannot be called on the implicit "data" variable. |
Functions
| Name | Return Type |
Description |
| destroy() | none |
Permanently deletes this data object. This is an instance function and cannot be called on the implicit "data" variable. |
| get (String1) | Data entry | Returns a single entry associated with the key String1. If no match is found, returns null. |
| getById (Number) |
Data entry |
Returns a single entry associated with the ID Number. If no match is found, returns null. |
| getEntries() | Array of Data entries |
Shortcut for getEntries('', '', 0). See getEntries(String1, String2, Number) below for full details. |
| getEntries(Number) |
Array of Data entries | Shortcut for getEntries('', '', Number). See getEntries(String1, String2, Number) below for full details. |
| getEntries(String1, String2) | Array of Data entries | Shortcut for getEntries(String1, String2, 0). See getEntries(String1, String2, Number) below for full details. |
| getEntries(String1, String2, Number) | Array of Data entries | Returns an Array of up to 500 Data entries, optionally filtered the key's starting substring, a substring the key contains, and an offset. If String1 is not an empty string, only entries whose key starts with the value in String1 will be returned. If String2 is not an empty string, only entries with keys that contain the value in String2 will be returned. If Number is > 0, the first entry returned will be offset by the value in Number. |
| getKeys (Number) | Array of Strings | Returns up to 1000 keys starting from the offset defined by Number. For example, given a site with 1500 keys, data.keys would return the first 1000 keys. data.getKeys(1000) would return the last 500. |
| getKeys (String1, String2) | Array of Strings | Returns up to 1000 keys, filtered by what the keys start with and/or contain. If String1 is not an empty string, only keys beginning with String1 will be returned. If String2 is not an empty string, only keys containing String2 will be returned. Both, either or neither argument can be an empty string. |
| getKeys (String1, String2, Number) |
Array of Strings | This function behaves exactly like getKeys(String1, String2) except that the results are offset by the value in Number. This can be used for key queries that result in more than 1000 results. |
| newEntry() | Data entry | Returns a new, empty Data object. The entry is not actually created until .save() is called. A unique key must be set on the returned object before the entry can be saved. |
| save |
none |
Saves changes to an existing data object or creates a new data object if it does not exist. This is an instance function and cannot be called on the implicit "data" variable. |
| search (String1, String2) |
Array of Data entries |
Performs a full text search on data, optionally filtered by key prefix. If String1 is not an empty string, only data entries with keys starting with String1 will be returned. If String2 is not an empty string, only data entries with values matching the supplied search query will be returned. The data value full text search supports the same Boolean search query features as EditMe's site search. This function returns a maximum of 500 results. If more than 500 results exist, the search(String1, String2, Number) function can be used instead. |
| search (String1, String2, Number) |
Array of Data entries | This function behaves exactly like search(String1, String2) except that the results are offset by the value in Number. This can be used for key queries that result in more than 500 results. |
Example
This is a full page example that provides a browser for all the data defined on a site. You can add this to your site by creating a page with plain text editing enabled and the MIME type set to EditMe Scripted Page. Simply paste this content in and save. Be sure to set the security for the page to Administrator View/Adminstrator Edit.
A more robust implementation of this script is also available for easy installation as a Module.
<div>
<script type="text/vnd.editme.js">
// This page displays data entries in a simple
// table and provides paging for cases where
// more than 500 entries exist.
// get the offset specified on the query string
var offset = server.request('offset');
if (offset=='') offset = 0;
else offset = parseInt(offset);
// get the entries to display
var entries = data.getEntries(offset);
</script>
<!-- display a "Previous 500" link if necessary -->
<span editme="if offset > 0">
<a editme="parse href" href="/{page.name}?offset={offset-500}">Previous 500</a>
</span>
<!-- page navigation link divider -->
<span editme="if offset > 0 && entries.length==500"> | </span>
<!-- display a "Next 500" link if necessary -->
<span editme="if entries.length==500">
<a editme="parse href" href="/{page.name}?offset={offset+500}">Next 500</a>
</span>
<!-- simple table to display data entries -->
<span editme="if entries.length==0">No entries found.</span>
<table border="1" width="100%" cellspacing="0" cellpadding="3">
<tr editme="foreach entry entries">
<td valign="top"><b editme="text entry.key"></b></td>
<td valign="top"><span editme="text entry.value" style="font-size:80%;"></span></td>
</tr>
</table>
</div>
Return to Java Script API