Magic Ajax in your Web Applications

 

Majax Documentation

Majax uses HTML5 data attributes to specify interaction within a web application. Our documentation will guide you through the few steps you need to learn Majax. You can also check out the demos.

Introduction

Majax is a Javascript library built on top of Mootools. First download the archive to get started. We have included Mootools so you can get started right away. However, you might want to be aware of the main Ajax concepts.

 

Installation

Download and get your page ready

Download Majax and copy the majax folder in your site. To make it simple, Mootools is already included in the archive.

Make sure your page includes the calls to all the needed scripts and style sheets:


<!-- mootools -->
  <script src="majax/mootools/mootools-core.js"></script>
  <script src="majax/mootools/mootools-more.js"></script>
<!-- majax and fms -->
  <script src="majax/majax/majax/Majax.js"></script>
  <script src="majax/majax/fms/fms.js"></script>
  <link rel="stylesheet" href="majax/majax/fms/fms.css">

Majax Instantiation

Remember to call Mootools in your page. Then make sure you call Majax and its basic modal box components. Finally, instantiate Majax using Mootools domready event. Basically, all you need is the code below:


<script type="text/javascript" src="js/majax/Majax.js"></script>
<script type="text/javascript" src="js/fms/fms.js"></script>
<link type="text/css" rel="stylesheet" href="js/fms/fms.css" />
<script type="text/javascript">
window.addEvent('domready', function() {
 Majax.main.init();
 });
</script>
 

The basics

Trigger updates an area
Figure 1: Updating one or more areas in the page

data-majax Attribute

HTML5 defines data attributes in order to embed invisible data in your page. Majax uses a few specific data attributes to let you define your interaction model.

When a page is loaded and once the DOM tree is ready in your browser, Majax adds events on all elements with a data-majax attribute. Attribute values are interpreted by Majax in order to trigger interactions.

Example

Let's consider a basic example. Your page contains links that are to be activated with Javascript to trigger an Ajax request. The request response content then refreshes an area. Let's code this with Majax and see how it works.

Links can trigger the update of various areas in a page, as shown in Figure 1.

 

However, let's first consider the case where areaA is updated using the content of the link's request response. Below is the HTML source code needed to achieve this interaction with Majax:


<div>
  <a href="urlA" data-majax="majaxLink majaxUpdate_areaA">Trigger link</a>
</div>
<!-- area A -->
<div id="majaxContain_areaA">content A</div>
Figure 2: HTML5 source code

How it works

When a user clicks on the link, the majaxLink class show Majax that the link is not to be activated but to use an Ajax request instead, using the link's specified URL. If the Ajax request is successful, majaxUpdate_areaA shows that response content will update the elemnt with the corrsponding ID majaxContain_areaA.

 

HTTP Headers and Server Response

Server Response

Server response MUST be a JSON formatted response with two properties:

  • success may have the following value
    • success means the request response is OK, its content can be displayed as a response, and other interactions can be triggered.
    • failure means something went wrong. The content response may be used to display an error message, but subsequent interactions MUST NOT be triggered.
    • formError is used when using Majax to submit form data. It means the content response is the same form with its error messages. Hence the content may be displayed, but subsequent interactions MUST NOT be triggered.
  • content: contains the HTML source code of the response. IMPORTANT: the HTML MUST be nested in a root element (typically a <div>).

HTTP Headers

In order to let your web server know that Majax is used, a custom HTTP header is added when the Ajax request is created. The X-Majax-Request is added with the value majax. Using this header, the server can automatically determine whether to send an HTML or JSON response. For example in PHP, check the $_SERVER['HTTP_X_MAJAX_REQUEST'] variable.

The following sections will explain the different Majax use cases in detail.

Updating areas in a page

As shown in the first example, Majax can be used to upade an area with a simple link. Majax may also be used to updates more areas as shown in Figure 1. Let's add a few lines to the HTML in order to achieve those interactions.


<div>
  <a href="urlA" data-majax="majaxLink majaxUpdate_areaA majaxFire_myEvent">Trigger link</a>
</div>
<!-- area A -->
<div id="majaxContain_areaA">content A</div>
<!-- area B -->
<div data-majax="majaxListenTo_myEvent" data-majax-url="urlB">content B</div>
<!-- area C -->
<div data-majax="majaxListenTo_myEvent" data-majax-url="urlC">content C</div>
Figure 3: HTML5 source code

When the trigger link is clicked, an Ajax request is sent for urlA. If the JSON success property is success, then area A is updated with the content property of the response, and two Ajax requests are triggered using urlB and urlC to update areas B and C. The majaxFire_[*] keyword (where [*] is defined within the application) specify the firing of an event when the Ajax request is successful. All elements with a corresponding majaxListenTo_[*] data-majax attribute will then trigger an other Ajax request using the URL specified in their data-url attribute. Each area to be updated can then specify which content to update itself with.

Displaying Error Messages

How it works

When the success property has a failure value, all subsequent interactions are stopped. You might, however, want to inform the user that something went wrong. The success property may contain HTML where the root element has a data-majax attribute with one of the following values:

  • majaxMessage: the HTML will then be used to display an error in the page. The element where the message is displayed is specified in the page with a data-majax in the form majaxMessageZone_errorMessage, and the initial trigger specifies the name of the message area with a majaxMessageTarget_errorMessage keyword.
  • majaxModalMessage: the error message will be displayed using a modal box (see below for more on modal boxes).

Example


<div>
<a href="examples/errorMessage.php" data-majax="majaxLink majaxMessageTarget_errorMessage">Error message displayed within the page</a> | <a href="examples/modalMessage.php" data-majax="majaxLink">Error message displayed in modal box</a></div>
<div>Error messages are displayed below.</div>
<div data-majax="majaxMessageZone_errorMessage">Here you will see the error message</div>
</div>

Example result

Reset this demo

Forms and Majax

How it works

Using a form with Majax is just like using a link. Simply add majaxForm in the form's data-majax attribute. Majax will handle the looping the form until it validates. Upon succesful validation and response, areas are updated based on majaxUpdate_[*] and/or majaxFire_[*] keywords.

The most important here is for the server response to set the success JSON property to formError as long as the form doesn't validate, in order to display the form again without triggering other interactions.

Example


<div id="majaxContain_yourname">
<form method="post" action="examples/nameForm.php" data-majax="majaxForm majaxUpdate_yourname majaxFire_nameDone">
<p>Last name:  <input type="text" name="lastname" value="" /></p>
<p>First name:  <input type="text" name="firstname" value="" /></p>
<p><input type="submit" name="go" value="Let us know you!" /></p>
</form>
</div>
<div data-majax="majaxListenTo_nameDone" data-url="examples/hello.php">This area will be updated once the form validates and its submission succeeds.</div>

Example result

Last name:  

First name:  

This area will be updated once the form validates and its submission succeeds.
 
Reset this demo

Summary of keywords

Main keywords

The table below summarizes the keywords Majax uses. Majax is still evolving, with new use cases being used as projects are being developped. Stay tuned while new features are being developped.

Summary of Majax keywords
RoleKeyword
Define interaction
majaxLink
majaxForm
majaxModal
noMajax
Event trigger
majaxEvent_[eventName]
majaxUpdate_[idSuffix]
majaxAdd_[idSuffix]
Event listener
Must be used with data-majax-url
majaxListenTo_[eventName]

Other Keywords

Earlier version(s) of Majax included other keywords with data attributes for particular purposes. These extra features are currently being reviewed to assess their usability and applicability to other projects that what they have been introduced for.

Such attributes include:

  • data-modal to specify a JSON formatted list of options for the FMS modal box.
  • data-majaxIf to add conditions to a trigger.

Other keywords for the data-majax attribute include:

  • majaxAutoLoad to autoload an area in the page.
  • majaxButton (new name must be found) to create edit-in-place form controls.

Stay tuned for new features and updates!