Perch Shop
Namespaces
The following namespaced tags are used by Perch Shop.
| Namespace | Used for |
|---|---|
| perch:shop | All shop tag types except those detailed below |
| perch:cartitems | Tag pair around items in the cart |
| perch:cartitem | Used for template tags for individual cart items |
| perch:productopts | Product options (size, colour) |
| perch:productopt | Single product option |
| perch:productvalues | Product option values (M, L, red, blue) |
| perch:productvalue | Single product option value |
| perch:variants | Product variants |
| perch:variant | Single product variant |
Master Templates
The master templates for Shop are as follows. All templates are within perch_shop/templates/shop and an individual template should be copied to the corresponding location within your local perch/templates/shop folder before editing.
| Entity | Template |
|---|---|
| Customer address | addresses/address.html |
| Brand | brands/brand.html |
| Cart | cart/cart.html |
| Currency | currencies/currency.html |
| Customer | customers/customer.html |
| emails/email.html | |
| Order | orders/order.html |
| Order status | orders/status.html |
| Product | products/product.html |
| Product file | products/file.html |
| Product options | product/option.html |
| Product variants | product/variant.html |
| Promotions | promotions/promotion.html |
| Shipping methods | shippings/shipping.html |
| Shipping zones | shipping/zone.html |
| Tax groups | tax/group.html |
| Tax locations | tax/location.html |
Template IDs
Perch Shop exposes the following variables as values for the id attribute in template tags.
Cart tags
| Tag | Description |
|---|---|
| product_count | Number of unique products in the cart |
| item_count | Number of individual items in the cart |
| shipping_id | Shipping ID for the shipping method in use for the cart |
| shipping_method | The name of the shipping method being used |
| shipping_weight | The combined weight of items being shipped |
| shipping_tax | Tax paid on selected shipping method, defaults to 0 |
| shipping_tax_formatted | Formatted value for shipping tax |
| shipping_tax_rate | Rate used for shipping tax |
| shipping_with_tax | Shipping charge with tax added |
| shipping_with_tax_formatted | Shipping charge with tax added, formatted |
| shipping_without_tax | Cost of shipping without tax |
| shipping_without_tax_formatted | Cost of shipping without tax, formatted |
| total_items | Total value of the items in the cart |
| total_items_formatted | Total value of the items in the cart, formatted |
| total_items_tax | The total tax amount on items in the cart |
| total_items_tax_formatted | The total tax amount on items in the cart, formatted |
| total_shipping | The total shipping amount |
| total_shipping_formatted | The total shipping amount, formatted |
| total_shipping_tax | The total tax amount on shipping |
| total_shipping_tax_formatted | The total tax amount on shipping, formatted |
| total_items_with_shipping | The total value of items and shipping combined |
| total_items_with_shipping_formatted | The total value of items and shipping combined, formatted |
| total_tax | The total amount of item and shipping tax combined |
| total_tax_formatted | The total amount of item and shipping tax combined, formatted |
| total_discounts | Total of discounts applied |
| total_discounts_formatted | Total of discounts applied, formatted |
| total_items_discount | The total value of discounts applied to items in the cart |
| total_items_discount_formatted | The total value of discounts applied to items in the cart, formatted |
| total_items_tax_discount | The total value of discounts applied to tax |
| total_items_tax_discount_formatted | The total value of discounts applied to tax, formatted |
| total_items_discounted | Total value of the items in the cart with discounts applied |
| total_items_discounted_formatted | Total value of the items in the cart with discounts applied, formatted |
| total_items_discounted_with_tax | Total value of the items in the cart with discounts and tax applied |
| total_items_discounted_with_tax_formatted | Total value of the items in the cart with discounts and tax applied, formatted |
| total_shipping_discount | Total value of discounts applied to shipping |
| total_shipping_discount_formatted | Total value of discounts applied to shipping, formatted |
| total_shipping_tax_discount | Total value of shipping with discounts applied |
| total_shipping_tax_discount_formatted | Total value of shipping with discounts applied, formatted |
| total_tax_discount | Total amount of discount applied to tax |
| total_tax_discount_formatted | Total amount of discount applied to tax, formatted |
| total_discounts_with_tax | Combined total of item, shipping and tax discounts |
| total_discounts_with_tax_formatted | Combined total of item, shipping and tax discounts, formatted |
| grand_total | Grand total - what your customer will pay |
| grand_total_formatted | Grand total, formatted |
| shipping_weight | Shipping weight |
| currency_id | Currency ID for the currency used for this cart |
| currency_code | Currency code |
| currency_name | Currency name |
| currency_symbol | Currency symbol |
Cart Item tags
| Tag | Description |
|---|---|
| identifier | The unique ID of this entry in the cart |
| id | Alias for identifier |
| qty | The quantity of this item in the cart |
| productID | The unique ID of the product |
| is_variant | True or false, if the item is a variant |
| variant_desc | The variant description of the item, if it is a variant |
| sku | The product SKU |
| title | Title of the product |
| slug | Product slug based on the title |
| brand | The product brand (use with type="shop_brand" |
| category | The product categories (use with perch:categories tags) |
| catalog_only | True or false, if the product is available for online sale |
| requires_shipping | True or false, requires physical shipping |
| weight | The weight of the item |
| width | The width of the item |
| height | The height of the item |
| depth | The depth of the item |
| price | Item price (use with type="shop_currency_value") |
| sale_price | Sale price (use with type="shop_currency_value") |
| trade_price | Trade price (use with type="shop_currency_value") |
| on_sale | True or false, if the item is currently discounted |
| tax_group | The product’s tax group (use with type="shop_tax_group") |
| stock_level | The number of items in stock |
| stock_status | The current stock status (use with type="shop_stock_status") |
| max_in_cart | The maximum allowable quantity of this item per cart |
| discount | The amount of discount applied to the item |
| price_with_tax | The price with tax included |
| price_with_tax_formatted | The price with tax included, formatted |
| price_without_tax | The price without tax |
| price_without_tax_formatted | The price without tax, formatted |
| tax_discount | The about of discount applied to the tax |
| tax_rate | The rate at which tax has been calculated |
| total_tax | The amount of tax |
| total_tax_formatted | The amount of tax, formatted |
| total_with_tax | The line total including tax |
| total_with_tax_formatted | The line total including tax, formatted |
| total_without_tax | The line total excluding tax |
| total_without_tax_formatted | The line total excluding tax, formatted |
Brand tags
| Tag | Description |
|---|---|
| title | The name of the brand |
| slug | The URL-safe slug version of title |
| description | A description of the brand |
| image | An image representing the brand |
Editing templates
As with all Perch Add-ons, Shop comes with some default templates. These are stored in perch/addons/apps/perch_shop/templates/shop. Inside that folder are subfolders for the different parts of Shop, for example for the Cart that is the folder cart which includes a simple cart.html template. This will be used if you do not specify your own template name when displaying the cart, and if there is no template with the same name in your custom templates folder at perch/templates/shop.
You should not edit the templates that are inside the app folder. Before making any changes copy the template you wish to change into its subfolder inside perch/templates/shop/ You can then make any changes you want and the changes will not be overwritten when you update the add-on.
For example, to edit the default product template, you would copy:
perch/addons/apps/perch_shop/templates/shop/products/product.html
to your local templates folder as:
perch/templates/shop/products/product.html
Your edited template will then be used in preference, and it won’t be overwritten when you apply updates to the Shop app.