Table of Contents
Download and get your page ready
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">
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:
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.
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:
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
HTTP Headers and Server Response
Server response MUST be a JSON formatted response with two properties:
successmay have the following value
successmeans the request response is OK, its content can be displayed as a response, and other interactions can be triggered.
failuremeans something went wrong. The content response may be used to display an error message, but subsequent interactions MUST NOT be triggered.
formErroris 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>).
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
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.
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
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
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-majaxin the form
majaxMessageZone_errorMessage, and the initial trigger specifies the name of the message area with a
majaxModalMessage: the error message will be displayed using a modal box (see below for more on modal boxes).
<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>
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
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.
<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>
Majax and Modal Boxes
Opening modal box
Majax comes with its own basic modal box (named FMS for Fenêtre Modale Simple). Interactions using a modal box are based on the same principles. A link's
data-majax attribute with the keyword
modalLink will (if successful) trigger the opening of a box to display the result content, just like this.
Interactions within modal box
Once content is loaded in the modal box, links default behavior is altered to automatically turn them into Majax links where the URL used is the link's href attribute value and the updated area is the modal box itself. To make a link behave normally, just use the
noMajax keyword within the
Closing modal box and triggers
For a link to close the modal box, use the
majaxModalClose keyword. When the modal box is closed, the interactions defined within the initial trigger (the one that opened the box) are triggered. It may be defined with
IMPORTANT: this only works if there has been no navigation within the modal box. This should be fixed in the future (?)
Example with modal box and triggers
<div><a href="examples/modalContent.php" data-majax="majaxModal majaxUpdate_modalreturn majaxFire_modalclosing">Open the modal box!</a></div> <div id="majaxContain_modalreturn">This area will get updated once modal box closes, using a link's content response.</div> <div data-majax="majaxListenTo_modalclosing" data-url="examples/simpleHello.php">This area will get updated once modal box closes, using its <code class="tag">data-url</code> attribute to fetch its content.</div>
data-urlattribute to fetch its content.
Staying within the modal box
As mentioned earlier, all links are activated as Majax links in order to stay within the modal box. Once navigation has occured within the modal box (whether with links or forms), a link that closes the modal box will not trigger the original link's interactions. As for now, it is not quite clear to us whether this should be a feature or a bug. In order to trigger other interactions, the closing link may contain
Forms in modal box
Loading forms in a modal box works the same as with links. Just load your form in the modal box. As long as the server response properly fills the
success JSON property; i.e. assigning it a
formError to loop within the modal box, your interaction is working.
IMPORTANT: due to eventual form looping within the modal box, the areas to update and events to fire MUST be specified within the form's
data-majax attribute AND the original trigger link. This should be fixed in the future (?)
Summary of 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.
majaxLink majaxForm majaxModal noMajax
majaxEvent_[eventName] majaxUpdate_[idSuffix] majaxAdd_[idSuffix]
Must be used with
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-modalto specify a JSON formatted list of options for the FMS modal box.
data-majaxIfto add conditions to a trigger.
Other keywords for the
data-majax attribute include:
majaxAutoLoadto autoload an area in the page.
majaxButton(new name must be found) to create edit-in-place form controls.