All template functions

These parameters are available for all template functions.

wrapper

The output of the template function will be wrapped within HTML element defined by this parameter.

If the template function outputs nothing or returns false, the wrapper element will not be generated.

<param name="wrapper">div#the-id.nice-class.another-class</param>
<div id="the-id" class="nice-class another-class"> ... </div>

before

Prints the given content before the template function output, if the template function outputs something and doesn't return false.

<param name="before">
    <h2>Title</h2>
    <ul>
</param>

after

Prints the given content after the template function output, if the template function outputs something and doesn't return false.

<param name="after">
    </ul>
</param>

js.ready

Here you can write your own JavaScript code that will be executed if the template function tag was successfully parsed and rendered.

<param name="js.ready">
    console.log("Something");
</param>

Some template functions have extra functionality implementated to the JavaScript class relating the template function. The keyword this refers to the TemplateFunction object created from that JavaScript class.

disabled

If given, template engine will skip this template function and it will not render anything. This is a quick way to disable a template function temporarily.

<param name="disabled"></param>

ArticleCategoryList

Prints article categories under root article category specified by parameter “root_id”.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for an article category. If this parameter is not given, inline template html will be used.
root_id Optional on article page or article category page. Otherwise this parameter must be given. On article category page defaults to current article category id (if root) or its parent's id. On article page defaults to current article's root category's id. Parent article category id for which subcategories should be printed.
empty Optional “” What should be printed when there are no article categories to show.
selected_class Optional “is-active” CSS class for selected article category. Use {article_category:selected_class} in the template html.

Usage

We can use the same ArticleCategoryList tag on article category page and article page because of the smart default value for parameter “root_id”.

<f:ArticleCategoryList>
    <param name="wrapper">ul.article-category-list.plain.cf</param>
    <li class="side-nav-item">
        <a href="{f:article_category:href}" class="side-nav-link {f:article_category:selected_class}">{f:article_category:name}</a>
    </li>
</f:ArticleCategoryList>

ArticleList

Prints articles under article category specified by parameter “category_id”.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for an article. If this parameter is not given, inline template html will be used.
category_id Optional on article page or article category page. Otherwise this parameter must be given. On article category page defaults to current article category id. On article page defaults to the id of article category containing the current article. Article category id for which articles should be printed.
count Optional How many articles should be shown. If not given, all containing articles are shown.
empty Optional “” What should be printed when there are no articles to show.
selected_class Optional “is-active” CSS class for selected article. Use {article:selected_class} in the template html.

Usage

<f:ArticleList>
    <param name="wrapper">ul.article-list.plain.cf</param>
    <param name="count">5</param>
    <param name="empty">
        <p class="alert alert-info alert-center">{text:articles_not_found}</p>
    </param>
    <li class="article-list-item cf">
        <a href="{f:article:href}" class="article-list-link cf" title="{f:article:name}">
            <span class="article-list-date icon-clock">{f:article:DatetimePublished(d.m.Y)} <span class="article-list-time">{f:article:TimePublished(H.i)}</span></span>
            <h3 class="article-list-title">{f:article:name}</h3>
            <span class="article-list-readmore">&rsaquo;</span>
        </a>
    </li>
</f:ArticleList>

Prints a specific banner or a randomly selected banner from a banner block. Notice that if the selected banner is set up to have a fixed html (from banner management), the given partial or inline template html will be ignored.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for the banner. If this parameter is not given, inline template html will be used.
banner_name Required, if block_name is not given. Name of the banner.
block_name Required, if banner_name is not given. Name of the banner block from which a banner is randomly selected.
lang Optional Current language In which language banner should be shown. Format: “fi”, “en”, “se” etc

Usage

<f:Banner>
    <param name="wrapper">div.banner</param>
    <param name="banner_name">my_banner</param>
    <a href="{banner:href}"><img src="{banner:image_src}" alt="{banner:image_alt}" /></a>
    <div class="header-banner-text">
        <h3 class="intro-banner__title">{banner:title}</h3>
        <p class="intro-banner__title">{banner:description}</p>
    </div>
</f:Banner>

BannerList

Prints banners from a banner block specified by parameter “block_name”. Notice that if a banner is set up to have a fixed html (from banner management), the given partial or inline template html will be ignored.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a banner. If this parameter is not given, inline template html will be used.
block_name Required Name of the banner block from which banners are printed.
lang Optional Current language In which language banner should be shown. Format: “fi”, “en”, “se” etc

Usage

<f:BannerList>
    <param name="wrapper">ul.sidebar-banners.plain.cf</param>
    <param name="block_name">sidebar_banners</param>
    <li class="sidebar-banner-item">
        <img src="{banner:image_src}" alt="{banner:image_alt}">
    </li>
</f:BannerList>

Prints breadcrumb links for current page.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a breadcrumb link. If this parameter is not given, inline template html will be used.

Usage

<f:Breadcrumb>
    <param name="wrapper">div.breadcrumb.plain.cf</param>
    <li class="breadcrumb-item">
        <a href="{link:href}" class="breadcrumb-link" title="{link:name}">{link:name}</a>
    </li>
</f:Breadcrumb>

CategoryList

Prints the category tree or specific parts of it.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a category. If this parameter is not given, inline template html will be used.
selected_class Optional “is-active” CSS class for selected category. Use {category:selected_class} in the template html.
has_children_class Optional “has-children” CSS class for category that has children. Use {category:has_children_class} in the template html.
start Optional “1” Level number from which category tree printing is started from. Supported values: Positive integers or following special values: “root” (1), “current” (selected category's level), “parent” (selected category's level - 1), “child” (selected category's level + 1)
levels Optional “all” How many levels of category tree should be printed, starting from the level specified using parameter “start”. Supported values: Positive integers or “all” which means that all following levels are printed.
mode Optional If value is “path”, we show all sibling categories for each category on the selected category path, and the subcategories for the currently selected category.
parent Optional “none” If given, only categories contained inside given category will be printed. Supported values: Category id or following special values: “root” (selected category's root category), “current” (selected category), “parent” (selected category's parent), “none” (no parent restriction, default)
level_wrapper Optional A jQuery selector that defines the wrapper element for a level of categories. Variable {level} will be replaced with category level of the current iteration.
category_wrapper Optional A jQuery selector that defines the wrapper element for a category. Variable {level} will be replaced with category level of the current iteration.

Usage

Examples for how to use the parameters “start”, “levels” and “mode”:

Full category tree:

<param name="start">1</param>
<param name="levels">all</param>

First level:

<param name="start">1</param>
<param name="levels">1</param>

First X levels (replace X with a positive integer):

<param name="start">1</param>
<param name="levels">X</param>

Using mode=path we can show sibling categories only for the selected category path:

First level fully, second level only for the selected first level category (if selected):

<param name="start">1</param>
<param name="levels">2</param>
<param name="mode">path</param>

First level fully, second level for selected first level category (if selected), third level for selected second level category (if selected):

<param name="start">1</param>
<param name="levels">3</param>
<param name="mode">path</param>

Second level for selected first level category (if selected):

<param name="start">2</param>
<param name="levels">1</param>
<param name="mode">path</param>

How to print full category tree as an ul list:

<f:CategoryList>
    <param name="wrapper">nav.side-nav.wrap.hide-mobile.cf</param>
    <param name="level_wrapper">ul.side-nav-lvl-{level}.cf</param>
    <param name="category_wrapper">li.side-nav-item.side-nav-item-lvl-{level}</param>
    <a href="{f:category:href}" class="side-nav-link side-nav-link-lvl-{f:category:level} {f:category:selected_class} {f:category:has_children_class}" title="{f:category:title}">{f:category:name}</a>
</f:CategoryList>

CheapestDeliveryMethod

Prints the cheapest delivery method (pickup is skipped) for a product on product page.

Notice: This template function can be used only on product page.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for the delivery method. If this parameter is not given, inline template html will be used.

Usage

<f:CheapestDeliveryMethod>
    <span class='cheapest-delivery-method-costs'>{delivery_method:costs}</span>
    <span class='cheapest-delivery-method-name'>{delivery_method:name}</span>
</f:CheapestDeliveryMethod>

FormHandler

This template function is used to implement different kinds of form actions that are performed using Ajax. The type of the functionality is specified using parameter “type”.

Requirements:

  • Form element's start tag must contain {form:id} as id: <form id='{form:id}'>
  • If form handler action returns some result using Ajax, specify a result element having {form:result_element_id} as id.
  • Make sure that this file is included: /site/templates/global/assets/js/form_handler.js

Parameters

Parameters for all types:

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for the form. If this parameter is not given, inline template html will be used.
type Required Supported values: “send_by_email”, “order_newsletter”, “back_to_stock_request”, “product_review”, “shop_review”
result_element_id Optional “form-result-element-for-{form:id}” Used to match the element that should contain the form handler action's result given using Ajax. Must be unique for each FormHandler.
result_element_class Optional “alert” The basic class that will be given to result element after action is performed.
result_element_success_class Optional “alert-success” The class that will be given to result element if action was successful.
result_element_error_class Optional “alert-error” The class that will be given to result element if action was not successful.
result_element_notice_class Optional “alert-warning” The class that will be given to result element if action result contained a notice.

Additional parameters for type “send_by_email”:

Name Required / Optional Default value Description
email_content_partial Required Partial that is used to render the email content. {data:field_name} contains value for input named as “field_name”.
email_subject Optional “ProsperCart FormHandler result received”
email_receiver Optional Value for ProsperCart setting “merchant_email”
email_field Optional Name for the field that contains the email sender address. If this parameter is given, the email (given by the user) in the related field will be validated. If valid the mail will be send from that email address.
success_message Optional The general message that is shown when form handler action was successful.
error_message Optional The general message that is shown when form handler action was not successful.

Additional parameters for type “order_newsletter”:

Name Required / Optional Default value Description
email_field Required Name for the field that contains the email address. Given email address will be validated.

Additional parameters for type “back_to_stock_request”:

Name Required / Optional Default value Description
product_id Required Id for the product that is requested.
email_field Required Name for the field that contains the email address. Given email address will be validated.

Additional parameters for type “product_review”:

Name Required / Optional Default value Description
use_points Optional true If true, “review_points” will be a required form field. Allowed field values for “review_points” are 1, 2, 3, 4 or 5.
product_id Required Id for the product that is reviewed.
email_field Optional email Name for the field that contains the email address. Given email address will be validated.

Additional parameters for type “shop_review”:

Name Required / Optional Default value Description
use_points Optional false If true, “review_points” will be a required form field. Allowed field values for “review_points” are 1, 2, 3, 4 or 5.
email_field Optional email Name for the field that contains the email address. Given email address will be validated.

JavaScript handlers (Version: 2.1.2.0)

These handlers can be bound in parameter “js.ready”.

Handler When it is applied Notes
beforeAction Before sending the form handler action using Ajax. If you throw an error, the action will not be performed.
afterAction After the Ajax request has been performed. First parameter is an object containing data from the action.
success After successful form handler action. First parameter is an object containing data from the action.
error After unsuccessful form handler action. First parameter is an object containing data from the action.
complete After success or error handler. First parameter is an object containing data from the action.

Default handlers:

// SlideUp is the default effect used after successful form handler action. See /site/templates/global/assets/js/form_handler.js
this.Bind("success", this.SlideUp);
 
// SetResult sets the output and CSS classes given by the form handler action to the result element.
this.Bind("complete", function(data) {
    this.SetResult(data.result_output, data.result_element_class);
});

If you bind your own handler, it will be applied after the default one. You can also replace the default handler:

// First unbind existing handlers, and then bind a new one.
this.Unbind("complete");
this.Bind("complete", function(data) {
    // ...
});
 
// There are shortcut functions for doing this: SetSuccessHandler / SetErrorHandler / SetCompleteHandler.
// This will replace any existing bindings with a new one.
this.SetSuccessHandler(function(data) {
    // ...
});

Usage

Using type “send_by_email”:

<f:FormHandler>
    <param name="type">send_by_email</param>
    <param name="email_content_partial">feedback_email_content</param>
    <param name="email_subject">Feedback received</param>
    <param name="email_field">email</param>
    <param name="success_message">{text:feedback_success_message}</param>
    <param name="error_message">{text:feedback_error_message}</param>
 
    <form id="{form:id}" class="basic-form">
        <div class="form-row cf">
            <label for="name" class="form-label">{t:name}</label>
            <div class="form-input"><input type="text" placeholder="{t:name}" name="name" id="name" class="input-text"></div>
        </div>
        <div class="form-row cf">
            <label for="email" class="form-label">{t:email}</label>
            <div class="form-input"><input type="text" placeholder="{t:email}" name="email" id="email" class="input-text"></div>
        </div>
        <div class="form-row cf">
            <label for="message" class="form-label">{text:message}</label>
            <div class="form-input"><textarea placeholder="{text:message}" name="message" id="message" class="input-text input-textarea"></textarea></div>
        </div>
         <div class="form-row cf">
            <button class="btn" type="submit">{t:send_feedback}</button>
        </div>
    </form>
    <div id='{form:result_element_id}'></div>
 
</f:FormHandler>

Using type “order_newsletter”:

<f:FormHandler>
    <param name="type">order_newsletter</param>
    <param name="email_field">email</param>
 
    <form id="{form:id}">
        <input type="text" placeholder="{t:email}" name="email" class="input-text">
        <button class="btn" type="submit">{text:order}</button>
    </form>
    <div id='{form:result_element_id}'></div>
 
</f:FormHandler>

Using type “back_to_stock_request”:

<f:FormHandler>
    <param name="type">back_to_stock_request</param>
    <param name="product_id">{product:id}</param>
    <param name="email_field">email</param>
 
    <form id="{form:id}">
        <input type="email" placeholder="{t:email}" name="email" class="input-text">
        <button class="form-submit-button" type="submit">{t:btn_send}</button>
    </form>
    <div id="{form:result_element_id}"></div>
 
</f:FormHandler>

Using type “product_review”:

Required form fields: review_points, review_text, name, email. Email field name can be redefined with parameter “email_field”.

<f:FormHandler>
    <param name="type">product_review</param>
    <param name="product_id">{product:id}</param>
 
    <div id='{form:result_element_id}' class="alert-center cf"></div>
 
    <form id="{form:id}" class="basic-form">
        <div class="form-row cf">
            <label for="form-field--review-points" class="form-label">{t:review_points}:</label>
            <input type="radio" id="review-point-1" name="review_points" value="1" data-value="1"><label class="js-add-review-point add-review-point icon-star" for="review-point-1"></label>
            <input type="radio" id="review-point-2" name="review_points" value="2" data-value="2"><label class="js-add-review-point add-review-point icon-star" for="review-point-2"></label>
            <input type="radio" id="review-point-3" name="review_points" value="3" data-value="3"><label class="js-add-review-point add-review-point icon-star" for="review-point-3"></label>
            <input type="radio" id="review-point-4" name="review_points" value="4" data-value="4"><label class="js-add-review-point add-review-point icon-star" for="review-point-4"></label>
            <input type="radio" id="review-point-5" name="review_points" value="5" data-value="5"><label class="js-add-review-point add-review-point icon-star" for="review-point-5"></label>
        </div>
        <div class="form-row cf">
            <label for="form-field--review-text" class="form-label">{t:review}:</label>
            <textarea id="form-field--review-text" name="review_text" class="input-text input-textarea" placeholder="{t:review}"></textarea>
        </div>
        <div class="form-row cf">
            <label for="form-field--name" class="form-label">{t:nickname}:</label>
            <input type="text" id="form-field--name" name="name" class="input-text" placeholder="{t:nickname}">
        </div>
        <div class="form-row cf">
            <label for="form-field--email" class="form-label">{t:email}:</label>
            <input type="email" id="form-field--email" name="email" class="input-text" placeholder="{t:email}">
        </div>
        <div class="form-row cf">
            <p class="info-text small">{t:email_wont_be_shown}</p>
        </div>
        <button class="btn form-submit-button" type="submit">{t:btn_send}</button>
    </form>
 
</f:FormHandler>

Using type “shop_review”:

Required form fields: review_text, name, email. Email field name can be redefined with parameter “email_field”.

Otherwise the same as type “product_review”, but form field “review_points” is not required by default (unless parameter “use_points” is given as true).

IncludeCSS

Prints <link> tags for given CSS files located in template theme directory “assets/cs”s. Files are firstly checked from selected template theme, and if not found there, from global template theme. Error is printed, if the file is not found from either places.

Parameters

No <param> tags are needed. Just give filenames separated with commas inside the template function tag.

Usage

<f:IncludeCSS>normalize.css, main.css</f:IncludeCSS>

IncludeJS

Prints <script> tags for given JavaScript files located in template theme directory “assets/js”. Files are firstly checked from selected template theme, and if not found there, from global template theme. Error is printed, if the file is not found from either places.

Parameters

No <param> tags are needed. Just give filenames separated with commas inside the template function tag.

Usage

<f:IncludeJS>jquery.js, domready.js</f:IncludeJS>

Prints links to pages specified in parameter “content”.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a link. If this parameter is not given, inline template html will be used.
content Required Comma separated list of pages. See below for formatting.
selected_class Optional “is-active” CSS class for link referring current page. Use {link:selected_class} in the template html.


Page type Content formatting Examples
General pages Page codename “index”, “shopping_cart”, “register/user_account”, “login/logout”
Product pages p:product_id “p:100003”
Category pages c:category_id “c:12”
Manufacturer pages m:manufacturer_id “m:7”
Article pages a:article_id “a:2”
Article category pages ac:article_category_id “ac:2”

Links for pages “login” and “register” are only shown if customer is not logged in, respectively “logout” and “user_account” only if customer is logged in. If you write “register/user_account” or “login/logout” only the other will be selected.

Usage

<f:LinkList>
    <param name="wrapper">ul.footer-links.cf</param>
    <param name="content">index, info, terms, contact</param>
    <li class="footer-link-item">
        <a href="{link:href}" class="footer-link {link:selected_class}" title="{link:name}">{link:name}</a>
    </li>
</f:LinkList>

ManufacturerList

Prints all manufacturers.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a manufacturer. If this parameter is not given, inline template html will be used.
empty Optional “” What should be printed when there are no manufacturers to show.
selected_class Optional “is-active” CSS class for selected manufacturer. Use {manufacturer:selected_class} in the template html.

Usage

<f:ManufacturerList>
    <param name="wrapper">ul.manufacturer-list.plain.wrap.cf</param>
    <li class="manufacturer-item">
        <a href="{f:manufacturer:href}" class="manufacturer-link" title="{f:manufacturer:name}">
           <img class="manufacturer-img" src="{f:manufacturer:ImageSrc(thumb)}" alt="{f:manufacturer:name}">
        </a>
    </li>
</f:ManufacturerList>

MostPopularCategories

Prints the most popular categories based on category page view counts.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a category. If this parameter is not given, inline template html will be used.
count Required How many categories to show.

Usage

<f:MostPopularCategories>
    <param name="wrapper">ul.category-list.plain.wrap.cf</param>
    <param name="count">10</param>
    <li class="category-item">
        <a href="{f:category:href}" class="category-link" title="{f:category:name}">
           <img class="category-img" src="{f:category:ImageSrc(thumb)}" alt="{f:category:name}">
        </a>
    </li>
</f:MostPopularCategories>

MostPopularSearches

Prints links to most popular product searches.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a product search link. If this parameter is not given, inline template html will be used.
count Required How many product search links to show.
font_size_min Required The minimum size for the product search links printed.
font_size_max Required The maximum size for the product search links printed.

Usage

<f:MostPopularSearches>
    <param name="count">20</param>
    <param name="font_size_min">10</param>
    <param name="font_size_max">30</param>
    <span style='font-size:{phrase:font_size}px;'>
        <a href='{phrase:href}'>{phrase:phrase}</a>
    </span>
</f:MostPopularSearches>

Partial

Renders a partial file located in template theme directory “partials”. Partial file is firstly checked from selected template theme, and if not found there, from global template theme. Error is printed, if the file is not found from either places.

Parameters

No <param> tags are needed. Just give the partial name inside the template function tag.

Usage

<f:Partial>header</f:Partial>

PaymentMethodList

Prints all payment methods that are set visible from the payment method management.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a payment method. If this parameter is not given, inline template html will be used.

Usage

<f:PaymentMethodList>
    <span class='payment-method-item'>
        <img class="payment-method-img" src="{payment_method:ImageSrc()}" alt="{payment_method:name}">
    </span>
</f:PaymentMethodList>

ProductImageList

Prints all images for a product.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a product image. If this parameter is not given, inline template html will be used.
product_id Optional on product page. Otherwise this parameter must be given. On product page defaults to current product id. Product id for which images should be printed.

Usage

<f:ProductImageList>
    <param name="wrapper">ul.product-main-images.plain.cf</param>
    <li>
        <a href="{image:Src(orig)}" class="product-main-image-link center-img fancybox" data-fancybox-group="product-images" title="{image:text}">
            <img src="{image:Src(prpage)}" alt="{image:text}" class="product-main-image">
        </a>
    </li>
</f:ProductImageList>
 
<f:ProductImageList>
    <param name="wrapper">ul.product-thumbs.plain.cf</param>
    <li class="product-thumb-item">
        <a href="#" data-slide-index="{image:ItemIndex(0)}" class="product-thumb center-img">
            <img src="{image:Src(thumb)}" alt="{image:text}" class="product-thumb-image">
        </a>
    </li>
</f:ProductImageList>

ProductImageUploader

This template function is used to activate image uploader for a product. The selected file is uploaded using Ajax when product is added to cart.

ProductImageUploader extends FormHandler template function.

Requirements:

  • Form element's start tag must contain {form:id} as id: <form id='{form:id}'>
  • Specify a result element having {form:result_element_id} as id.
  • These must be found included:
    • /site/templates/global/assets/js/form_handler.js
    • /site/templates/global/assets/js/dropzone.js
    • /site/templates/global/assets/css/dropzone.css

Parameters

Name Required / Optional Default value Description
product_id Required Id for the product for which the image should be uploaded.
partial Optional Partial that contains the template html for the form. If this parameter is not given, inline template html will be used.
max_filesize Optional 3 How big files are allowed for upload. Supported values: Positive integers or decimal numbers in format “3.5”.
result_element_id Optional “form-result-element-for-{form:id}” Used to match the element that should contain the form handler action's result given using Ajax. Must be unique for each FormHandler.
result_element_class Optional “alert” The basic class that will be given to result element after action is performed.
result_element_success_class Optional “alert-success” The class that will be given to result element if action was successful.
result_element_error_class Optional “alert-error” The class that will be given to result element if action was not successful.
result_element_notice_class Optional “alert-warning” The class that will be given to result element if action result contained a notice.

JavaScript handlers (Version: 2.1.2.0)

These handlers can be bound in parameter “js.ready”.

Handler When it is applied Notes
beforeAction Before uploading the file using Ajax. If you throw an error, the file will not be uploaded. Thrown error message will be shown to user.
afterAction After the Ajax request has been performed. First parameter is an object containing data from the action.
success After successful file upload. First parameter is an object containing data from the file upload action.
error After unsuccessful file upload. First parameter is an object containing data from the file upload action.
complete After success or error handler. First parameter is an object containing data from the file upload action.

Usage

On product page:

<?php if ($product->IsImageUploadAllowed()): ?>
    <f:IncludeJS>dropzone.js</f:IncludeJS>
    <f:IncludeCSS>dropzone.css</f:IncludeCSS>
    <f:ProductImageUploader>
        <param name="wrapper">div.image-upload-form-wrapper</param>
        <param name="product_id">{product:id}</param>
 
        <param name="js.ready">
            this.Bind("beforeAction", function() {
                console.log("ProductImageUploader: BeforeAction!");
                // throw "an error message to prevent file upload.";
            });
            this.Bind("afterAction", function(action_result) { console.log("ProductImageUploader: AfterAction!"); });
            this.Bind("success", function(action_result) { console.log("ProductImageUploader: Success!"); });
            this.Bind("error", function(action_result) { console.log("ProductImageUploader: Error!"); });
            this.Bind("complete", function(action_result) { console.log("ProductImageUploader: Complete!"); });
        </param>
 
        <form id="{form:id}"></form>
        <div id="{form:result_element_id}"></div>
 
    </f:ProductImageUploader>
<?php endif; ?>

ProductList

Prints different kinds of product lists specified by parameter “content”.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a product. If this parameter is not given, inline template html will be used.
content Required on pages other than category / manufacturer page On category / manufacturer page defaults to current category's / manufacturer's product list. This parameter defines the content of this product list. See below for supported values and examples.
name Required Name of this ProductList template function. Must be unique.
count Required with: “most_sold_in_category”, “newest”, “offers”, “most_sold”, “recently_sold”, “front_page”, “back_to_stock”. Optional with: “pre_orders”, “related”. Only with “related”: Value for ProsperCart setting “number_of_related_products”. How many products to show. Supported only with: “most_sold_in_category”, “newest”, “offers”, “most_sold”, “recently_sold”, “front_page”, “back_to_stock”, “pre_orders”, “related”. For other product lists there is no count limit.
cache_products Optional “true” If “true” or “1”, products will be cached for an hour.
sorting Optional “false” If “true” or “1”, this product list can be sorted and sorting can be altered by user using ProductListUpdater template function.
default_sort Optional Defines the sorting method that is used until another sorting method is selected (using ProductListUpdater). See below for supported sorting methods.
forced_sort Optional Forces the sorting method so that nothing can change it. See below for supported sorting methods.


Supported “content” values:

Content value Product list result
“category:{category:id}” Products from current category. This is the default value on category pages.
“category:12” Products from specific category with id 12.
“manufacturer:{manufacturer:id}” Products from current manufacturer. This is the default value on manufacturer pages.
“manufacturer:7” Products from specific manufacturer with id 7.
“most_sold_in_category:{category:id}” Most sold products from current category. This is the default value on category pages.
“most_sold_in_category:12” Most sold products from specific category with id 12.
“search” Product search results.
“newest” Newest products.
“most_sold” Most sold products.
“recently_sold” Recently sold products.
“offers” Product offers.
“offers:random” Product offers ordered randomly.
“front_page” Front page products.
“back_to_stock” Products that have most recently come back to stock.
“highlight:1” The product that is marked as the first highlight product.
“highlight:2,3,4” The second, third and fourth highlight products.
“related:100007” Related products for product with id 100007.
“pre_orders” All products that are marked as pre-order products.
“pre_orders:12” Pre-order products only from category with id 12.


Supported sorting methods:

Sorting method key Result
“original” This is the original order in which the products are shown when sorting is not activated. For example on the category pages the products are shown in the order specified in the product management.
“price_asc” The cheapest products are shown first.
“price_desc” The most expensive products are shown first.
“date_desc” The newest products are shown first.
“date_asc” The oldest products are shown first.
“alphabetical_asc” Products are shown from A to Z.
“alphabetical_desc” Products are shown from Z to A.
“sold_desc” The most sold products are shown first.
“random” Products are shown in random order. Only supported for front page products.


ProductListUpdater related parameters:

Name Required / Optional Default value Description
updater Optional “false” If “true” or “1”, this product list can be altered by user using ProductListUpdater template function.
wrapper Required if “updater_wrapper_element_selector” is not given. Wrapper element is automatically created (as usual). It will be used as the wrapper for real time updating if “updater_wrapper_element_selector” is not given.
updater_wrapper_element_selector Required if “wrapper” is not given. A jQuery selector that defines the wrapper element for real time updating. A unique element matching given selector must be found and contain the product list. This parameter can be used if you want to specify the wrapper element yourself (without using parameter “wrapper”).


ProductListPagination related parameters:

Name Required / Optional Default value Description
pagination Optional “false” If “true” or “1”, products will be paginated using ProductListPagination template function.
wrapper Required if “pagination_wrapper_element_selector” is not given. Wrapper element is automatically created (as usual). It will be used as the wrapper for real time pagination if “pagination_wrapper_element_selector” is not given.
pagination_wrapper_element_selector Required if “wrapper” is not given. A jQuery selector that defines the wrapper element for real time pagination. A unique element matching given selector must be found and contain the products that are paginated. This parameter can be used if you want to specify the wrapper element yourself (without using parameter “wrapper”).
products_per_page Optional Value for ProsperCart setting “products_per_page” How many products should be printed on a single pagination step.

Usage

Newest products:

<f:ProductList>
    <param name="name">product_list_front_newest</param>
    <param name="wrapper">div.newest-products</param>
    <param name="partial">product-newest-item</param>
    <param name="content">newest</param>
    <param name="count">12</param>
</f:ProductList>

Category products with pagination (on category pages, category.inc):

<f:ProductListPagination>
    <param name="product_list_name">category_list</param>
    <param name="wrapper">div.pagination-links</param>
    <param name="autoload">true</param>
    <param name="autoload_distance">100</param>
    <param name="show_near_count">2</param>
    <param name="link_divider">
        <span class='pagination-divider'>&hellip;</span>
    </param>
    <param name="previous_page_link">
        <a class='pagination-show-more-link icon-loader btn'><span>{text:pagination_load_prev_page}</span></a>
    </param>
    <param name="next_page_link">
        <a class='pagination-show-more-link icon-loader btn'><span>{text:pagination_load_next_page}</span></a>
    </param>
 
    <a class='js-pagination-page-link pagination-link'><span>{pagination:page_number}</span></a>
</f:ProductListPagination>
 
<f:ProductList>
    <param name="name">category_list</param>
    <param name="wrapper">ul.product-list.plain.cf</param>
    <param name="products_per_page">24</param>
    <param name="partial">productlist</param>
    <param name="pagination">true</param>
    <param name="cache_products">false</param>
    <param name="empty">
        <p class="alert alert-info alert-center">{text:products_not_found}</p>
    </param>
</f:ProductList>

ProductListPagination (Version: 2.3.0.0)

Activates pagination functionality in a ProductList specified by parameter “product_list_name”.

Parameters

Name Required / Optional Default value Description
product_list_name Required The name of the ProductList that should be paginated.
autoload Optional “false” If “true” or “1”, more products are loaded automatically when the user scrolls down the product list.
autoload_distance Optional “0” If autoloading is activated, this defines how many pixels before the last loaded product we should start loading more products. Supported values: Non-negative integers
pagination_link_selector Optional “.js-pagination-page-link” This specifies the jQuery selector for page link elements.
visible_class Optional “is-visible” This class will be given to page link elements that are visible based on parameter “show_near_count”.
hidden_class Optional “is-hidden” This class will be given to page link elements that are hidden based on parameter “show_near_count”.
selected_class Optional “is-active” This class will be given to selected page link element.
page_loading_class Optional “is-loading” While more products are loading, this class will be given to the wrapper element containing the product list, and if given, to either load previous page or load next page link (defined using parameters “previous_page_link” and “next_page_link”).
previous_page_link Optional If given, this element will be inserted before the wrapper element containing the product list. Clicking this element will load products on the previous page using Ajax.
next_page_link Optional If given, this element will be inserted after the wrapper element containing the product list. Clicking this element will load products on the next page using Ajax.
show_near_count Optional “1” This specifies how many page link elements should be shown near the selected page link element.
link_divider Optional “<span>&hellip;</span>” This element will substitute page link elements that are hidden based on parameter “show_near_count”.

JavaScript handlers (Version: 2.1.2.0)

These handlers can be bound in parameter “js.ready”.

Handler When it is applied Notes
beforeAction Before sending the Ajax request to load more products.
afterAction After the Ajax request has been performed. First parameter is an object containing data from the action.
complete After more products has been loaded. First parameter is an object containing data from the action.
<param name="js.ready">
    this.Bind("beforeAction", function() {
        console.log("Before loading more products.");
    });
    this.Bind("complete", function(data) {
        console.log(data);
    });
</param>

Usage

See example on ProductList template function.

ProductListUpdater

This template function is used to update a ProductList using Ajax. Updating is done through triggers that are described inside template html. Supported update actions and triggers are:

Action Trigger example
Set partial {updater:SetPartial(partial_name)}
Set sorting method {updater:SetSorting(price_asc)}

See ProductList documentation for supported sorting methods.

Parameters

Name Required / Optional Default value Description
product_list_name Required The name of the ProductList that should be updated.
set_partial_class Optional “js-trigger-set-partial” This class will automatically be given to triggers that set partial.
selected_set_partial_class Optional “selected” The class given to selected trigger that sets partial.
set_sorting_class Optional “js-trigger-set-sorting” This class will automatically be given to triggers that set sorting method.
selected_set_sorting_class Optional “selected” The class given to selected trigger that sets sorting method.
general_trigger_class Optional “js-trigger-product-list-updater” This class will automatically be given to all triggers.

JavaScript handlers (Version: 2.1.2.0)

These handlers can be bound in parameter “js.ready”.

Handler When it is applied Notes
beforeAction Before sending the Ajax request to update product list.
afterAction After the Ajax request has been performed. First parameter is an object containing data from the action.
complete After the product list has been updated. First parameter is an object containing data from the action.
<param name="js.ready">
    this.Bind("beforeAction", function() {
        console.log("Before the updater action.");
    });
    this.Bind("complete", function(data) {
        console.log(data);
    });
</param>

Usage

<f:ProductListUpdater>
    <param name="wrapper">div.listing-functions.cf</param>
    <param name="product_list_name">category_list</param>
    <ul class="set-listing plain cf">
        <li class="set-listing-item">
            <a {updater:SetPartial(productlist)} href="#" class="set-listing-link icon-grid"></a>
        </li>
        <li class="set-listing-item">
            <a {updater:SetPartial(productlist-list)} href="#" class="set-listing-link icon-list"></a>
        </li>
    </ul>
 
    <div class="product-sorting cf">
        <span class="product-sorting-title">{text:sorting_order}:</span>
        <select class="input-text input-select select-sorting">
            <option {updater:SetSorting(original)}>{t:sort_by_original}</option>
            <option {updater:SetSorting(price_asc)}>{t:sort_by_price_asc}</option>
            <option {updater:SetSorting(price_desc)}>{t:sort_by_price_desc}</option>
            <option {updater:SetSorting(date_desc)}>{t:sort_by_date_desc}</option>
            <option {updater:SetSorting(date_asc)}>{t:sort_by_date_asc}</option>
            <option {updater:SetSorting(alphabetical_asc)}>{t:sort_by_alphabetical_asc}</option>
            <option {updater:SetSorting(alphabetical_desc)}>{t:sort_by_alphabetical_desc}</option>
        </select>
    </div>
</f:ProductListUpdater>
 
<f:ProductList>
    <param name="wrapper">ul.product-list.plain.cf</param>
    <param name="name">category_list</param>
    <param name="partial">productlist</param>
    <param name="updater">true</param>
    <param name="sorting">true</param>
    <param name="cache_products">false</param>
    <param name="empty">
        <p class="alert alert-info alert-center">{text:products_not_found}</p>
    </param>
</f:ProductList>

ProductOptionList

Prints product option list for the product specified by parameter “product_id”.

Parameters

Name Required / Optional Default value Description
partial Required Partial that contains the template html for a product option item. If this parameter is not given, inline template html will be used instead (the php variables referencing to the current list item used in the template html are not usable.)
product_id Required The id of the product
name Required Name of this ProductOptionList template function. Must be unique.
after_select_tag Optional template html content that is printed after options printed with type 'select' - container

Usage

Listing the product options with product-option-list-item partial

<f:ProductOptionList>
    <param name="wrapper">div.product-list.plain.cf</param>
    <param name="name">products_options</param>
    <param name="product_id">{product:id}</param>
    <param name="partial">product-option-list-item</param>
</f:ProductOptionList>  

Listing the product options with the “add to cart” - buttons

<f:ProductOptionList>
    <param name="wrapper">div.product-list.plain.cf</param>
    <param name="name">products_options</param>
    <param name="product_id">{product:id}</param>
    <param name="after_select_tag">
        <div class="product-option-add">
             <input {product_option:AddToCart(selection_quantity)} class="product-qty input-text" type="number" min="1" max="999" maxlength="3" value="1"> {text:pcs}
            <button {product_option:AddToCart(selection_trigger)} class='btn btn-buy-icon'><i class="icon-cart"></i></button>
        </div>
    </param>
    <param name='partial'>product-option-list-add-to-cart-btn-item</param> 
</f:ProductOptionList>  

ProductReviewList

Prints published product reviews for a product.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a product review. If this parameter is not given, inline template html will be used.
product_id Optional on product page. Otherwise this parameter must be given. On product page defaults to current product id. Product id for which reviews should be printed.
count Required How many product reviews to show.
empty Optional “” What should be printed when there are no reviews to show.

Usage

<f:ProductReviewList>
    <param name="wrapper">div.product-review-list.cf"</param>
    <param name="count">3</param>
    <param name="empty">
        <p class="info-text">{text:no_product_reviews}</p>
    </param>
 
    <div class="product-review">
        <f:ReviewRating>
            <param name="wrapper">ul.review-stars.plain.cf</param>
            <param name="scale">5</param>
            <param name="rating">{review:points}</param>
            <li class='{rating:active_class} product-star icon-star'></li>
        </f:ReviewRating>
        <p class="info-text">{review:ReviewDate()} - {review:name}</p>
        <div>{review:text}</div>
    </div>
</f:ProductReviewList>

ReviewRating

Prints review rating items having the amount of items defined with parameter “scale”. The actual rating is defined with parameter “rating” so that the first “rating” amount of items will get a CSS class defined in parameter “active_class”. This template function be used for product reviews with “scale” value “5”.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a rating item. If this parameter is not given, inline template html will be used.
scale Required The maximum rating.
rating Required The actual rating.
active_class Optional “is-active” CSS class for items that represent the actual rating. Use {rating:active_class} in the template html.

Usage

Used on product page to show the average review points given:

<f:ReviewRating>
    <param name="wrapper">ul.product-stars.plain.cf</param>
    <param name="scale">5</param>
    <param name="rating">{product:AverageReviewPoints()}</param>
    <li class='{rating:active_class} product-star icon-star'></li>
</f:ReviewRating>

See ProductReviewList documentation for how to use for individual product reviews.

ShoppingCartPreview

Prints a preview for shopping cart content and total price. Preview html is updated in real time when products are added to cart.

Requires JavaScript file “shopping_cart_preview.js” which can be included like this: <f:IncludeJS>shopping_cart_preview.js</f:IncludeJS>

Notice: It's not allowed to use ShoppingCartPreview on shopping cart page.

Parameters

Name Required / Optional Default value Description
partial Required Partial that contains the template html for the shopping cart preview.
wrapper Required if “wrapper_element_selector” is not given. A wrapper element (that is automatically created) will be used as the wrapper for real time updating.
wrapper_element_selector Required if “wrapper” is not given. A jQuery selector that defines the wrapper element for real time updating.

You should use either “wrapper” or “wrapper_element_selector”, not both. If “wrapper” is given, wrapper element is automatically created as usual. If “wrapper_element_selector” is given, a unique element matching given selector must be found inside given partial. The wrapper element is used to wrap the content that should be updated in real time when products are added to shopping cart.

JavaScript handlers (Version: 2.1.2.0)

These handlers can be bound in parameter “js.ready”.

Handler When it is applied Notes
beforeAction Before sending the Ajax request to update shopping cart preview.
afterAction After the Ajax request has been performed. First parameter is an object containing data from the action.
complete After the shopping cart preview has been updated. First parameter is an object containing data from the action.
<param name="js.ready">
    this.Bind("beforeAction", function() {
        console.log("Before updating the shopping cart preview.");
    });
    this.Bind("afterAction", function(data) {
        console.log(data);
    });
</param>

Usage

ShoppingCartPreview template function:

<?php if ($page->codename != 'shopping_cart'): ?>
    <f:ShoppingCartPreview>
        <param name="wrapper_element_selector">.sc-preview</param>
        <param name="partial">sc-preview</param>
    </f:ShoppingCartPreview>
<?php endif ?>

Notice: Shopping cart preview is not supported on shopping cart page.

Partial sc-preview.inc:

<div id="sc-preview" class="sc-preview cf">
 
    <a href="{global:Href(shopping_cart)}" class="js-header-link header-link cart-link icon-cart" title="{t:shopping_cart_title}" rel="header-cart">
        <span class="sc-prev-title">{t:shopping_cart_title}</span>
        <?php if ($cart->HasProducts()): ?>
        <span class="sc-total-alert">{cart:ProductsCount()}</span>
        <?php else: ?>
        <span class="sc-total-alert sc-total-alert-empty">{cart:ProductsCount()}</span>
        <?php endif ?>
    </a>
 
    <div id="header-cart" class="header-dropdown hide-mobile cf">
        <div class="sc-inner">
            <?php if ($cart->HasProducts()): ?>
            <div class="sc-total-count">{text:items_in_cart_1} {cart:ProductsCount()} {text:items_in_cart_2}</div>
            <?php
            foreach($cart->GetProducts() as $cart_product):
                echo "<div class='sc-item-row cf'>";
                echo "<div class='sc-item-image center-img'>";
                if ($cart_product->HasMainImage())
                {
                    echo "<img src='" . $cart_product->ImageSrc(1, "scprev") . "'/>";
                }
                else
                {
                    echo "<div class='no-image icon-camera'></div>";
                }
                echo "</div>";
                echo "<div class='sc-item-name'>" . $cart_product->quantity . "x <a href='" . $cart_product->href . "' title='" . $cart_product->name . "'>" . $cart_product->name . "</a></div>";
                echo "<div class='sc-item-price'>" . $cart_product->ActualPrice() . "</div>";
                echo "</div>";
            endforeach;
            ?>
            <div class="sc-preview-total-price">{t:sc_total}: <span class="sc-item-price">{cart:TotalSum()}</span></div>
 
            <a href='{global:Href(shopping_cart)}' class='btn sc-preview-checkout'><i class="icon-cart"></i> {text:to_checkout}</a>
 
            <?php else: ?>
            <p class="sc-empty alert">{t:sc_is_empty}</p>
            <?php endif ?>
        </div>
    </div>
</div>

ShopReviewList

Prints the given amount of published shop reviews randomly.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a shop review. If this parameter is not given, inline template html will be used.
count Required How many shop reviews to show.
empty Optional “” What should be printed when there are no reviews to show.

Usage

<f:ShopReviewList>
    <param name="wrapper">div.shop-review-list.cf"</param>
    <param name="count">5</param>
 
    <div class="shop-review">
        <f:ReviewRating>
            <param name="wrapper">ul.review-stars.plain.cf</param>
            <param name="scale">5</param>
            <param name="rating">{review:points}</param>
            <li class='{rating:active_class} shop-star icon-star'></li>
        </f:ReviewRating>
        <p class="info-text">{review:ReviewDate()} - {review:name}</p>
        <div>{review:text}</div>
    </div>
</f:ShopReviewList>

SiblingCategories

Prints all sibling categories for given category.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a category. If this parameter is not given, inline template html will be used.
category_id Optional on category page. Otherwise this parameter must be given. On category page defaults to current category id. Category id for which sibling categories should be printed.
selected_class Optional “is-active” CSS class for selected category. Use {category:selected_class} in the template html.

Usage

<f:SiblingCategories>
    <param name="wrapper">ul.siblingcategories.plain.cf</param>
    <li class="siblingcategory-item">
        <a href="{f:category:href}" class="siblingcategory-link {f:category:selected_class}" title="{f:category:name}">{f:category:name}</a>
    </li>
</f:SiblingCategories>

StaticContent

Prints static content that are created in Layout text management.

Parameters

No <param> tags are needed. Just give the layout text name inside the template function tag.

Usage

<f:StaticContent>info_content</f:StaticContent>

Subcategories

Prints all immediate subcategories for given category.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a category. If this parameter is not given, inline template html will be used.
category_id Optional on category page. Otherwise this parameter must be given. On category page defaults to current category id. Category id for which subcategories should be printed.

Usage

<f:Subcategories>
    <param name="wrapper">ul.subcategories.plain.cf</param>
    <li class="subcategory-item">
        <a href="{f:category:href}" class="subcategory-link" title="{f:category:name}">{f:category:name}</a>
    </li>
</f:Subcategories>

TierPrices

Prints tier price rows for a product with AddToCart functionality.

Parameters

Name Required / Optional Default value Description
partial Optional Partial that contains the template html for a tier price row. If this parameter is not given, inline template html will be used.
product_id Optional on product page. Otherwise this parameter must be given. On product page defaults to current product id. Product id for which tier prices should be printed.

Usage

<f:TierPrices>
    <param name="before">
        <div class="tier-prices cf">
        <table class='tier-prices-table'>
            <tr>
                <th>{t:w_tier_qty}</th>
                <th>{t:w_tier_price}</th>
                <th>{t:w_tier_total}</th>
                <th>&nbsp;</th>
            </tr>
    </param>
    <param name="after">
        </table>
        </div>
    </param>
 
    <tr>
        <td class='tier-qty'>{tier:Quantity()}</td>
        <td>{tier:UnitPrice()}</td>
        <td>{tier:TotalPrice()}</td>
        <td><a class='btn btn-buy btn-tier-price' {tier:AddToCart()} href='#'>{t:w_tier_buy}</a></td>
    </tr>
</f:TierPrices>
template_functions.txt · Last modified: 2017/05/03 09:25 (external edit)
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0