SW-Retail Handleiding: Webshop templating

Lees dit eerst!

Belangrijke informatie over het stylen van je webshop!

SW-Retail bied 3 varianten om je webshop aan te passen aan je eigen huisstijl.

1) Je past alleen dingen aan die in het configuratie scherm aan te passen zijn zonder HTML / CSS te gebruiken. Hiermee kun je lettertypes / kleuren / logos e.d. aanpassen. Hiermee ben je _altijd_ compatibel met een upgrade en heb je geen technische uitdagingen en kunnen we je volledig ondersteunen met al je vragen.

2) Je doet alles uit punt 1, maar daarnaast biedt het configuratie scherm ook nog wat extra velden waarin je CSS / Javascript kunt plakken. Hiermee kan je thema nog altijd geupdate worden, en loop je een sterk verminderd risico op problemen / aanpassingen na een update. Deze kunnen echter nog wel ontstaan en moet je dan wel zelf oplossen.

3) Je zet het vinkje "ik pas mijn thema zelf aan" op actief, en gaat de thema bestanden zelf wijzigen. Hiermee heb je verreweg de meeste vrijheid om dingen aaan te passen en te wijzigen, en je webshop volledig op smaak te maken. Niets is dan bijna te gek. Je thema is dan echter niet meer updatebaar, en de kans is aanwezig dat na een update van SW-Retail je thema ook aangepast moet worden. We zijn niet in staat van te voren (dus voor een SW-Retail update) aan te geven of er iets in je thema aangepast moet worden na de update. Uiteraard doen we ons uiterste best dat dit niet hoeft, maar we kunnen niets meer garanderen. Goede kennis van HTML / CSS / Javascript, of een webbouwer, is absoluut noodzakelijk voor deze optie. Maak hier afspraken over met je webbouwer!

We hebben de rest van de documentatie over het aanpassen van het thema in het engels gemaakt, zodat je maximale vrijheid hebt bij het kiezen van een webbouwer mocht je dat willen.

General information

It is possible to modify the templates of the SW-Retail Webshop system. The system allows you to modify

the stylesheet
the template files that are used to generate the webshop_templating
extend the javascript

The files are available using SFTP. The templating system reads the template files and based upon that the webshop is generated. Files are cached by the caching engine, but when a file changes the cache is automatically updated.

General

The templating system does not offer a real scripting language. It is deemed to complex and to insecure to allow this. So no php / python or whatever you are used to. Instead, the system works with a templating system that provides variables that are populated from the backend of the webshop system. To inject the value of a variable you can use brackets { }. For example {shopname} to display the name of the webshop. The shopname variable is filled by the webshop system based upon what you put in the configuration of SW-Retail.

It is possible to use foreach and if statements in the templating system. Also it is possible to introduce variables and allow the end user to set them in the userinterface of SW-Retail.

Before the templater starts working you have to give the start command for the templater {templater_start} . To stop the templater use {templater_stop}. You can also toggle the templater with the shortcut {$}

Files

You can find the files in your SFTP directory /webshop_/ For basis setups the webshop id will generally be 1.

All themes that are published by SW-Retail can be found on GITHUB. Link! We also store the latest version of the themes there. So in case new functionality has been introduced you can find the latest version there and backport it in your theme

If you mess something up, you can redeploy the base theme via the

Template files

You should not change the filenames on the SFTP server since it wil break the webshop system. Also, these files are not avaiable to the public, it is impossible to download the sources via the webserver. The folowing files comprise a template

Filename	Explanation
footer.ctp	Footer of the webshop
header.ctp	Header of the webshop
base.ctp	The base file of the webshop. This file is loaded first.
article_list.ctp	This is loaded for listing articles
article_list_small.ctp	This is loaded for listing small article lists (for example lists of cross / upsell / homepage articles)
article_detail.ctp	Article detail page
article_search_results.ctp	The page for layouting search results
checkout.ctp	Checkout page
customer_login.ctp	Login page for a customer that wants to login
customer_orders.ctp	Page that gets shown when a customer lists its orders
system_blocks.ctp	Contains all blocks needed for rendering the webshop, it is by default empty. You can override blocks in this file
configurables.ctp	Contains variables. These variables can be set in the SW-Retail UI if needed for your theme.

Template static files

These files are available to the public. All directories are relative to /public/webshop_/.

You can also store other files here.

Filename	Explanation
/javascript.js	This is a virtual file. Contains the javascript of the webshop(WE DO NOT RECOMMEND TO OVERRIDE THE JAVASCRIPT)
css/stylesheet.css	Contains the stylesheet of the webshop
/webshop_stylesheet.css	This is a virtual file. Contains additional styling, which comes from the configuration within SW-Retail. You won't find this file, but it is there. You can also override this but settings won't work then in SW-Retail
css/font_awesome_all.min.css	Contains fontawesome for nice icones
css/bootstrap*	Contains the bootstrap framework, when a template is loaded with bootstrap. Do not change
js/jquery.zoom.min.js	Contains a small zoom library /
js/bootstrap*	Contains the bootstrap framework. Do not change!

We do not recommend to override virtual files as they are updated in every upgrade, for new features and bug fixes. If you override them you will get in trouble sooner or later.

Images of articles are stored in a different location. You cannot access these. Also, images that are uploaded in SW-Retail for the CMS are also stored in a location that is inaccessible via SFTP.

There is a public webspace available, it is located in the /public directory.

Do not store video on the public webspace

It is a violation of our terms and conditions to serve video content. Video must be delivered from a proper CDN.

Javascript and ID's and classes

The webshop system frontend includes a javascript file, javascript.js. This file contains the core "engine" of the webshop frontend. We have kept it as simple and minimal as possible. You can completely override the javascript but beware this needs to be maintained then by yourself. In general, if you wish to modify the template, do not tamper with the javascript when possible. Or, override just one function of the javascript classes.

The javascript has some objects. The most important ones are

swShopHelper - mainly DOM manipulation functions that get reused from swShop
swShop - the main shop engine which does most of the ajax calls
swCustomer - handles most customer interaction
swPaymentProvider - helper for handling payments
swSendMethods - helper for sendmethods
language - contains a language translation table

Settings in the frontend

The platform loads a div with id ajax-helper which contains some attributes with information about the current loaded page.

The platform sets an object javascript shopConfiguration which contains information about the configuration of the shop.

ID's and classes

It is important that to tie the javascript and DOM together that ID's and classes on elements are not changed! You can add classes if you want, you can also modify CSS for existing classes.

Article fields

You can refer in the template to the articles fields. For example {artoms}

There is also a possibility to show all free fields. For that, freefields need to have an internal name set (column "Interne naam") You can refer to this internal name for displaying the internal fields. Alternatively (and this is the default behaviour for themes) you can use the field {article_freefields} for a list of all freefields.

Session

You can access the session manager to store persistent values (for example somebody clicked Cookie OK) or something like that.

Session example

<!-- Read the session variables-->
{define_l:myplugin_session:data.session}

<!-- Now we can read session variables .. -->
{if:{myplugin_session:sw_web_sortorder}:=:artoms_az}
Sorting from a to z
{if_end}

<!-- To set a session variable -->
{write:data.session:myplugin_key:value}

for instance
{write:data.session:sw_web_sortorder:artoms_za}

Webspace

The webshop system allows for hosting some files , also without scripting possibilty. They are located in /public on your SFTP location.

The webserver first looks into the /public directory to see if a file exists there. If not, it will continue towards the webshop platform. This means, if you have for example a file checkout in your public directory this file will be server for the checkout and will essentially break the webshop platform. Be carefull of this.

When you run into problems

You can redeploy the "default" file from the administration pages of SW-Retail. If you run into deep-trouble you can ask the helpdesk to redeploy the shop.

The helpdesk does not debug templating issues. If you run into an issue, the default response will be to redeploy the templates. If the problem is then solved we close our case.

The helpdesk cannot assist in debugging problems that arise from templating issues.

Of course you can always contact us for questions and general inquiry.

Article images

Each article image is resized into two tumbnails and the offcourse the original image is kept.

mini
small

You can request these images by requesting the url image/small/ or image/mini/

It is strongly adviced to use the smalles image that gives an accetable result. Keep in mind: The modern web is NOT about image quality but about SPEED.

Variables

The webshop engine contains a simple template parser which is able to do not too complex parsing. You can read almost every field there is in the database in your template.

Define a variable

To declare a variable you can define one

{define:variablename:variablevalue}

You can also overwrite a variable in this way so be carefull

To only define a variable when it isn't defined yet, you can use a conditional define {define_c:variablename:variablevalue}

article_detail page

size_select renders a selection of the sizeruler (can be extended with a parameter {size_select:{article_id}} )

fields for manufacturer

rl_web_logo
rl_web_text
rl_web_url
rl_web_title
rl_web_metadescription
rl_name

fields for categories

Use the prefix current_cat.

logo
cms_page
name
url
article_count

Example: To read out the image URL of the category (when added in SW-Retail) use {current_cat.logo} You can only use the category information when a category is associated with the current page.

Double reference field.

You can "double reference" a field by using a *. This means, the field will be evaluated, and then the evaluated value will be evaluated again.

Ajax

Sometimes stuff needs to be updated using ajax. For example in the checkout the price upon selecting a carrier. This can be arranged by using blocks. Declare a div with an id. Inside this div declare a block. You can then load with the block parameter. For example in the checkout $("#totals").load(swShop.getAjaxHelper("data-base-url")+"checkout?block=totals");

Showing / hiding elements

Sometimes you need to show or hide elements in the user interface depending on the state of the webshop. For example if a product has a discount we hide the "normal" price, of if there is crosselling available we add a hide class to the crosselling block.

We use a technique that adds a class "hidden" to a div element for certain information not to be visible. The class hidden is set using a ui toggle.

Off couse this impacts only visual information, the backend will adhere to all business rules. So make sure everything is aligned with the backend (the default themes are aligned)

And finally you can also off course use conditional statements (if)

Forms

To define a form start with {form:formname:formtitle} and close with {form_end}

Forms allow you to set parameters. For example to set where the filled in information should be sent to when the form is finished {form_param:: } Possible parameters:

after_submit :the text displayed after submit
confirm
from: the from field in the email
bcc: the email adres that should always be bcc'ed
sendnotification: when set to 1 the form will send a notification to the configuration notification email adress in the webshop settings

{field type:field_backendname:} Options can be any of

validate_notempty
validate_email
no_edit
html

field_type can be any of

input
checkbox
textarea
select

Form submit is needed on each form on order to create a submit button.

Some field examples

Example form field:

{input:name:validate_notempty}

For more fine grained control you can also add HTML into the <input tag for example for a placeholder and other stuff

{input:name:validate_notempty:html=placeholder="placeholdertext" }

It is also possible to add a different class

{input:name:validate_notempty:class=customclass }

Example selectbox with selectable options a b c d e f

Selectbox {select:myselectbox:options=a;b;c;d;e;f}

Complete Contact form example

This can be pasted into any CMS page to work

{form:contactform}
Naam    {input:name:validate_notempty:html=placeholder="Uw naam" }     
E-mailadres    {input:email:validate_email}    
Telefoonnummer    {input:phone:validate_phone}    
Uw bericht    {textarea:message}
{form_submit:Versturen} 
{form_param:after_submit:Bedankt voor uw bericht} 
{form_param:sendnotification:1}
{form_param:subject:Contact formulier} 
{form_end}

Complete custom form example

Example form, which content will be send to the general notification email adres. This can be pasted into a CMS page.

{form:lotsodata} 
Name {input:name:validate_notempty} 
Email {input:email:validate_email} 
Haircolor {input:haircolor} 
Length{input:lengt:validate_notempty} 
Share all my data {checkbox:share_data} 
I like to receive email {checkbox:send_me_mail} 
Frequency {select:selectedoptions:options=Once a day;Twice a week;Once a month} 
Extra info   {textarea:message} 
{form_submit:Send it} 
{form_param:after_submit:Thanks for submitting!} 
{form_param:sendnotification:1} 
{form_param:subject:Just some data from a form} 
{form_end}

Plugins

It is possssible to use and create plugins. To render the content of a plugin in a block : {block:plugin:pluginname}

Plugins can be created in your own plugin definition file. The name of this file should be: {plugin_blocks}. If you create this file in your template directory the system will read it and the plugin blocks are avaiable to you

Subsequently, you can also publish plugin for other customers within SW-Retail. For this you need to use a different approach which is describe in the webshop plugins topic

Blocks

List all articles that are available in block

Lists of articles

For example, on your homepage, you want all articles that have the homepage field set to appear. For this an article block can be used.

Block definition	What it displays
`{block:articles:homepage:article_list_small}`	displays all articles that have set the "homepage"
`{block:articles:outlet:article_list_small}`	displays all articles that have set the "outlet" attribute
`{block:articles:newest:article_list_small}`	displays all articles that have recently been added to the system
`{block:articles:artgroup:article_list_small:source=url}`	displays all articles that are in the indicated url (without starting / !)

You can also add limit= to limit the output for each block

Load a CMS page

To render something from the cms {block:cms:[item ID from the CMS]} Or, to use the ID from the CMS selector {block:cms_id:{variable_with_value_from_the_cms_selector}

Showing a menu

{block:menu:[menuid from cms]:class=}

Declare your own block

To declare your own block

{block_declare:[blockname]:[clear]:[ajax]}  
{block_end}

clear -> the block will not be displayed until referenced with {block

To use your own block {block:blockname:[optional]} where optional means the when the block is not available it will not halt the templateparser

Appending and prepending a block

It is also possible to append / prepend an existing block. This is usefull for even more finegrained function manipulation. If you append or prepend and the block did not exist already the block will be defined.

{block_append:[blockname]:[clear]}
{block_end}

{block_prepend:[blockname]:[clear]}
{block_end}

Reference

UI Toggles

Toggle	What it does
uitoggle_pricing_discount	When discount available this will be empty, otherwise hide
uitoggle_crosssell_available	When there are crossells available this will be empty, otherwise hide
uitoggle_upsell_available	When there are upsells available this will be empty, otherwise hide
uitoggle_tierprices	When there are tierprices this will be set to hide, otherwise it will be empty
uitoggle_pricing_normal	When there are only normal prices, this will be empty, otherwise hide
uitoggle_addtocart	When an article is not orderable this will be set to hide, otherwise empty

System variables

Variable	What it contains
current_url	The URL of the current page you are on. For home it will be empty /index.html. It will always start with /
header	The header html
footer	The footer html
content	The main renderded content (base.ctp)
page_type	The type of page(can be any of article_detail, article_search_results, checkout, customer_login, customer_modify, customer_orders,order_finished, cms, homepage, wishlist)
meta_title	Metatitle of the page
meta_description	Metadescription of the page
meta_keywords	Metakeywords of the page

There parameters are advised to leave alone since the form an essential part of the inner-workings of the webshop system

Variable	What it contains
swretail_plugin_place_head	Here SW-Retail insert plugin specific html / javascript for the head section of the page
swretail_plugin_place_top	Here SW-Retail inserts plugin specific html / javascript
swretail_plugin_place_bottom	Here SW-Retail inserts plugin specific html / javascript
configuration_json	Special variable that contains json which will be inserted into javascript for proper functioning of the system
additional_javascript	Additional javascript, this is the javascript that is inserted from the UI

System blocks

There are several system_blocks located in system_blocks.ctp that are essential for the workings of the system. You can alter the blocks but do not change their name! If the templater can't find a block with a certain name it will stop executing.

You can find the default blocks here:

Plugins hardecoded plugins come from the same kind of file:

Conditional

The templating engine supports a simple IF statement. {if:left_side_condition:condition:right_side_condition} your conditional template part {if_end}

The condition can be either text / number of a variable name. For example, to test wether you are currently on the homepage

{if:current_url:=:/index.html} Hi this is the homepage {if_end} Currently left_side must be a parameter. Right side can be a parameter or a value. It automagically evaluates. This will be changed in the future.

Condition	Explanation
=	Test equal
<>	Unequal
>	Larger
<	Smaller

You can also test agains parameter values in the configurables.ctp file.

Loops

The templating engine supports a simple loop statement. {foreach:variable:prefix} your loop template part {foreach_end}

The prefix is there to prefix the data from the dataprovider. For example, if the data has a field url in it, if you give a prefix, the field will be called valueofyyourprefix.url For a loop to function you need to define a variable using a data provider. There are a couple of data providers. You can load a variable using the {define_l:variabletoload:dataprovider:optionalparameter} construct

Provider	Explanation
data.manufacturers	All manufacturers in the system that are set to published
data.childcategories	The categories underneath the current category
data.getcrosssell	All crosssells of an article
data.getupsell	All upsells of an article
data.sizeruler	A list of all data from a sizeruler `{define_l:sizes:data.sizeruler:{article_id}}` fields: position,desc,sale_delta,pur_delta
data.session	Session variables
data.itemamounts	Item amounts
data.timestamp	Current timestamp in array

Example {define_l:upsells:data.getupsell:{current_article_id}} will fetch all upsell articles of the currently displayed article

Complete example

<!-- Define the variable upsellers using the dataprovider data.getupsell, and as parameter we use the current_article_id -->
{define_l:myplugin_upsellers:data.getupsell:{current_article_id}}

<!-- Now we define a for each loop, we foreach each upsellers record, and put its values in up. We can access the variables using up.artoms etc.. -->
{foreach:myplugin_upsellers:myplugin_upsell}
	<!-- We show up.artoms -->
	{myplugin_upsell.artoms}    
	<!-- This is all we do in the loop so end the foreach here -->
{foreach_end}

Example with categories

Print a list with all categories that are on the root level

   {define_l:all_main_categories:data.childcategories:-1}
   -- you can also replace the -1 with another parent id, or leave it empty for the current category to get its children
   {all_main_categories}   -- this will dump the whole array so you can see which fields there are in the array
   {foreach:all_main_categories:category}
   <a href="{category.url}">{category.name}</a>
   {foreach_end}

Example with a sizeruler

 
{define_l:ruler:data.sizeruler:{article_id}}
{foreach:ruler:size}
	{size.desc}
	{size.position}
{foreach_end}

Arrays

The templating engine supports an in_array statement.

Example

{if:{in_array:article_array:{current_article_id}}:=:true}
	<!-- If current_article_id is in the article_array we show the article id -->
	{current_article_id}    
	<!-- This is all we do if the current article id is in the array so end the if statement -->
{if_end}

Introducing your own variables in a template

It is possible to introduce your own variables in a template, where the user can set the values of these variables, in the user interface of SW-Retail. For this the file configurables.ctp is used. This file is read by the webshopsystem, and by the userinterface of the configuration screens of SW-Retail. To define a variable you can use the field system that exists in SW-Retail, More information here The variables will be set as template variables.

Authorisations

It is possible to shield template content from non-logged-in users. For example to only display prices for logged in users. There are three fields that can be used:

Field	Description
`{auth_logged_in}`	Is the current session logged in
`{auth_active}`	Wether the system is in logged in mode where a user needs to be logged in to see anything
`{auth_display}`	True when content can be displayed. Is true when auth_logged_in is true and auth_active is true, and is true when auth_active is false

Key-Value pair database

The webshop engine provides a simple key-value pairs database. The information is stored and persistent over all sessions and always accessable. Though performance is high, be carefull, many database accesses could make the system slower to respond!

Command	Description
`{db:read:key}`	Read a key
`{db:read:key:parameter}`	Read a key into parameter
`{db:write:key:value}`	Write a key with value
`{db:write_c:key:value}`	Write a key with value if key is empty (handy for default values)
`{db:clear:key}`	Clear a key
`{db:clear_all}`	Clear all keys

Javascript helpers

To generate nice and clean javascript you can use two javascript helper functions from the templater to get variables from the templating engine into your javascript.

to_js_var - to generate a javascript variable from a template parameter
to_js_obj - to generate a javascript object with parameters from the templating engine

Examples

{to_js_var:current_article_id}

Generates the folowing javascript code

 var current_article_id='the current article_id';

To generate a javascript object with settings you can use the {to_js_obj:name of the javascript:variable1;variable2;variable3;..} function. Make sure you seperate the variable names with a ; (semicolon)

{to_js_obj:myplugin_settings:current_article_id;shop_name}

Generates the following javascript code

var myplugin_settings = {'current_article_id':'the current article id','shop_name':'the current shopname'};

Calculating

In some cases some calculations must be made in the template engine. This can be done using the {calc} command. The general syntax is: {calc:leftside:operation:rightside} The operations supported are : + - * \ (plus, minus, multiply, divide)

Some examples

Displaying a calculation: {calc:{{parameter1}:+:{parameter2}}}

Assigning a calculation to a variable myvalue {define:myvalue:{calc:{parameter1}:+:{parameter2}}}

When you have your value in myvalue, you probably want to format it to currency (i.e. round on two digits). You can use the format instruction for that on the parameter {myvalue:format:currency}

Field formatting

String formatting

It is possible to value of a field when outputting in the template engine. {fieldname:format:format to use}

Command	Description
htmlspecialchars	Format the field for html `{field:format:htmlspecialchars}`
htmlattribute	Format the field for an html attribute `{field:format:htmlattribute}`
currency	Format the value as currency `{field:format:currency}`
integer	Format the value as an integer (i.e. 10,00 becomes 10) `{field:format:integer}`
tolower	Format the value to lower case `{field:format:tolower}`
lpad	Left pad `{field:format:lpad:final string length:character to pad with}`
rpad	Right pad `{field:format:rpad:final string length:character to pad with}`
free_field	Used to replace the separation characters in a multidropdown `{field:format:free_field:string_to_replace_with:set to anyvalue to sort}`

To asssign the value instead of outputting it, you can add as last parameter the name of the variable where the value should be written to. {field:format:integer:newfield}

String modifications

It is also possible to modifiy the value of the sting. For this there are multiple commands available.

substr	Substring of the string. `{field:substr:startpos:endpos}`

Publishing a theme on the theme store

If you want a theme can be published so that more people can install it on their SW-Retail webshop. Follow these steps for publishing your theme.

First you need to request a partner environment. You can request this at our helpdesk.
You need to fill out all the relevant information at the Instellingen -> partner tab when there is an environment for you
We will also create a theme "creation" environment for you, and will link it to the partner environment. In this environment you will make your theme. Make it is beautifull as possible.
After creating the theme, you will have to fill in some meta information about in the partner environment (so NOT the theme environment)
When ready let us know and we will publish the theme
It is possible to publish multiple theme's. We will simply all link them to your partner environment.

Usefull links and

When a theme is available in SW-Retail, a customer can select it and install it. Which customers have installed your particular theme you can find here :

What happens when your theme changes

The changes are directly available. This means, when you change something in the theme environment, the change will be available on the store immediatly when a customer installs or upgrades the theme.

Updating a theme installed at a customer

The theme gets automatically updated when SW-Retail is updated or when someone clicks the theme in the theme store again.

Considerations

Considerations for creating themes

Make sure all assets are free of copyright.
You have to bill the customer yourself.