jQuery Soap
file: jquery.soap.js
version: 1.7.3
jQuery plugin for communicating with a web service using SOAP.
This script uses $.ajax to send a SOAPEnvelope. It can take XML DOM, XML string or JSON as input and the response can be returned as either XML DOM, XML string or JSON too.
Big thanx to everybody that contributed to $.soap!
Let's $.soap()!
NOTE: Please see my note on contacting me about issues, bugs, problems or any other questions below. I really prefer you use the issue tracker on github instead of sending me mail....
License GNU/GPLv3
Copyright (C) 2009-2017 - Remy Blom, the Netherlands
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Example
$.soap({
url: 'http://my.server.com/soapservices/',
method: 'helloWorld',
data: {
name: 'Remy Blom',
msg: 'Hi!'
},
success: function (soapResponse) {
// do stuff with soapResponse
// if you want to have the response as JSON use soapResponse.toJSON();
// or soapResponse.toString() to get XML string
// or soapResponse.toXML() to get XML DOM
},
error: function (SOAPResponse) {
// show error
}
});will result in
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<helloWorld>
<name>Remy Blom</name>
<msg>Hi!</msg>
</helloWorld>
</soap:Body>
</soap:Envelope>And this will be send to: url + method
http://my.server.com/soapservices/helloWorld
Installation
You can download the latest version as a zip, which contains all the files within this repository.
Or just get the file jquery.soap.js
Or install by bower or npm:
$ npm install jquery.soap
$ bower install jquery.soap
Dependencies
jQuery -- Should work fine with any version 1.9 or up, MAY work back to v1.6
the function SOAPResponse.toJSON() depends on any 3rd party jQuery.xml2json plugin
Previously the bower.json mentioned the one from fyneworks, published by XTREEM, as a dependency but that has been removed due to the fact that it has jquery 1.11 as dependency and is thus not usable with 1.9, 1.10 or 2.x versions of jquery.
As from version 1.6.7 you must manually install any 3rd party jQuery.xml2json plugin when you wish to use the SOAPResponse.toJSON function, like one from the list below:
sparkbuzz/jQuery-xml2json
fyneworks
Keep in mind that changing the plugin you are using might break your existing code that is already using SOAPResonse.toJSON because all plugins create objects with different structures!
Options overview
In depth overview of all the available options for $.soap
Promise
Since version 1.3.0 $.soap() returns the jqXHR object which implements the Promise interface. This allows you to use .done(), .fail(), .always(), etc. So instead of using the success and error option, you can also do:
$.soap({
...
}).done(function(data, textStatus, jqXHR) {
// do stuff on success here...
}).fail(function(jqXHR, textStatus, errorThrown) {
// do stuff on error here...
})
The advantage is that these promise callbacks give you direct access to the original parameters provided by
globalConfig
Since version 0.9.3 it is possible to make a call to $.soap just to set extra config values. When you have a lot of calls to $.soap and are tired of repeating the same values for url, namespace and error for instance, this new approach can come in handy:
$.soap({
url: 'http://my.server.com/soapservices/',
namespaceQualifier: 'myns',
namespaceURL: 'urn://service.my.server.com',
error: function (soapResponse) {
// show error
}
});
$.soap({
method: 'helloWorld',
data: {
name: 'Remy Blom',
msg: 'Hi!'
},
success: function (soapResponse) {
// do stuff with soapResponse
}
});The code above will do exactly the same as the first example, but when you want to do another call to the same soapserver you only have to specify the changed values:
$.soap({
method: 'doSomethingElse',
data: {...},
success: function (soapResponse) {
// do stuff with soapResponse
}
});But it won't stop you from doing a call to a completely different soapserver with a different error handler for instance, like so:
$.soap({
url: 'http://another.server.com/anotherService'
method: 'helloWorld',
data: {
name: 'Remy Blom',
msg: 'Hi!'
},
success: function (soapResponse) {
// do stuff with soapResponse
},
error: function (soapResponse) {
alert('that other server might be down...')
}
});NOTE: the data parameter is used as a key. If no data is specified in the options passed to $.soap all options are stored in the globalConfig, a SOAPEnvelope won't be created, there will be nothing to send. When a method is specified the globalConfig will be used and all options passed to $.soap will overrule those in globalConfig, but keep in mind, they won't be overwritten!
WS-Security
As from version 1.1.0 jQuery.soap supports a very basic form of WSS. This feature was requested (issue #9) and rather easy to implement, but I don't have a way to test it properly. So if you run into problems, please let me know (see below)
$.soap({
// other parameters..
// WS-Security
wss: {
username: 'user',
password: 'pass',
nonce: 'w08370jf7340qephufqp3r4',
created: new Date().getTime()
}
});
HTTP Basic Authorization
Using the HTTPHeaders option it is relatively simple to implement HTTP Basic Authorization as follows:
var username = 'foo';
var password = 'bar';
$.soap({
// other parameters...
HTTPHeaders: {
Authorization: 'Basic ' + btoa(username + ':' + password)
}
});Same Origin Policy
You won't be able to have a page on http://www.example.com do an ajax call (
Basically, when you are not able to do a call to your webService with a relative url, you will have to do something to circumvent same origin policy, here are some links to help you out:
http://stackoverflow.com/questions/3076414/ways-to-circumvent-the-same-origin-policy
If you have full control over the apache or nginx server you are serving your html from, the easiest way to setup a proxy is by using their reverse proxy capabilities:
Setting up a reverse proxy in apache
Setting up a reverse proxy in nginx
I apologise when you get upset for using lmgtfy.com in the previous links, I just love that site! ;)
Demo page
I included a simple demo page that you can use for testing. It allows you to play around with all the options for $.soap. Please take note that to make it work with your SOAP services you are again bound by the same origin policy.
Contacting me
Please note I don't mind you contacting me when you run into trouble implementing this plugin, but to keep things nice for me too, just follow these simple guidelines when you do:
- First make sure you're not getting an error because of same origin policy! Please double check!! About 80% of the people that contact me because they have trouble getting $.soap to work are having problems because of same origin policy.
- Check the issues section and the closed issues section to see if someone else already had your problem, if not
- Open an issue in the issues section instead of sending me mail. This way others can learn from your case too! Please include the following:
- the versions of your jquery and jquery.soap
- your $.soap call
- the request as sent to the server
- the response from the server
- Being polite helps, especially when you want me to help you with your problems. So please take the time to formulate something like a question. Opening an issue with just some code and/or error messages will be regarded as unpolite and will receive a ditto reply. (I just don't like receiving stuff like issue #18 on my day off...)
I also have a dayjob with deadlines, I'm a dad of two lovely little girls and I like to go out camping a lot, so please understand I am not always able to reply to you asap...
Thanx for understanding!! =]
History
Especially Zach Shelton and Anthony-redFox helped me improve $.soap a lot! A big thank you to everybody involved!
Version numbers are semver compatible.