Getting Started
QBO3's Javascript library enables full control of all QBO objects via a simple javascript interface.
To start, include the QBO3 javascript library as follows:
<script type="text/javascript" src="Theme.ashx/Javascript">
To log into a QBO3 site:
new qbo3.LoginObject().login({Username: "myemail@company.com", Password: "myPassword"}, function(json) { alert(json.success ? 'Logged in!': 'Bad credentials'); });
To add a new Organization to the system:
new qbo3.OrganizationObject().invokeJson(
'Save',
{'Organization': 'Acme', 'Company': 'Acme Mining Company', 'Address': '123 Main Street', 'City': 'San Diego', 'State': 'CA', 'PostalCode': 92101},
function(json) { console.log(json) }
);
All QBO3 javascript class objects support invokeJson({method}, {data}, {callbacks}), where:
method: the server-side method to be executed
data: json representation of the data to be posted
callbacks: (optional) a function to execute with the JSON results returned by the QBO3 server
To search for all organizations in the state of CA:
new qbo3.OrganizationObject().invokeJson('Search', {'State': 'CA'}, function(json) { console.log('Here are the results:'); console.log(json); });
All QBO3 tables include a SQL identity column as a primary key; the Organization table has an OrganizationID. Let's assume the Acme organization has an OrganizationID of 1.
// Set up a variable so we can reuse it.
// By default, all AJAX calls are async (and should remain so for 'real' apps). For our purposes, however, we'll make the calls sync, so we don't need to chain callback functions.
var organization = new qbo3.OrganizationObject({async: false});
// See what our current address is
organization.invokeJson('Select', {'ID': 1}, function(json) { console.log('Address is ' + json.Address) });
// Change the address
organization.invokeJson('Save', {'ID': 1, 'Address': '234 Center Street'}, function(json) { console.log('Address is now ' + json.Address) });
// See what our new address is
organization.invokeJson('Select', {'ID': 1}, function(json) { console.log('New address is ' + json.Address) });
// An Organization inherits from Contact, which supports geo-coding. Let's geocode!
organization.invokeJson('Geocode', {'Address': '234 Main Street', 'City': 'San Diego', 'State': 'CA', 'PostalCode': 92101}, function(json) { console.log(json) });
// Just geocode Acme and save it in the database; I don't need to see the lat and lng right now
organization.invoke('Normalize', {'ID': 1});
Notes on the above code:
You can pass JSON options when creating new qbo3.{Abstract}Object(options)
The Organization/Normalize method does not return any data, so we just used .invoke(method, data) instead of .invokeJson(method, data)
Displaying Data
Manipulating data via javascript and JSON is well and good, but at some point you will need to display this data to an end user. You're welcome to use javascript to do this; Handlebars is a pretty cool way to work with JSON. QBO3 also comes with a standard set of transformations (XSLTs) designed to display our data in a nice Bootstrap-based UI. To leverage the Bootstrap-based UI, make sure you include our CSS:
<link href="Theme.ashx/Css?Version=2" type="text/css" rel="stylesheet">
Include an HTML element where you want to display the XHTML delivered by the QBO3 server:
<div id="myResults">Loading...</div>
Then, you can leverage our invokeHtml method:
// Set up a variable so we can reuse it. Note that we include a target HTML element id.
var organization = new qbo3.OrganizationObject({'target': 'myResults'});
// Display all Organizations in the state of California inside the myResults div tag, using the standard Organization.Search.xslt
organiztaion.invokeHtml('Search', {'State': 'CA', 'Transform': 'Organization.Search.xslt'});
// Most QBO3 methods that return data include a 'default' transform; if you omit the 'Transform' parameter, the default transform will be used.
// This call is functionally identical to the call above.
organiztaion.invokeHtml('Search', {'State': 'CA'});
// If you prefer your own UI, create your own XSLT and call it.
organiztaion.invokeHtml('Search', {'State': 'CA', 'Transform': 'My.Custom.Organization.Search.UI.xslt'});
Notes:
All QBO3 javascript class objects support invokeHtml({method}, {data}, {callbacks}, {target})
This is just like invokeJson, except that we will update the target div tag with the XHTML returned by the server
The target parameter is optional; if you don't specify it, the target passed in with on creation will be used
Extending the QBO3 javascript library
The Theme.ashx/Javascript method will serve up a single javascript file containing all scripts in the /Scripts folder of the web server. If you wish to include your own extensions in the QBO3 javascript library, simply add your .js file to the /Scripts folder of the QBO3 website.