An Add-On involves four different types of files:
- One XML manifest
- One HTML file that sets up the initial display
- Zero or more CSS files
The XML Manifest
Here is a sample manifest file:
From the general user’s perspective your XML manifest “is” your program. It’s the URL they provide to Heap when they install the Add-On.
The HTML File
The HTML file sets up the basic structure within the “api” divs within Heap (the white content area). You should not, therefore, include a header, body or other wrapper tags.
What you can do in the HTML section is entirely up to you. However, to avoid confusion, you should only use names, ids and classes that start with “api_”. This is a reserved space within Heap and will guarantee that there is no conflicts now or in the future.
When doing an AJAX call: Because of security reasons, browsers don’t allow you to directly access files from a different domain. Instead you must use the following function.
YData_GetURL(url, Callback Function)
YData_GetURL will use the content type sent by your server to either provide it as plain text or XML to the callback function. Please note, YData_GetURL will timeout after 10 seconds.
To save something for later use (either in the same session or at a later date or even from a different user) you need persistent storage. The Heap API provides four functions for this purpose:
HData_PutData(key, value, Callback Function) HData_PutUserData(key, value, Callback Function) HData_GetData(key, Callback Function) HData_GetUserData(key, Callback Function)
The “key” is a case-insensitive string (up to 254 characters long). When you wish to save data you “Put” it. If successful, your callback function will be sent a “true” otherwise it will receive “false.” If you “Put” a key that already exists, the existing data will be overwritten by the data you supplied.
When you are retrieving data you “Get” it. If successful your callback function will receive the data (otherwise it will receive an empty string).
The difference between the “User” data and the standard functions is scope. HData_PutData and HData_GetData apply to the entire sub-domain (i.e. the data can be set by one user and retrieved by another). HData_PutUserData and HData_GetUserData apply only to the logged in user.
When you wish to receive a list of items your “List” them. These four functions will provide a a multidimensional array where each row is a result and within each row there is an associative array with a “key” and a “title” (provided to the callback function).
HData_ListMessages('Search Term', Callback Function) HData_ListPeople('Search Term', Callback Function) HData_ListEvents('Search Term', Callback Function) HData_ListLOCA('Search Term', Callback Function)
You can do exactly the same advanced searches here as you can within Heap. For information on operators, bucket selectors and more, please refer to http://heap.wbpsystems.com/find.php.
Once you have found the record you wish to inspect you can use the “key” to retrieve it.
HData_GetMessage(key, Callback Function) HData_GetPerson(key, Callback Function) HData_GetEvent(key, Callback Function) HData_GetLOCA(key, Callback Function)
The callback function will receive an associative array with key names appropriate to each record (you can use Firebug to dump an array, which is very helpful when developing).
When you want to create a record, you use the following functions:
HData_CreateMessage(Associative Array, Callback Function) HData_CreatePerson(Associative Array, Callback Function) HData_CreateEvent(Associative Array, Callback Function) HData_CreateLOCA(Associative Array, Callback Function)
These functions are the exact inverse of the HData_Get* functions. The array you provide the HData_Create* function should have identical keys to the one provided to you by HData_Get*.
The following functions are used to update a record:
HData_UpdateMessage(key, Associative Array, Callback Function) HData_UpdatePerson(key, Associative Array, Callback Function) HData_UpdateEvent(key, Associative Array, Callback Function) HData_UpdateLOCA(key, Associative Array, Callback Function)
These functions are identical to HData_Create*, except you must also provide the key of the record you wish to update.
The following functions are used to delete a record:
HData_DeleteMessage(key, Callback Function) HData_DeletePerson(key, Callback Function) HData_DeleteEvent(key, Callback Function) HData_DeleteLOCA(key, Callback Function)
HData_ListMessageCategories(Callback Function) HData_ListPeopleCategories(Callback Function) HData_ListCalendars(Callback Function)