LemonStand Documentation

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
  }
}

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

Below you will find list of events triggered by different LemonStand modules.

Core module events

Events provided by the LemonStand Core module.

User events - extending the user model, user-related user interface in the Administration Area

CMS module events

Events provided by the LemonStand CMS module.

CMS page events - extending the page model, page-related user interface in the Administration Area.

CMS partial events - extending the partial model, partial-related user interface in the Administration Area.

CMS template/layout events - extending the template model, template-related user interface in the Administration Area.

Shop module events

Events provided by the LemonStand Shop module. Some events listed below are described in the Extending existing models article.

Order events - extending order model, handling order status change, handling order information change, extending order-related user interface in the Administration Area.

Order item events - extending order items, processing order item updates

Customer events - extending the customer model and customer-related user interface in the Administration Area

Product events - extending the product model, product-related user interface in the Administration Area, handling file uploads on the Product Details page on the front-end website.

Product group events  - extending the product group model, product group related user interface in the Administration Area.

Extra option events - extending the product extra option model, extra option-related user interface in the Administration Area.

Product option events - extending the product option model, option-related user interface in the Administration Area.

Product type events -extending the product type model, product type related user interface in the Administration Area .

Product review events -extending the product review model, product review related user interface in the Administration Area .

Category events - extending the product category model and the category-related user interface in the Administration Area

Manufacturer events - extending the manufacturer model and manufacturer-related user interface in the Administration Area

Shopping cart item events - extending the shopping cart item model, handling shopping cart updates

Invoice events - enabling the invoice support, processing invoice items

Shipping method events - altering the shipping cost, etc.

Product search events - extending the product search

Reporting events - extending the reports

List of undocumented events

Documentation for the following events will be added later.

Shop module

  • shop:onBeforeOrdersRssExport
  • shop:onCustomerAfterDelete
  • shop:onExtendCustomerPreviewTabs
  • shop:onExtendOrderPaymentTransactionsToolbar
  • shop:onExtendOrderPreviewHeader
  • shop:onExtendOrderStatusForm
  • shop:onExtendOrderStatusModel
  • shop:onGetOrderStatusFieldOptions
  • shop:onGetOrderStatusFieldState
  • shop:onExtendProductPreviewHeader
  • shop:onExtendProductPreviewTabs
  • shop:onExtendProductPreviewToolbar
  • shop:onGetCategoryProductSortingQuery
  • shop:onGetOrderFieldState
  • shop:onGetProductFieldState
  • shop:onGetProductSortColumns
  • shop:onOrderCopyBillingAddress
  • shop:onPrepareProductListData
  • shop:onAfterOrderRecordFetch

Core module

  • core:onAfterSoftwareUpdate
  • core:onAfterSoftwareUpdateRequest
  • core:onBeforeArchiveCreate
  • core:onBeforeArchiveRestore
  • core:onBeforeDatabaseConnect
  • core:onBeforeFormRecordCreate
  • core:onBeforeFormRecordDelete
  • core:onBeforeFormRecordUpdate
  • core:onBeforeFormRender
  • core:onBeforeFormRenderPreview
  • core:onBeforeListExport
  • core:onBeforeListRecordDisplay
  • core:onBeforeSoftwareUpdate
  • core:onBeforeSoftwareUpdateRequest
  • core:onFileBeforeCreate
  • onFrontEndLogin
  • onLogin

CMS module

  • cms:onEvaluateCode
  • cms:onBeforeTrackingCodeInclude
  • cms:onGetPageBlockContent
  • cms:onAfterRenderPartial
  • cms:onBeforeDataExport
  • cms:onBeforeDataImport
  • cms:onBeforeRenderPartial
  • cms:onListPageEditorSidebarTabs
  • cms:onPreparePageListData
  • cms:onPreparePartialListData
  • cms:onPrepareTemplateListData

Backend module

  • backend:onBeforeRemoteEvent
  • backend:onBeforeRenderPage
  • backend:onBeforeRenderPartial
  • backend:onControllerReady

Next: shop:onExtendCustomerModel event
Previous: Using module access points
Return to Developing LemonStand modules