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

Shop_Category class

Defined in /modules/shop/models/shop_category.php, lines 41-1087
Inheritance Phpr_Extension » Phpr_Extensible » Phpr_Validatable » Db_Base » Db_WhereBase » Db_SqlBase » Db_ActiveRecord » Shop_Category
Author LemonStand eCommerce Inc.
Represents a product category. The class has fields and methods for accessing the category name and description as well as a list of the category products. The category class is proxiable.
This class is extended with Db_Act_As_Tree class which implements tree functionality. It allows categories to be accessed as a hierarchy with methods get_parent(), get_parents(), list_root_children() and list_children(). By default list_root_children() and list_children() methods sort items by name. To sort the category lists accordingly the order you set in the Administration Area, pass the front_end_sort_order value to the methods: 
$root_categories = Shop_Category::create()->list_root_children('front_end_sort_order');
$subcategories = $category->list_children('front_end_sort_order');

See Also

Public properties

Show inherited properties.

Property Type Description Defined By
auto_create_timestamps array a list of create timestamp columns. Db_ActiveRecord
auto_timestamps boolean determines whether create and update timestamp field should be set automatically. Db_ActiveRecord
auto_update_timestamps array a list of update timestamp columns. Db_ActiveRecord
code string the category API code. Shop_Category
description string specifies the category description in HTML format. Proxiable. Shop_Category
fetched array contains an associative array of table column values fetched from the database. Db_ActiveRecord
has_one array contains a list of Has One relations. Db_ActiveRecord
id integer specifies the category database identifier. Shop_Category
images Db_DataCollection a collection of images assigned to the category. Shop_Category
name string specifies the category name. Proxiable. Shop_Category
parent Shop_Category a reference to a parent category. Shop_Category
primary_key string specifies a name of the table primary key. Db_ActiveRecord
short_description string specifies the short description of the category as a plain text. Shop_Category
url_name string specifies the category URL name. Shop_Category
validation Phpr_Validation contains the model's validation object. Db_ActiveRecord

Public methods

Show inherited methods.

Method Description Defined By
add_form_custom_area() adds a form custom area. Db_ActiveRecord
add_form_field() makes a column visible in forms. Db_ActiveRecord
add_form_partial() adds a custom form partial. Db_ActiveRecord
add_form_section() adds a form section. Db_ActiveRecord
after_create_saved() called after a new object is saved to the database. Db_ActiveRecord
after_delete() called after an existing or new record is deleted from the database. Db_ActiveRecord
after_save() called after an existing or new record is created or updated in the database. Db_ActiveRecord
after_update() called after an existing record is updated in the database. Db_ActiveRecord
after_validation() triggered after the model column values are validated. Db_ActiveRecord
after_validation_on_create() triggered after a new model column values are validated. Db_ActiveRecord
after_validation_on_update() triggered after an existing model column values are validated. Db_ActiveRecord
as_options() returns an HTML string containing a set of OPTION elements corresponding to all product categories. Shop_Category
before_create() called before a new object is saved to the database. Db_ActiveRecord
before_save() called before an existing or new record is created or updated in the database. Db_ActiveRecord
before_update() called before an existing record is updated in the database. Db_ActiveRecord
before_validation() triggered before the model column values are validated. Db_ActiveRecord
before_validation_on_create() triggered before a new model column values are validated. Db_ActiveRecord
before_validation_on_update() triggered before an existing model column values are validated. Db_ActiveRecord
collection() executes the find_all() method and returns a collection. Db_ActiveRecord
columnValue() alias for the displayField() method. Db_ActiveRecord
define_column() adds a column definition to the model. Db_ActiveRecord
define_multi_relation_column() adds column definition for has_and_belongs_to_many or has_many relation field. Db_ActiveRecord
define_relation_column() adds column definition for has_on or belongs_to relation field. Db_ActiveRecord
delete() deletes the record from the database. Db_ActiveRecord
delete_form_field() deletes a form field by its corresponding column name. Db_ActiveRecord
displayField() returns a formatted column value. The field should be defined with define_column(), Db_ActiveRecord
find() finds a record by its primary key value. Db_ActiveRecord
find_all() finds all records and returns the Db_DataCollection object, containing a list of models. Db_ActiveRecord
find_by() finds a record by a field value. Db_ActiveRecord
find_column_definition() finds a column definition by the column name. Db_ActiveRecord
find_form_field() finds a form field definition by its corresponding column name. Db_ActiveRecord
get_url_name() returns the category URL name. Shop_Category
image_url() returns an URL of a category image thumbnail. Shop_Category
is_current() a helper function which returns TRUE in case if the category URL name matches a value passed to the first parameter. Shop_Category
join() adds a table to the query with JOIN statement. Db_SqlBase
limit() allows to limit the result of the find_all() method with the specified number of records. Db_ActiveRecord
list_manufacturers() returns a list of manufacturers of products belonging to the category. Shop_Category
list_products() returns a list of the category products. Shop_Category
list_related_records_deferred() returns a list of relation objects, taking into account deferred relations. Db_ActiveRecord
order() allows to order the result of the find_all() method by a specific table column. Db_SqlBase
orWhere() adds OR statement to the where clause, allowing to to limit the result of the find() and find_all() methods with SQL filter. Db_WhereBase
page_url() returns the category page URL, based on the URL passed in the parameter. Shop_Category
paginate() allows to limit the result of the find_all() method with a single page of records. Db_ActiveRecord
requestRowCount() returns a number of rows which would be returned with find_all() method. Db_ActiveRecord
save() saves record to the database. Db_ActiveRecord
where() allows to limit the result of the find() and find_all() methods with SQL filter. Db_WhereBase

Events

Event Description
shop:onAfterCategoryRecordFetch Triggered after a category record is fetched from the database.
shop:onExtendCategoryForm Allows to add new fields to the Create/Edit Category form in the Administration Area.
shop:onExtendCategoryModel Allows to define new columns in the product category model.
shop:onGetCategoryFieldOptions Allows to populate drop-down, radio- or checkbox list fields, which have been added with shop:onExtendCategoryForm event.
shop:onGetCategoryFieldState Determines whether a custom radio button or checkbox list option is checked.
shop:onGetCategoryProductSortingQuery Allows you to add a custom sorting field support to the Shop_Category::list_products() method.

Property details

code property

public string $code;
The category API code. You can use this field for finding a specific category in your API calls. Proxiable. Example: 
$category = Shop_Category::create()->find_by_code('computers');

description property

public string $description;
Specifies the category description in HTML format. Proxiable.

id property

public integer $id;
Specifies the category database identifier.

images property

public Db_DataCollection $images;
A collection of images assigned to the category. Each element in the collection is an object of the Db_File class. You can use this property directly to output category images, or use the image_url() method. Not proxiable.

name property

public string $name;
Specifies the category name. Proxiable.

parent property

public Shop_Category $parent;
A reference to a parent category. This field is NULL for the root-level categories. Proxiable.

short_description property

public string $short_description;
Specifies the short description of the category as a plain text. To output the short description use h() function to escape HTML-sensitive characters. Proxiable.

url_name property

public string $url_name;
Specifies the category URL name. The shop:category action uses this field to load a category by an URL. Usually you don't need to access the field directly. Use the page_url() method for creating links to category pages.

Method details

as_options() method

public static string as_options(integer $current_id=NULL)
$current_id integer specifies an identifier of current category.
{return} string returns HTML string.
Returns an HTML string containing a set of OPTION elements corresponding to all product categories. Nested categories are indented. The method does not take into account category visibility and always return all categories. You can use this method for creating a drop-down category selector. The optional parameter allows you to specify a category identifier to be selected by default. This method is not proxiable. Example: 
<select name="category_id">
  <?= Shop_Category::as_options() ?>
</select>

get_url_name() method

public string get_url_name()
{return} string returns the category URL name.
Returns the category URL name. If nested category URLs and Prepend parent category URL options are enabled on System/Settings/eCommerce Settings page, the method returns category URL name with the parent category URLs prepended. This method is proxiable.

image_url() method

public string image_url(integer $index=0, mixed $width='auto', mixed $height='auto', boolean $as_jpeg=true, array $params=array( 'mode'=>'keep_ratio'))
$index integer specifies the zero-based image index.
$width mixed specifies the thumbnail width. Use the 'auto' word to scale image width proportionally.
$height mixed specifies the thumbnail height. Use the 'auto' word to scale height width proportionally.
$as_jpeg boolean determines whether JPEG or PNG image will be created.
$params array a list of parameters.
{return} string returns the image URL relative to the website root.
Returns an URL of a category image thumbnail. Use this method for displaying category images. The $width and $height parameters are thumbnail width and height correspondingly. You can use exact integer values, or word 'auto' for automatic image resizing. The $as_jpeg parameter allows you to generate PNG images with transparency support. By default the parameter value is TRUE and the method generates a JPEG image. The $params array allows to pass parameters to image processing modules (which handle the core:onProcessImage event). This method is proxiable. The following line of code outputs a thumbnail of the first category image. The thumbnail width is 100 pixels, and thumbnail height is calculated by LemonStand to keep the original aspect ratio. 
<img src="<?= $category->image_url(0, 100, 'auto') ?>"/>

See Also

is_current() method

public boolean is_current(string $current_category_url_name, boolean $look_in_subcategories=false)
$current_category_url_name string specifies URL name of a current category.
$look_in_subcategories boolean determines whether the method should also examine subcategories.
{return} boolean returns TRUE if the category is current. Returns FALSE otherwise.
A helper function which returns TRUE in case if the category URL name matches a value passed to the first parameter. If the second parameter is TRUE, the function also examines all subcategories. It allows to mark a category as current in the category list, if the category itself is not current, but one of its subcategories is current. This method is proxiable.

list_manufacturers() method

public Db_DataCollection list_manufacturers()
{return} Db_DataCollection returns a collection of Shop_Manufacturer objects.
Returns a list of manufacturers of products belonging to the category. This method is not proxiable. The method returns an instance of the Db_DataCollection class. Each element in the collection is an object of Shop_Manufacturer class. You can output a list of a category manufacturers with the following code: 
<ul>
  <?
    $manufacturers = $category->list_manufacturers();
    foreach ($manufacturers as $manufacturer):
  ?>
    <li><?= h($manufacturer->name) ?></li>
  <? endforeach ?>
</ul>

list_products() method

public Shop_Product list_products(array $options=array())
$options array specifies the method options.
{return} Shop_Product returns an object of the Shop_Product class.
Returns a list of the category products. This method is not proxiable. The result of this function is an object of the Shop_Product class. To obtain a collection of all category products call the find_all() method of the returned object. 
$full_product_list = $category->list_products()->find_all();
The find_all() methods returns an object of the Db_DataCollection class, which you can use as a usual array. You can use the result of the method for further processing, for example for paginating the category products list. Please read the Displaying a list of products article for the examples.
You can pass an array of options to the method. The supported options are sorting, manufacturer_url_name and apply_top_products. By default the product list is sorted by product name. You can sort products by another field. Also, you can sort the product list by multiple fields. 
$product_list = $category->list_products(array(
  'sorting'=>array('price', 'name')
));
The supported fields you can sort the products by are:
  • name - sort the product list by name
  • price - sort the product list by the base price
  • sku - sort the product list by SKU
  • weight - sort the product list by weight
  • width - sort the product list by width
  • height - sort the product list by height
  • depth - sort the product list by depth
  • created_at - sort the product list by the product creation date
  • rand() - sort products randomly
  • manufacturer - sort products by the manufacturer name
  • expected_availability_date - sort products by the availability date
You can add desc suffix to the sort field name to enable the descending sorting. For example, to sort the product list by price in descending order, you can use the following code: 
$product_list = $category->list_products(array(
  'sorting'=>array('price desc')
));
You can add custom sorting fields with shop:onGetCategoryProductSortingQuery event.
Note that if there are top products defined for the category, they are always returned in the beginning of the list, and their order is independent on the sorting parameters you specify in the method call. You can disable the top products feature and display them on their normal positions by passing FALSE value to the apply_top_products option. 
$product_list = $category->list_products(array(
  'sorting'=>array('price desc'),
  'apply_top_products'=>false
));
You can filter category products with a specific manufacturer by passing the manufacturer's URL name to the manufacturer_url_name element: 
$product_list = $category->list_products(array(
  'manufacturer_url_name'=>'lemonstand_ecommerce_inc'
));
If you need to obtain a number of products in a category you can use the following code: 
$product_num = $category->list_products()->requestRowCount();

See Also

page_url() method

public string page_url(string $base_url)
$base_url string specifies the base category page URL.
{return} string returns the category page URL.
Returns the category page URL, based on the URL passed in the parameter. Use this method to create links to categories. If there is no custom page assigned to a category, this method just adds the category URL name to the base URL specified in the parameter. So, if you passed the category string to the method, it would return strings like /category/computers or /category/monitors. For categories which have a custom page assigned and no URL Name assigned, the method returns the custom page URL. For categories with both a custom page and URL Name specified, the method returns an URL of the custom page plus the value of the URL Name parameter: /custom_page/url_name . This method is proxiable. Usage example: 
<a href="<?= $category->page_url('/category') ?>"><?= $category->name ?></a>

See Also