This is the API docs for LemonStand V1, which has been discontinued. LemonStand is now a cloud based platform, available at lemonstand.com.

LemonStand API

Cms_Controller class

Defined in /modules/cms/classes/cms_controller.php, lines 15-1708
Author LemonStand eCommerce Inc.
CMS controller class is responsible for pages, partials and templates rendering It provides methods required for building a website, acting as a glue for website elements. The instance of the class is created automatically by LemonStand and available in the code of any page, template and partial as $this variable.

Public properties

Property Type Description Defined By
customer Shop_Customer a reference to the current customer. Cms_Controller
data array a filed for passing variables from actions to pages and partials. Cms_Controller
page Cms_Page a reference to the current page. Cms_Controller
request_params array keeps the page request parameters. Cms_Controller

Public methods

Method Description Defined By
action() executes the page CMS action. Cms_Controller
create_redirect_url() creates a redirection URL string suitable for using with redirect_url() method. Cms_Controller
css_combine() combines and minifies multiple CSS files. Cms_Controller
exec_action_handler() executes an AJAX handler directly. Cms_Controller
get_customer() returns the current customer object. Cms_Controller
get_customer_group() returns a customer group the current customer belongs to. Cms_Controller
get_customer_group_id() returns an identifier of a customer group the current customer belongs to. Cms_Controller
get_instance() returns the current CMS Controller object. Cms_Controller
js_combine() combines and minifies multiple JavaScript files. Cms_Controller
redirect_url() returns URL of a page which was originally requested before the redirection. Cms_Controller
render_block() outputs a page block contents. Cms_Controller
render_head() outputs the page head declarations block contents. Cms_Controller
render_page() renders the page. Cms_Controller
render_partial() outputs a partial with the specified name. Cms_Controller
request_param() extracts a page request parameter from the requested URL by the parameter index. Cms_Controller

Events

Event Description
cms:onAfterDisplay Triggered after a front-end page is displayed.
cms:onAfterEvalPageContent Triggered after a page content is evaluated.
cms:onAfterHandleAjax Triggered after an AJAX request is handled.
cms:onAfterRenderPartial Triggered before a partial is rendered.
cms:onApplyPageSecurity Allows to perform security checks before a page is displayed.
cms:onBeforeDisplay Triggered before a front-end page is displayed.
cms:onBeforeEvalPageContent Triggered before a page content is evaluated.
cms:onBeforeHandleAjax Triggered before an AJAX request is handled.
cms:onBeforeRenderPartial Triggered before a partial is rendered.
cms:onBeforeResourceCombine Allows to implement custom resource combining approaches.
cms:onBeforeRoute Allows to override the default front-end page routing process.
cms:onBeforeTrackingCodeInclude Allows to deny Google Analytics tracking code output on a page.
cms:onEvaluateCode Triggered before PHP code on a page, partial or layout code is evaluated.
cms:onGetCustomerGroupId Allows to override the default current customer group identifier in the front-end requests.
cms:onPageNotFound Allows to override the default processing of not found front-end pages.

Property details

customer property

public Shop_Customer $customer;
A reference to the current customer. This variable is NULL if there is no customer logged in.

data property

public array $data;
A filed for passing variables from actions to pages and partials. See the Actions page for details. The contents of this field is automatically converted to PHP variables when the page is rendered.

See Also

page property

public Cms_Page $page;
A reference to the current page. You can access the current object in any CMS template with the following code: 
$page = $this->page;

request_params property

public array $request_params;
Keeps the page request parameters. Use request_param() method to access page parameters by index.

Method details

action() method

public void action()
Executes the page CMS action. Use this method in custom AJAX handlers to force the controller to execute the default page action. The following example demonstrates how to execute the page action in an AJAX handler. 
function my_handler($controller)
{
  $controller->action();
}

See Also

create_redirect_url() method

public string create_redirect_url()
{return} string returns then encoded URL string.
Creates a redirection URL string suitable for using with redirect_url() method. A result of this method can be attached to the Login page URL. 
Please <a href="<?= root_url('login').'/'.$this->create_redirect_url() ?>">login</a>.

See Also

css_combine() method

public string css_combine(array $files, array $options=array(), boolean $show_tag=true)
$files array a list of files or file aliases to include to the page.
$options array specifies a list of options.
$show_tag boolean determines whether HTML link tag should be generated.
{return} string returns a string containing a reference to the resource files.
Combines and minifies multiple CSS files. Please read Combining and minifying JavaScript and CSS files documentation article for details about the method usage. The $files parameter should contain a list of СЫЫ files to include. The files must be specified relative to the LemonStand root directory. Remote resources should be prefixed with http:// or https:// protocol specifier. Theme resources should be prefixed with @ symbol. Alongside with the file paths, the $files array accepts file aliases, which point to LemonStand built-in front-end CSS libraries:
  • ls_styles - includes LemonStand front-end CSS styles file
The $options parameter accepts the following parameters:
  • reset_cache - reset the file cache. LemonStand caches combined files on the server. By default it updates the cache as soon as any of the cached files is changed. However it cannot track updates of remote files. You can use this parameter for forcing LemonStand to update the file cache.
  • skip_cache - do not cache the combined files.
  • src_mode - do not minify the combined files (leave the comments, and formatting as is).
LemonStand automatically processes relative URLs in the CSS files, so you can use CSS files from different locations and it will not break images. The $show_tag parameter determines whether link HTML tag should be returned. The default value is TRUE, meaning that the tag is returned. If you want to create the tag manually pass FALSE to the parameter.
The following code adds LemonStand front-end CSS file, styles.css file and FancyBox CSS file to the page (the example assumes that FancyBox files have been uploaded to the /resources directory). 
<head>
<?= $this->css_combine(array(
  'ls_styles',
  '/resources/css/styles.css',
  '/resources/fancybox/jquery.fancybox-1.3.4.css'
)) ?>
...
The returning value of this method can be affected by cms:onBeforeResourceCombine event.

See Also

exec_action_handler() method

public void exec_action_handler(string $handler)
$handler string specifies a handler name, for example shop:on_addToCart
Executes an AJAX handler directly. This method is extremely helpful for customizing default server handlers. It allows to wrap any code around a standard LemonStand handler. The following example demonstrates a custom AJAX event handler, which can be used for implementing a single-form checkout process. This code should be entered to the AJAX Handlers field of the AJAX tab on the Create/Edit Page page. 
function my_custom_checkout($controller, $page, $params)
{
  if (!Shop_Cart::list_active_items())
    throw new Exception('Your cart is empty.');

  $controller->exec_action_handler('shop:on_checkoutSetBillingInfo');

  Shop_CheckoutData::copy_billing_to_shipping();
  Shop_CheckoutData::set_payment_method(
    Shop_PaymentMethod::find_by_api_code('no_payment')->id
  );
  Shop_CheckoutData::set_shipping_method(
    Shop_ShippingOption::find_by_api_code('free_shipping')->id
  );
  Shop_CheckoutData::place_order($controller->customer);

  Phpr::$response->redirect('/receipt');
}

get_customer() method

public static Shop_Customer get_customer()
{return} Shop_Customer returns the customer object or NULL.
Returns the current customer object. If a customer is not logged in, or the script is working out of the context of a front-end page request, returns NULL.

get_customer_group() method

public static Shop_CustomerGroup get_customer_group()
{return} Shop_CustomerGroup returns a customer group object.
Returns a customer group the current customer belongs to. If the customer is not logged in, returns the Guest group object.

get_customer_group_id() method

public static integer get_customer_group_id()
{return} integer returns an identifier of the customer group.
Returns an identifier of a customer group the current customer belongs to. If the customer is not logged-in, the method returns an identifier of the Guest group. The result of this method can be altered by the cms:onGetCustomerGroupId event handler.

get_instance() method

public static Cms_Controller get_instance()
{return} Cms_Controller returns the controller object or NULL.
Returns the current CMS Controller object. This method allows to get access to the controller object outside of the CMS templates. The method returns NULL if there is no CMS Controller instance available. This means that the script works out of the front-end page rendering context.

js_combine() method

public string js_combine(array $files, array $options=array(), boolean $show_tag=true)
$files array a list of files or file aliases to include to the page.
$options array specifies a list of options.
$show_tag boolean determines whether HTML script tag should be generated.
{return} string returns a string containing a reference to the resource files.
Combines and minifies multiple JavaScript files. Please read Combining and minifying JavaScript and CSS files documentation article for details about the method usage. The $files parameter should contain a list of JavaScript files to include. The files must be specified relative to the LemonStand root directory. Remote resources should be prefixed with http:// or https:// protocol specifier. Theme resources should be prefixed with @ symbol. Alongside with the file paths, the $files array accepts file aliases, which point to LemonStand built-in front-end JavaScript libraries:
  • mootools - included MooTools core script
  • ls_core_mootools - includes LemonStand MooTools-specific front-end library/li>
  • jquery - includes jQuery core script
  • jquery_noconflict - includes jQuery noConflict() call
  • ls_core_jquery - includes LemonStand jQuery-specific front-end library
The $options parameter accepts the following parameters:
  • reset_cache - reset the file cache. LemonStand caches combined files on the server. By default it updates the cache as soon as any of the cached files is changed. However it cannot track updates of remote files. You can use this parameter for forcing LemonStand to update the file cache.
  • skip_cache - do not cache the combined files.
  • src_mode - do not minify the combined files (leave the comments, and formatting as is).
The $show_tag parameter determines whether script HTML tag should be returned. The default value is TRUE, meaning that the tag is returned. If you want to create the tag manually pass FALSE to the parameter.
The following code adds jQuery, LemonStand jQuery library and FancyBox plugin to the page (the example assumes that FancyBox files have been uploaded to the /resources directory). 
<head>
  <?= $this->js_combine(array(
    'jquery',
    'ls_core_jquery',
    '/resources/fancybox/jquery.fancybox-1.3.4.pack.js'
  )) ?>
  ...
The returning value of this method can be affected by cms:onBeforeResourceCombine event.

See Also

redirect_url() method

public string redirect_url(string $default, integer $index=0)
$default string specifies the default page URL. This value will be used if the Login page was opened directly.
$index integer specifies the page URL segment index to extract the original page URL. The built-in authentication mechanism passes the URL in the first segment, which zero-based index is 0.
{return} string returns the URL of the originally requested page.
Returns URL of a page which was originally requested before the redirection. If a not logged on visitor tries to access a page, which can only be accessed by registered customers, he is redirected to the Login page. This function returns the URL of the original page, which allows to redirect the customer back to that page after the successful log in. This method is useful for creating the customer login page. The following example creates a hidden field with name redirect which is supported by the shop:login action. 
<input type="hidden" value="<?= $this->redirect_url('/') ?>" name="redirect"/>
There is the Twig function redirect_url() as well.

See Also

render_block() method

public void render_block(string $block_code, string $default=NULL)
$block_code string specifies a code of the block to output.
$default string string to output if the block is not defined on the page.
Outputs a page block contents. Use this method for displaying code block defined on the Head & Blocks tab of the Create/Edit Page form. If the specified block does not exist no error will occur. Please read this article for details. Example: 
<? $this->render_block('sidebar') ?>

See Also

render_head() method

public void render_head()
Outputs the page head declarations block contents. You can define the header content on the Head & Blocks tab of the Create/Edit Page form. Please read this article for details. Example: 
<? $this->render_head() ?>

See Also

render_page() method

public void render_page()
Renders the page. Call this method inside layouts to output a current page content. Example: 
<? $this->render_page() ?>

See Also

render_partial() method

public mixed render_partial(string $name, array $params=array(), array $options=array( 'return_output'=>false))
$name string specifies the partial name.
$params array a list of parameters to pass to the partial.
$options array a list of options.
{return} mixed returns NULL by default. Returns the partial content if the $options parameters has return_output element with value TRUE.
Outputs a partial with the specified name.
The following code renders the product_list partial and passes the products variable to it. 
$this->render_partial('product_list', array('products'=>$category->products));
The $options parameter supports the following elements:
  • return_output - determines whether the method should return the partial content instead of displaying it.
  • cache - enables the caching.
  • cache_vary_by - array or string (for a single value parameter). Specifies parameters the cache should depend on. For example, you can create different versions of a partial cache for different pages (if you reuse a partial on different pages), or for different customers, customer groups, and other parameters.
  • cache_versions - array or string (for a single value parameter). Allows to specify names of content types which versions the partial cache should depend on. You can use the following values in this parameter: cms, catalog, blog. If you specify the catalog content type, the partial will be automatically recached if you update the catalog (add/update/delete products, apply catalog price rules, update categories, etc). The cms and blog parameters work in the same way. but watch updates of the CMS and blog content.
  • cache_ttl - cache item time-to-live, in seconds. Please note, that file-based caching does not support per-item TTL setting and always use the global TTL value specified in the caching configuration parameters.
The following example renders a partial with caching: 
<?
  $this->render_partial('my_partial', 
     array(), // No partial-specific parameters (to simplify the example)
     array(
        'cache'=>true,// Enable caching
        'cache_vary_by'=>array('url'), // We are going to reuse this partial on different pages, but its content can be different for different pages so we want to create different partial cache versions for different pages
        'cache_versions'=>array('catalog'), // The partial should be recached then the catalog updates
        'cache_ttl'=>1800 // Recache each 30 minutes
    )
  ) 
?>

See Also

request_param() method

public string request_param(integer $index, mixed $default=NULL)
$index integer specifies the parameter index.
$default mixed specified a default value to return in case if the parameter with the specified index does not exist.
{return} string returns the parameter value or the default value.
Extracts a page request parameter from the requested URL by the parameter index. When LemonStand parses an URL, it considers all URL segments following a page address as parameters. For example, if there was a page with address /category (the value, specified in the Page URL field of the Create/Edit Page form), and you opened the page using URL /category/computers, the word computers would be considered as a parameter with index 0. The second optional parameter specifies a default value for a parameter. It is used if a parameter with the specified index is not found.
The $index parameter can take negative values. In this case the method returns index'th parameter from the end of the URL. For example, if the input URL was /category/men/jumpers/2, calling the method with $index=-1 would return 2 (i.e. the first parameter from the end).