LemonStand Front-End JavaScript Framework

The LemonStand front-end JavaScript framework is a set of JavaScript libraries which enables you to send AJAX requests to the server and update page content without reloading the page. There are two implementations of LemonStand JavaScript framework - MooTools-based and jQuery-based. To include required libraries to your pages, you need to include minimum required JavaScript libraries described in the Combining and minifying JavaScript and CSS files article.

LemonStand front-end JavaScript library extends the DOM element class with new method: sendRequest.

element.sendRequest method

The element.sendRequest method sends an AJAX request to a server. This method should be called on HTML FORM elements. Use the element.getForm method to find a FORM element wrapping the element.

Syntax

element.sendRequest(handler_name, options)

Arguments

1. handler_name, string. A name of a function to call on the server.
2. options, JavaScript object. The request options object. This argument is optional.

Return value

Returns false

Example

<input value="Add To Cart" onclick="return
  $(this).getForm().sendRequest('shop:on_addToCart', 
    {update: {'mini_cart': 'shop:mini_cart','product_page': 'product_partial'}}
  )"
type="button" />

In the handler_name argument you can specify either a function defined in the page Action code, or a handler name defined in LemonStand modules. For example, the Shop module defines the shop:on_addToCart AJAX request handler.

The options argument can have the following elements:

• update – a set of page element Ids and corresponding LemonStand partials to update the elements.
• loadIndicator – an object for managing the loading indicator behavior: loadIndicator{show: true, hideOnSuccess: true}
• onComplete – a function to execute when the request is complete
• onAfterUpdate - a function to execute when the request finished updating the page 
• onFailure – a function to execute in case of the request's failure
• onSuccess -  a function to execute in case of the request's success
• onBeforePost – a function to execute before data is sent to the server
• confirm – a text of a confirmation message to display before sending data to the server. If the visitor click the Cancel button in the confirmation message, the request will be cancelled.
• extraFields - a JavaScript object, containing additional POST fields which you want to send to the AJAX handler. For example:

  <a href="#" onclick="
  return $(this).getForm().sendRequest(
  'shop:on_addToCart', {
  extraFields: {no_flash: 1},
  update: {
    'mini_cart': 'shop:mini_cart', 
    'product_page': 'product_partial'
  }})">Add to cart</a>

• preCheckFunction - function to execute before sending data to the server. Inside the function you can validate the form fields. The function should return TRUE if posting data is allowed. Example:

  <input value="Add To Cart" onclick="return
    $(this).getForm().sendRequest('shop:on_addToCart', 
      {
        preCheckFunction: function()
        {
          if (!$('#some_field').val().trim().length)
          {
            alert('Please enter something!');
            $('#some_field').focus();
            return false;
          }
    
          return true;
        }
      }
    )"
  type="button" />
  

• loadIndicator - options for the load indicator. Use the 'html' field to set the load indicator text. The default text is "<span>Loading...</span>". Example: 

  <a href="#" onclick="
  return $(this).getForm().sendRequest(
  'shop:on_addToCart', {
  extraFields: {no_flash: 1},
  loadIndicator: {html: '<span>Adding...</span>'}
  })">Add to cart</a>

For details about AJAX handlers supported by LemonStand modules please refer to the API section.

As from the version #1.11.74 of the Core module the jQuery front-end AJAX library supports simplified syntax for the AJAX requests - the getForm() call is not required and the sendRequest() method can be called directly on the element. The following expressions are similar. Old syntax:

onchange="$(this).getForm().sendRequest('shop:on_updatePaymentMethod')" ...

New syntax:

onchange="$(this).sendRequest('shop:on_updatePaymentMethod')" ...

The frontendready event

LemonStand front-end framework fires the frontendready event on the window object after loading all required front-end libraries. You can use this event instead the domready event to be sure that LemonStand front-end framework is ready. 

window.addEvent('frontendready', function(){
  alert('The framework is ready');
});

The onAfterAjaxUpdate event

The onAfterAjaxUpdate is triggered on the window object each time when an AJAX request updates an element on the page. The event handler function can accept two arguments - jQuery event object and the identifier of the updated element (in MooTools the handler has a single argument - the updated element). Example:

<script type="text/javascript">
  window.addEvent('onAfterAjaxUpdate', function(event, element_id){alert('Updated: '+element_id)});
</script>

Rendering partials instead of flash messages

If you pass the flash_partial POST parameter to the AJAX call, and call the flash_message() function in the updated page block, LemonStand will render a partial specified in the flash_partial parameter, instead of displaying a flash message. Example:

// The Add To Cart button which renders the 'add_to_cart_partial' partial on success
<input onclick="return $(this).getForm().sendRequest('shop:on_addToCart', {
 extraFields: {
   flash_partial: 'add_to_cart_partial'
 },
 update: {'mini_cart': 'shop:mini_cart', 'product_page': 'product_partial'}})"
 type="button" value="Add to cart"/>

If there any flash message has been assigned by the AJAX hander, you can access it inside the partial using the $message variable.

Using jQuery with MooTools

If you need to use both jQuery and MooTools libraries on your store pages, please use jQuery noConflict plugin to avoid conflicts between jQuery and MooTools frameworks. jQuery library should be linked and the noConflict() function should be called before you link MooTools libraries required by LemonStand. The js_combine() controllers method has two aliases for linking jQuery and noConflict scripts: jquery and jquery_noconflict. The jquery alias links the jQuery framework copy distributed with LemonStand, but you can link any other copy of the library instead of this alias. Example of using jQuery with LemonStand: 

// Old way: using the include_resources function

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
<script type="text/javascript">jQuery.noConflict();</script>

<?= include_resources() ?>

// New way: using the js_combine method:
  
<?= $this->js_combine(array(
  'jquery',
  'jquery_noconflict',
  'mootools',
  'ls_core_mootools')) ?>
  
// Linking jQuery copy from an external source
  
<?= $this->js_combine(array(
  'http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js',
  'jquery_noconflict',
  'mootools',
  'ls_core_mootools')) ?>

Please also remember that in noConflict mode you should use jQuery instead of $ in your jQuery calls.

The core:on_null event handler

The core:on_null event handler does not execute any specific code on the server and can be used for updating (redrawing) partials on a page. Example:

<input onclick="$(this).getForm().sendRequest('core:on_null', {
  update: {'mini_cart': 'shop:mini_cart'}})"
  type="button" 
  value="Update mini cart"/>

Data attributes API

As from the version #1.11.74 of the Core module the jQuery front-end AJAX library supports the data attributes API. The data attributes API simplifies the AJAX request triggering syntax, in many cases allowing to get rid of the JavaScript code in CMS pages, partials and layouts.

The data attributes API requires jQuery version 1.7 or higher.

The following data attributes are supported.

data-ajax-handler

Specifies the AJAX handler to execute. The event the AJAX request is triggered depends on the element the attribute is declared for:

• for the SELECT attribute the request is triggered when the selection is changed
• for buttons and anchors the request is triggered when the element is clicked
• for forms the request is triggered with the form is submitted.

The following statements are equivalent. Data attributes syntax:

<a href="#" data-ajax-handler="shop:on_evalShippingRate" ...
...
<?= open_form(array('data-ajax-handler'=>'shop:on_evalShippingRate')) ?>

JavaScript syntax:

<a href="#" onclick="return $(this).sendRequest('shop:on_evalShippingRate')" ...
...
<?= open_form(array('onsubmit'=>"return $(this).sendRequest('shop:on_evalShippingRate')")) ?>

data-ajax-update

Specifies a list of the page elements and partials to update when the AJAX request finishes. This attribute is equivalent for the update configuration parameter in the JavaScript code. The attribute value should list the page element identifiers and corresponding partials in the following format:

element_id=parital

Use the comma to list multiple elements and partials:

element_id_1=parital_1, element_id_2=parital_2

The following statements are equivalent. Data attributes syntax:

<a data-ajax-handler="shop:on_evalShippingRate" data-ajax-update="shipping_options=shop:estimated_shipping_options" ...

JavaScript syntax:

<a onclick="$(this).sendRequest('shop:on_evalShippingRate', {update: {'shipping_options': 'shop:estimated_shipping_options'}})"

data-ajax-confirm

This attribtue corresponds to the confirm option in the JavaScript sendRequest() syntax. Specifies a confirmation message to display before the request is sent. Example:

<a href="#" data-ajax-handler="shop:on_deleteCartItem" data-ajax-confirm="Do you really want to remove this item from the cart?" ...

data-ajax-extra-fields

This attribute corresponds to the extraFields option in the JavaScript sendRequest() syntax. Specifies extra field names and values to post to the server with the AJAX request. Field names and values should be specified in the following format: 

field_name='field_value'

Multiple fields can be separated with the comma: 

field_name='field_value', field_name_2='field_value_2'

The following statements are equivalent. Data attributes syntax:

<a href="#" 
    data-ajax-handler="shop:on_deleteCartItem" 
    data-ajax-confirm="Do you really want to remove this item from the cart?" 
    data-ajax-update="cart-content=shop:cart_content, mini-cart=shop:mini_cart"
    data-ajax-extra-fields="key='<?= $item->key ?>'"
>Remove</a>

JavaScript syntax: 

<a href="#" 
    onclick="return $(this).sendRequest(
        'shop:on_deleteCartItem', {
            confirm: 'Do you really want to remove this item from the cart?',
            update: {'cart-content': 'shop:cart_content', 'mini-cart' :'shop:mini_cart'},
            extraFields: {'key': '<?= $item->key ?>'}
        })"
>Remove</a>

data-ajax-indicator-html

Allows to set a custom loading indicator content. The default value is "<span>Loading...</span>".

Next: Caching API
Previous: Programming Pages
Return to LemonStand Back-End