Spark Pay online stores Theme System Overview


Spark Pay online stores Theme System Overview

Before You Begin
Spark Pay online stores Theme structure Overview
Tips for Building With Base
Do's and Don'ts
Common Merge Codes
Wire Frames and Code
Bootstrap Framework And How To Make Changes

Before you Begin

Before you begin creating a theme, be aware that it requires a thorough knowledge of HTML/CSS. You can make changes to a theme without using HTML/CSS, but the process of creating a new theme can be exhaustive for those lacking experience. You can do more to a theme with scripting abilities (Javascript), but it is not required.



Spark Pay online stores REV Themes are responsive (REV Themes are all our new themes built on Base). That means that they adapt to different devices (Desktop, tablet, mobile). They use Twitter's Bootstrap framework, though other frameworks can are available for responsiveness. Only REV themes are accepted in the Spark Pay online stores theme store.


When building, keep the user in mind

When building a new theme, remember that someone will be using and changing it. Messy code, difficult-to-understand ui patterns, broken layouts all bespoke carelessness. So, be nice. Show the end user that you care by keeping them in mind. Go the extra mile to make it easier for them to use.


Users generally like this stuff:

• Dropdown menus

• Mega Dropdown menus (sometimes)

• Product Flags

• Slideshows

• Easy to upload images for marketing ads, banners, promos etc.

• Social media

• Cat gifs

• Details, Details, Details (It goes a long way)


Look at what others are doing

When creating a new theme, don't be an island. Look at what others are doing and learn from them. Use existing conventions when appropriate. The best themes aren't the ones that do everything new and crazy-different. The best themes are easy to use, unique, and thoughtful.


Base Theme

"Base" is Spark Pay online stores foundation theme. It has been painstakingly built and vetted by a bunch of nerds who are really good at this stuff. "Base" has the minimum required feature set for theme store approved themes. Unless otherwise authorized, don't do less than Base. It also has a bunch of stuff built in, so you don't have to build from the ground up every time or ever really. All themes in the Spark Pay online stores theme store must be built using Base.


"Base" uses Bootstrap.

Bootstrap is a responsive framework. It is based off of a 12 column grid, but also includes other style elements. That means that you will find common classes for Bootstrap (.well, .panel, .col...). That also means that HTML elements are inheriting style rules from Bootstraps' style sheet. You may end up overriding some of these classes when building, but that also means that if you don't override any CSS, it doesn't look so bad. Not great, but not bad.

Bootstrap offers a great description of their system:

Grid systems are used for creating page layouts through a series of rows and columns that house your content. Here's how the Bootstrap grid system works:

• Rows must be placed within a .container (fixed-width) or .container-fluid (full-width) for proper alignment and padding.

• Use rows to create horizontal groups of columns.

• Content should be placed within columns, and only columns may be immediate children of rows.

• Predefined grid classes like .row and .col-xs-4 are available for quickly making grid layouts. Less mixins can also be used for more semantic layouts.

• Columns create gutters (gaps between column content) via padding. That padding is offset in rows for the first and last column via negative margin on .rows.

• Grid columns are created by specifying the number of twelve available columns you wish to span. For example, three equal columns would use three .col-xs-4.

You can learn more about Bootstrap here:


Spark Pay online stores Theme structure Overview


Working with a CMS

If you've ever worked with websites, then you understand that from page to page of a single website, you have repeated information. Sections such as the Header, Footer, Left Column, and Right Column. As this information repeats, it only really needs to be created once. With Spark Pay themes, you are able to place your code/information in these areas once. They will then populate in their appropriated areas. Similarly, there also exist page types that use the same layout. These are populated with dynamic information (product, category, shopping cart, checkout pages, and more). These page types need to be built once, so in the end the theme becomes a framework that the Spark Pay system populates with appropriate information.

This is where you come in. As a theme creator, you build the HTML framework and style it with CSS. This way the user can install the theme and only have to do minimal work to have a great looking site. All sandbox accounts have default store data (products, categories, content...). This lets you see what the theme should look like when it is active on a user's store.


Writing code in Spark Pay online stores

The Spark Pay online stores system has 40 + theme pages (home, category, product, checkout, login, blog…). All the pages are accessible in your store/sandbox admin. Each page has an area for HTML, CSS, adding widgets, and settings. When building a new theme, you do not need to use programs such as Dreamweaver or sublime text. Just write your code in the html section of these theme pages.


Since the system has so many pages and allow different ways/places for editing these pages, there is the possibility that you can unintentionally override code (if you have multiple pages open at once). You will get an error message whenever you are about to save a page that does not have the most recent saves. If ever you are unsure if a page is the most recent, just refresh before you begin writing.


Every theme page in Base has a default layout. Even though you can access the code for each one, many of these pages are rarely used and do not need HTML modification. The primary pages are Home, Category, Product, Shopping Cart, Checkout, Manufacturer, and Catalog Search.



FTP (File Transfer Protocol) allows you to access files (product images, design images, files…). Store owners and theme designers are given FTP access to their site upon request. However, Spark Pay online stores has a file manager (Content > Files) that makes FTP access unnecessary. You can find your theme files in Shared Directory > Themes > [Theme Name].

When building a theme, all images that are relevant to a theme need to go into the theme folder. This theme folder is what a user will receive when installing a theme.


Live Design

Live Design is a theme editing interface that allows users to edit their theme styles. It includes drag-n-drop widgets and allows setting odifications while viewing the front end of their site. Be aware that many users edit their themes in this way. This makes standardized code and proper building processes paramount.


Merge Codes

Spark Pay online stores uses merge codes (##PRODUCTNAME##, ##STORENAME##) to display dynamic content. These merge codes represent actual store data that show up when you view the theme on the frontend.

When building the layout of the product page, you are able to use ##PRODUCTNAME## to populate the name of the product. Similarly, merge codes don't appear if it doesn't have any information to display. If you have ##PRODUCTNAME## but the product doesn't have a name nothing will show up.

There are rules that govern merge codes. For example, if you put ##PRODUCTNAME## on the about us page, the system can't know what product you are referring, ergo the merge code won't work. There are also rules that determine which merge codes belong to which page types and layout areas. The merge codes are listed and appropriately grouped here.



In Spark Pay themes, the word "template" refers to something specific. The template, built with html and merge codes, determines the over-all structure of a page. Think of the the frame of a house. In the template, you specify that the header ($$HEADER$$) is at the top of your site and footer is at the bottom. The main content is placed between these sections.

Templates also allow for pages to have different layout elements. If your Category page has a left column but your Home page does not, you would set your Category page to "Left Column" template and set your Home page to "Content Only". Each page type in the theme is set to a template and "Base" has several built in (Content Only, Left Column, Right Column, Left and Right Column, Blank). In fact it is common to not have to do anything with the template when building with "Base", depending on the complexity of the layout.

When building a new theme, be sure to check all templates even if they are not being used in the design. For example, a user may want to use a left column for the category page even if the design doesn't originally have it. Broken layouts on none used templates are not accepted in the theme store.

Click here for more information on templates



Widgets are awesome. They do everything, well, almost. Widgets are pre-built bits of functionality that you can place and drag/drop in a theme. Some common widgets are: Slideshow, MenuList, Product Display, Image/Logo, Search, Mailing List, Custom HTML, and many more. When building themes, you should use widgets whenever possible.  Even if you are building something with custom HTML, use the custom HTML widget. This gives the users the ability to drag/drop what you built from one place to another, and it is easy to manage.


Widgets have the ability to be referenced with merge codes. You can generate the merge code in the widget settings. Once you do, the widget will only appear where the merge code is placed. Widget merge codes have to be on the same page that the widget actually exists, otherwise it won't show up.


Widgets are grouped in areas called widget areas (<ac:widgetarea id="TopHomePage"></ac:widgetarea>) that are placed in the page html. These areas represent where a user can add new widgets and drag/drop existing widgets. Each widget area must have a unique id. It is important to build your layouts and Bootstrap columns around the widget areas.

You cannot use custom HTML inside of a widget area that isn't inside of a widget.


For example, these two highlighted elements are widget areas each holding one widget. Each one is contained by their Bootstrap columns and both of them together are held by one Bootstrap row.



Here's the code for this:

<div class="row">

<div class="col-md-5">

<ac:widgetarea id="SmallProducts">



<div class="col-md-7">

<ac:widgetarea id="Seo">





If not sure, install one or two of Spark Pay online stores free themes and see how it's done.



Each Spark Pay online store theme has a stylesheet {global CSS editor}. This stylesheet is pulled into the Spark Pay online store system. It can be accessed just like any theme page, and the file itself is in the theme's CSS folder. The CSS editor has a lot of code by default, as a bunch of the theme work has already been done in Base. It also uses a parser, so any misused (unclosed tags, repeating syntax...) and often fringe CSS will not save, you will see an error message when this happens.

Common CSS Issues that won't pass the parser:

• -No media queries in style.css

• No gradients in style.css

• Missing last semi-colon

• Duplicate group sections

• Same property multiple times


All widgets and pages have CSS sections. This information compiles in the global CSS editor when they save. For this reason, the system will warn you when you are trying to save over new information.


Base comes with a responsive style sheet (response.css) with all the common media queries. It is in the themes CSS folder. This will help when Bootstrap doesn't get everything quite right.


Home Page

The home page is where people land when they type in the website domain, this akin to index.html. This page does not connect with any dynamic product information like many other pages in the system. You are able to pull in product information with widgets though. All information on this page should be built using widgets. So, if you want to show a group of featured products, add a product display widget.


Template Override areas

A template override area (<ac:templateoverridearea id="HeaderAddonArea"></ac:templateoverridearea>), allows you to add content that overrides the template's defined layout. You simply put the template override area on a page (with a unique id), then place that same override area in the template where you want it to appear. This way you can display content that is specific to a page in a different place on the template.


This is commonly used on the home page to allow a widget area to appear below the header, above both the left column and the page content. This way a slideshow widget can appear above the left column, but the rest of the home page content appears next to the left column.



Category Page

The category page connects with dynamic store information called categories. Categories (also called collections elsewhere) are groups that systematically hold products or other child categories (similar, but not the same as manufacturers or brands), so when shopping you might click on "Shoes" and expect to find shoe products. "Shoes" is the category (I know, over explaining).


This theme page is often mistaken for two pages, because categories many times hold sub-categories. So, when viewing the frontend, you may see a grid of products or a grid of subcategories, (or both) depending on how the categories are set up and how the page is built.


Layout Areas

On the category you are introduced to layout areas (<ac:layoutarea id="ProductList"></ac:layoutarea>). Layout areas are sections of the page that respond to only certain merge codes and hold specific information. (Layout areas are also found on the product page, some widgets, manufacturer page...etc. They inheritly act the same way on all pages.) On the category, for example, you have a layout area for ProductListLayout, ProductListGroup, ProductList.


ProductListLayout - Contains the product list layout. Generally only holds the ProductListGroup ($$GROUP$$)


ProductListGroup - On the category page, you are able to group products together, usually to form rows. This is what the productlistgroup layout area is for. Here you would generally wrap the $$ITEM$$ (ProductList) in a Bootstrap row. The Spark Pay online stores system also allows you to determine how many products populate in this group (it is a setting for the category page), or you can just determine how many populate in a row by specifying the column size around the item.


ProductList - The product list is the layout for each individual product. You specify elements such as product photo, product name, price, sale price, review rating... This layout area is repeated to form the listing of products. This area will generally take up the majority of the category page HTML.


Inside of the ProductList layout area, there are visibility areas (<ac:visibilityarea id="AddToCartArea"></ac:visibilityarea>). These areas serve to contain certain specific information. The one above, for example, contains the add-to-cart button area. Visibility areas allow for the user to hide/reveal certain sections via settings.


<ac:layoutarea id="ProductListLayout">



<ac:layoutarea id="ProductListGroup">



<ac:layoutarea id="ProductList">

[This is where the code for the product goes.]



Manufacturer Page

The manufacturer page is almost identical to the category page. It does the same thing as the category page, only it coordinates the products by their manufacturer. When building a theme, if you modify the layout of the product list of the category page, you should make the same changes to the manufacturer page.


Product Page

As with the category page, the product page is riddled with layout areas and visibility areas. They inherently work the same way.


The product page has a lot of merge codes in the HTML that don't show up on the frontend at a given time. This happens because products can have a lot of complex information or features that may not be in use. These merge codes need to be accounted for when building a theme. Simply deleting all them is not a accepted for theme store themes


Content Pages

Content pages (About Us, Contact Us, Shipping Policy…) are stored as store content rather than theme pages. That means that content pages will not transfer with a theme when it is installed. You can find them in Content > Pages.



It is important to note that ASP.NET (one of the technologies Spark Pay online stores is built on) does not support multiple forms on a page. To add a form in Spark Pay online stores you will need:

1. Create the Form as a static html file.

2. Display the form via an iFrame or the ##CUSTOMFORM# merge

  • ##CUSTOMFORM[/store/pg/3-test.aspx,100]## - This will pull an html form into an iFrame and pull in the url
    • URL can be external ( ) or internal (/store/pg/3-test.aspx). It just reads the content of the form into an iframe.
    • The 2nd value will override the height of the iframe.


Tips for Building With Base


The magic of Deputy

"Deputy" is a little creation of the Spark Pay online stores Frontend Dev team. It has pre-built classes for common styling practices (such as classes for determining padding, margin, width, height, floats...). It is intended to be a collection of help classes, which speed up creating general layouts. It doesn't replace the need for custom CSS.

P.s. "But this is not semantic," you say. Yeah, we know, you don't have to use it if you are a purist, but be aware that "Base" uses it, and it's awesome.


Starting out and what to remove

When you start building your theme, there will be elements in Base that you don't need. Some elements should be removed, but there are some things in the code that should remain, even if you aren't going to use it (this is especially true for themes that go into the theme store). Feel free to delete any widgets that you don't need. In fact, that is something that you can do right off. It is not advisable (and in the case of theme store themes, not permitted) to remove important merge codes that may be needed later on or for use cases that your site is not using.


Overriding CSS

When building a new theme you will often have to override CSS (most of the time Bootstrap's classes). There is also a lot of styling already in the global CSS editor. Feel free to delete what you don't need. Most of the CSS has a specific function somewhere in the theme, so if you're not sure and don't need it gone for a specific reason, just leave it.


Sometimes you will come across classes that may exist in your style sheet, but you can't find the class in the HTML. Don't worry, they probably aren't there. Anytime you click on a widget's CSS section, it automatically generates the default classes in the CSS. Similarly, you may come across an HTML element with a class, but you can't find the class in the style sheet. If you can't find it, it's probably not there, just create one.


Dos and Don'ts

• Don't use inline styling. Seriously, there is a style sheet.

• Always use widgets where applicable. Use columns to build layouts around widget areas. Very rarely, would there be an exception.

• Always wrap columns in rows (unless you clear the floats manually). Also, make sure rows exist in a parent container. (If not it can create a 30px side scrolling issue.)

• Make sure the theme works in all the browsers (Chrome, Firefox, IE, Safari, Opera)




Layout Area (<ac:layoutarea></ac:layoutarea>) - Layout Areas are generally used in conjunction with repeated areas (such as product lists) wherein you can specify the different hierarchy of content such as the Item, the row (group) of items, and the grid (layout). Layout areas are also used to enclose higher functioning areas such as tabs and product page product image.

Visibility Area (<ac:visibility></ac:visibilityarea>) - Visibility areas allow users to hide/show specified content based on store settings. Only predefined visibility areas will work in this way. Visibility areas must contain unique ids.

Widget Area (<ac:widgetarea></ac:widgetarea>) - A widget area specifies where widgets can go. Widget areas must contain unique ids.

Template Override Area (<ac:templateoverridearea></ac:templateoverridearea>) - Template override areas allow you to place page content into a different area of the template without changing the layout of the template. You just place the template override area in the page HTML (with unique id) and place the same template override area (with same id) in the template where you want the content to appear.

Page Layout (<ac:pagelayout> </ac:pagelayout>) - Page layouts are used to define the page type. Some merge codes can only be used in conjunction with certain page layouts.

Merge Code - Merge codes (##PRODUCTNAME##, ##STORENAME##) display dynamic content. These merge codes represent actual store data that show up when you view the theme on the frontend. There are different kinds of merge codes. You can read more about them here.

Widget - Widgets are pre-built bits of functionality that can be placed and dragged/dropped in a theme. They can only exist in Widget Areas. They can also be referenced with merge codes.

Menu - A menu is a collection of links used for site navigation. The system stores menus as store date but references them with Menu Widgets. They can also be created through the Menu Widget.

Session Theme id (?sessionthemeid=1) - You place this at the end of your site url (with the correct id number) to specify the theme that you want to view. Each theme is given an id number and can be specified in this way.


Common Merge Codes


$$ITEM$$ - This merge is used to refer to the object of a widget or layout area. Products are the most common types "Items".

$$GROUP$$ - Used to display "groups" of items.

$$HEADER$$ - Used in the template to reference the Header of the site. This is also used to show the Header for widgets and pages.

$$PAGELAYOUT$$ - Used in the template to reference the page content.

$$FOOTER$$ - Used in the template to reference the site footer.

$$HEADTAGS$$ - Used in the template to reference the head tags.

$$TEXT$$ - Used in menu widgets to display the link text.

$$SUBMENU$$ - Used in menu widgets to display the submenu, generally as a drop down.

See full list here.


Wire Frames and Code






More Useful Help:
Spark Pay online stores Help Articles on Theme & Site Design
Spark Pay Online Stores Community

Tips and Tricks With CSS on
Tips and Tricks with HTML on



Note: Theme modification involves any change to the default values in the HTML or CSS of any theme or widget. Support can direct you to the correct page to make changes or to reset the widget, page HTML or CSS to its default value. This will undo any customization that may be in place. Before you create or modify a theme using HTML and CSS it is suggested to have a backup handy.

While theme modification is outside what support is allowed to assist with, if you need assistance with making modification to the theme, our implementation department is available to make these modification at an hour rate. If the service is ever needed please let us know and we will get that process started for you. Or check out our new Theme Store to find a theme that suits your needs.

Have more questions? Submit a request


  • Avatar
    Kathy Sechrist


    Edited by Kathy Sechrist
  • Avatar
    Kathy Sechrist

    I guess I am going to stop checking the KB first and just call support every time I have a question, since the KB is so often either completely wrong, or incomplete.

    Edited by Kathy Sechrist