LemonStand - Shop

Shop_Category

The Shop_Category class represents a category of products in the online store. The class has fields and methods for accessing the category name and description as well as a list of the category products.

Parent class: Db_ActiveRecord

For information about displaying a list of categories, or creating a Category page, please refer the following articles:

Class fields

$name – a category name. Proxiable.
$description – category description in HTML format. Proxiable.
$short_description – short description of a category as a plain text. To output the short description, please use the h function to escape HTML-sensitive characters. Proxiable.
$url_name – a category URL name. The shop:category action uses this field to load a category by an URL parameter. Usually you don't need to access the field directly. Use the page_url method for creating links to category pages.
$parent – a reference to a parent category. This field is NULL for the root-level categories. Proxiable.
$images – a collection of images assigned to a category (an object of the Db_DataCollection class). Each image in the collection is an object of the Db_File class. You can use this field directly to output category images, or use the image_url method. Not proxiable.
$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');
```

Class methods

page_url($base_url) – returns a 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. So, if you pass the category string to the method, it will return strings like category/computers or category/monitors. For categories which have a custom page assigned and no URL Name assigned, the function will return the custom page URL. For categories with both a custom page and URL Name specified, the function will return an URL of the custom page plus the value of the URL Name parameter: custom_page/url_name . See the Displaying a list of categories article for the usage example. Proxiable.
image_url($index, $width, $height, $as_jpeg = true, $params = array()) – returns a relative URL of a category image thumbnail, or NULL if an image with specified index is not found. Use this method for displaying category images. The first parameter specifies a zero-based image index. The second and third 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. Pass the FALSE value to the parameter to generate a PNG image. The $params array allows to pass parameters to image processing modules (which handle the core:onProcessImage event). 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. Proxiable.
```
<img src="<?= $category->image_url(0, 100, 'auto') ?>"/>
```
list_products([$options]) - returns a list of the category products. 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() methods of the method result.
```
$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 list_products() 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 optional method parameter. The supported options are the sorting and the 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 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 the " 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')
))
```
Please remember 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 URL name to the manufacturer_url_name index of the list_products() method:
```
$product_list = $category->list_products(array(
  'manufacturer_url_name'=>'limewheel_creative_inc'
))          
```
If you need to obtain a number of products in a category you can use the following way:
```
$product_num = $category->list_products()->requestRowCount(); 
```
list_root_children($sort_column = 'name') - returns a list of the top-level categories. Proxiable. The optional parameter allows you to sort the category list. By default the method returns a list of categories sorted by name. To sort the category list accordingly the order you set in the Administration Area, pass the 'front_end_sort_order' value to the method:
```
$root_categories = Shop_Category::create()->list_root_children('front_end_sort_order');
```
list_children($sort_column = 'name') - returns a list of subcategories. Proxiable. The optional parameter allows you to sort the category list. By default the method returns a list of subcategories sorted by name. To sort the category list accordingly the order you set in the Administration Area, pass the 'front_end_sort_order' value to the method:
```
$subcategories = $category->list_children('front_end_sort_order');
```
get_parents($include_this = false) - returns all parent categories of the current category. Proxiable. The optional parameter allows to include a current category to the result list. Returns an array of Shop_Category objects. You can use this method for displaying a path to a category, for example on the product page, in the following format:
Category: Crafts, Stationery and more » Art
Example code for a displaying a category path on a product page:
```
<p>Category:    
  <?
    $categories = $product->category_list[0]->get_parents(true);
    $cnt = count($categories);
    foreach ($categories as $index=>$category):
  ?>
    <a href="<?= $category->page_url('/category') ?>"><?= h($category->name) ?></a>
    <? if ($index < $cnt-1) echo "»" ?>
  <? endforeach ?>
</p>
```
get_parent() - returns a parent category of the current category. Proxiable.
list_manufacturers() - returns a list of manufacturers of products which belong to the category. Not proxiable. The method returns an instance of the Db_DataCollection class. Each element in the collection is an instance of the 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>
```
is_current($category_url_name, $look_in_subcategories = false) - 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. Proxiable.
get_url_name() - returns category URL name. If nested category URLs and Prepend parent category URL options are enabled, the method returns category URL name with parent category URLs prepended. Proxiable.
as_options($current_id = null) - a static method, 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. Not proxiable.. Example:
```
<select name="category_id">
  <?= Shop_Category::as_options() ?>
</select>
```

LemonStand Documentation

Shop_Category

Class fields

Class methods

See also: