• View
• Edit
• History
• Attach
• Print
• Backlinks

SimpleAjax

Questions answered by this recipe

All sections are optional, you can remove those that do not apply to your recipe, and add new ones.

Description

Provide a framework for quick-and-dirty AJAX interaction between client/server.

(If you know what AJAX is then feel free to skip this end-user-oriented description) AJAX is a combination of technologies which (briefly, glossing over the technicalities) allows you to interface with the server without re-loading the page. Your browser (the client) sends a message back to the server and the server responds with a message back to your browser. Each of these messages are made up of data in various formats. Thus, for example, the client could send data from a form to the server which could save these data fields in a database and send a confirmation message back to be displayed on the client. Or an ID could be sent from the client to the server which could query a database and send back the data to the client which would then display the data. All of this occurs without re-loading the page, thus realizing some speed improvements but, more importantly, users feel less interrupted in their flow of work -- it is one seamless work session rather than a series of individual events punctuated by waiting for the page to re-load.

Although AJAX is surprisingly simple to implement, it can be daunting at first due to the number of different technologies that have to be brought together. The idea of SimpleAjax is to allow pmwiki authors who know only pmwiki markup to be able to do some rudimentary AJAX tasks without moving over into JavaScript and PHP and etc. And, if the user is familiar with WikiSh and/or WikiShDb then the possibilities multiply and quite useful forms can be implemented using AJAX with minimal effort.

Installation

• Download SimpleAjax.zipΔ and unzip it.
• Put simpleajax.php in the cookbook directory and simpleajax.js in the pub directory.
• Download toolbox.phpΔ and place it in your cookbook directory.
• Place lines like this in config.php (or in some other config file such as a page-specific config file for greater security):

include_once("$FarmD/cookbook/toolbox.php");
include_once("$FarmD/cookbook/simpleajax.php");

Configuration

These are not yet implemented

• $EnableFreeJS = true; // allows {! <javascript> !} code anywhere on the page
• $EnableFreeJSForm = true; // allows (:ajaxinput ...:) to use jsEVENT="<javascript>" similarly to ajaxEVENT

Usage

The following discrete steps are all pretty relevant to AJAX processing and will help us to organize the documentation:

1. Some event occurs which triggers the transaction
2. Data is sent from the client to the server
3. The server processes the data
4. The server sends data back to the client
5. The client makes use of the data

Here is who does each of these:

1. Your (:ajaxinput ... ajaxEVENT:) markup sets this up
2. SimpleAjax takes care of this for you (sending all form-related data to the page/section you specified)
3. You handle this via WikiSh markup on the page
4. SimpleAjax handles this
5. SimpleAjax handles this, displaying or setting data as appropriate based on the output of the markup from step #3

Step #1 - markup to set up an event to trigger the AJAX transaction

In your page source you will create form (input) elements, but instead of using (:input ...:) you will use (:ajaxinput ...:) and then you will include an ajaxEVENT argument such as the following:

(:ajaxinput text name=abc ajaxonchange>Group.Page#Section>outputid:)

The ajaxEVENT argument is actually made of several chunks:

• ajaxEVENT (in the example it was ajaxonchange)
  • This specifies what event will trigger the AJAX operation. You could use ajaxonclick, ajaxonblur, etc. (See here for a list of all events -- just prefix them with "ajax".)
• PAGE (in the example it was Group.Page#Section)
  • This specifies the page (and perhaps the section) which contains the server's response.
  • If you leave out the Group.Page part of this chunk then the current page is assumed (unless you have specified a different default page via (:simpleajax ...:) markup).
    • In other words if you are viewing MyGroup.MyPage and you are sending the AJAX request to MyGroup.MyPage#foo you can leave out the group and page and have just ajaxonchange>#foo>outputid.
  • If you leave the # but don't specify a section name then it is assumed that the section will be named after the current field name.
    • In other words if you are working with a field named fname and you had ajaxonchange>Group.Page# then it is assumed that you meant ajaxonchange>Group.Page#fname.
  • Putting both of these together means you could easily have ajaxonchange>#>outputid which would mean use the current (or default) page and use a section based on the current element/field name in the form.
  • If you leave out the # then it is assumed that the entire page will be processed, without looking for any section.
• ID (in the example it was outputid)
  • If you are using the straight text form of returning data to the browser (as opposed to XML) then the element with this ID will have its innerHTML property set to the text returned.
  • For example, you could create a div with an id of outputid in this manner:
• Note that >PAGE and >ID are optional.

You can set an alternate default page using this markup:

(:simpleajax [page=]Group.AltPage:)

(The "page=" is optional.)

You can also specify the pages and sections for specific fields using this markup if you prefer it:

(:simpleajax fname=Group.Page#section:)

(By doing this you can specify a page and section for multiple events in a single setting.)

And you can put the 2 together like this:

(:simpleajax Group.AltPage fname=Group.Page#section:)

Step #3, the markup on your page which processes the AJAX request

All data sent from the client will be available in $_GET variables. To access these you will need a tool such as HttpVariables or WikiSh. With HttpVariables a field named foo would be available using a {!$foo} syntax while in WikiSh the same variable would be available using a ${!foo} syntax.

Simpleajax can be used to send data from the server back to the client either as straight text (in which case it is simply assigned the innerHTML of the element with matching ID) or it can be sent in an XML form which can then set the value property of document objects, send specific text to innerHTML of various ID's, etc.

Content-type: (:contenttype ...:)

Running rules over your data (:addrule ...:)

Notes

Change log / Release notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

Comments

See discussion at SimpleAjax-Talk?