TextAmerica Javascript XMLHttpRequest Bindings Library </head> <body bgcolor="#FFFFFF"> <h1>TextAmerica Javascript XMLHttpRequest Bindings Library</h1> Get the Javascript source code <a href="http://www.darklilac.com/textamerica.zip">here</a>.<br> This document covers use of the TextAmerica XML Javascript library for accessing XML based services provided by the TextAmerica website. There are two primary applications of this library, AJAX and Mozilla/Firefox based extensions. Since browsers limit XMLHttpRequests from the originating server, using it in an webpage will require that page to be served by http://xml.api.textamerica.com. The way around this restriction involves creating a Mozilla or Firefox extension which allows the developer to work around this restriction. An obvious advantage of Javascript over other languages is the ability to run within a web browser. <br> <h2>Application Integration</h2> The TextAmerica server returns XML for each call. Since this string is difficult to parse, particularly for each different XML string, using the Xparse library makes it easier to pull the desired data out of the XML string. See the section on Xparse below for more information. To integrate the TextAmerica Javascript XMLHttpRequest bindings library into your application, you must first include two Javascript files into your document: If writing a Firefox extension, something like: <pre> <script type="application/x-javascript" src="chrome://browser/content/textamerica.js"/> <script type="application/x-javascript" src="chrome://browser/content/xparse.js"/> </pre> Or if using an AJAX architecture: <pre> <script language="JavaScript" src="/textamerica.js"></script> <script language="JavaScript" src="/xparse.js"></script> </pre> The map your code to call the functions defined in textamerica.js. Then rewrite or replace the update() function in textamerica.js to take the appropriate action each time it receives the callback from the server. <pre> function update() { //in case of bad return data, catch the exception and take appropriate action try { var root = Xparse(gXMLHttpRequest.responseText); //add your code here //do something with root node here depending on which call was made //you don't have to return root, it's here for debugging purposes return root; } catch (e) { alert(e); } } </pre> The callback is asynchronous, so there maybe a considerable delay between the original call and the call to update(). You must be careful not to make further calls into the library until the previous function has completed this cycle. This library is NOT thread safe. The calling application must handle waiting until the previous call returns before making another one. A global variable can be used to track the original calling function to plot the appropriate behavior in the update() function. Some knowledge of the Xparse data structure is necessary to pull out data from the XML returned from the server. <br> The following global parameters must be configured correctly:<br> <pre> var key = 'TA113805'; //change these settings based on user input var login = ''; var pass = ''; </pre> The login and pass variables should be the user's login and password to the TextAmerica.com website. Some sort of form or dialog for retrieving the user information is recommended. The developer's login and password can be used until deployment. The application key, is defined on the TextAmerica API page <a href="http://www.textamerica.com/api.aspx">http://www.textamerica.com/api.aspx</a>. <br> <h2>AJAX</h2> The AJAX architecture is described considerably in <a href="http://www.adaptivepath.com/publications/essays/archives/000385.php">this document</a>. Examples of AJAX bases sites are <a href="http://maps.google.com/">http://maps.google.com</a> and <a href="http://www.google.com/webhp?complete=1&hl=en">Google Suggest</a> among others. The server side component for the XML data is http://xml.api.textamerica.com, but a site not hosted on that URL can still use the service in certain cases using <a href="http://www.mozilla.org/projects/security/components/signed-scripts.html#privs">expanded permissions</a>. A benefit of AJAX over developing a Firefox extensions is IE support, which is described below. <br> <h2>Mozilla/Firefox Extension</h2> Firefox extension development is becoming more popular as the number of Firefox installations increases. The TextAmerica Javascript library can be used in a Firefox extension with impunity to the originating host restriction since permission is givin at extension installation time. Some possible applications are: using data from the current webpage as parameters to a function call or a completely new but fully integrated XUL interface. I had thought of being able to add a bookmark from right click menu option to automatically set my current webpage as a bookmark. More information on developing Firefox extensions can be found at <a href="http://extensions.roachfiend.com/howto_bug.html">here</a> and <a href="http://kb.mozillazine.org/Dev_:_Extensions">here</a>. Firefox was used to test and develop this Javascript library. <br> <h2>How to create a Firefox extension</h2> The file structure for Firefox extensions is particular. Using "textamerica" as an example name for an extension, your directory structure will look something like: <br> -- textamerica/<br> -- textamerica/chrome/<br> -- textamerica/chrome/content/<br> -- textamerica/chrome/skin/<br> <b>1.</b> First create a file called install.rdf in the textamerica/ directory. This file contains substantial boilerplate but will look something like:<br> <pre> <?xml version="1.0"?> <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:em="http://www.mozilla.org/2004/em-rdf#"> <Description about="urn:mozilla:install-manifest"> <em:creator>Your Name Here</em:creator> <em:description>A Firefox toolbar for TextAmerica.</em:description> <em:homepageURL>http://textamerica.com/apicalls.aspx?call=Favorites.AddMoblog</em:homepageURL> <em:id>{unique guid}</em:id> <em:name>TextAmerica Toolbar</em:name> <em:version>1.0</em:version> <em:targetApplication> <Description> <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> <em:minVersion>0.7</em:minVersion> <em:maxVersion>1.2</em:maxVersion> </Description> </em:targetApplication> <em:file> <Description about="urn:mozilla:extension:file:textamerica.jar"> <em:package>content/</em:package> <em:package>skin/</em:package> </Description> </em:file> </Description> </RDF> </pre> For the unique guid, go to <a href="http://www.hoskinson.net/webservices/guidgeneratorclient.aspx">http://www.hoskinson.net/webservices/guidgeneratorclient.aspx</a> and retrieve a guid and put use it for the extension guid not the target application guid. It will look something like {e3cf557e-89f0-48d5-a3a3-39bae95fa5f4}. <br> Edit the other fields as per your wish but leave the targetApplication unchanged. <br> <b>2.</b> Create a file in the textamerica/chrome/content directory called contents.rdf. This has less boilerplate and will look similar too:<br> <pre> <?xml version="1.0"?> <RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:chrome="http://www.mozilla.org/rdf/chrome#"> <RDF:Seq about="urn:mozilla:package:root"> <RDF:li resource="urn:mozilla:package:textamerica"/> </RDF:Seq> <RDF:Description about="urn:mozilla:package:textamerica" chrome:extension="true" chrome:name="textamerica"/> <RDF:Seq about="urn:mozilla:overlays"> <RDF:li resource="chrome://browser/content/browser.xul"/> </RDF:Seq> <RDF:Seq about="chrome://browser/content/browser.xul"> <RDF:li>chrome://textamerica/content/textamerica.xul</RDF:li> </RDF:Seq> </RDF:RDF> </pre> <b>3.</b>Next, in the textamerica/chrome/content directory, create a file called textamerica.xul. This file will hold the graphical portion of the extension as well as the mapping from the UI to the Javascript functions. You will want to customize this portion to fit your particular needs. I used a toolbar for development since it seemed like the easiest extension to develop. For the sake of a quick demo, I did the following: <pre> <?xml version="1.0"?> <?xml-stylesheet href="chrome://textamerica/skin/textamerica.css" type="text/css"?> <overlay id="TextAmerica-Overlay" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"> <script type="application/x-javascript" src="chrome://textamerica/content/textamerica.js"/> <script type="application/x-javascript" src="chrome://textamerica/content/xparse.js"/> <toolbox id="navigator-toolbox"> <toolbar id="TextAmerica-Toolbar" accesskey="T" class="chromeclass-toolbar" context="toolbar-context-menu" toolbarname="TextAmerica Toolbar" hidden="false" persist="hidden"> <toolbaritem flex="0"> <toolbarbutton id="TextAmerica-MainMenu" type="menu" tooltiptext="TextAmerica Toolbar Main Menu"> <menupopup> <menuitem label="TextAmerica Home Page" accesskey="T" tooltiptext="Browse to the TextAmerica home page" oncommand="alert('called home page')" /> </menupopup> </toolbarbutton> </toolbaritem> <toolbaritem flex="0"> <toolbarbutton id="TextAmerica-TB-Web" tooltiptext="button 2" label="button 2" oncommand="alert('button 2')" /> </toolbaritem> </toolbar> </toolbox> </overlay> </pre> The tie in to the Javascript functions are called from the button attribute "oncommand". I have place holder calls to the alert function for testing purposes in the above example. You will want to replace those with a function defined in textamerica.js as defined above. The textamerica.js file can hold all your application code or you can use another file and add it to the list of imported script's above. <br> Additional UI elements should be added within the toolbar element. For more information on what elements to add, try consulting <a href="http://www.xulplanet.com">XUL Planet</a>. I recommend a input fields for the various parameters that can be sent to TextAmerica. <br> <b>4.</b>Once you have defined your UI and the Javascript function calls from any UI elements, you must define the Javascript functions in textamerica.js. From the functions you define you can call into the textamerica Javascript bindings. This is a trivial example: <pre> //this is called with two input fields from textamerica.xul function callfromXUL(mylogin, mypassword) { login = mylogin; password = mypassword; sendGetMyBlogs(); } //then retrieve the callback in the update function function update() { try { var root = Xparse(gXMLHttpRequest.responseText); //do something with returned data here //by parsing the root node's children //and for example, display the results in the toolbar } catch (e) { alert(e); } } </pre> <b>5.</b> The last piece of code to implement is the extensions skin. Create a directory called "skin" in the textamerica/chrome directory. In that directory create a file called contents.rdf. This is similar to the last contents.rdf file created in another directory. The skin/contents.rdf file will look like: <pre> <?xml version="1.0"?> <RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:chrome="http://www.mozilla.org/rdf/chrome#"> <RDF:Seq about="urn:mozilla:skin:root"> <RDF:li resource="urn:mozilla:skin:classic/1.0" /> </RDF:Seq> <RDF:Description about="urn:mozilla:skin:classic/1.0"> <chrome:packages> <RDF:Seq about="urn:mozilla:skin:classic/1.0:packages"> <RDF:li resource="urn:mozilla:skin:classic/1.0:textamerica" /> </RDF:Seq> </chrome:packages> </RDF:Description> </RDF:RDF> </pre> Create a file called textamerica.css in the skin/ directory. Here we can define any style properties we wish to reference from the content/textamerica.xul file. An example of this would look like: <pre> #TextAmerica-TB-Combined > .toolbarbutton-menubutton-button { -moz-box-orient: horizontal; } </pre> <b>6.</b> The last step involves creating the actual file that will be installed in Firefox. You must use WinZip or software similar to it. First create a Zip file called textamerica.jar in the textamerica/chrome directory. The contents of the textamerica.jar file should be the contents/ directory and the skin/ directory. Then create another Zip file called textamerica.xpi in the textamerica/ directory that has the chrome/textamerica.jar file and the install.rdf file in it. The .xpi file is the install file for Firefox. You can test your install file by selecting the File->Open File option on the Firefox menu and select the textamerica.xpi file to open. This will test your extension. Firefox is very touchy about incorrectly manufactured .xpi files, so you may want to backup your installation before trying. <br> Most of these instructions were borrowed from <a href="http://www.borngeek.com/firefox/tutorial/">Born Geek</a>. <br> <h2>Xparser</h2> The Xparser library is a lightweight XML parser and the source code is stored in xparser.js. It is used to parse the XML returned from the server into a data structure that is consistent across all the TextAmerica Javascript library calls. The reference returned by the update() method is the root node of the XML. By iterating down through the children of the node structure, data specific to each call can be pulled out. More documentation on the Xparser API can be found at <a href="http://www.jeremie.com/Dev/XML/">http://www.jeremie.com/Dev/XML/</a>. It is strongly recommended that you consult the xparser.js file itself for more information on retrieving data from the root node. <h2>Note:</h2> Microsoft IE 5.0 (and later) support can be added by using the following code to make the XmlHttpRequest as documented here <a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/xmobjxmlhttprequest.asp">http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/xmobjxmlhttprequest.asp</a>. The differences between IE and Mozilla are documented as well, on Mozilla.org: <a href="http://www.mozilla.org/xmlextras/">http://www.mozilla.org/xmlextras/</a>. <br> <br> Address all complaints, flames and 'are you an idiot's to contact at darklilac dot com. </body> </html>