The plugins site is currently in development.
We've been looking to provide a higher-quality, spam-free experience at the plugins site for some time, and a major error on our part forced us to shut down the current site before we could put the new one in place. We are developing a new site, and you can follow along with its development on GitHub. For more information about this transition, including steps you can take as a plugin author to prepare, please read our post about what's going on.
SOAPjr - create clean, fast AJAX API's using JSON 1.3.0
SOAPjr is SOAP without the bloat and JSON not XML. It's JR (JSON-RPC) with rich error handling and file uploads. It works well on browsers from IE6 through to the iPhone.
It lets jQuery developers handle multiple errors in a clean and efficient way, and makes it easy for server-side developers to provide clean and fast APIs. (See SOAPjr.org for more detailed information).
Traditional SOAP is no longer the Simple Object Access Protocol it was initially designed to be. It's bloated and overly verbose making it bandwidth hungry and slow. It's also based on XML, making it expensive to parse and manipulate - especially on mobile or embedded clients. However, it's core Envelope/Head/Body design pattern is really useful for AJAX style API's.
SOAPjr uses a similar Envelope/Head/Body model, but instead of bloated and verbose XML it uses lightweight and easy to manipulate JSON. After all, there's no X in SOAP and it's Envelope/Head/Body concept is not bound in any way to requiring XML.
In contrast to SOAP, JR (JSON-RPC) is overly simplistic and basically tunnels HTTP GET style key/value pairs within a query string using JSON. However, within JSON-RPC there is no clear Head/Body separation leaving metadata to pollute the main data space.
SOAPjr combines the best of these two concepts and is designed to create modern AJAX API's that can easily be used by mobile devices, embedded systems or PC browsers.
Requirements
http://jqueryjs.googlecode.com/files/jquery-1.2.6.min.js
- see http://jquery.com/
http://www.json.org/json2.js
- see http://www.json.org/
http://jsonschema.googlecode.com/files/jsonschema-b2.js
- see http://code.google.com/p/jsonschema/
Support
For support, suggestions or general discussion please visit the #SOAPjr irc channel on freenode.net or visit http://SOAPjr.org.
Implementation overview
1. Load this plugin (jquery.SOAPjr.js)
2. Configure default settings using .config() [OPTIONAL]
3. Make a call using .get()
6. Setup a callback to process the results or errors
Demonstration
See http://SOAPjr.org/demos.html for a working example of using this plugin.
NOTE: The MIME-like Object with ENVELOPE/HEAD/BODY is called a MOBject.
Lite API
// Configure the defaults
$.SOAPjr.config({ "url" : "http://SOAPjr.org/demos/SOAPjr.pl" });
// url must be absolute including protocol (http://...)
$.SOAPjr.config({ "callback" : "my_callback" });
// callback can be a function_name or an anonymous function
// Then call a SOAPjr service
$.SOAPjr.get({
"HEAD" : { "source" : HEAD_DATA_SOURCE, "fields" : HEAD_FIELD_FILTER },
// DATA_SOURCEs can be a form_name, a var_name or a data object
"BODY" : { "source" : BODY_DATA_SOURCE, "fields" : BODY_FIELD_FILTER }
// FIELD_FILTERs can be an array of fields or an object map e.g. { input : output }
});
// Or if all the defaults are already set using config then you can just make a simple call
$.SOAPjr.get();
// Otherwise you can pass them all in at once
$.SOAPjr.get({ "url" : url, "BODY" : { "source" : "form_name", "fields" : ["first_name"] }, "callback" : "my_callback" });
// And don't forget to setup callbacks to handle your response
function my_callback(resp) {
// resp is a SOAPjr_response object
if (resp.result()) {
var BODY = resp.get("BODY");
// process the results here
} else {
var HEAD = resp.get("HEAD");
// dump all errors
alert((HEAD.errors.dump());
}
}
File Upload using the "related" API
// Same as the Lite API for config
// Plus a simple config call to add the upload form src url
$.SOAPjr.config({ "file_upload_form" : "url_to/file_upload_form" });
//EXAMPLE FILE UPLOAD FORM
//<html>
//<head>
//<meta http-equiv="expires" content="0" />
//<meta http-equiv="cache-control" content="no-cache" />
//<meta http-equiv="pragma" content="no-cache" />
//</head>
//<body>
//<!-- edit the action here to point to your upload script -->
//<form action="file_upload.pl" name="SOAPjr_file_upload_form" method="POST" enctype="multipart/form-data">
//<input type="hidden" name="json" value="">
//<div id="SOAPjr_file_upload_fields"></div>
//<input type="file" name="new_file">
//</form>
//</body>
//</html>
// Then attach one or more files (one at a time)
$.SOAPjr.attach_file(file_input_dom_ref); // e.g. <input type="file" onChange="$.SOAPjr.attach_file(this)">
// A much richer version of this can be implemented using clone(), but does not work in IE6.
// Then upload the file(s) and data to the server as a SOAPjr request
$.SOAPjr.upload_file({ "HEAD" : { "related" : { "filename1" : "binary" } }, "BODY" : { "source" : data_obj }, "callback" : "my_callback" });
// upload_file() supports a subset of the features that get() does and requires at least one file to have been attached before it's called
// NOTE1: BODY.source should be a JSON data object and not a var_name or form_name as this requires a more complex data structure
// NOTE2: HEAD.related is only required if the file itself is also being updated
JSON Schema validation
// You can also use JSON Schema (http://json-schema.org) to validate the data structures of the BODY on both send and receive.
// First load any schema you want to re-use
$.SOAPjr.config({ "schema" : { "SEND_SCHEMA_KEY" : SCHEMA_GOES_HERE } });
// SCHEMA_GOES_HERE can be an absolute URL or a schema object
// Then assign these when you make your get() call
$.SOAPjr.get({
"schema" : { "send" : "SEND_SCHEMA_KEY", "receive" : "RECEIVE_SCHEMA_KEY" }
});