• Home
• |
• Products
• |
• Request a Quote
• |
• Testimonials
• |
• Articles
• |
• Contact
• |
• Pay Invoice

 

tppAJAX v1.5 - 12/8/2007

Documentation

Javascript Reference

The Javascript interface is very simple. There are a lot of other things you can do with Javascript to enhance the look and feel of your site that we do not cover. This reference will cover the two (four with JSON) simple ways to use tppAJAX to modify your web page without needing to refresh the entire page.

---

Global Variables

These variables customize the way tppAJAX works.

Change tppAJAXTimeout if your PHP script takes longer than 10 seconds (the default timeout) to process. Specified in milliseconds (1000 = 1 second)
var tppAJAXTimeout = 10000;

var tppAJAXNoAJAXSupportMessage = 'Your browser does not support AJAX';

There are two ways to change these default values.

1. Modify ajax.js to apply changes site-wide.
2. Create a <script> tag with new values immediately after including ajax.js.

---

Functions

function updatePage( urlToLoad )
function getJSON( callback, urlToLoad )

This first function uses a url (HTTP GET) to update part of a page.

Use this in events or in urls in links on pages when you don't need to send back form data from user data-entry. The variables in the url will be available to your PHP script like you're already used to: in $_GET.

If you want to create a link with an embedded record id number for displaying a database record, you could do this in the html of your page:

<a href="javascript:"
onclick="updatePage( 'displayRecord.php?table=content&amp;id=101' );" >View Record</a>

This may also be used in button onClick and mouseOver events. It can be used in any event you want. Use the JSON function, getJSON, to utilize JSON on the server with an HTTP GET. When using the JSON function, you must provide a callback function (define a function and use the name of the function for callback without quotes). This callback function will be used to process the results of the JSON response from the server and takes a single argument for the object created from the JSON data. Please see the example for sendFormJSON for an example

---

function sendForm ( formID, formProcessor )
function sendFormJSON( callback, formID, formProcessor )

Use this in a form's onSubmit event to send the form via tppAJAX just like it was being sent when a user presses the submit button.
Use the JSON function to utilize JSON on the server. When using the JSON function, you must provide a callback function (define a function and use the name of the function for callback without quotes). This callback function will be used to process the results of the JSON response from the server and takes a single argument for the object created from the JSON data.

<form onsubmit="sendForm('signupForm','checkUsername.php'); return false;">
    ...
</form>

// JSON example:
<script type="text/javascript">
// sample callback function - see PHP Function section for the server side example
function LoadJSON_data( data )
{
    for(ix=0;ix<data.length;ix++)
    {
        var d=data[ix];
        alert( d.name + ' => ' + d.goodSoftware );
    }
}
</script>

<form onsubmit="sendFormJSON( LoadJSON_data, 'signupForm','checkUsername.php'); return false;">
  ...
</form>


---

PHP Functions

• tppAJAXStartResponse
• tppAJAXGenerate
• tppAJAXRegisterList
• tppAJAXJSON

---

function tppAJAXStartResponse( )
Call tppAJAXStartResponse() at the top of your response script that is generating the Ajax response.

This is a required function call, it must be invoked before any script output occurs - including accidental empty lines - it is absolutely critical that there are no spaces or lines before the <?PHP

---

function tppAJAXGenerate( $documentPieces, [$documentSettings], [$javascriptToEval] )
Call tppAJAXGenerate with the different arrays for output. The contents will be immediately generated and your script should end at this point.

$documentPieces is how you return different pieces of html code to update the page. This is an associative array where the key is a container's ID on the html page. The complete innerHTML of the container will be replaced with the value of the array entry.

You would typically use divs or spans with IDs assigned on the html page; your array key would be the ID value.

$documentSettings is also an associative array where the key is the name of a property on the document object that will be set to the value of the array entry. This was primarily added to provide an easy way to change the window title of the browser.

$javascriptToEval is a simple array where each entry is a bit of Javascript that will be eval'd one at a time in the browser. Alerts may be created this way, however any Javascript can be sent back to the browser and eval'd. This provides a tremendous amount of power in that you have complete access to the DOM from PHP via Javascript.

These variables are all demonstrated on the demo page.

---

function tppAJAXRegisterList( $ID, $callbackProcessor, $options = null )
Call tppAJAXRegisterList after creating the HTML for your list.

Please see the scriptaculous documentation on how to create the HTML for a list - or look at the source for the demo

$ID is the ID property for your list container (usually an unordered list - UL).

$options (optional - may be omitted) are documented, however onUpdate is created automatically in the function and will be overwritten if try to pass a value in for it.

$callbackProcessor is the PHP script that you write to handle the processing of list updates. See the example code to see how my sortable demo works.

---

tppAJAX has a built in security measure to prevent a specific XSS (cross site scripting) attack: tppAJAXJSON should be used in place of a standard call to the PHP version of the JSON encoding function.

Your version of PHP must have the JSON module loaded for this to work. This is available in the standard PHP compile starting with PHP 5.2.0.

function tppAJAXJSON( $array )

Call tppAJAXJSON with an array of variables. This will be turned into JSON output that is used by the Javascript JSON tppAJAX functions to create a data structure that is passed to your JSON handler. (See Javascript reference above)

$array is the array of information you want to return. This is most useful when it is a numerically indexed array of associative arrays.

In other words, this:

<?php

$out[] = array( 'name' => 'ThePhpPro', 'goodSoftware' => true );
$out[] = array( 'name' => 'Linux', 'goodSoftware' => true );

tppAJAXJSON( $out );

?>
An example Javascript processing function for this would be something like:


function LoadJSON_data( data )
{
    for(ix=0;ix<data.length;ix++)
    {
        var d=data[ix];
        alert( d.name + ' => ' + d.goodSoftware );
    }
}



---

Regular Price: $55 - On Sale for only $50! The price will go up soon, so don't delay, buy it today!

For web site hosting I recommend - www.bluehost.com