Sandvox Designers Guide

Experienced CSS web designers can build their own designs for Sandvox (or tweak existing designs from Karelia.)

If you do not know CSS (Cascading Style Sheets), then this section is not for you! Instead, please visit Sandvox Designers Only for a designer-centric look at Sandvox.

Download the Sandvox Design Kit (includes CSS starting points and sample HTML files for testing).

Please note that all of Karelia's designs are licensed only under the terms of the Sandvox Design License.

If you just want to make a quick change to an existing design, see our page titled Quickly modifying existing designs.

Recent updates to this page:

Design Overview

Please read Sandvox Designers Only first for an overview of the designs and their contents.

Design Considerations and Constraints

Unlike some web-building programs where designs are simply “skins” on a fixed layout, Sandvox designs are completely abstract, subject to a few sizing constraints. Site/Page titles could go on the top, side or bottom; sidebars can go to the left or right; layouts can even be horizontally scrolling instead of vertically.

Most pages have the same overall structure, but there are several different page types (e.g. text page, photo-viewing page, etc.) that the designer will want to take advantage of.

The HTML markup is very rich, with many opportunities for a designer to hook into special div's throughout the page. Repeated elements have special markup that allows variety in the output.

Many header level text elements can be processed and converted into a graphic that is displayed in place of the text, as well; we call this "Header Textual Images” (described later in this document)

Special effects (such as having items appear to move when you scroll) are OK but should not be intrusive.

JavaScript for special effects and such are OK, as long as the site works perfectly well without JavaScript enabled! It should definitely not be required for navigation.

A page will generally not be empty, except that when the page is first created, it will start out empty. So be sure your design works OK if there is basically no content. If you need to use min-height to force elements to be at least a certain size, that is a good workaround — we want the layout to look OK when it's empty for the authoring environment (which uses Safari's rendering engine). When the real page is published, it hopefully won't need to rely on the min-height property (since that property is not supported in IE 6).

Page Structure Definitions

A Typical Page Layout

The body of a page generated by Sandvox may have one or more classes associated with it. See below.

A page can optionally have a logo image set for it. A page should look good with a logo of any size - or no logo at all. You may want to center the logo horizontally and vertically in the space allotted for it; see the thumbnail section for more details.

h1 is the site title.

h2 is the page title.

The sitemenu holds a short list of links to main pages on the website

On most page types (the “allow-sidebar” ones), there is a sidebar which contains pagelets (a small unit of content), at least 200px wide. Each pagelet has an optional h4 title. Generally, content in a pagelet should be centered (e.g. images) or have reasonable margins (e.g. text).

The main area is the area which holds the main contents.

An article div contains a single block of text & graphics.

Each article can have a callout which is supplemental content for that article. It is made up of pagelets as well.

For a folder, which we call a collection, its index.html page can be any page type. After the “main” area, it can optionally have an index which lists its contents in a variety of ways. (textual like a weblog, simple listing, photo thumbnails, etc.)

h3 is used for the title of each linked page in an index, which is a list of items listed in a folder.

The following tags have within them a <span class="in">. This is used for header textual replacement.

Warning: Sandvox uses some element classes such as kBlock and kImage that only appear in the applications' web view, for editing use, and are not part of the exported pages. Do not rely on these classes in your CSS.

Body Classes

Target Browsers

Testing Parameters

Be sure to validate your CSS. CSS should be valid except for aspects where you are pushing the limits of the standards; please use The W3's or WDG's validation service. Mac users may find this script useful: http://earthlingsoft.net/ssp/blog/2007/01/css_validation

If you are doing non-standard but non-breaking things, like CSS 3.0 things that generate an error, that's OK. Some examples of CSS that is not technically valid, but still fine:

See how well the design works with larger and smaller text; imagine the user increasing the browser font sizes...

See how well the design works if you add more content within the body (e.g. a title with multiple lines), or take all the content away.

Look out for any other combinations of large and small bits of content. For instance, what happens if you have a weblog-style collection, with long callout content but short article content ?

Testing Files

A number of test files are included with this package, these can be used to exercise the style sheets as much as possible. Though ideally, the design should be installed into Sandvox and taken through its paces, especially to make sure that the editing boxes are reasonable.

Structure of a Sandvox Design Package

A sandvox design is a packaged in folder. It is named for the design's title (a hopefully catchy name which doesn't appear on the page) with the extension ".svxDesign". (It will be a package in the Finder on Mac OS X if you have Sandvox installed.)

The folder contains the following elements:

main.css
CSS file to handle all page types generated by Sandvox. (Optionally, you can include other CSS files from main.css to deal with browser-specific issues.)
print.css
optional print-media CSS file.
Info.plist
Computer-readable file describing the technical details about the design. Also a good catch-all place to store information such as the sources of images and fonts. See details below.
placeholder.jpg
a picture (optional), 640 pixels wide or tall, that will show up as a placeholder for a photo page. This photo should go well thematically with the design it accompanies. Karelia can often find a good placeholder to go with your design.
javascript.js (optional) if any javascript is used
thumbnail.png or thumbnail.tiff
A thumbnail image representing your design. Not a miniaturized version of the page, but an image to indicate the essence (color and images, not text) of the design. Sandvox adds a rounded-rectangle border around this image, so do not include any border in your image. For thumbnails showing a pixel pattern from the design, the image can be its minimum size of 100 pixels wide by 65 pixels high. Most thumbnails should be double size (200 by 130) or even quadruple size (400 by 260) for a future version of Sandvox to display at a higher resolution ... but if the thumbnail image has pixel textures equivalent to the web page, it should not be scaled up. You can use a multi-resolution TIFF if you want to make sure the thumbnail looks good in several sizes.
Credits.rtf
Credits file containing copyright information, credit for third-party graphics and fonts, etc.

The folder also contains any images (.png, .jpg, .gif) and fonts (for Header Textual Images) used by the design. These should be in the same directory as the rest of the files, not a subdirectory.

Additional text files (ending in .txt or .rtf) containing notes, licensing information, etc. are fine; they will not be uploaded to web sites that use your design.

Info.plist format

This XML file can be opened in Property List Editor or a text editor. It contains the following keys and values:

CFBundleIdentifier
unique identifier for your design using the reverse domain name, like com.domain.name. Designs provided with Sandvox will be of the form sandvox.title. (Spaces are OK in this identifier) Yours would be like com.myCompany.Sandvox.MyDesignTitle
CFBundleShortVersionString
Numerical/string version of design; this is shown to the user when they do a "Get Info" from the finder.
CFBundleVersion
An integer like 1, 21, 87, 30493, etc. (no letters or decimals); this should be incremented each time it is released to help Sandvox notify users of new versions.
title
Title of design. (memorable rather than purely descriptive)
genre
one of the following: simple, business, artistic, fun, specialty (for use by future versions of Sandvox)
contributor
author(s) of design; this is shown with the design in the program
url
home page of design’s contributor; clicking on link will go to this page.
comments
Additional information about the design. (Be careful about keeping this text as valid XML so that the file stays valid!)
CalloutBorderable
true or false, whether callout pagelets can have a border attribute set. Set this to false if your design doesn’t have any differing look between bordered and non-bordered pagelets in the callout.
SidebarBorderable
like CalloutBorderable, for the sidebar.
KTIgnoredResources
An array of paths (within the bundle) of any resource files that should not be published. By default Sandvox ignores files named "thumbnail.png" and "placeholder."
KTMenusUseNonBreakingSpaces
By default Sandvox converts spaces in Site Menu items to non-breaking spaces. This ensures that long titles are not split over 2 lines. However, in some designs you may wish to keep the standard spaces. If so, include this key in your Info.plist file with a value of NO.
KSMinimumAppVersion
The oldest version of Sandvox this design can be used with.
imageReplacement
a dictionary indicating what elements can be replaced, and what Quartz Composer file should be used. See “Header Textual Images” section.
bannerName
file name of banner (see section below)
ATSApplicationFontsPath
Name of font file in bundle, or name of folder containing fonts. Required for Sandvox to load any embedded fonts. Documented here.
ParentBundleIdentifier
If you have a group of designs, with multiple variations (color scheme, width, etc.) please come up with a single identifier that all of the variations share. This way, in a future version of Sandvox, we can recognize that the separate design packages all belong to the same "family" and can be grouped together in a main choice.
MainColor
If your design is part of a group of designs, please specify a hex string like #FF9999 what the main distinguishing color of the scheme is. That way our new version of Sandvox can show what the various color choices are at a glance. For particularly dark colors, you may want to cheat a bit and use a slightly lighter color; the swatches will be shown against a background of approximately #333333 so a dark gray swatch might not show up.
hasLocalFonts
If your design does image textual replacement, and you have included a non-standard font in the design package (that you have the rights to distribute), setting this to true will cause the font to be loaded by Sandvox.
viewport
This is to provide the best experience when viewing a website with a mobile device such as the iPhone. The default value is 771, which is the standard minimum size for standard sandvox designs. If your design has enough padding on the left and right that this can be an even smaller number, please specify that so that the website won't waste valuable screen space on the iphone by showing borders on the left and right sides. Conversely, if you have a wide design, you should specify a larger value here.
bannerCSSSelector
See the section below.
bannerWidth
Width of banner. If unspecified it will be 800 pixels.
bannerHeight
Height of banner. If unspecified it will be 200 pixels.

Banners

A banner is an image (generally shown along the top of the page) that is part of your design but can be replaced by the user using the inspector. Several of the built-in designs have settable banners.

Some designs may want to always have a banner (providing a default image); others may want to initially have no banner showing, and insert the banner image into the flow if there is a custom banner image specified. (using the CSS selector tt>has-custom-banner</tt> to reserve space for it.)

To allow users to customize the banner in your design, you just have to supply the appropriate CSS selector in your Design's Info.plist file. For example:

<key>bannerCSSSelector</key>
<string>#page-top</string>

If the user does then set a custom banner, the above code would cause Sandvox to generate this CSS, thereby overriding the design default:

#page-top
{
    background: url(path-to-custom-banner.jpeg);
}

You can also adjust other features of the design if the user has chosen a custom banner by using the CSS selectors has-custom-banner and no-custom-banner.

Sizing

Clearly, the user may well select a banner image that is of a different size to the space available. Thus, Sandvox also needs to know the dimensions of your banner image. The preferred method is to use Sandvox's support for customizing media sizes.

Header Textual Images

Because browsers may not have very good fonts installed, and as a way to foster creativity, Sandvox can generate lovely textual images out of headline elements. Text is converted to an image by passing it through a Quartz Composer file that is specified in the design; it is then included in the website and replaced for the actual text using revised Phark image replacement. (This CSS is generated by Sandvox; the designer does not need build any of this into the CSS.)

Note: Your CSS will need to use image replacement on a few specific Graphical Navigation elements. Though it's the same image replacement technique, this is distinct from Header Textual Images.

The hooks we support for image replacement are as follows.

Code CSS Selector Equivalent Description
mc #sitemenu li.currentPage span Current page in site menu
m #sitemenu li span Other page in site menu
h1h .home-page h1 Site title for the Home Page
h1 h1 Site title on other pages
h2 h2 Title of page
h3 .article h3 Heading of an index’s link to another page
h4s #sidebar h4 Title of a sidebar pagelet
h4c .callout h4 Title of a pagelet attached to an callout

You can specify any and all of the above selectors in your Info.plist file under the key of “image replacement”. (See some existing Info.plist files for an example.) Please note that, unlike with CSS, you must explicitly specify an entry in Info.plist for each type of text that you want replaced; if you specify a replacement for #sitemenu li but not #sitemenu li.currentPage, you will see a Header Textual Image on all links in the site menu except for the current page.

The Quartz Composer files are generally simple files since they are only rendering a still image. The files should be configured to have a published “String” and “Size” inputs and a published “Image” output. "String" is for the string (not rich text or HTML); "Size" is a value from 0.0 to 1.0 (default value:0.5) that is some adjustment on the size which allows the user to tweak the size to better fit or better word-wrap their title text. Generally, the top level of the file is a “Render in Image” patch with specific image dimensions set which correspond to the area reserved on the web page for the image.

You should match the font, size, and color as closely as possible in your CSS for each element that is to be replaced; that will make it optimal if image replacement is turned off or we are in "editing" mode. Also, if you specify the font-size and width and height of the block in pixels, it will be easiest to drop in the image of the right dimensions.

Note: any element that is getting replaced will be marked as class=”replaced” in the HTML. This will allow your style sheet to provide a reasonable fallback font and size for non-replaced text, and then specify the actual font and size to match the replaced font, so that it matches the rendered text more closely.

Element Specification

Logical Structure of a page

Please download the PDF document showing the hierarchy. (Not embedded in this wiki due to formatting constraints; if we can figure out how to do a table with indentation, it might be worth moving to the wiki.)

RECENT UPDATES

(Not reflected in the PDF or this diagram)

span#logo-container contains img#logo or a.imageLink > img#logo.

div.sitemenu > div.sitemenu-content > ul > > li, with these possible classes:

Within the site menu li, you have a > text, or just text

div#page-content has these classes: has-photo-navigation or has-text-navigation or no-navigation depending on what kind of navigation arrows there are.

For navigation arrows, there is a div of class collection-navigation and either photo-navigation or text-navigation. Within that div, there are divs for each navigation element: previous-page, next-page, collection-index. For photo-navigation, there are always all three, and there is an anchor if there is a page to link to. For text, the div for previous or next does not appear if it is not appropriate.

On pages that can have a callout (e.g. text page, you have div.article with a class of has-callout or no-callout (depending on whether there are callouts there). Other kinds of pages (like movie pages) have div.no-callouts around the content. (Apologies for this being confusing -- it's for backward compatibility.) You may want to clear floats in .article-info to properly clear floated images in the article.

Inside div#page-bottom, as of Sandvox 1.6, we now generate div#page-bottom-contents. Inside that, there may be paragraphs or divs, or neither!


Photo Grid

One of the index types built into Sandvox is the photo grid. The aim is to lay out the pages' thumbnails in a neat grid.

HTML

For each item in the grid, the following HTML is generated:

<div class="gridItem">
    <a class="imageLink"><img /></a>

CSS

The photo grid should have fixed-width, left-floated .gridItem divs to allow an arbitrary "photo album" of image thumbnails to display nicely with floating.

In order to make the thumbnail images be nicely centered vertically and horizontally, you may want to employ some CSS similar to the following. It's a bit of a trick, which unfortunately fails in some browser engines. Please use it anyway for the benefit of modern browsers. Note the top: and bottom: declarations.

.gridItem img {
   margin: auto;
   display:block;
   position: absolute;
   top: 0;
   bottom: 45px;
   right: 0;
   left: 0;
}

Custom Media Sizes

Sandvox sites can make use of images in a number of locations. Sandvox provides sensible defaults for the sizes of these images, but if your design is unusually sized, you can customize them.

To customize a media size:

  1. Control-click the Sandvox application and select "Show Package Contents."
  2. In the Resources folder, locate the KTScaledImageTypes.plist file and open it. This is the master list of all the media sizes Sandvox knows about.
  3. Open up your design's Info.plist and (if it doesn't exist yet) create a new dictionary for the key KTScaledImageTypes.
  4. In that dictionary, create a copy of the original entry in KTScaledImageTypes.plist.

So for example, the most common use is to create a custom banner size:

<key>KTScaledImageTypes</key>
<dict>
    <key>bannerImage</key>
    <dict>
        <key>alignment</key>
        <string>top</string>
        <key>behavior</key>
        <string>CropToRect</string>
        <key>maxHeight</key>
        <integer>265</integer>
        <key>maxWidth</key>
        <integer>800</integer>
     </dict>
</dict>

Navigation Arrows

The user can enable navigation arrows for the entirety of any collection, regardless of content. Furthermore, there are both graphical and textual styles available; which is used is automatically determined by the index in use.

HTML

The HTML Sandvox generates differs slightly between graphical and textual navigation arrows. Of particular note is reversed order of the "next page" and "list" links.

Textual Navigation

<div class="collection-navigation text-navigation">
    <div class="previous-page"><a><span>&laquo;</span> Page Title</a></div>
    <div class="collection-index"><a>List</a></div>
    <div class="next-page"><a>Page Title <span>&raquo;</span></a></div>
</div>

Sandvox will automatically generate the « & » characters for you; the <span> can be used for styling.

Graphical Navigation

<div class="collection-navigation photo-navigation">
    <div id="previous-photo" class="previous-page"><a>Previous</a></div>
    <div id="next-photo" class="next-page"><a>Next</a></div>
    <div id="photo-index" class="collection-index"><a>List</a></div>
</div>

These should be replaced with Previous, Next, and List graphical buttons. Use revised phark replacement: text-indent: -5000px; background: url(...); height: ...

Important: The div ids "next-photo" etc. are deprecated as of Sandvox 1.5 and remain only for backward compatibility.

Continue Reading Link

If the user chooses to truncate summaries then Sandvox will also display a link at the end of the summary that links to the full article. The HTML is generated at the top of the .article-info div as follows:

<div class="continue-reading-link">
    <a>Continue reading…</a>
</div>

It is important to note that the anchor tag is not generated while previewing in Sandvox in order to allow editing. So, please do not rely on it for styling.

CSS

You can use CSS to position the navigation controls pretty much anywhere you like.

Please be careful about vertical spacing for the header, page title, and controls; it would be annoying for somebody to have to scroll down, down, down just to see the page's content. So, it might make sense to put the navigation controls inline next to the title, for example.

Default Styling

To make your life easier, Sandvox provides some sensible default formatting of textual navigation:

div.text-navigation { text-align:center; margin-bottom:1em;}
div.text-navigation div { display:inline; margin:0px 0.5em; }

Navigation-Dependent Layout

There is also a CSS selector higher up the tree to note if a page contains navigation arrows within. This is useful for affecting the layout of other page elements in the presence of navigation. For example, some designs place graphical navigation arrows beside the page title, so this can be used to make the title narrower at the same time. The selector will be one of:

Minimal Standards

Most designs will want to take advantage of a number of selectors to make the design fun and beautiful. But a design should do a few things, at the minimum:

Making Use of Third-Party Content

If you are distributing a design, it is your responsibility to make sure you have clearance for any content you use.

You can document the sources and permissions in the comments section of the "License.rtf" file that goes with a design.

Installation of Designs in Sandvox

Your custom Sandvox designs can be put into any of:

You will need to re-launch Sandvox to have it notice any changes to your installed designs.

Related Articles

How can we improve this page? Let us know.