PROTO Client Documentation (Javascript Client)
From DocMGR
Contents |
Features
can send requests in JSON, XML, or URL-QUERY (serialized) format
Will process response based on response header, regardless of request format
Response data is automatically converted into a javascript array, if the response is in JSON or XML, and then passed to the callback function
Automatically converts strings or arrays for sending
Various shortcut functions for QUERY request types, which are usually used for non-API calls.
Can use debug method to see data and url before submitted
Servers as a wrapper for whatever library we want to use for AJAX requests (mootools, jquery, etc). Also allows us to change the protocol later if something better comes along
Callback Functions
By default, JSON and XML responses are decoded and sent as an array to the callback function. All other responses are sent raw. If the setDecode(false) is called before the request is sent, the raw response is set to the callback function no matter what the response mode is.
Debug/Error Handling
If a server-side PHP error is thrown on a valid HTTP request, the user will see a browser alert box with the error message displayed in it.
If the HTTP request fails, an alert box will be thrown with the HTTP status code and any text returned with the response.
The debug method can be used to see data and url before submitted with p.debug(true). If debug is called with p.debug('nosend') PROTO will show the url and data to submit, but won't actually send the request.
Client Non-API Examples
There are shortcut functions which basically load a url with PROTO in query mode. Useful for calling a module for list information. You can also pass XML or JSON data in the query (i.e. apidata=<data><command>listaccounts</command></data>).
You'll notice not much is to be gained calling the PROTO class directly here. It's either the same amount of code or less to use the shortcut functions
Example 1. Calling a module and passing response using POST
Shortcut function:
postReq("index.php?module=accountlist","writeAccounts");
Through PROTO class
var p = new PROTO('QUERY');
p.add("module","accountlist");
p.post("index.php","writeAccounts");
Also through PROTO class
var p = new PROTO('QUERY');
p.post("index.php?module=accountlist","writeAccounts");
Example 2. Submitting elements in a container (like a form or div) using POST
Shortcut function:
var url = "index.php?module=accountsave&" + dom2Query(document.pageForm);
postReq(url,"writeAccountSave");
Through PROTO Class
var p = new PROTO("QUERY");
var p.addDOM(document.pageForm);
p.post("index.php?module=accountsave","writeAccountSave");
Also through PROTO Class
var p = new PROTO("QUERY");
var parms = p.encodeDOM(document.pageForm);
var url = "index.php?module=accountsave&" + parms;
p.post(url,"writeInfo");
Example 3. Loading data via a synchronous request
Shortcut function:
var url = "index.php?module=accountlist";
var data = protoReqSync(url,"POST");
Through PROTO class:
var p = new PROTO("QUERY");
p.setAsync(false);
var data = p.post("index.php?module=accountlist");
Client API Examples
PROTO takes all data added using "add" or "addDOM" methods and sends it using the "apidata" name after it has been converted to JSON or XML, depending on the mode PROTO was initialized in.
Using PROTO class directly here makes more sense, as you don't have to manually create an XML or JSON structure to pass to the API
Example 1. Running a information retrieval command on API:
var p = new PROTO();
p.add("command","docmgr_object_getinfo");
p.add("object_id","5");
p.post(DOCMGR_API,"writeObjectInfo");
Example 2. Submitting a form to the API
var p = new PROTO();
p.add("command","docmgr_object_saveinfo");
p.addDOM(document.pageForm);
p.post(DOCMGR_API,"writeObjectSave");
Example 3. Redirect to new url (like for downloading streamed file from API)
Through PROTO class:
var p = new PROTO();
p.add("command","docmgr_file_get");
p.add("object_id","5");
p.redirect(DOCMGR_API);
Example 4. Uploading a file to API
//setup data to submit with form to api
var p = new PROTO();
p.add("command","docmgr_file_save");
p.add("name",fileName);
var url = DOCMGR_API + "?" + p.encodeData();
//point the form to our iframe for background processing
//and use the PROTO url for the action
document.pageForm.action = url;
document.pageForm.target = IFRAME_NAME;
document.pageForm.submit();
Shortcut Functions
|
Function |
protoReq |
|
Purpose |
sends asynchronous ajax request through PROTO class |
|
Inputs |
url → web address to load callback → function to pass results to reqMode → GET or POST |
|
Returns: |
none |
|
Function |
protoReqSync |
|
Purpose |
sends synchronous ajax request through PROTO class |
|
Inputs |
url → web address to load reqMode → GET or POST |
|
Returns |
array → request response |
|
Function |
postReq |
|
Purpose |
sends asynchronous ajax request through PROTO class in POST mode |
|
Inputs |
url → web address to load callback → function to pass results to |
|
Returns |
none |
|
Function |
getReq |
|
Purpose |
sends asynchronous ajax request through PROTO class in GET mode |
|
Inputs |
url → web address to load callback → function to pass results to |
|
Returns |
none |
|
Function |
protoRedirect |
|
Purpose |
just like location.href = url, but uses PROTO. Basically for naming completeness |
|
Inputs |
url → web address to load |
|
Returns |
none |
|
Function |
dom2Query |
|
Purpose |
pulls the values of all html forms in the specified DOM container and stores their name/value pairs in an array |
|
Inputs |
cont → DOM container to search for values ignore → array of html form names to skip |
|
Returns |
array |
Class Definition
|
Class |
PROTO |
|
Purpose |
Wrapper for handling AJAX requests. Can handle all the encoding and decoding of requests and responses. Also allows to swap for a different javascript request library later. |
|
Inputs |
protocol (optional) → “XML”, “JSON”, or “QUERY”. defaults to PROTO_DEFAULT value, or “JSON” if not set. |
|
Returns |
class reference |
Class User Methods
|
Method |
setProtocol |
|
Purpose |
sets PROTO transfer protocol |
|
Inputs |
pm → “JSON”, “QUERY”,”XML” |
|
Returns |
none |
|
Method |
setRequest |
|
Purpose |
sets our request mode |
|
Inputs |
m → “GET” or “POST” |
|
Returns |
none |
|
Method |
setAsync |
|
Purpose |
sets the request to be asynchronous or synchronous |
|
Inputs |
as → true for asynchronous, false for sync |
|
Returns |
none |
|
Method |
setDecode |
|
Purpose |
sets whether or not to decode request responses to pass to the callback function |
|
Inputs |
m → true or false |
|
Returns |
none |
|
Method |
debug |
|
Purpose |
sets mode for debugging. can also change request method behaviour |
|
Inputs |
db → true: shows url and query data before request submit false: disables debugging nosend: shows query to be sent, but does not submit request |
|
Returns |
none |
|
Method |
add |
|
Purpose |
adds a new member to the DATA array to be sent with our request |
|
Inputs |
key (string) → form name data (string,array) → form value |
|
Returns |
none |
|
Method |
addDOM |
|
Purpose |
adds the values of all forms in DOM container to our DATA array using the form name as the value key and the form value as the array entry value |
|
Inputs |
cont → container to search ignore (array) → names of form elements to skip over |
|
Returns |
none |
|
Method |
encodeDOM |
|
Purpose |
gets the values of all forms in a DOM container and encodes them to the current protocol |
|
Inputs |
cont → container to search ignore (array) → names of form elements to skip |
|
Returns |
string → encoded form data |
|
Method |
get |
|
Purpose |
submits the contents of DATA to the url provided using a GET request |
|
Inputs |
url → url to send data to callback → function to call on a successful response |
|
Returns |
none |
|
Method |
post |
|
Purpose |
submits the contents of DATA to the url provided using a POST request |
|
Inputs |
url → url to send data to callback → function to call on a successful response |
|
Returns |
none |
|
Method |
redirect |
|
Purpose |
compiles DATA and our desired url, and redirects the page to that destination |
|
Inputs |
url → destination url |
|
Returns |
none |
|
Method |
encodeData |
|
Purpose |
converts DATA to a url string for submitting to our destination |
|
Inputs |
none |
|
Returns |
none |
Class Utility Methods (Not generally user-called)
|
Method |
request |
|
Purpose |
master function for submitting ajax requests. compiles DATA and our desired url, and submits the request. Calls a callback function (if specified) on success or displays an error on failure |
|
Inputs |
url → destination url callback → function to call when successful |
|
Returns |
none |
|
Method |
encode |
|
Purpose |
converts an array to JSON or XML formatted string |
|
Inputs |
arr → array to convert |
|
Returns |
string |
|
Method |
decode |
|
Purpose |
converts a JSON or XML formatted string to an array |
|
Inputs |
str → string to convert |
|
Returns |
array |
|
Method |
traverse |
|
Purpose |
pulls the values of all html forms in the specified DOM container and stores their names/values in an array |
|
Inputs |
cont → DOM container to search for values ignore → array of html form names to skip |
|
Returns |
array |
|
Method |
setData |
|
Purpose |
sets our DATA array to the input array |
|
Inputs |
data (array) → array of data to post during request |
|
Returns |
none |
