Creating your own design theme for Shop-Script

A Shop-Script design theme must contain the following templates:

  • index.html (general storefront page layout)
  • home.html (homepage design template)
  • category.html (category listing pages template)
  • product.html (product-viewing page template)
  • cart.html (”Shopping cart“ page template)
  • error.html (error page template displaying various error messages; e.g., ”Page not found“)

Because an online store works in such a way that customer are supposed to place orders, there must be templates for various checkout pages: contact information form, shipping and payment methods selection screens, etc. For an easy start, you may simply copy the following templates to your own design theme from the ”Default“ theme (you can later modify them if necessary):

  • checkout.html
  • checkout.contactinfo.html
  • checkout.shipping.html
  • checkout.payment.html
  • checkout.confirmation.html
  • checkout.success.html
  • checkout.error.html

1. Creating design theme structure

A new design theme should be created as an arbitrarily named folder on your computer. As you create a new theme, various HTML templates and other files (CSS, JavaScript + mandatory manifest file theme.xml) will be saved to that folder.

A design theme can be created either only for Shop-Script or as part of a design theme family with similar visual elements which is intended for use by several Webasyst apps for creating common visual appearance of different frontends within one website. For more details about creating and using design theme families read article ”Parent design themes“.

2. Main templates


Template index.html is used to create the general layout for all storefront pages using elements <DOCTYPE>, <html>, <head>, and <body>.

Inside element <head> you can connect CSS and JavaScript files.

Inside element <body> you can create the main website navigation block (e.g., by using the {$wa->apps()} method, like in the ”Default“ theme), sidebars, website footer, and other blocks which should appear in all storefront pages.

Important note: Template index.html must contain variable {$content} to ensure that the main content is displayed in your website. Failure to add this variable will result in non-appearance of dynamically generated content such as product lists, category listings, shopping cart contents, etc.


Template home.html (used for displaying main content in the homepage) is not supposed to have any specific content; you may add anything here that you want to be displayed in your homepage: product lists, links to selected product categories, advertising materials, video, etc.


Category properties

Template category.html is used for displaying product category listing pages.

Category description, name, subcategory list, META tags, URL, product count, and other category properties are contained in variable {$category} in the form of an associative array. It means that, in order to add category name, you need to add variable {$|escape} to template category.html (modifier |escape is necessary for correct displaying of various special characters such widely used ”&“ character, which may be contained in category names).

Product list

To display the list of products in category listing pages, use the {$products} variable, which contains an array with information about all products added to the current category. For iteration through the category product array Smarty cycle {foreach}...{/foreach} is often used.

Tip: Smarty code displaying category product listing in template category.html can also be used in other storefront pages; e.g., in search result page. Therefore, it is convenient to add such code to a separate template file named product-list.html, for example. Such an extra file can be loaded inside the category.html template using Smarty function {include} as shown below:

{include file='product-list.html'}

Design theme ”Default“ utilizes two different templates for this purpose: list-table.html and list-thumbs.html, in order to generate product lists with different visual appearance in various parts of the storefront.

Product filters

Another key element of category pages is the product selection filter. It is a web form allowing customers to search through the product catalog using various criteria (product feature values). The list of product features selected for filtering products in the current category is contained in variable {$filters}. For an easy start, we recommend that you simply copy the portion of source code marked with comment <!-- filtering by product features --> from template category.html of the ”Default“ theme, in which the {$filters} variable is used.


Template product.html is used to display the main content of product-viewing pages. The key elements of such pages are product name, description, product features, and ”Add to cart“ button.

Product details are contained in the {$product} variable as an instance of the shopProduct class.

The source code of PHP class shopProduct resides in file wa-apps/shop/lib/classes/shopProduct.class.php.

For example, similarly to categories, product name can be added to the storefront as {$|escape}.

To learn about adding product images to the storefront, read article ”Image thumbnails“.

In addition to the product details which should be displayed in product pages, online shoppers should also be offered the ability to add a product to the shopping cart and to proceed to the checkout. The form for adding a product to the shopping cart can be created by means of a <form> element, which must send data to server using the POST to the URL returned by method {$wa->getUrl('/frontendCart/add')}.

SKUs, services, stock information, recommended products

Adding these elements to product pages requires relatively much programming with Smarty and JavaScript; therefore, we suggest that you copy their implementation in template product.html of the ”Default“ theme and then modify them to fit to your own design theme.


Template cart.html is used to display the list of products added to the shopping cart. As a rule, in such a page customers can change the quantity of previously added items, delete some of the previously added items, or proceed to the checkout.

Information about the current customer's shopping cart is available by means of the {$cart} variable as an associative array with the following elements:

  • items: list of products added to the shopping cart
  • total: total amount including the prices of selected SKUs and services
  • count: total number of items added to the shopping cart

Adding automatic recalculation of the order subtotal upon changing the quantity of individual items and selecting available services, as well as updating shopping cart contents when items are removed, requires relatively much programming with JavaScript. Therefore, for fast creation of your own design theme, we recommend that you use the implementation of these features from the ”Default“ theme and later modify it if necessary.


If an error occurs when some URL within your storefront is requested (e.g., ”Page not found“ or ”Internal server error“), then template error.html is used to display information about the error occurred. The following variables are available in this template:

  • $error_message: error message generated by the online store
  • $error_code: server response code; e.g., 404 or 500

3. Support for plugins

Basic design themes of Shop-Script (such as ”Default“) have built-in support for plugins in the form of special code snippets (hooks), which allow adding extra content to the storefront (e.g., product brand list). Below is an example of a hook in template file product.html:

<!-- plugin hook: '' -->
{* @event *}
{foreach $frontend_product as $_}{$}{/foreach}

To ensure that your own design theme also supports adding of extra content to the storefront by means of plugins, copy such snippets from one of the basic themes (e.g., ”Default“) to the corresponding templates of your theme.

4. CSS & JavaScript files

A design theme can utilize framework's common CSS and JavaScript files as well as its own files belonging only to that specific theme. Below are shown examples of how such files should be correctly connected to your theme's templates.

Connecting framework's common files

Common CSS and JavaScript files of the Webasyst framework reside in directories wa-content/css/ and wa-content/js/. In order to connect them inside a design theme template, be sure to specify their URLs by taking the main URL of the installed Webasyst framework into account. It is easy to do so by means of the {$wa_url} variable as shown below:

<link href="{$wa_url}wa-content/css/wa/wa-1.0.css" rel="stylesheet" type="text/css"> <script type="text/javascript" src="{$wa_url}wa-content/js/jquery-plugins/jquery.cookie.js"></script>

Connecting theme's own files

In order to connect theme's own CSS and JavaScript files, be sure to specify their URL by taking the URL of your theme directory into account. To do so, use the {$wa_theme_url} variable:

<link href="{$wa_theme_url}style.css" rel="stylesheet" type="text/css">
<script type="text/javascript" src="{$wa_theme_url}script.js"></script>

Files style.css and script.js mentioned in the above example should be added to the theme folder next to other theme files.

5. Creating manifest file

To make Shop-Script recognize all template files as parts of one design theme, the names of all such files must be specified in a special manifest file theme.xml. An example of a manifest file and a description of its structure are available in article ”Integration with Site app“.

Important note: The id of your design theme specified in file theme.xml should not be the same as those of other themes installed in your online store!

6. Uploading theme to server

Before you upload themes files to the server, compressed them to an archive file in the TAR.GZ format. Compress only files, not the folder they are stored in on your computer! Archive file name has no importance. Upload the archive file using ”Upload theme“ link in backend screen ”Storefront“.

Once the archive has been uploaded, select your new theme name in your online store's settlement settings to enable it your for the storefront.


    Add comment

    To add a comment please sign up or login

    Раздел помощи работает на основе приложения «Хаб»