Custom templates (layouts)

What are custom templates?

With very few exceptions (the products modules for example are an exception, they have 2 list type layouts) most modules had one of each, the but the general rule is one module - a single set of layouts.

Custom templates are basically an extension to regular layouts. Now you can create as many custom layoutes for any module that supports this feature.

Another usage for custom templates is to suppress the output of modules. If you are using Liquid collections for example to suppress a module's output you might build your own rendering logic instead, see the "collection" parameter for more details on this approach.

Use custom layouts to render modules

The custom templates are actually plain files however we usually advise to change their extension to .tpl - that is to avoid having them indexed by search engine bots.

The simplest way to get started is to create a new empty file, let's call it productfeaturelist.tpl and create it under the /layouts/onlineshop/custom/ folder. Next, we need to populate it with some tags. The easiest way to get started is to copy the HTML code of an existing layout and paste it into the productfeaturelist.tpl file.

Step 1 - create the custom template file


  1. Go to the Pages > Module Templates > Online Shop Layouts and open up the Individual Product - Small.
  2. Switch to the HTML view and copy everything. Go to the productfeaturelist.tpl file and paste everything in there. To confirm the new custom template is rendering properly add a few new tags so it looks differently then the regular Individual Product - Small layout.

Step 2 - configure the module to use the custom template


  1. Now that the custom template is created and populated we need to add an eCommerce module and configure it to use it.
  2. Let's assume we need a product listing to use this new template. This means we will use the {module_productfeaturelist} module. This is the syntax we will use:

    {module_productfeaturelist,special offer,3,price,_blank,true template="/layouts/onlineshop/custom/productfeaturelist.tpl"}

If you insert this on a webpage and preview that webpage you will notice it is using the custom layout instead of the default Individual Product - Small.

Use custom layouts to suppress a module's output

With the introduction of collections you might want a module not to output anything and use only its collection representation to render the data.

To hide a module's output simply remove the path to the custom layout specified by the template parameter.

For example this webapp module

{module_webapps collection="myWebapp" render="collection" template="/layouts/custom/car_collection.tpl" id="35209" filter="all"}

Will do two things - render the webapp items according to the template="/layouts/custom/car_collection.tpl" layout and will create the myWebapp collection in the background.

This module on the other hand:

{module_webapps collection="myWebapp" template="" id="35209" filter="all"}

will not render anything. In this scenarioit will only create the collection and it's up to you how to display its contents.

Syntax

The general rule is the template="/layouts/onlineshop/custom/productfeaturelist.tpl" string is added at the end of the module declaration just before the ending curly bracket.

Make sure you use double brackets instead of single brackets. This is incorrect: {module_productfeaturelist,special offer,3,price,_blank,true template='/layouts/onlineshop/custom/productfeaturelist.tpl'}

Parameters

The custom template declaration has only one parameter, that is the path to the file itself. If the file does not exist or it cannot be found for any reason the module will render with its default layout instead. So for example if the custom template file "/layouts/onlineshop/custom/productfeaturelist.tpl" does not exist or we have a typo in its path the {module_productfeaturelist} module will render using the Individual Product - Small layout instead.

Note: if the value of template parameter is empty template=”” you will end up having an empty output - see related section above.

Examples

  • {module_productfeaturelist,special offer,3,price,_blank,true template="/custom-layouts/prod.tpl"} - this rendes a list of products using this custom template
  • {module_booking,i,63522 template="/custom-layouts/booking.tpl"} - this rendes an individual event a custom template
  • {module_product,63882,5450055,_top template="/custom-layouts/prod.tpl"} - this rendes an individual product a custom template
  • {module_productfeaturelist,special offer,3,price,_blank,true template="/custom-layouts/prod.tpl"} - lists the products that are tagged with the "special offer" tag using a custom template (the "true" parameter that states the backup template should be used is ignored). The products are sorted by price (cheapest first) and when clicking the product's name the detail view opens in a new window
  • {module_productresults,2,_self,2,,,true template="/custom-layouts/prod.tpl"} - displays the products that match the search criteria 2 per page and renders No products found matching your query. if no products are found. The structure is no longer an unordered list as the true parameter would suggest, the custom template is used instead.

Supported Modules

Here is the list of modules where you can apply your own templates as attributes:

  • {module_literature}
  • {module_announcement}
  • {module_faq}
  • {module_forum}
  • {module_blog}
  • {module_case}
  • {module_order}
  • {module_webappscustomer}
  • {module_affiliateprogram}
  • {module_webappsresults}
  • {module_booking}
  • {module_catalogue}
  • {module_product}
  • {module_productresults}
  • {module_ratingfeedback}
  • {module_caseresults}
  • {module_webapp}
  • {module_blogsitepost}
  • {module_blogpostlist}