Editing SmartThemes Offline

You can create and use SmartThemes without worrying about the file structure that is used to represent them (see Using SmartThemes). The structure is completely open, however, so you can edit the SmartThemes you create offline if you'd like. This can be especially powerful when you want to quickly create a family of SmartThemes, with modest differences among them.

If you aren't planning to edit SmartTheme files offline, then you do not need to know the details in this article.

Basic SmartTheme File Structure

SmartThemes are defined by a collection of directories and files that conform to a particular naming convention. Optional metadata can be specified to tune the behavior of a given element. SmartThemes are installed and distributed as SmartTheme archives; zip files following the directory and naming conventions outlined in this document.

When working with SmartThemes outside of Webvanta (on your local computer, for instance), you should start with a root directory that can be easily identifiable with your theme. We suggest that you follow a naming convention of your reverse domain name plus theme name. For instance, official Webvanta SmartThemes follow the naming convention of "com.webvanta.theme.THEMENAME".

When it comes time to distribute or upload a SmartTheme, you will zip up the contents of this folder (and name the zip using the name of your folder).

A Minimal SmartTheme

For a SmartTheme to be recognized as a SmartTheme, you must create a "files" folder and put within it a "style.css" stylesheet and an "index.html" homepage pair of files. It would look like:

com.webvanta.theme.sample/

  files/

    index.html

    style.css

  preview.png

Primary Stylesheet

The SmartTheme must include a primary stylesheet named style.css. This file must have identifying metadata entered at the top of the file in the form of a comment. The comment block must be at the top of the style.css file.

/*

Theme Name: Sample

Theme URI: http://www.webvanta.com/smartthemes/sample

Version: 1.0

Sample URI: http://www.webvanta.com/samplesite

Description: Webvanta Sample SmartTheme

Author: Webvanta Inc

Author URI: http://www.webvanta.com/



Assumes Blueprint CSS has been loaded first

(if using our standard templates they take care of that)



*/

The following fields are required:

  • Theme Name is the human readable title of your theme and is mandatory.
  • Theme URI is the globally unique identifier that you assign to your theme. You SHOULD use your domain name and a unique path for each SmartTheme. You MAY have this URI point to an actual resource on your site that has additional information about the theme.
  • Version of this SmartTheme. You MAY use any format you wish, although we suggest you stick with the standard dotted major.minor number format.

The other fields are optional, but can be used to identify the theme. Values for each field must be on one line, including the description. Arbitrary comments can occur after an empty line and are strictly optional

Site Home Page

The top-most index.html file contains the homepage content for a site. HTML pages in a theme are not used directly, but rather as carriers for the content that will be rendered from the CMS. The CMS combines the contents of a page's regions with a template to ultimately display a page. (See later in this document for more details about page handling.)

For the purposes of a minimal homepage, however, all that is needed is a plain HTML file. The contents between the opening and closing body tags will be used as the region contents for that page (the "body" region). All other content of the file is ignored.

Unless a template is specified (see below), the system will use a built-in, plain vanilla HTML template that simply puts the body region inbetween body tags.

Preview Image

While not strictly required, we strongly recommend that you include a preview.png image file in the root directory of your SmartTheme. This image should be 320 × 240 pixels and be representative of the SmartTheme's appearance. It is used in the Webvanta UI to illustrate the theme in various visual pickers. The graphic must be a PNG and must be named "preview.png".

Page (File) Handling

Most of the time, you will want to have a more complicated site structure with respect to the pages and files that are used for a site. The SmartTheme system is designed so it is possible to do a fair degree of manipulation and testing of content "offline". That is, HTML, CSS, etc., can be structured to get a reasonable approximation of appearance of markup even without all of the WebvantaScript being executed.

The files directory acts as the root of your site. You place all of your HTML, CSS, JS, and XML in this directory. You organize pages like you would a static site served by a web server. You can create folders to provide hierarchy to your site. The filename of each file is used to construct the slug for that page. HTML pages use the basename of the file (the extension is stripped), while non-HTML pages use the full filename (extension included).

Page Hierarchy

When your content is in the CMS, and you have built a hierarchy of pages, pages that act as "folders" for other pages are still addressable pages with respect to navigation. They can have their own HTML and are both destinations in their own right, as well as contributors to URL paths for other pages.

In a SmartTheme, you build these folder-like pages in two parts. You create a folder and name it the same as the desired slug for the CMS page. You then place an index.html file inside of that directory to act as the content. This is the same as how static sites would be served by a web server such as Apache.

When the SmartTheme is imported, the two pieces are reassembled as far as the CMS goes. If you fail to include an index.html, the generated folder page will simple be empty.

Non-HTML Files

Currently, non HTML files (JS, CSS, XML) should be stored at the root level. Although provisional support exists for putting all of one class of file into a directory one level below root, you MUST keep style.css in the root. While you can technically use @import directives to pull in pieces of your CSS from a subdirectory, the control panel editing system will get confused as to where to place new files. We'll be addressing this shortcoming in a future release.

CSS, JS, and XML type pages should specify a filename that is to be used exactly as written within the CMS. File extension is important and should be one of .css, .js, or .xml.

The content of the file should be the plain content of the desired file. No other special comments or other metadata is required within the file. (The one exception is the primary style.css file, which must have the comment block described earlier.) The entire content of the file will appear in the default "body" region of the associated page (although this is normally hidden from Control Panel users).

HTML Files

Only the simplest of HTML files can rely on the built-in template. To leverage page regions and the ability to approximate the rendered appearance of a page, you can construct an HTML document that contains both content that will be directly imported into the CMS as well as content whose only purpose is to "test the page".

Unlike the "all or nothing" import of content from non-HTML files, two kinds of content are extracted from HTML files in a SmartTheme. First, one or more regions can be identified anywhere between the opening and closing html tags. Second, metadata can be specified to tune the settings of the page.

Region Handling

Regions can be identified anywhere in the HTML document, although they work best between the opening and closing body tags. A region is bound by two HTML-style comments with a specific naming convention:

<!-- begin region: body -->

<h1>Welcome <span>to your new Webvanta site!</span></h1>

<p>This is content</p>

<!-- end region: body -->

You open a region with the "begin region: region name" comment and close it with an "end region: region name" comment. "region name" is the name of the region, of course.

These comments can appear anywhere, but it is tidier if you start them on a new line like the example above.

Regions can not currently be embedded in other regions.

HTML Page Metadata

You can specify optional page metadata using HTML-style comments at the top of your file immediately after the html tag. Currently you can specify the Template Name, Page Type, Title, Keywords, and Description using this technique. Note that in a future release the latter three will also support scanning for any title and meta tags if present and use those values if page metadata comments are not present.

<html>

<!--

Template Name: two_col_wide_left

Page Type: Page

Title: Home

-->

   <head>

   ...
  • The Template Name field specifies the name of the template you want to use for this page.
  • The Page Type is "Page" (or not specified) for a regular page, or can be any of the supported page types in the CMS (such as Category or Item).
  • Title, Keywords, and Description are the overrides to use for those metadata fields for the page.

Page Sidecar Files

If the kind of page you are creating is not represented by a complete html file with an html tag and the ability to embed html style comments, you will need to use a page "sidecar" file. A sidecar file is simply a plain text file that sits in the same directory as the file it is associated with, with the same filename as its paired file but instead using an extension of ".wvmetadata". Sidecar files are ONLY used to associate metadata with a file and are discarded on import.

Format a page sidecar file with label and value pairs like this, one per line:

Template Name: desired template name

Content Type: content type of this page

Page Type: Page or the special page type used (e.g. ItemPage, AjaxPage, etc)

Status: Published or Draft

Title: your page's title

Label: your page's label 

Description: your page's meta description

Keywords: your page's meta keywords

ACLs: empty if regular access, or comma separated list of roles (e.g. Member, Admin)

Templates

Templates are stored in the templates directory under your root SmartTheme directory (see the full directory layout illustration below). A template file must be named "template name.html" (e.g. one_column.html). If the content-type is not html, you will need to use a template "sidecar" file, described below.

Webvanta provides built-in templates for CSS, JS, and XML files. Typically, you will specify templates for different HTML layouts, but you can build templates for any content you wish.

An HTML template is a standard Webvanta template. Write it in a file using any WebvantaScript you wish. Minimally, you'll want to use standard tags to specify regions.

You specify template metadata in a comment block at the top of the file (which MUST occur within the top 10 lines). For an HTML template, use HTML comments:

<html>

  <!-- Template Name: single_column

       Content Type: text/html

       Template Description: Single Column

  -->

<head>

  <w:snippet name='html_head' />

...
  • Template Name is the short-hand name of the template. If this is specified the filename won't be used. The Template name is also used as the key to tie a page back to the template in its metadata (see HTML Pages above).
  • Content Type is the MIME content type you want to be sent back with the content when rendered.
  • Template Description is the expanded human visible name, and shows up in a variety of places in the Control Panel UI.

Template Sidecar Files

The same rules apply for template sidecar files as they do for Page sidecar files. However, the supported fields in the sidecar are simpler. You'll mostly need to use a sidecar file to be able to specify alternate content-types, particularly those with slashed in their names such as "application/json".

Template Name: desired template name

Content Type: content type (MIME type) for pages generated with this template

Template Description: friendly description of template

Snippets

Snippets capture small blocks of reusable text. They can contain any textual material you desire.

Create a snippets directory at the root of your SmartTheme. If you wish to "group" related snippets together, you may create folders within the snippets directory. The name of the folder will be used as the group name.

Create individual files for each snippet within the desired group. Snippet files in the top-level snippets directory will not be "organized".

The filename for each snippet should omit an extension unless you want that extension to be part of the snippet name.

SmartTheme Data

Data used to populate a new site is organized within various subdirectories within the data/ directory at the root level of your SmartTheme.

Permanent data is stored in the data/permanent/ directory tree. Permanent data is data that is a fundamental part of the SmartTheme's structure.

Global Settings

Global Settings (config settings) are stored in the data/permanent/configs.csv file. Configs are organized in a CSV file with four columns that correspond to the fields in the Control Panel: group, key, value, and description.

A header must reside in the first row of the file.

Any row after the first that starts with a hash (#) in the first column will be treated as a comment.

Row contents need to be properly formed CSVs. No white space should be permitted between commas and content, and double quotes should surround any content that contains commas. Content with double quotes in it should have those quotes escaped (\").

Group, key, and description fields are limited to 255 characters. The value field can be up to 64K.

This is an example configs.csv file:

group,key,value,description

# System Configuration Settings for sitev4

"admin","RSS_feed_language","en-us","Language setting for site RSS feeds"

"blog","comments.setting.premoderate","false",""

"colors","color_blogarticle_borders","#cdcdd4","These color settings are used in our default CSS files. You can change values here if you are using our CSS. Or you can just edit the CSS files directly."

"colors","color_body","#333",""

Taxonomies

Taxonomies are stored in the data/permanent/taxonomies/ directory. Name a taxonomy csv file with the desired name of the taxonomy: tags.csv.

You can populate the three built-in taxonomies (categories, kinds, or tags), or create new taxonomies. Both flat and hierarchical taxonomies are supported.

A taxonomy CSV has a mandatory header row in the first row that have the name of the taxonomy in the first column.

Rows that start with a hash (#) in the first column are comments

You must properly quote values per CSV rules.

"Special" terms are marked with an asterisk (*) in the next column over from the term name.

Hierarchical entries are constructed by shifting the children of terms of a taxonomy to the next column under their parent. In a spreadsheet, this is easy to visualize. In a CSV file, this means that multiple commas may appear before the row:

Categories

# A simple hierarchy

drinks

,water

,juice

food

,fruit

,veggies

,,carrots,*

The CSV filename MUST match the desired taxonomy name or else a new taxonomy will be created with that name.

Menus

Webvanta SmartThemes currently support specifying one menu in the theme since only the "main" menu is editable in the Control Panel.

Place the menu specification in the data/permanent/menus/main.csv file.

As elsewhere, CSV rules apply. Since menus can be hierarchical, the spreadsheet trick of shifting columns under a parent is used here too. However, the first column is always used for the menu items "label".

An internal menu item is specified by the absolute path to the desired page (e.g. "/about/contact_us").

An external link menu item is specified by spelling out the URL: (e.g. http://www.webvanta.com).

label,path,subpath,subsubpath

# Main menu for sitev4

Home,"/"

Blog,"/bp/blog/"

Resources,"/resources/"

Calendar,"/calendar/"

Media Demos,"/multimedia/"

Photo Gallery,,"/photo-gallery/"

Video Demo,,"/video-demo/"

About,"/about/"

Webvanta Support,,"http://support.webvanta.com"

Contact,"/contact/"

Assets (Files)

SmartThemes may contain plain files and directories that are to be installed into an account's Files area. Create a top-level directory called assets/ and construct your file system structure under that point.

Any files that exist at the top level of the assets/ directory will be imported into the root level of the target account's Files area. These files are then accessible as normal, from the root of the account.

It is suggested that if you are constructing a theme that uses certain assets for things like CSS sprites, icons, fonts, or other purposes, that you use a directory and naming convention to clearly identify and store your files.

Webvanta SmartThemes use a top-level asset directory called webvanta_theme_images/ under which other directories appear for specific themes. In this way, when different SmartThemes are installed, previous theme files are not overwritten. This is not required, but a nicity to think about.

SmartTheme Archive Files (zips)

When expanding a SmartTheme Archive file on a typical desktop computer, the zip software will generally place the content of the SmartTheme into a directory with the same name as the zip file itself.

However, due to a quirk of some zip programs, when you do the reverse process of zipping a directory up, if you select the container directory and build a zip, you actually get a zip file that itself contains a single directory in its root, named after the folder you selected, and then all of the content is below that.

The SmartTheme system can figure this out, but if you want to avoid an extra level of directories when working on your local sysytem, simply select the CONTENTs of your directory and compress those elements into a zip. For example, on the Mac OS X operating system, you would open your top level SmartTheme directory, select all items within it, and then select the compress command in Finder. This is similar with the Window's File Explorer.

SmartTheme Internal Unique IDs

SmartThemes are designed to be shared and used across many accounts. To help uniquely identify a particular SmartTheme, Webvanta constructs an internal ID that is composed of three parts:

  • Theme URI
  • Version
  • Account in which the theme gets uploaded to

This means that if you upload the same Theme URI and version archive into two different accounts, the themes will not conflict with one-another (for instance, if the theme archive is installed in a parent account, it can still be uploaded into a child account as a private copy).

However, if you upload two SmartTheme archives that have the same Theme URI and version number in the same account, even if they are different, the last one to be uploaded "wins" and takes over for previous versions.

This behavior may change in the future, but for now, this means that you really want to bump version numbers if you are creating new versions or updates of existing themes in your account OR you should change the Theme URI value itself if you are creating a variant (or new) theme.

If you don't already have a style.css file in the current account, the system will generate a blank one for you and load the supplied metadata. If you DO have a style.css file, the new metadata replaces any existing metadata in that file. This replacement ONLY happens in the archived style.css, NOT in your active one.

When you save the Generate SmartTheme form, the system will begin to build the archive for you (this can take a bit of time). Once done, the SmartTheme is placed in your library list. From there, you can download it for further refinement if desired.

REMEMBER: Update the version number and Theme URI if you are making a new version or whole-sale theme, respectively.

Custom Item Type Definitions and Data

Custom Item Type Definitions are exported when generating a SmartTheme and stored as .cit files in the data/permanent/custom_item_types directory. While the format is not documented at this time, .cit files are plain text files with somewhat self-explanatory fields. Direct editing of a cit is not supported but you can study the serialized JSON objects.

Exported DATA from custom item types IS supported, and simply uses the same comma separated value format as is used for regular data import features. The first row of the file contains headers generated from the field_name of the custom item type. Each row after that contains the data. See our Data Import articles for more information.