Important note: The Javascript API for submitting data to your database is currently disabled on most databases. (It remains enabled for reading data.) We no longer recommend using the API for submitting data. Instead, please try using the Pages feature, which allows you to build forms without any coding. Pages forms can also be used to submit data programattically. For additional information, visit the User’s forum or contact us.
The purpose of this interface is to enable Dabble applications to be integrated with external websites. To activate it, log into your application and go to Sharing at the pop of the page. Under the Schema tab you will find a link to your application’s schema, and the access key.
(Note: Under the Users tab, there is also a checkbox, Allow public access to exports, which must be checked if you want to display entries on another website, or if you want to include lists of entries in a data entry form.)
Data in a Dabble application is organized according to the schema defined for that application. The schema contains a list of fields, which are grouped into categories. Each field has a name and a type, such as Text, or Number. It’s possible for an entry to have more than one category, so any field in the schema can appear on an entry form.
As an example, let’s consider a Library application, one we might use to catalog a collection of books. The schema might look something like this:
The administrator of a Dabble application can export its schema in JSON format, so that it can be loaded into an HTML document via a <script> tag. As an example, the JSON export for the schema above is available:
Notice that that the schema object is passed as an argument to Dabble.addSchema(). This means that the Dabble API script, which creates the global Dabble, must already be loaded into the page. The API script is located at the following URL:
http://www.dabbledb.com/js/api.js
Another thing to notice about the schema is that all its objects have unique identifiers. These are used when building the form, so that fields with the same name but different categories can be correctly identified.
Once the schema is loaded, creating a form input for a given field is easy. Let’s use the Author category from our Book application as an example. An input for the Name field can be created like this:
<script type="text/javascript">Dabble.field(86).writeInput();</script>
This is a snippet of Javascript, wrapped in a script tag, which generates the form input required to enter the name of an author. It executes as the page is loading.
The first bit of the script is a call to the field() method of the Dabble object to fetch field number 86 out of the schema. (In this example, the Name field has an id of 86.) We then call writeInput(), which appends the form input to the end of the partially loaded document.
In order to create a usable entry form, we also need to attach labels to the inputs, so that the user knows what to enter. The most “correct” way to do this is with a <label> tag:
<label for="dabble-input-86">Name</label>
Notice the for attribute. All writeInput() methods will add an id attribute on the inputs it creates that follow the same pattern: dabble-input-<field id>. This makes it easy to refer to the input by id, whether from the <label> tag, CSS or Javascript.
We can also generate the above label automatically, using a script like this:
<script type="text/javascript">Dabble.field(86).writeLabel()</script>
This will ensure that the labels always match the application schema. If a field is renamed, the labels will be updated to match.
The last thing required is a submit button. This is created by calling Dabble.writeSubmit():
<script type="text/javascript">Dabble.writeSubmit('Add Author', 'http://www.example.com/thanks');</script>
The first argument is a label for the submit button, while the second is the URL to which the server should redirect after the data has been successfully submitted. Both arguments are optional. If the second argument is omitted, the browser will be redirected back to the form page. If the first argument is omitted, or null, the button will be simply labelled Submit.
Putting these pieces together, we can create a simple form for entering new authors into the Library application:
<script src="json-api.js" language="javascript"></script>
<script src="schema.js" language="javascript"></script>
<form class="dabble-form">
<div>
<script type="text/javascript">Dabble.field(86).writeLabel()</script>
<span><script type="text/javascript">Dabble.field(86).writeInput()</script></span>
</div>
<div>
<script type="text/javascript">Dabble.field(88).writeLabel()</script>
<span><script type="text/javascript">Dabble.field(88).writeInput()</script></span>
</div>
<div class="spacer"> </div>
<span>
<script type="text/javascript">Dabble.writeSubmit('Add Author', 'http://www.example.com/thanks');</script>
</span>
</form>
Another thing we can do with Dabble’s Javascript API is display data. In order to give application administrators control over what data they expose to the outside world, the forms API relies on views defined in the application, and made public via JSON export.
The JSON export of the Authors category might look something like this:
Dabble.addView({
_class: 'View',
id: 'e63a411d-7cbb-4399-9b65-37cfee8546e3',
name: 'Authors',
fields: [88],
entries: [
{_name: 'Homer', _id: 45, country: 'Greece'},
{_name: 'Margaret Atwood', _id: 95, country: 'Canada'},
{_name: 'James Joyce', _id: 44, country: 'Ireland'}
]
});
Again, the view is passed as an argument to Dabble.addView(), so that many views can be included on the same page using <script> tags. Creating a table with this data is simple:
<script type="text/javascript">Dabble.view('Authors').writeTable()</script>
This will produce the following HTML:
<table id="dabble-view-e63a411d-7cbb-4399-9b65-37cfee8546e3" class="dabble-table">
<tbody>
<tr id="dabble-entry-45" class="dabble-row dabble-row-odd">
<td class="dabble-cell dabble-field-name dabble-type-text">Homer</td>
<td class="dabble-cell dabble-field-88 dabble-type-89 dabble-type-text">Greece</td>
</tr>
<tr id="dabble-entry-95" class="dabble-row dabble-row-even">
<td class="dabble-cell dabble-field-name dabble-type-text">Margaret Atwood</td>
<td class="dabble-cell dabble-field-88 dabble-type-89 dabble-type-text">Canada</td>
</tr>
<tr id="dabble-entry-44" class="dabble-row dabble-row-odd">
<td class="dabble-cell dabble-field-name dabble-type-text">James Joyce</td>
<td class="dabble-cell dabble-field-88 dabble-type-89 dabble-type-text">Ireland</td>
</tr>
</tbody>
</table>
The view is rendered as a simple table:
Homer Greece Margaret Atwood Canada James Joyce Ireland
Each element has a class attribute specified, so that they can be easily styled via CSS. writeTable() generates this table by examining the view named Authors.
First it creates a table, and gives the element and id based on the id of ‘Authors’. Then it creates a row for each entry in the view. It gives the row element an id based on the id of the entry. Each row contains a table cell for each field in the entry. The cell classes are set based on the type of its field, and the cell contents are formatted by the field.
While a table is the natural way to display a view, it’s also possible to create other renderings of the same data. For example, the following code displays the view in a simple textual format:
<script type="text/javascript">
var entries = Dabble.view('Books').entries;
for (var i=0; i<entries.length; i++)
{
document.write('<p>');
var size = entries[i].fields.length;
for (var j=0; j<size; j++)
{
entries[i].writeFieldName(j);
document.write(': ');
entries[i].writeValue(j);
document.write("<br />\n");
}
document.write('</p>')
}
</script>
The most important parts of this snippet are the calls to writeFieldName() and writeValue(). Both take an integer as argument, and they write the name and value of the indicated field into the document using document.write(). Given the view data above, the resulting HTML looks like this:
<p>
Author: James Joyce<br />
Binding: Hardcover<br />
Pages: 237<br />
Price: 34.99 USD<br />
Tags: irish, fiction<br />
Published: September 1915<br />
</p>
<p>
Author: Homer<br />
Binding: Paperback<br />
Pages: 537<br />
Price: 3000.00 USD<br />
Tags: classical, mythology<br />
Published: September 16, 2006 3:00 am<br />
</p>
<p>
Author: Homer<br />
Binding: Paperback<br />
Pages: 137<br />
Price: 12.00 USD<br />
Tags: classical, greek, mythology<br />
Published: December 12, 1972<br />
</p>
On a web page, the output would appear like this:
Author: James Joyce
Binding: Hardcover
Pages: 237
Price: 34.99 USD
Tags: irish, fiction
Published: September 1915Author: Homer
Binding: Paperback
Pages: 537
Price: 3000.00 USD
Tags: classical, mythology
Published: September 16, 2006 3:00 amAuthor: Homer
Binding: Paperback
Pages: 137
Price: 12.00 USD
Tags: classical, greek, mythology
Published: December 12, 1972
The form-building code in the first section of this guide is sufficient for most types of data, but not all. For Link and List fields, more information is required. Links and Lists are references to other entries, and therefor should be rendered in a way that allows the user to select from a list of options. However, this has security implications as it exposes data to a user who has not logged into the Dabble application.
In our Library example, the Book category has both a link and a list. The field Author is a link from the book to its Author. When rendering the form input, we want to present a list of Authors for the user to choose from, so we pass a view as an argument to the writeInput() method:
<script type="text/javascript">Dabble.field(48).writeInput(Dabble.view('Authors'));</script>
We can do the same with the Tags field. The complete form for entering a book looks like this:
<script src="json-api.js" type="text/javascript"></script>
<script src="schema.js" type="text/javascript"></script>
<script src="authors.js" type="text/javascript"></script>
<script src="tags.js" type="text/javascript"></script>
<div class="form">
<form class="dabble-form">
<div>
<script type="text/javascript">Dabble.field(76).writeLabel();</script>
<span><script type="text/javascript">Dabble.field(76).writeInput()</script></span>
</div>
<div>
<script type="text/javascript">Dabble.field(48).writeLabel();</script>
<span><script type="text/javascript">Dabble.field(48).writeInput(Dabble.view('Authors'))</script></span>
</div>
<div>
<script type="text/javascript">Dabble.field(78).writeLabel();</script>
<span><script type="text/javascript">Dabble.field(78).writeInput()</script></span>
</div>
<div>
<script type="text/javascript">Dabble.field(80).writeLabel();</script>
<span><script type="text/javascript">Dabble.field(80).writeInput()</script></span>
</div>
<div>
<script type="text/javascript">Dabble.field(82).writeLabel();</script>
<span><script type="text/javascript">Dabble.field(82).writeInput()</script></span>
</div>
<div>
<script type="text/javascript">Dabble.field(84).writeLabel();</script>
<span><script type="text/javascript">Dabble.field(84).writeInput()</script></span>
</div>
<div>
<script type="text/javascript">Dabble.field(68).writeLabel();</script>
<span><script type="text/javascript">Dabble.field(68).writeInput(Dabble.view('Tags'))</script></span>
</div>
<div class="spacer"> </div>
<span>
<script type="text/javascript">Dabble.writeSubmit('Add Book', 'http://www.example.com/thanks');</script>
</span>
</form>
</div>
You can use cascading style sheets (CSS) to control the visual appearance of elements served with the API. For example, the <form> tag used on the input form will always have the CSS class of dabble-form, so you can use this to change the font, color or layout. Each element used to enter or select a value also has a class (e.g. dabble-type-datetime for date and time fields), and an ID that corresponds to the internal identifier number of the field. (The identifier is written in the schema.)
If you use the Dabble.writeTable() method to display a table view, there are also class names provided for the table, even and odd table rows, and each table cell.
Note that some elements may have multiple class names. For example, every table row will have the class dabble-row and either dabble-row-even or dabble-row-odd depending on whether its an even or odd row.
So, as an example, you could use the following CSS rules to alternate the background color of table rows:
tr.dabble-row-odd { background-color: #FFFFFF; }
tr.dabble-row-even { background-color: #EEEEEE; }
In the tables below, <view id>, <entry id> and <field id> in the class or ID name denotes the unique identifying number of, respectively, a view, entry, or field in the schema.
| Element | Tag name | Class name | ID name |
|---|---|---|---|
| The form container | <form> |
dabble-form |
None |
| All fields | (as below) | dabble-field-<field id> |
dabble-input-<field id> |
| Text fields (1 line) | <input> |
dabble-type-text |
|
| Text fields (2+ lines) | <textarea> |
dabble-type-text |
|
| Number fields | <input> |
dabble-type-number |
|
| Money fields | <input> |
dabble-type-money |
|
| Date and time fields | <input> |
dabble-type-datetime |
|
| Location fields | <input> |
dabble-type-location |
|
| Choice fields | <select> |
dabble-type-choice |
|
| Link fields | <select> |
dabble-type-link |
|
| List fields | <select> |
dabble-type-list |
| Element | Tag name | Class name | ID name |
|---|---|---|---|
| The table | <table> |
dabble-table |
dabble-view-<view id> |
| All table rows | <tr> |
dabble-row |
dabble-entry-<entry id> |
| Odd table rows (1st, 3rd, etc.) | <tr> |
dabble-row-odd |
|
| Even table rows (2nd, 4th, etc.) | <tr> |
dabble-row-even |
|
| All table cells | <td> |
dabble-cell |
|
| Table cells with field names | <td> |
dabble-field-name |
|
| Table cells with field values | <td> |
dabble-field-<field id> |
|
| Text fields (1 line) | <td> |
dabble-type-text |
|
| Text fields (2+ lines) | <td> |
dabble-type-text |
|
| Number fields | <td> |
dabble-type-number |
|
| Money fields | <td> |
dabble-type-money |
|
| Date and time fields | <td> |
dabble-type-datetime |
|
| Location fields | <td> |
dabble-type-location |
|
| Choice fields | <td> |
dabble-type-choice |
|
| Link fields | <td> |
dabble-type-link |
|
| List fields | <td> |
dabble-type-list |