Product

Extends Object. Product objects appear throughout an Evance shop and support a number of product types - primarily physical or digital goods.

A product variable containing a Product object is automatically instantiated on product pages. 

Templates for products should be located within a Theme's   ~/theme/productdirectory. These templates will have access to the current product's properties and methods described on this page.

Properties of your product can be output using the existing product variable.

<div>
    <h1>{{ product.title }}</h1>
    <p>{{ product.description }}</p>
    <p>{{ product.price }}</p>
</div>


Due to the configuration options available, products are one of the largest objects in Evance. To explore a product in-depth we recommend using the dump() function or referring to this page whenever you feel stuck.

Programmatically finding products

You can also gain access to a product and its properties from any page programmatically.
If you need to find multiple products you should use the ProductSearch object instead as it will be more efficient than calling multiple queries.

We now recommend using the new find methods when fetching a single product:

The example below shows how you can find a product by its system ID:

<?ev
    var myProduct = new Product();
    
    if (myProduct.findById(1234)) {
        print(myProduct.title + ' was found');
    } else {
        print('Product was not found');
    }
?>

Instantiation

Finding product data may be done when instantiating a new Product object and supplying the page's URL or ID. However, we now recommend using the newer 'find' methods (as described above)


<?ev
    // new Product() class method
    var myProduct = new Product('/product/path-to-product');
    
    if (myProduct.id) {
        print(myProduct.title + ' was found');
    } else {
        print('Product not found');
    }
?>

Note hard coding URLs in this manner can be open to error if URL no longer exists.


Construct parameters
reference String | Url | Number

The page reference is either a String/Url representing the URL relative to root (see also Product.findByAlias()) or a Number representing the product.id (see also Product.findById()). 

For international and multi-lingual sites you should use the default URL as the reference for the product and not the localised version. Evance will automatically correct the URL format for you once the Product object is retrieved.



Properties
allowEnquiries Boolean

True if visitors may add this product to cart to enquire, else false.

allowPreOrders Boolean

True if the product may be ordered even when product.isOutOfStock, else false.

averageRating Number

The average review rating across totalReviews for the product.

barcode String

The EAN barcode number for the product. If set this number should be compatible with the <ev:barcode> EV Tag, which is able to render barcodes as a PNG.

canAddToCart Boolean

True if visitors may add the product to their shopping cart for either purchase or enquiry, else false. This takes into account whether the all of the statuses for the product allow the product to be purchased or enquired upon.

categories CategoryCollection

A collection of categories the product belongs to in order as they appear within the category manager.

commodityCode String

The Harmonized Commodity Code (HS Code) - commonly used throughout the export process for goods and used by customs authorities around the world to identify products when assessing duties and taxes.

condition String

The condition of the product will be one of the following:

  • new
  • used
  • refurbished
created Date

The date the product was added into the database.

description String

The short description for the product.

discontinued Date

The date a product was discontinued on.

discontinuedReason String

A discontinuation message.

discount PriceDiscount

The value of the saving between Product.listPrice and current Product.price.

discountPercentage Number

The percentage saving between listPrice and current price to the nearest whole number.

expires Date

The date the product will expire and will not longer be available online.

featured Boolean

Whether the Product has been marked as a featured Product.

hasPrice Boolean

True if product has a price set and is not null - set to Price Only Application (POA).

hasReviews Boolean

True if reviews are enabled the totalReviews is greater than zero.

id Number

The system's unique' ID for the product. The System ID is not sequential to an accout therefore the system ID is used for code reference (e.g. addition to cart) and is not used for visual reference. For human readable or visual reference please use either product.quickfind or product.sku .

includesTax Boolean

True if the product price includes tax, else false. This is subject to the tax rule for the current visitor and is regardless of the setting for the product price within Evance

isAdvancedVariant Boolean

True if the product is linked as a variant of a master product, but is also a product in its own right.

isBasicVariant Boolean

True if the product is a basic variant of a master product.

isBuy Boolean

True if the product's price mechanism is set to purchase rather than hire, else false.

isBuyable Boolean

True if the product's price mechanism is set to purchase rather than hire and the product's statuses allow it to be purchased online, else false.

isDiscontinued Boolean

True if the product has been discontinued, else false.

isEnquiryOnly Boolean

True if the product is not purchasable but may be added to cart as an enquiry, else false.

isFromPrice Boolean

True if the current price for the product is the lowest in its class. For example if a product has a cheaper price when ordering 5 or more the cheapest price will be shown due to volume pricing.

isHire Boolean

True if the product's price mechanism is set to hire rather than purchase, else false.

isHirable Boolean

True if the product's price mechanism is set to hire rather than purchase and the product may be hired online, else false.

isLowStock Boolean

True if the product has warehouse stock tracking enabled and has a stock level less than or equal to product.lowStockLevel, else false.

isMadeToOrder Boolean

True for custom products where the vendor makes the product when ordered.

isOffer Boolean

True if the product's current product.price is lower than the product.listPrice, else false.

isOutOfStock Boolean

True if the product has warehouse stock tracking enabled and has a stock level of zero across all warehouses, else false.

isPriceOnRequest Boolean

True when a product has a current price of NULL. A merchant may choose to set a NULL price, often for high value or custom products.

isShippingRequired Boolean

True if the product is physical and false if it’s a digital good.

isStocked Boolean

True if the product has warehouse stock tracking enabled, else false. Note that isStocked will be true even if a product's stock is depleted.

isSubscribable Boolean

True if the product's price mechanism is set to subscription and the product is purchasable online.

isSubscription Boolean

True if the product's price mechanism is set to subscription.

isSuperseded Boolean

True if the product has been discontinued and superseded by another product, else false.

listPrice Price | null

The standard list price for the product excluding offers or discounts.

lowStockLevel Number

Show a low level alert to visitors (i.e. Limited availability) when stock levels reach this Number or less.

maxDispatchDate Date

The latest the merchant is estimated to be able to dispatch this product (usually when out of stock). Does not include delivery time.

maxLeadTime Number

The maximum number of days it takes to dispatch this item to the customer (usually when the product is out of stock). Does not include delivery time.

maxOrderQuantity Number

The maximum quantity that may be ordered per order.

metaDescription String

The product page's meta description.

metaKeywords String

The product page's meta keywords.

metaTitle String

The product page's meta/browser title.

minDispatchDate Date

The soonest the merchant is estimated to be able to dispatch this product (usually when in stock). Does not include delivery time.

minLeadTime Number

The minimum number of days it takes to dispatch this item to the customer (usually when the product is in stock). Does not include delivery time.

minOrderQuantity Number

The minimum quantity that may be ordered per order.

minUnits Number

The minimum number of product.priceUnit per order.

model String

The manufacturer's product model (e.g. Apple iPhone 5S where Apple is the manufacturer and iPhone is the range and 5S is the model).

modified Date

The date the product was last modified.

partNumber String

The manufacturer's part number for the product, which may be different to the shop's SKU.

price Price | null

The current price for the product including offers or discounts.

priceId Number

The System ID for the current price associated with the product. The current price is calculated as the lowest available price for the visitor.

priceMechanism String

The active price mechanism, which may either be buy, hire or subscription.

priceQuantity Number

The order quantity at which the current price is applicable. This may be higher than one if the merchant has quantity based pricing.

priceSuffix String

The the string to be shown after a price e.g. +VAT. This automatically knows whether to use an inclusive or exclusive of tax suffix subject to the current session tax rule.

priceType String

The the price mechanism used by this product, which may be:

  • buy
  • hire
priceUnit String

The units of measurement for the product pricing. This may currently be:

  • each
  • day
  • week
  • month
  • year
published Date

The date the product was published and became visible online.

quickfind Number

The sequential ID for the product for the Account. Because quickfind codes are sequential, but not unique they are only used for search/visual representation. They should not be used for code references (e.g. when adding a product to cart). For code reference please use product.id.

range String

The manufacturer's product range (e.g. Apple iPhone 5S where Apple is the manufacturer and iPhone is the range and 5S is the model).

rrp Price | null

The "Recommended Retail Price" of the product.

sku String

The "Stock Keeping Unit" is a unique user specified code for the product and is used for tracking stock of a product.

stock Number | null

The total available stock across all warehouses, or null if not stocked.

suspendOnDepletion Boolean

True if the product may not be ordered when Product.isOutOfStock, else false.

thumbnail Url | null

The thumbnail Url chosen to represent the Product. This is called thumbnail for historic reasons, but may be of any size. The thumbnail is generally shown on the parent category page and will be the image selected for the primary media entry for the product.

title String

The title for the product.

totalReviews Number

The total number of reviews for the product.

url Url

The URL of the Product. If you have an international website this Url will represent the current Locale of your website.



Methods
assets() Object

Returns an object containing any configured Assets for the Product as defined within the templates.json config for the template assigned to the product.

canAddReview() Boolean

True if the user is logged is allow to add a review.

categories() CategoryCollection

The list of Categories the product belongs to.

contacts() Contact[]

Returns an array of Contacts associated with the Product, based on its Category assignments. This functionality is intended to show a list of sales advisors for the Product. This may be helpful where the product is complex or where the product has no price - "Price on Application" (POA).

For international sites with multiple locales, each Contact 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.

customisations() Array

An array containing ProductCustomisation groups and options. Product customisation allows visitors to customise a product for example engraving on a watch.

downloads() Array

Gets an array of available downloads for the product. Each element in the Array returned contains a ProductDownload object.

findByAlias(String uri) Boolean

Find a product by its unique alias/URI. Returns true if the product was found, and false if not found.

<?ev
    var myProduct = new Product();
    
    if (myProduct.findByAlias('/product/my-product')) {
        // Product found
    } else {
        // Product not found
    }
?>


The alias supplied must be the URI path to the product (e.g. '/product/my-product'). If the path includes a locale prefix (e.g. '/en-gb/product/my-product') Evance will globalise the URI prior to lookup.

findById(Number id) Boolean

Find a product by its system ID. Returns true if the product was found, and false if not found.

<?ev
    var myProduct = new Product();
    
    if (myProduct.findById(1)) {
        // Product was found
    } else {
        // Product Not Found
    }
?>
findByQuickfind(Number quickfind) Boolean

Find a product by its Quickfind number. Returns true if the product was found, and false if not found.

<?ev
    var myProduct = new Product();
    
    if (myProduct.findByQuickfind(123)) {
        // Product was found
    } else {
        // Product Not Found
    }
?>
findBySku(String value) Boolean

Find a product by its SKU reference. Returns true if the product was found, and false if not found.

<?ev
    var myProduct = new Product();
    
    if (myProduct.findBySku('MY-CODE-123')) {
        // Product was found
    } else {
        // Product Not Found
    }
?>
fragment(String ref) Fragment | false

Returns a content fragment associated with the Product, or False if the fragment is not found. This allows programmatic access to edtiable regions on the product page. However, you would typically use <ev:editable> when implementing editable regions.

fragments() Object

Returns an object containing all available editable regions for the Product.

hasFragment(String ref) Boolean

True if the product has an available editable region with the reference provided.

hasUpsell() Boolean

True if the product has upsell options.

hasVolumePricing() Boolean

True if the product has order quantity/volume based pricing.

inWishlist() Boolean

True if the product exists within the current user's wishlist.

manufacturer() Manufacturer | null

The Product's Manufacturer.

master() Product | null

Returns the Master Product for a variant, or NULL if the product is not a variant.

media() Array

Gets an array of available photos, videos or 360°s for the product. Each element in the Array returned contains a ProductMedia object.

priceOptions() Array

Gets an array of available price options for the current visitor based on available price Units. Each element in the Array returned contains a ProductPrice object. For example you may have a product that may be hired based on a monthly or annual rate.

prices() Array

Gets an array of available prices for the current visitor. Each element in the Array returned contains a ProductPriceobject.

related() ProductCollection

A list of related products in the order specified within the Evance product manager.

relatedByManufacturer() ProductSearch | false

Returns a ProductSearch pre-built to find products with the same manufacturer excluding itself.

relatedByOrder() ProductSearch

Returns a ProductSearch pre-built to find products that are frequently bought together with the current product.

relatedByOrderAlso() ProductSearch

Returns a ProductSearch pre-built to find any products users also purchased (not necessarily in the same order).

relatedByRange() ProductSearch | null

Returns a ProductSearch pre-built to find products with the same manufacturer and in the same manufacturer's range, excluding itself.

reviews() ReviewSearch | false

Returns a Review search object pre-built to search reviews for this product. Search is automatically sorted by publish date (descending order).

share() PageSharer

Returns the PageSharer object, which allows you to build social media share links using the product's data.

specifications() Array

Gets the list of specifications assigned to the product. Each element within the Array contains a ProductSpecification object.

stockists() StockistProductCollection

Returns a collection of stockists for the product.

supersededBy() Product | null

If the product is discontinued and has been superseded by an alternative Product returns the available alternative Product, else null.

template() Template | null

Retrieves the available template settings for the current product, else null.

toString() String

Returns the product title as the string representation of the product.

upsell() Array

Gets the upsell options for a product.

variants() ProductCollection

Gets a list of available variants for the current product (must be the master product).

variations() Array

Gets a list of available variations for the current product. Each element within the Array contains a ProductVariation object.

volumePricing() Object

The Object returned has properties based on priceUnit e.g. product.volumePricing().each. Each property contains an Array of ProductPrice objects.