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:

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 id.

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 Category.parents()

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.

Parameters

limit 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.

  • A Contact with zero territories will be made available across all locales.
  • A Contact with one or more territories must have a country match with the current locale.

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

alias String
The root URL/alias of the Category (e.g. '/shop/cookware')

Example

<?ev
    var fashion = new Category();
    
    if (fashion.findByAlias('/shop/fashion')) {
        // category found
    } else {
        // category not found
    }
?>


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

id Number
The system ID of the Category.

Example

<?ev
    var myCategory = new Category();
    
    if (myCategory.findById(1)) {
        // category found
    } else {
        // category not found
    }
?>
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 null if not. The order of categories is always in order of sequence:asc. When a limit is supplied returns a collection of Category objects.

Parameters

limit 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 null if unavailable. The order of categories is always in order of sequence:asc. When a limit is supplied returns a collection of Category objects.

Parameters

limit 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:

  • Products will be sorted based upon the sort order defined by the Category's settings.
  • The limit will default to the number defined within the Category's template, or 10 if unavailable.
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.