Using the Framework object
This tutorial will introduce you to the framework interface. The framework is an object that is created for every DTX application. A DTX toolbar will have its own framework object. The framework holds the state of the DTX runtime and provides several utility functions. This tutorial will take you through some of them.
Creating Elements
The framework can be used to create new instances of elements on the fly. For instance, if you want to create a new toolbar button and append it to the toolbar, you may use the following example:
var newButton = mytoolbar.framework.createElement("toolbarbutton");
newButton.setAttribute("label", "Hello World")
mytoolbar.framework.mainContainer.appendChild(newButton);
The createElement() function takes the tag name of the element that you want to create as a parameter.
Also note that this example uses the “mainContainer” property in the framework. This property points to the main visual element in the DTX application. For a toolbar project, this would be the toolbar. Calling appendChild() on the toolbar adds the new button.
Locating elements
The framework can be used to locate elements based on their “id” attribute. The element may be anywhere in the DTX DOM. To do so, use the getElementById() function:
var element = mytoobar.framework.getElementById("mybutton");
Please note that every DTX element will also have a getElementById() function. The difference is that for elements, this function will only look in the direct children of the element. In some instances, this may be exactly what you want, so you should avoid calling the framework’s getElementById() instead. The performance would be much better in this case.
File Handling
The framework provides several basic functions to deal with files. To read from a file, use:
var fileContents = mytoolbar.framework.loadFile("test.txt");
The file path is relative to the user data folder. Locations outside will be ignored. The result is a string containing the contents of the file. In the same way, you can save to a file:
mytoolbar.framework.saveFile("test.txt", "HELLO WORLD!");
To read from the chrome folder use:
var fileContents = mytoolbar.framework.loadChromeFile("test.txt");
As with “loadFile”, the result will be a string with the contents of the file.
It is important to remember that the framework will not let you save to the chrome file, for that reason there is no “saveChromeFile” method in the framework.
XML support
It is likely that at some point you will need to handle XML. The framework provides some functions that will help you with that.
To create an XML Document Object Model out of a string you can use:
var xmlDoc = mytoolbar.framework.loadXML("<xyz>Hello</xyz>");
This will return a W3C-compliant interface to the XML document. This is a very convenient way to load the contents of a text file into a XML DOM.
To do the opposite, that is, obtain a string containing the contents of the XML out of an XML DOM you can use:
var xmlContents = mytoolbar.framework.serializeXML(xmlDoc);
Here “xmlDoc” is the XML DOM. It will return a string containing the XML Document serialized into tags and attributes. This function can help you save the contents of an XML DOM to a text file.
If you need to create a blank XML DOM you can use:
var xmlDoc = mytoolbar.framework.createXML();
This will return a blank W3C compliant XML DOM interface.
HTTP access
DTX applications can be built pretty much like regular AJAX applications. Your application will need to asynchronously interact with a HTTP server.
To create a W3C standard HTTP request object you may use the following example:
var httpReq = mytoolbar.framework.createHTTPRequest(
"http://www.mydomain.com/test.xml", "GET", true);
The createHTTPRequest() function takes three parameters:
- The URL for the request
- The HTTP verb for the request
- A Boolean value to indicate whether the request is asynchronous
These parameters are exactly the same as the one provided to the W3C open() method for the request. After calling createHTTPRequest() you may proceed using the object as specified by the W3C standard. Just keep in mind that the framework has already called the open() method for you.
In most cases you will be performing an asynchronous “GET”. The framework includes a function named download() to make this simpler for you:
mytoolbar.framework.download(
"http://www.mydomain.com/test.xml",
function(url, code, response) {
if (code == 200) {
alert(response);
}
});
The first parameter to download() is the URL you want to get. The second parameter is a function that will be called once the request is complete. This function takes three parameters: the URL so you can know which request it is, the HTTP response code, and the actual contents of the file, assuming the request was successful.
There is another advantage in using the download() function. Some browsers may limit the number of active HTTP requests to 2. If you send HTTP requests indiscriminately you may slow the browsing experience for the user. The download() function makes sure only one HTTP object is used at any time, even if you flood the framework with calls to the download function. The requests are queued and then processed as the single HTTP request object becomes available.
Timers and time-outs
If you need a function to run every time a given time interval has elapsed you may use the setInterval() function:
var intervalId = mytoolbar.framework.setInterval(
function() {
alert("10 seconds have elapsed!");
}, 10000);
The setInterval() function takes two parameters: a function that will be called when the interval has elapsed and the duration of the interval, in milliseconds. The function will return an ID that can be used to cancel the interval anytime later by calling the framework’s clearInterval() function and provide the ID returned by setInterval().
If you want the function called only once instead of periodically, you may use the setTimeout() function:
var timeoutId = mytoolbar.framework.setTimeout(
function() {
alert("10 seconds have elapsed!");
}, 10000);
This time the alert will show only once. If you want to cancel the timeout call before it has occurred, you may use the clearTimeout() function and provide the ID returned by setInterval() as a parameter.
