simply put: Javascript - Asynchronous requests to the server, timestamps, and more.

Pie.js

PIE provides its own little javascript file that is included by default in every app. This file provides the developer with some very useful functionality on the front end, including the ability to communicate with PIE on the server.

Pie.js defines the Pie javascript object, which can be used to access things like:

• Pie.app - the name of the PIE app
• Pie.info.baseUrl - the base URL of the app
• Pie.info.url - the URL requested on the server
• Pie.info.uri - the internal URI that was ultimately served
• Pie.urls - a hash mapping internal URIs to URLs, where the URIs are listed in the pie/javascripts/uris config field

Integration with javascript frameworks

PIE tries to remain agnostic with respect to which javascript framework you use, but jQuery is encouraged. This is because, although the core library is independent of any js frameworks, additional plugins and tools in PIE use the jQuery library. If you wish, thought, you can mix and match additional libraries, such as YUI or Ext.

The Pie.ready() function is supposed to be called on the "DOM Ready" event of your favorite javascript framework. You will learn more about what Pie.ready() does in the article about tools.

Asynchronous requests

The term "AJAX" was coined in 2005 by Jesse James Garrett, and has come to encompass various forms of asynchronous requests from javascript to the server. PIE encourages the use of asynchronous requests that return JSON data, since it is the most compact and can easily be consumed by Javascript. To remain pragmatic, PIE unabashedly refers to all these requests as "Ajax".

You send AJAX requests using your favorite Javascript framework. But, before sending the request, you should use PIE on the front end to process the URL, like so:

var ajax_url = Pie.ajaxExtend(url, 'slot1,slot2')

PIE inserts some additional information into the querystring of the URL, indicating that this is an AJAX call, and listing the slots that should be filled and returned. These additional querystring fields are called

• _[ajax] set to "JSON"
• _[slotNames] a comma-delimited list of slot names

On the server, PIE makes use of the following functions to process the request:

• Pie_Request::isAjax() returns "JSON" or whatever was in _[ajax]. Otherwise, it returns false.
• Pie_Request::slotNames() returns an associative array whose keys are the names of the requested slots.

The default pop/response handler is well-equipped to handle all these scenarios:

• When the request is not an AJAX request, PIE fills the four default slots: title,dashboard,content,errors. You can override this list with your own, by setting the $module/response/slotNames config field. The results are then inserted into the layout.
• If the request is an AJAX request, Pie_Request::slotNames() is called to see which slots, if any, need to be filled. If Pie_Request::isAjax() returns "JSON", the result is returned as JSON. If there are errors or exceptions, they are returned instead.

Sending and receiving with JS

You can use your favorite javascript library to do AJAX. For example, using jQuery, you would do:

var url_json = Pie.ajaxExtend(url, 'friends');
$.ajax({
  type: 'POST',
  url: url,
  data: data,
  success: function (data) {
    if (data.errors) {
	  alert(errors[0].message);
      return false;
    }
    // otherwise use data.slots
    // also check out the other data that has been returned
  },
  dataType: 'json'
});

Timestamps

Because of the asynchronous nature of the calls, and varying conditions on the internet, you may receive responses before other responses, to messages you sent later than other messages. To take care of this problem, you should use timestamps.

When an AJAX call returns, PIE also returns a "timestamp" along with the data.

On the client side, when you send a request, you can get the current timestamp with new Date().getTime(). You are well advised to tie this information into the callback function, and compare it to the timestamp of the latest response that was processed. If the timestamp is outdated, simply exit the callback, rather than process the response.

By implementing timestamp comparisons on both the client and the server sides, you can eliminate the synchronization issues and race conditions that can plague ajax applications. For example, an "auto-suggest" box will only show suggestions for what's really in the box, and not what was there a moment ago because of some AJAX glitch.