Please note: this documentation applies to Phase2 web only, Phase1 is now considered antideluvian (things move fast here).

A theme is, quite simply, a collection of files that define the layout, appearance and behaviour of a Pearl site. A theme would generally be made up of the following:

• index.html
  
• product_listing.html
  
• product.html
  
• styles.css
• c_smartmenus.js
  
• c_config.js
  
• image assets

The individual HTML files are templates within Pearl. The index.html sets out the main structure, and would typically include the markup for header and footer elements. It must also contain the [%content%] object - which pulls in dynamically generated/parsed content - positioned in the centre column of a 3-col ecommerce layout, for example. With the exception of the content object, most widgets available also live within the index.html template - such as [#cart#], [#account#], [#login#] and so on. The two other templates would be pulled into wherever [%content%] is positioned. The product_listing.html template defines the appearance of just ONE product as it is displayed in search results, or listed under a product category, where the system takes the template and repeats it for every instance returned. Here you would typically see image, product title and price objects, with a 'more info' button. The product.html template controls the appearance of a product detail screen. Typically, this would include image, title, description, options (colour, size etc) and price objects. Custom field objects allow a lot of flexibility in data positioning and type, so a product detail page can be as simple or as complicated as you need. There are also a few widgets available for use within the product template space - customer reviews, for example. See the Widgets & Objects doc for a detailed list.

The styles.css file is the main stylesheet - really the only one you need to worry about. Although it's not an essential part of a theme as Pearl churns out clean markup, any site with even a hint of complexity would end up looking rather odd without any styles in place. Phase2 has seen the introduction of a much more robust, styling-friendly codebase and as a result even a few lines of CSS can massively improve visuals. There are a number of generic classes in place controlling the appearance of all titles, product lists, page titles etc. See the Widgets & Objects doc to get an understanding of widget structure and generic classes.

c_smartmenus.js and c_config.js are config files for the dynamic menu widget. While they're not necessary if you have no intention of using the dynamic menu, they're essential if you do. The dynamic menu is essentially a port of the SmartMenus application, so we're not going to attempt to rewrite the documentation for it when Vasil Dinkov has already done a fine job.

Rounding up the theme are any image assets, generally packaged in the folder (theme_name)/images. If you choose to upload them with a folder structure different from the original, you might need to do a find-and-replace search on the .html and .css files.