LemonStand Documentation

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').value.trim().length)
        {
          alert('Please enter something!');
          $('some_field').focus();
          return false;
        }
  
        return true;
      }
    }
  )"
type="button" />

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

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 a single parameter - the identifier of the updated element. Example:

<script type="text/javascript">
  window.addEvent('onAfterAjaxUpdate', function(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"/>

Next: Db_ActiveRecord
Previous: post_array_item
Return to Reference