List

This function is under development, results may vary and content on this page may become out of date or incorrect - if you have any issues with this function, submit your feedback at the bottom of the page then revert to a [%thumb_list%] or equivalent function.

Generate a list of content based on the type specified.

The [%list%] is a new function that replaces many other Maropost Commerce Cloud B@SE functions such as [%thumb_list%], [%content_menu%] and other functions.

Body template

While the [%thumb_list%] function takes it's body template from the thumbs directory, the [%list%] function takes it's body template from the list directory, which isn't in a theme directory by default. If you want the exact templates from your thumbs directory then you could copy /httpdocs/assets/themes/[THEME-NAME]/templates/thumb/product/*.html into /httpdocs/assets/themes/[THEME-NAME]/templates/list/product. The [%list%] type will dictate which sub directory the template comes from, e.g , [%list type:'content' template:'category'%] would have a template at /httpdocs/assets/themes/[THEME-NAME]/templates/list/content/category.template.html.

Parameters

[%list type:'content' template:'category' limit:'12' filter:'content_type=category' sort:'content_name' sort_direction:'asc'%]
    ...
[%/list%]
Name Options Description
type string See below for details on each type.
template string A template filename without file extension.
File should be placed under theme folder within below mentioned directory `[THEME_FOLDER]/template/list/[filename].template.html`
**Usage**: template='filename'
limit number Sets the limit of results.
filter urlencoded object See each type for specific filters.
sort string See each type for specific sort.
page number When pagination is active, load the specified page of results
sort_direction string Sets the sorting direction of the result set
`sort_direction:'asc'` or `sort_direction:'desc'`

Filters

Filters can be used to fine-tune the results of the list function. A single filter can be used, or multiple filters can be joined using an ampersand & to further limit the results. For example [%list type:'product' filter:'min_price=100'%] will only show products that have a price higher than $100. By adding a max_price=500 filter we can limit the results to only products between $100 - $500: [%list type:'product' filter:'min_price=100&max_price=500'%] Some filters can take multiple values separated by a commaa , for example filter:'parent_sku=item2,item7' will show only child products from those parent SKUs. This is different to joining filters in that you are increasing the results by adding additional values to the same filter. Filters with multiple values can also be combined to different filters, for example: [%list type:'product' filter:'parent_sku=item2,item7&promo_current=y'%] will show all the child products that match those parent SKUs but only if they are on special.

For a full list of filters and their usage see under each list type.

Types

The list tag is consolidated into the following types:

The data tags available will be dependant on the type

Type:product

For displaying different types of products and product information.

Type product example

This list function will display the 4 top selling products, using the default product template: /httpdocs/assets/themes/[THEME-NAME]/templates/list/product/template.html.

[%list type:'product' template:'' sort:'top_sellers' limit:'4'%]
     [%param *header%]
          <h3>Popular Products</h3>
          <div class="row">
     [%/param%]
     [%param *footer%]
          </div>
     [%/param%]
[%/list%]
Filter
Usage
Description
approval `filter:'approval=y'` or `filter:'approval=n'` Filter by product approval
content `filter:'content=1'` or `filter:'content=1,2,3'` Filter by product content
content_type `filter:'content_type=1'` Filter a product by content type
first_letter `filter:'first_letter=(text)'` Filter product by matching product name
user_group `filter:'user_group=1'` Filter by user groups
min_height `filter:'min_height=10'` Filter by height
hide_parent_products `filter:'hide_parent_products=y'` or `filter:'hide_parent_products=n'` Filter parent products
promo_current `filter:'promo_current=y'` or `filter:'promo_current=n'` Filter by products currently in promotion
in_stock `filter:'in_stock=y'` or `filter:'in_stock=n'` Filter by products in stock
inventory_id `filter:'inventory_id=22'` Filter by inventory id
item_group `filter:'item_group=1'` Filter by item group
keywords `filter:'keywords=(text)'` Filter by keywords
min_length `filter:'min_length=(number)'` Filter by length
max_price `filter:'max_price=(number)'` Filter products by restricting maximum price
min_price `filter:'min_price=(number)'` Filter products by restricting minimum price
parent_inventory_id `filter:'parent_inventory_id=[@inventory_id@]'` Show the children of the specified inventory_id
parent_sku `filter:'parent_sku=[@sku@]'` Show the children of the specified SKU
product_type `filter:'product_type=(text)'` Filter by type of product
promo_past `filter:'promo_past=y'` or `filter:'promo_past=n'` Filter by product not in promotion
promo_future `filter:'promo_future=y'` or `filter:'promo_future=n'` Filter by upcoming promotion
search_ids `filter:'search_ids=1,2,3'` Filter by providing list of inventory ids
show_hidden `filter:'show_hidden=1'` Flag to display products regardless of visibility status
show_unapproved `filter:'show_unapproved=1'` Flag to display products regardless of approval status
specifics `filter:'specifics='` Filter by product specifics. Separate IDs by comma. E.g: `filter:'specifics=2,7'`
visible `filter:'visible=y`' or `filter:'visible=n'` Filter by visibility
warehouse `filter:'warehouse=(text)'` Filter products by warehouses
min_width `filter:'min_width=(number)'` Filter by width
wishlist `filter:'wishlist=?'` Filter by wishlist
wishlist_purchased `filter:'wishlist_purchased=y'` or `filter:'wishlist_purchased=n'` Filter by already purchased wishlist products
Sort
Usage
Description & Usage
brand `sort:'brand'` Sort by product brand
display_priority `sort:'display_priority'` Sort by display priority
highest_price `sort:'highest_price'` sort by highest price
highest_qty `sort:'highest_qty'` Sort by highest quantity
inventory_id `sort:'inventory_id'` Sort by inventory id
largest_item `sort:'largest_item'` Sort by largest item
longest_item `sort:'longest_item'` Sort by longest item
lowest_price `sort:'lowest_price'` Sort by lowest price
lowest_qty `sort:'lowest_qty'` Sort by lowest quantity
name `sort:'name'` Sort by name
new_arrivals `sort:'new_arrivals'` Sort by new arrivals
promo_end `sort:'promo_end'` Sort by promotion ending
random `sort:'random'` Sort randomly
shortest_item `sort:'shortest_item'` Sort by shortest item
SKU `sort:'SKU'` Sort by sku
smallest_item `sort:'smallest_item'` Sort by smallest item
sortorder `sort:'sortorder'` Sort by sortorder
sortorder2 `sort:'sortorder2'` Sort by other sort order
sortorder_price `sort:'sortorder_price'` Sort by sort order price
sortorder2_price `sort:'sortorder2_price'` Sort by other sort order price
sortorder_sortorder2 `sort:'sortorder_sortorder2'` Sort by sort order's sort order
subtype_sortorder2 `sort:'subtype_sortorder2'` Sort by subtype's sort order
top_sellers `sort:'top_sellers'` Sort by top sellers
trending `sort:'trending'` Sort by trending
wishlist `sort:'wishlist'` Sort by wishlist
Data tags
Description
`[@acc_code@]` Accounting Code
`[@actual_height@]` The assembled dimensions in height for the SKU. Prints as meters by default
`[@actual_length@]` The assembled dimensions in length for the SKU. Prints as meters by default
`[@actual_width@]` The assembled dimensions in width for the SKU. Prints as meters by default
`[@allow_oversell@]` Virtual product tag boolean
`[@arrival_date@]` Arrival date of SKU, recommended to use format tag
`[@artist_author@]` Artist/Author tag
`[@availability_description@]` Availability Description for the SKU, typically used to explain when product will become available.
`[@barcode@]` The barcode tag, can be used with the barcode_url asset to generate an image
`[@base_unit@]` The base unit of measure
`[@base_unit_qty@]` Unit quantity description
`[@brand@]` Product brand, can be used with brand tag to load further information.
`[@committed_quantity@]` Quantity committed to orders
`[@coupons@]` Number of coupons associated with a product
`[@cubic@]` Cubic weight calculated for the SKU
`[@date_created@]` Date the product was created in Maropost Commerce Cloud, can be edited
`[@display_template@]` Body template selected for SKU
`[@editable_bundle@]` Boolean that when true indicates that a product is an editable kit/bundle
`[@extra@]` Boolean that when true indicates the product has "Extra Options" available
`[@format@]` Product Format field
`[@free_gifts@]` Boolean that when true has free gifts assigned to SKU
`[@has_components@]` Boolean that when true indicates the SKU has kit components
`[@height@]` The Dimensions for the SKU and prints as meters by default
`[@inpromo@]` Boolean that when true indicates the item has a promotional price that is valid
`[@inventory_id@]` A unique ID assigned to the item, typically for internal use
`[@is_kit@]` Determines that a product is actually a kit containing two or more products
`[@itm_gp_id@]` A unqiue id for kits/variations/parent items, typically for internal use
`[@itm_sortorder@]` Sort order integer, used to determine the sort order of the item
`[@itm_sortorder2@]` Sort order integer, used to determine the sort order of the item
`[@manufacturer_model@]` The model no. / Sku provided by the manufacturer
`[@model@]` The item name
`[@notax@]` A boolean that when true indicates it is tax free
`[@preorder@]` A boolean that when true indicates that the item meets the conditions to be available for preorder
`[@preorder_quantity@]` The anticipated quantity available for preorder
`[@product_subtype@]` The product subtype
`[@product_type@]` The product type
`[@promo_end@]` The promotional price end dates
`[@promo_price@]` The promotional price active during promo dates
`[@promo_start@]` The promotional price startdates
`[@purchased_first_name@]` First name of the customer who purchased a product from their wishlist
`[@purchased_last_name@]` Last name of the customer who purchased a product from their wishlist
`[@rental_only@]` A boolean that when true means it is a rental only item
`[@retail@]` Retail price
`[@service_only@]` A boolean that when true indicates a service item which has no delivery options required
`[@sh_type_id@]` The shipping ID of the shipping method that the item belongs to
`[@short_description@]` Item short description, has a character limit of 250 characters
`[@SKU@]` The items SKU, the unique identifier
`[@start_date@]` The date the product was created
`[@store_price@]` The price stored against the user group
`[@store_quantity@]` The quantity available for purchase. If the products inventory policy is set to `Don't track inventory for this SKU` the value will return `0`.
`[@subtitle@]` The items subtitle
`[@swatch@]` The colour code in hex on the product
`[@tax_inc@]` A boolean that when true indicates a tax inclusive product
`[@unit@]` The unit of measure
`[@weight@]` Item weight
`[@width@]` The Dimensions for the SKU and prints as meters by default
`[@wishlist_date_added@]` Date when product was added to the wishlist of a user
`[@wishlist_date_purchased@]` Date when wishlist product was purchased
`[@wishlist_purchased@]` Boolean when true indicates the wishlist product has been purchased
`[@wishlistitems_id@]` A unique ID of the wishlist item
`[@wishlistitems_priority@]` Value that indicates the priority of the wishlist item
`[@{custom_field}#@]` Any custom field defined for a product, for example `{custom_field}` could be `[@misc1@]`

Type:content

For displaying different content types information, e.g, brands or categories.

Type content example

This list function will display 6 items from the content type brands, using the 'brand' template: /httpdocs/assets/themes/[THEME-NAME]/templates/list/content/brand.template.html.

[%list type:'content' filter:'content_type=brand' template:'brand' limit:'6' sort:'content_name'%]
    [%param *header%]
        <hr/>
        <h2 class="text-center">Featured Brands</h2>
        <div class="row featured-brands">
    [%/param%]
    [%param *footer%]
            <div class="col-xs-12 text-center">
                <a href="[%url type:'content' id:'100'/%]">Show All Brands</a>
            </div>
        </div>
    [%/param%]
[%/list%]
Filter
Example
Description & Usage
content `filter:'content=1,2,3'` Get child contents
content_level `filter:'content_level=1'` Filter by content levels
content_type `filter:'content_type=blog'` Filter by content type. By default content_type is set to 'category'. (Available content types: page, form, category, buying, brand and blog)
first_letter `filter:'first_letter=a'` Filters by the starting character specified in the parameter
hide_private `filter:'hide_private=1'` If hide_private is set to 1, contents will be hidden if access_control is set to private
inventory_id `filter:'inventory_id=1,2,3'` Comma separated list to filter contents which contain this list of products
related_content_inverse `filter:'related_content_inverse=1,2,3'` Get all contents that are related to these contents
related_content `filter:'related_content=1,2,3'` Get all the related contents for these contents
show_hidden `filter:'show_hidden=1'` Filter by show hidden. (eg: "Visible On Menu" is checked) `1` will show contents which are hidden on menu, 0 will filter them out. 0 is default if undefined.
sku `filter:'sku=SAMPLE'` Filter by product sku
user_group `filter:'group_id=1'` Specifies a group for the list. If not defined it will either use the current group_id or default group_id
Sort
Example
Description & Usage
content_name `sort:'content_name'` Sort by content name
Data tags
Description
`[@content_id@]` Id of the content
`[@content_type_id@]` Id of the type of the content
`[@parent_content_id@]` Id of the parent of the content
`[@content_level@]` The level of the content
`[@content_name@]` Name of the content
`[@content_ref@]` Reference of the content
`[@content_fullpath@]` Full path of the content
`[@content_external_src@]` External source of the content
`[@content_external_ref1@]` External reference 1 of the content
`[@content_external_ref2@]` External reference 2 of the content
`[@content_external_ref3@]` External reference 3 of the content
`[@content_short_description1@]` Short description 1 of the content
`[@content_short_description2@]` Short description 2 of the content
`[@content_short_description3@]` Short description 3 of the content
`[@content_label1@]` Label 1 of the content
`[@content_label2@]` Label 2 of the content
`[@content_label3@]` Label 3 of the content
`[@content_description1@]` Description 1 of the content
`[@content_description2@]` Description 2 of the content
`[@content_description3@]` Description 3 of the content
`[@content_wufoo_form@]` Wufoo form of the content
`[@templatebody@]` Template body of the content
`[@content_allow_reviews@]` Is the content allow to have reviews?
`[@access_control@]` Access
`[@sortorder@]` Sort order of the content
`[@content_author@]` Author of the content
`[@date_posted@]` Date posted of the content
`[@timestamp@]` Timestamp of the content
`[@content_type_code@]` Code of the content type for the content
`[@content_type_name@]` Name of the content type for the content
`[@url@]` Url of the content
`[@thumb@]` Thumb url of the content
`[@thumb_alt1@]` Thumb alt1 url of the content
`[@num_of_reviews@]` Number of reviews of the content
`[@rating@]` Average rating of the content
`[@rating_decimal@]` Average decimal rating of the content
`[@rating_round_half@]` Average half rating of the content

Type:content_review

For displaying content page reviews.

Type content_review example

This list function will display a max of 5 content reviews, which is standard for a page that uses the default.template.html template, e.g blogs or information pages.

[%list type:'content_review' limit:'5' filter:'content_id=[@content_id@]'%]
    [%param *header%]
        <h3>Comments ([@reviews@])</h3>
    [%/param%]
    [%param *body%]
        <div itemprop="review" itemscope itemtype="http://schema.org/Review">
            <blockquote>
                <h4 itemprop="name"><i>[%nohtml%][@title@][%/nohtml%]</i></h4>
                <div>
                    <strong>[%if [@reviewname@]%]By: <span itemprop="author">[@reviewname@]</span> on [%/ if%]<meta itemprop="datePublished" content="[%FORMAT type:'date'%][@insert_date@][%/FORMAT%]">[%FORMAT type:'date'%][@insert_date@][%/FORMAT%]</strong>
                </div>
                <span itemprop="description">[%nohtml%][@review@][%/nohtml%]</span>
                [%IF [@review_response@]%]
                    <br /><br />
                    <blockquote>
                        <span class="review_response text-muted"><strong><i>[@config:website_name@] Response</i></strong><br /> [%nohtml%][@review_response@][%/nohtml%]</span>
                    </blockquote>
                [%/IF%]
            </blockquote> <hr />
        </div>
    [%/param%]
[%/list%]
Filter
Example
Description & Usage
content_id `filter:'content_id=1'` Filter by a content_id
Sort
Description & Usage
insert_date

Sort by review insert date.

Note: review insert date is the default sorting field.

Any other field from the above listed data tags can be used to sort the list. However using other fields may affect performance.

Usage

sort:'title'

Data tags
Description
`[@approved@]` Status of review
`[@bill_city@]` City of reviewer

`[@bill_first_name@]`

First name of reviewer
`[@bill_last_name@]` Last name of reviewer
`[@content_id@]` A unique ID of content
`[@content_name@]` Content name
`[@insert_date@]` Date of review
`[@review@]` A review
`[@review_response@]` Response on review
`[@reviewname@]` Name of reviewer
`[@score@]` Ratings of review
`[@title@]` Title of review
`[@username@]` Username of reviewer

Pagination

The [%list%] function uses its own [%pagination%] function instead of the existing [%paging%] setup. This function acts in the same way to generate a list of paging URLs to navigate through the entire list results however uses data tags specific to the list function. For example, to correctly page through a large category, your list function would look something like this:

[%set [@list_sort@]%][%sortby type:'products'/%][%/set%]
[%list type:'product' template:'' filter:'content=[@content_id@]' limit:'[@config:THUMB_LIMIT@]' page:'[@form:pgnum@]' sort:'[@list_sort@]'%]
    [%param *header%]
    <div class="row sort_container">
        <div class="col-4 d-none d-lg-block">
            <div class="btn-text">
                <strong>[@total_items@]</strong> Product[%if [@total_items@] > 1%]s[%/if%] Found
            </div>
        </div>
        <div class="col-8 col-md-5 col-lg-4">
            <form method="get" action="[@config:CURRENT_URL@]">
                <input name="rf" type="hidden" value="[%FILTER_CODE%][%/FILTER_CODE%]">
                <div class="form-row">
                    <label class="col-2 col-form-label" for="sortby">Sort</label>
                    <div class="col-10">
                        <select id="sortby" name="sortby" onChange="return this.form.submit();" class="form-control" aria-label="Sort products by">
                            <option value="popular" [%SORTBY type:'products' if:'eq' value:'popular'%]selected[%/SORTBY%]>Most Popular</option>
                            <option value="name" [%SORTBY type:'products' if:'eq' value:'name'%]selected[%/SORTBY%]>Name</option>
                            <option value="SKU" [%SORTBY type:'products' if:'eq' value:'SKU'%]selected[%/SORTBY%]>SKU</option>
                            <option value="lowest_price" [%SORTBY type:'products' if:'eq' value:'lowest_price'%]selected[%/SORTBY%]>Lowest Price</option>
                            <option value="highest_price" [%SORTBY type:'products' if:'eq' value:'highest_price'%]selected[%/SORTBY%]>Highest Price</option>
                        </select>
                    </div>
                </div>
            </form>
        </div>
    </div>
    <div class="row">
        <div class="col-12">
            <hr aria-hidden="true" />
        </div>
    </div>
    <div class="thumb">
        <section class="row products-row" aria-label="Products in category">
        [%/param%]
        [%param *footer%]
        </section>
    </div>
    [%if [@total_items@] > [@config:thumb_limit@]%]
        <div class="row">
            <div class="col-12">
                <hr aria-hidden="true"/>
                <nav aria-label="Page navigation">
                    [%pagination total_items:'[@total_items@]' items_per_page:'[@items_per_page@]' current_page_num:'[@current_page@]'%]
                        [%param *header%]
                            <ul class="pagination justify-content-center">
                        [%/param%]
                        [%param *previous_page%]
                            <li class="page-item"><a class="page-link" href="[@url@]" aria-label="Go back one page"><i class="fa fa-chevron-left" aria-hidden="true"></i></a></li>
                        [%/param%]
                        [%param *goback_pages%]
                            <li class="page-item"><a class="page-link" href="[@url@]" aria-label="Go to page [@page@]">[@page@]</a></li>
                        [%/param%]
                        [%param *current_page%]
                            <li class="page-item active"><a class="page-link" href="[@url@]" aria-label="Current page">[@page@]</a></li>
                        [%/param%]
                        [%param *gonext_pages%]
                            <li><a href="[@url@]" class="page-link" aria-label="Go to page [@page@]">[@page@]</a></li>
                        [%/param%]
                        [%param *next_page%]
                            <li class="page-item"><a class="page-link" href="[@url@]" aria-label="Go forward one page"><i class="fa fa-chevron-right" aria-hidden="true"></i></a></li>
                        [%/param%]
                        [%param *footer%]
                            </ul>
                        [%/param%]
                    [%/pagination%]
                </nav>
                <hr aria-hidden="true"/>
            </div>
        </div>
    [%/if%]
    [%/param%]
    [%param *ifempty%]
        <div class="row">
            <div class="col-12">
                <p>This category is empty! Please try another category or use our search function to find what you are looking for. If you require further assistance please contact us.</p>
            </div>
        </div>
    [%/param%]
[%/list%]

For a full understanding of the pagination functinon please refer to our [%pagination%] function page.

Was this article useful?

Be notified when this page is updated. Optional.