Category
Extends Object. A Category is a shop's department promoting products and/or sub-categories. A "category" variable containing a Category object is automatically instantiated on URLs governed by the category controller.
A category
variable containing a Category object is automatically instantiated on category pages.
Templates for categories should be located within a Theme's
~/theme/category
directory. These templates will have access to the current category's
properties and methods described on this page.
Properties of your category can be output using the existing category variable.
<div>
<h1>{{ category.title }}</h1>
<p>{{ category.description }}</p>
</div>
Programmatically finding categories
You can also gain access to a category and its properties from any other template programmatically.
If you need to find multiple categories you should use the CategorySearch object instead - it's more efficient.
We now recommend using the new find methods when fetching a single category:
-
findById()
- find a category by its System ID. -
findByAlias()
- find a category by its Alias/URI.
The example below shows how you can find a category by its system ID.
<?ev
var myCategory = new Category();
if (myCategory.findById(1234)) {
print(myCategory.title + ' was found');
} else {
print('Category was not found');
}
?>
Instantiation
Accessing any Category in your shop can be achieved from anywhere within your website and not just from Product Category governed pages. This can be done by instantiating a new Category object and supplying the page's URL:
<?ev
// new Category() class method
var shop = new Category('/shop');
?>
Note hard coding URLs in this manner can be open to error if the URL no longer exists.
Construct parameters |
---|
reference
String |
Url |
Number
The page reference is either a String/Url representing
the URL relative to root (e.g. /shop represents your shop's root category), or a Number representing
the category For international and multi-lingual sites you should use the default URL as the reference for the category and not the localised version. Evance will automatically correct the URL format for you once the Category object is retrieved. |
Properties |
---|
created
Date
The date the page was created represented as a Date object. |
description
String
The short description for the page represented as a String. Pages do not have a single content block as they may have any number of editable regions. These are represented as fragments that should be rendered via the <ev:editable>
tag.
|
featured
Boolean
True if the category is featured, else false. |
filterable
Boolean
True if the category is has filtering enabled, else false. |
hasChildren
Boolean
True if the category has sub-categories, else false. |
id
Number
The system ID for the category. |
image
Url
An alternative image Url chosen to represent this category. This is called thumbnail for historic reasons, but may be of any size. The image is generally shown on the category page, whilst thumbnail (below) is generally shown on the parent category page. |
modified
Date
The date the page was last modified as a Date object. |
parentId
Number
The System ID of the parent category. |
template
Template
The current Template for the Category. |
thumbnail
Url
The image Url chosen to represent this category. This is called thumbnail for historic reasons, but may be of any size. The thumbnail is generally shown on the parent category page, whilst image (above) is generally shown on the category page. |
title
String
The title of the department. |
url
Url
The URL of the category. If you have an international website this Url will represent the current Locale of your website. |
Methods |
---|
ancestors()
Alias of |
assets()
Object
Returns an Object containing assets for the Category. |
children([limit])
CategoryCollection
Returns all or a number of child categories in order of sequence as they appear within the Product Category tree manager. Parameterslimit
Number
Optional. The number of Categories to return. |
contacts()
Contact[]
Returns an array of Contacts associated with the category, or from its closest parent with Contacts. This functionality is intended to show a list of sales advisors for products contained within the Category. This may be helpful where product ranges are complex or where a number of products are presented with "Price on Application" (POA). For international sites with multiple locales, each Contact assigned to a Category may have zero or more territories.
Non-international sites should not implement territories on Contacts. |
descendants()
CategoryCollection
Returns all sub-categories recursively as a single collection excluding the current Category. |
filters()
CategoryFilterCollection
Returns all filters for the current category, or the closest category with an assigned filter set. Filters are assigned to a Category within the Product Categories manager. |
findByAlias(alias)
Boolean
Find a Category by its unique alias/URI. Returns true if the category was found, and false if not found. Parameters
Example
The alias supplied must be the URI path to the page (e.g. '/shop/fashion'). If the path includes a locale prefix (e.g. '/en-gb/shop/fashion') Evance will globalise the URI prior to lookup. |
findById(id)
Boolean
Find a category by its system ID. Returns true if the page was found, and false if not found. Parameters
Example
|
fragment(reference)
Object | false
Returns an Object containing a Content Fragment matching the reference name
provided, or false if the fragment does not exist.
|
fragments()
Object
Returns an Object containing Content Fragments, including the Category's primaryContent and secondaryContent fragments.
|
hasChildren()
Boolean
Returns true if the Category has one or more sub-categories.
|
hasFragment(reference)
Boolean
Returns true if the Category has a Content Fragment matching the reference supplied.
|
next([limit])
Category |
CategoryCollection |
null
Get the next sibling of the current category as a Category object if one exists or
Parameterslimit
Number
Optional. Use a limit to return the next N number of Category siblings. |
parent()
Category | null
Returns the parent Category, or null if the current Category is the root for
the Website.
|
parents()
CategoryCollection
Get the list of parent category objects i.e. the breadrcumbs of the current category up to the top ancestor. Returns a CategoryCollection of page objects with the closest parent first. |
prev([limit])
Alias of Category.previous() .
|
previous([limit])
Category |
CategoryCollection |
null
Returns previous sibling of the current category or Parameterslimit
Number
Optional. Use a limit to return the previous N number of Category siblings. |
products()
ProductSearch
Returns a Product Search object pre-configured with the following:
|
share()
PageSharer
The PageSharer object allows you to generate social media share links from the Category data. |
template()
Template | null
Returns the Template Object for the Category if a Template has been assigned to the Category, or Null if it uses the default. |
toString()
String
Returns the title of the Category. |
topAncestor()
Category
Returns the top shop level Category. |
tree()
CategoryCollection
Returns all sub-categories recursively as a single collection including the current Category. |