Handling LemonStand Events

Handling LemonStand events allows you to override or extend standard functionality of the application in many ways. For example, you can extend existing LemonStand models (customers, products etc), customize visitors shopping experience, execute some code before a front-store page is displayed and do other things. The list of events is growing constantly. Please contact us if you need to handle some event which is not listed below.

Handling events

To handle LemonStand events you need to develop a simple module. The process of developing LemonStand modules is described in this article. A simplest module can have only two files - the module information class and the module version information file. Event handlers can be defined in the module information class. To subscribe to system events use the subscribeEvents() method of the module information class. For example:

public function subscribeEvents()
{
  Backend::$events->addEvent('shop:onNewOrder', $this, 'on_new_order');
}

The code subscribes a module information class to the shop:onNewOrder event. When it is triggered the on_new_order method (specified in the third parameter) will be called. This method (event handler) must be defined in the module information class. There are no special rules for event handler function names. Below is an example of the event handler code:

public function on_new_order($order_id)
{
  // Find the order
  $order = Shop_Order::create()->find_by_id($order_id);
  if ($order)
  {
    // Do something with the order object
  }
}

Important! The subscribeEvents() method should not contain any code except addEvent() calls. 

Invoking custom module events from standard LemonStand pages

In some cases you will need to call an event handler in your module from a standard LemonStand page. The custom event solution allows you to trigger any event on some LemonStand pages in order to handle them in your custom module. The feature is supported in all back-end controllers, but implementation for the Products and Orders controllers differs from implementation in other controllers. 

To call an event from your module, trigger a standard AJAX request to the onCustomEvent handler. In the extra POST fields specify the event name you want to be invoked on the server. The event handler should accept 2 parameters - the controller object and the record identifier, which you can use for loading the object from the database. For the Products and Orders controllers the second parameter is the product and order object. Thus, on the Edit Order page the second parameter will be the Shop_Order object, and on the Edit Product page the second parameter will be the Shop_Product object. Example:

// Button on the Order Preview page, which opens a popup window 
// with a content provided by the Subscriptions module
<?= backend_ctr_button('Generate subscription invoice', 'generate_subscription_invoice',
  array('href'=>'#', 'onclick'=>"new PopupForm(
    'onCustomEvent', {
        ajaxFields: {custom_event_handler: 'subscriptions:onGenerateInvoice'}
     }); return false;
")) ?>
  
// Event subscription in the Subscriptions module
public function subscribeEvents()
{
  Backend::$events->addEvent('subscriptions:onGenerateInvoice', $this, 'generate_order_invoice');
}
  
function generate_order_invoice($controller, $order)
{
  $controller->renderPartial(PATH_APP.'/modules/subscriptions/partials/_generate_invoice.htm');
}

List of LemonStand events

You can find the full list of LemonStand events in the API section.

Next: Reporting events
Previous: Working with the Database
Return to Extending LemonStand