This is the main PAX library, encapsulating xmlHttpRequest, event handeling, and so on.
Mikkel Bergmann, http://www.pointful.com
| pax | This is the main PAX library, encapsulating xmlHttpRequest, event handeling, and so on. |
| Properties and Functions | |
| pax | Main library OBJ |
| pax.$ | Simple alias to document.getElementById |
| pax. | Emulates the most common jQuery functionality such as chainable events and find. |
| pax. | String to prefix all server calls with, useful for ensuring security is not broken easily |
| pax. | Array of requests. |
| pax. | Boolean to choose if we should display the status spinner |
| pax. | The default container (DOM Element) to put the statusbox spinner into. |
| pax. | List of functions bound to objects. |
| pax. | The default CSS class to use for the spinner |
| pax. | Unique ID counter for generating temporary DOM IDs |
| pax. | Outputs debug to console in certain instances, if true |
| pax.post | Send a POST request via the XMLHttpRequest object. |
| pax.get | Send a GET request via the XMLHttpRequest object. |
| pax. | Returns the current unique ID |
| pax. | Increments the unique ID counter, and returns the ID |
| pax. | Add an event to an OBJ |
| pax. | Binds the event once only, ie: clears any other bound functions on the event first. |
| pax. | Returns true if an object has a certain event bound to the given function. |
| pax. | Remove an event from an OBJ |
| pax. | Remove all registered events from all OBJs. |
| pax. | Binds a key down event to an object |
| pax. | Binds a key up event to an object |
| pax. | Binds a key press event to an object. |
| pax. | Brings the scope of an object into the current scope, with the optional given name. |
| pax. | Converts a JSON string to an object. |
| pax.JSON | Converts an object into a JSON string. |
| pax. | URL encodes an oject into a post string to be used in pax.post. |
| pax. | URL decodes a post string back into a set of parameters |
| pax. | Overrides default arguments in the given object only if they exist in the given argument |
| pax. | Overrides default arguments in the given object, and adds any other attributes in the argument |
| pax. | Hides the status spinner |
| pax. | Set the onreadystatechange to a callback function, which calls the given function. |
| pax. | Cancel the pax call, and destroy request object |
pax.post = function( url, post, callBack, callDesc, spinnerBox, spinnerClass )
Send a POST request via the XMLHttpRequest object. Note that you do not need to specify all parameters
| url | URL to send a request to. |
| post | POST string to include in the call, use pax.postString to encode an object containing key / value pairs |
| callBack | Function to call once the request responds. |
| callDesc | Description of what the request is doing - is displayed as a title for the status spinner. |
| spinnerBox | DOM element to put the spinners into |
| spinnerClass | Class to use on the request spinner. |
| xml | If the response is in XML format, this will contain the response, otherwise it will be empty |
| txt | If the response is in Text format, this will contain the response, otherwise it will be empty |
| url | what URL the response came from |
<div id='pax.post.example1'></div>
[:.
var mycallBack = function( xml, txt, url ) {
var response = pax.unJSON( txt );
pax.$('pax.post.example1').innerHTML = "The name retreived from the server is: " + response.data[0].name;
};
pax.post( '/pax/pax.post.example.php', pax.postString( { action: 'editAction', id: 2 } ), mycallBack, 'Post example', 'pax.post.example1' );
:]This will send a request, with id = 2, action = ‘editAction’, showing the default spinner image via the spinner queue. It should be noted that the php script has a 2 second delay, so that you actually see the spinner.
<div id='pax.post.example2'></div>
[:.
var mycallBack = function( xml, txt, url ) {
var response = pax.unJSON( txt );
pax.$('pax.post.example2').innerHTML = "The country retreived from the server is: " + response.data[0].country;
};
pax.post( '/pax/pax.post.example.php', pax.postString( { action: 'editAction', id: 1 } ), mycallBack, 'Post example', 'pax.post.example2', 'load_snake_blue.gif' );
:]This will send a request, with id = 1, action = ‘editAction’, showing a custom spinner image via the spinner queue. It should be noted that the php script has a 2 second delay, so that you actually see the spinner.
pax.get = function( url, callBack, callDesc, spinnerBox, spinnerClass )
Send a GET request via the XMLHttpRequest object. Note that you do not need to specify all parameters
| url | URL to send a request to. |
| callBack | Function to call once the request responds. |
| callDesc | Description of what the request is doing - is displayed as a title for the status spinner. |
| spinnerBox | DOM element to put the spinners into |
| spinnerClass | Class to use on request spinner box. |
| xml | If the response is in XML format, this will contain the response, otherwise it will be empty |
| txt | If the response is in Text format, this will contain the response, otherwise it will be empty |
| url | what URL the response came from |
<fieldset><legend>Response from pax.get</legend>
<div id='pax.get.example1'></div>
</fieldset>
[:.
var url = '/pax/pax.get.example1.txt';
var callBack = function( xml, txt, url ) {
pax.$('pax.get.example1').innerHTML = txt;
};
pax.get( url, callBack, 'get example', false, false );
:]You can add a timestamp at the end of the URL, to make it unique, to avoid caching issues in certain browsers
pax.event.bind = function( obj, event, func )
Add an event to an OBJ
| object | DOM Object to attach the event / function to |
| event | The event we’re listening for. Note that we don’t add the ‘on’ part |
| func | Function to run when event fires |
<div id="pax.event.bind.example1">Click me!</div>
[:.
pax.event.bind( pax.$('pax.event.bind.example1'), 'click', function() { alert('Thanks for clicking!') } );
:]Alerts when the div’s onclick function fires.
var el = document.getElementById(‘exampleWindowCloseButton’); pax.event.bind( el, ‘click’, function() {...
pax.event.bind( pax.$(‘exampleWindowCloseButton’), ‘click’, function() {...
Then there is no memory leak, as pax.unbindAll will clear the binding before we unload the window.
pax.event.hasBinding = function( obj, event, func )
Returns true if an object has a certain event bound to the given function. This uses the pax.bindQueue
| object | DOM Object we’re inspecting |
| event | The event we’re testing for. Note that we don’t add the ‘on’ part |
| func | Function that we’re testing for |
<div id="pax.event.hasBinding.example1"></div>
[:.
var myFunc = function() {
alert('Thanks for clicking!');
};
var box = pax.$('pax.event.hasBinding.example1');
box.innerHTML += 'has binding: ' + pax.event.hasBinding( box, 'click', myFunc ) + '<bR>';
box.innerHTML += 'adding binding...<bR>';
pax.event.bind( box, 'click', myFunc );
box.innerHTML += 'has binding: ' + pax.event.hasBinding( box, 'click', myFunc ) + '<bR>';
box.innerHTML += 'removing binding...<bR>';
pax.event.unbind( box, 'click', myFunc );
box.innerHTML += 'has binding: ' + pax.event.hasBinding( box, 'click', myFunc ) + '<bR>';
:]
pax.event.unbind = function( obj, event, func )
Remove an event from an OBJ
| object | DOM Object to remove the event from |
| event | The event we assigned originally. Note that we don’t add the ‘on’ part |
| func | Function that was assigned to run when event fires |
<div id="pax.event.unbind.example1">Click me!</div>
[:.
var cluck = function() {
pax.event.unbind( pax.$('pax.event.unbind.example1'), 'click', cluck );
alert('Thanks for clicking! Now click OK, and try again. It wont work the 2nd time, as we have unbound the function.');
};
pax.event.bind( pax.$('pax.event.unbind.example1'), 'click', cluck );
:]Removes the previously bound function event.
<div id="pax.event.unbind.example2">Click me!</div><input type='button' id="pax.event.unbind.example2.button" value='Unbind'>
[:.
var cluck1 = function() { console.log('1'); };
var cluck2 = function() { console.log('2'); };
pax.event.bind( pax.$('pax.event.unbind.example2'), 'click', cluck1 );
var unbindCluck = function() {
pax.event.unbind( pax.$('pax.event.unbind.example2'), 'click' );
alert('Thanks for clicking! Now click OK, and try again. It wont work the 2nd time, as we have unbound the function.');
};
pax.event.bind( pax.$('pax.event.unbind.example2'), 'click', cluck2 );
pax.event.bind( pax.$('pax.event.unbind.example2.button'), 'click', unbindCluck );
:]Removes all previously bound click events.
pax.event.bindKeyDown = function( obj, func )
Binds a key down event to an object
| object | DOM Object to bind the keydown event to |
| func | Function that runs when the key fires |
Type in this box: <input type="text" id="pax.event.bindKeyDown.keyInput"> Key code: <input type="text" id="pax.event.bindKeyDown.keyPressed" size="3">
[:.
var myKeyFunc = function( event ) {
pax.$('pax.event.bindKeyDown.keyPressed').value = event.keyCode;
};
pax.event.bindKeyDown( pax.$('pax.event.bindKeyDown.keyInput'), myKeyFunc );
:]This will show what keycode is returned when you press a key in the first text box
pax.event.bindKeyUp = function( obj, func )
Binds a key up event to an object
| object | DOM Object to bind the keyup event to |
| func | Function that runs when the event fires |
Type in this box: <input type="text" id="pax.event.bindKeyUp.keyInput"> Key code: <input type="text" id="pax.event.bindKeyUp.keyPressed" size="3">
[:.
var myKeyFunc = function( event ) {
pax.$('pax.event.bindKeyUp.keyPressed').value = event.keyCode;
};
pax.event.bindKeyUp( pax.$('pax.event.bindKeyUp.keyInput'), myKeyFunc );
:]This will show what keycode is returned when you press a key, then let go of it, in the first text box
pax.event.bindKeyPress = function( obj, action )
Binds a key press event to an object. The reason we have this method is that it will work in all browsers
| object | DOM Object to bind the keypress event to |
| func | Function that runs when the event fires |
Type in this box: <input type="text" id="pax.event.bindKeyPress.keyInput">
Key code: <input type="text" id="pax.event.bindKeyPress.keyPressed" size="3">
[:.
var myKeyFunc = function( event ) {
pax.$('pax.event.bindKeyPress.keyPressed').value = event.keyCode;
};
pax.event.bindKeyPress( pax.$('pax.event.bindKeyPress.keyInput'), myKeyFunc );
:]This will show what keycode is returned when you press a key in the first text box
pax.scope = function( obj, name )
Brings the scope of an object into the current scope, with the optional given name. If no name is specified, then it is assumed an object with ‘name’ -> value is passed, and each variable will be available as ‘name’. The global variable is simply a copy, and is not linked to the local variable
| obj | object to put into global name space |
| name | optional name to use for the object; if no name is given, the object will be traversed, and the items in it will be globalised. |
Type before global scope: <div id='pax.scope.example1.type' style='border: 1px solid red'></div>
Type after global scope: <div id='pax.scope.example1.typeAfter' style='border: 1px solid green'></div>
[:.
var globalise = function () {
var localVariable = "local";
pax.scope( localVariable, 'gVar' );
};
pax.$('pax.scope.example1.type').innerHTML = typeof(gVar) + '<b' + 'r>';
globalise();
pax.$('pax.scope.example1.typeAfter').innerHTML = typeof(gVar) + '<b' + 'r>';
:]This example brings a variable from the scope of the function, into the current scope.
Log: <div id='pax.scope.example1.log' style='border: 1px solid black'></div>
[:.
var myFunc = {
init: function ( value ) {
this.variable = value;
},
scopalise: function() {
pax.scope( this.variable, 'gvar2' );
},
log: function( header) {
var t = pax.$('pax.scope.example1.log');
t.innerHTML += '[' + header + ']<b' + 'r> local type: <b>' + typeof(this.variable) + '</b> value: <b>' +
this.variable + '</b><b' + 'r>global type: <b>' + typeof(gvar2) + '</b>';
if( typeof(gvar2) != 'undefined' )t.innerHTML += ' value: <b>' + gvar2 + '</b>';
t.innerHTML += '<hr>';
}
};
myFunc.init( 'I\'m a local' );
myFunc.log( 'before scopalise' );
myFunc.scopalise();
myFunc.log( 'after scopalise' );
gvar2 = "I\'m a global";
myFunc.log( 'change scopalised variable' );
:]This example brings a variable from the scope of the function, into the current scope, and shows that it is just a copy, not the actual variable.
Note: This function is REALLY expensive due to eval!
pax.unJSON = function( jsonStr )
Converts a JSON string to an object. This method is only here because it is best practice to do it this way.
| jsonStr | the string to convert. |
<div id='pax.unJSON.example1'></div>
[:.
var myFruitString = "{ 'apples': ['Granny Smith', 'Red delicious'], ";
myFruitString += " 'oranges': ['Valencia', 'Blood'], ";
myFruitString += " 'pears': 'green' }";
var myFruits = pax.unJSON( myFruitString );
pax.$('pax.unJSON.example1').innerHTML = pax.util.toString(myFruits);
:]Will return an object with this shape:
{ ‘apples’: [ ‘Granny Smith’, ‘Red delicious’ ], ‘oranges’: [ ‘Valencia’, ‘Blood’ ], ‘pears’: ‘green’ }
pax.JSON = function( obj, prev )
Converts an object into a JSON string.
| obj | the object to convert. |
<div id='pax.JSON.example1'></div>
[:.
var myFruitObj = {
'apples': ['Granny Smith', 'Red delicious'],
'oranges': ['Valencia', 'Blood'],
'pears': 'green'
};
var myFruitString = pax.JSON( myFruitObj );
pax.$('pax.JSON.example1').innerHTML = myFruitString;
:]Will display the object in JSON string format, with strings URI encoded
pax.postString = function( param )
URL encodes an oject into a post string to be used in pax.post.
| param | an object containing key / value pairs to be encoded |
Before: <div id='pax.postString.example1.before'></div>
After: <div id='pax.postString.example1.after'></div>
[:.
var postObj = { id: 23, action: 'update' };
var myPost = pax.postString( postObj );
pax.$('pax.postString.example1.before').innerHTML = pax.util.inspect(postObj);
pax.$('pax.postString.example1.after').innerHTML = myPost;
:]When this is run, myPost becomes ‘&id=23&action=update’
pax.defaultArgs = function( obj, args )
Overrides default arguments in the given object only if they exist in the given argument
| obj | an object containing key / value pairs to be overridden |
| args | an object containing optional key / value pairs to override the contents of obj |
Before: <div id='pax.defaultArgs.example1.before'></div>
After: <div id='pax.defaultArgs.example1.after'></div>
[:.
var config = { name: 'Bob Smith', email: 'bob@smith.com', action: 'update' };
pax.$('pax.defaultArgs.example1.before').innerHTML = pax.util.toString( config );
pax.defaultArgs( config, { action: 'insert' } );
pax.$('pax.defaultArgs.example1.after').innerHTML = pax.util.toString( config );
:]Changes config to contain the action ‘insert’
pax.defAddArgs = function( obj, args )
Overrides default arguments in the given object, and adds any other attributes in the argument
| obj | an object containing key / value pairs to be overridden |
| args | an object containing optional key / value pairs to override the contents of obj |
Before: <div id='pax.defaultArgs.example1.before'></div>
After: <div id='pax.defaultArgs.example1.after'></div>
[:.
var config = { name: 'Bob Smith', email: 'bob@smith.com', action: 'update' };
pax.$('pax.defaultArgs.example1.before').innerHTML = pax.util.toString( config );
pax.defaultArgs( config, { action: 'insert' } );
pax.$('pax.defaultArgs.example1.after').innerHTML = pax.util.toString( config );
:]Changes config to contain the action ‘insert’
pax.setCallBack = function( url, callBack, callDesc, spinnerBox, spinnerClass )
Set the onreadystatechange to a callback function, which calls the given function. Also shows hides the status spinner as required.
| url | URL to send a request to. |
| callBack | Function to call once the request responds. |
| callDesc | Description of what the request is doing - is displayed as a title for the status spinner. |
| spinnerBox | DOM element to put the spinners into, false = don’t use |
| spinnerClass | CSS Class to use for the request spinner, false = don’t use |
This method is only useful if you’re overriding one of the request methods, such as pax.get or pax.post
<fieldset><legend>Response from Request Object</legend>
<div id='pax.setCallBack.example1'></div>
</fieldset>
[:.
var url = '/pax/pax.getRO.example1.txt';
var callBack = function( xml, txt, url ) {
pax.$('pax.setCallBack.example1').innerHTML = txt;
};
var myRObj = pax.setCallBack( url, callBack, 'setCallBack example', false, false );
myRObj.ro.open( 'GET', url, true );
myRObj.ro.send( null );
:]This will send a request, and receive a response via using the setCallBack method.
pax.cancel = function( robj )
Cancel the pax call, and destroy request object
| robj | Request object to cancel call from |
<div id='pax.cancel.example1'></div>
[:.
var mycallBack = function( xml, txt, url ) {
var response = pax.unJSON( txt );
pax.$('pax.cancel.example1').innerHTML = "The name retreived from the server is: " + response.data[0].name;
};
var myRO = pax.post( '/pax/pax.post.example.php', pax.postString( { action: 'editAction', id: 2 } ), mycallBack, 'Post example', 'pax.cancel.example1' );
window.setTimeout( function() { pax.cancel( myRO.ro ); pax.$('pax.cancel.example1').innerHTML = 'Cancelled request'; }, 1000 );
:]This example creates a call that takes 2000ms, then cancels the call after 1000ms
Simple alias to document.getElementById
pax.$ = function( id )
Send a POST request via the XMLHttpRequest object.
pax.post = function( url, post, callBack, callDesc, spinnerBox, spinnerClass )
Send a GET request via the XMLHttpRequest object.
pax.get = function( url, callBack, callDesc, spinnerBox, spinnerClass )
Returns the current unique ID
pax.getId = function()
Increments the unique ID counter, and returns the ID
pax.getNextId = function()