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!

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.

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.

Scroll bars (overflow:scroll) within the page are generally discouraged, though there may be some designs for which this makes particular sense.

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.

Page Structure Definitions

A Typical Page Layout

The body of a page generated by Sandvox can have a class of allow-sidebar or no-sidebar. The former indicates whether the page can have a sidebar, even if empty; the latter means that there isn't room for a sidebar, usually because the contents are too wide (e.g. it contains a big photo.) The home page for a site is also given an additional class of home-page to allow for a different “look” on the home page, like a bigger header. 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. 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.

Target Browsers

Testing Parameters

CSS should be valid; please use The W3's or WDG's validation service. (If you are doing non-standard but non-breaking things, like CSS 3.0 things that generate an error, that's OK.)

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.

Text should be of decent contrast and size; color palettes should be used that work with the color blind. You can use Vischeck to test colors.

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.

z_HTMLPage_no_sidebar.html A page with custom HTML, with no sidebar allocated
z_HTMLPage_sidebar.html A custom HTML page, with a sidebar allocated
z_iframe.html An iFrame page (containing the apple.com home page)
z_PhotoPage1.html A photo page, first in a series with no “previous” button.
z_PhotoPage2.html A photo page with both a “previous” and “next” button
z_PhotoPage3+GeneralIndex_.html A photo page, last in a series with no “next” button. Also, a general index afterwards, and some really long elements to test overflows
z_PhotoPage_oneoff.html A photo page, not part of a photo album, so there are no prev/next/list controls.
z_Text+Empty.html An empty page; it should have some “main” area showing, at least on Safari (since our editing environment is essentially Safari)
z_Text+Home+Empty.html Similar to above, but a home page
z_Text+Home+GeneralIndex_.html A full text page, with callouts, lots of sidebar content, and a general index.
z_Text+ListingIndex_.html A text page with a simple listing index
z_Text+PhotoIndex+Long_Stuff+Home.html A page with a photo grid index; a lot of elements are longer than usual to test how the layout behaves on overflows
z_Text_Empty_Sidebar_No_Menu+Home.html Text with embedded graphics (wide and narrow) and no sidebar contents. (There should still be room allocated for the sidebar, though perhaps not a background drawn.)
z_Text_Long_Sidebar_No_Menu+Home.html Text with embedded graphics (wide and narrow), plus a very long sidebar.

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.)
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.
javascript.js (optional) if any javascript is used
thumbnail.png
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.
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 should be incremented each time it is released to help prevent caching of old versions of the design.
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 differening 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.
KTMinimumAppVersion
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)

Banners

New as of version 1.2 are settable banners. A banner is an image (generally shown along the top of the page), up to 800 pixels wide and up to 300 pixels tall, that are part of your design but can be replaced by the user using the inspector. Several of the built-in designs have settable banners.

The way you can make a design take advantage of this is to specify the info.plist, setting a property for bannerName, with the value being the file name of the initial image:

<key>bannerName</key>
<string>Sky.jpeg</string>

Your design will make use of the image, but you should consider what will happen if there is an image specified that is larger or smaller than the one you provide. It should probably be cropped if it is too big, and probably not repeat if it is too small.

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 can use image replacement on a few specific elements such as #previous-photo, #next-photo, and #photo-list to replace text with images. This should be included in the CSS, as it is not associated with 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.

Fonts

Fonts to use for standard text

Fonts for Header Textual Images

The fonts that are already installed on Mac OS X Tiger are safe to use in your Quartz Composer files; you shouldn't bundle that font in the package. For third-party fonts, you can bundle the font in the design package and it will be opened. Of course you will need permission for redistribution of that font, which is usually harder to obtain than permission to simply use a font. (See the Font Sources section for sources of useable fonts.)

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.)


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:

Optional opportunities for nice "goodies" to make your design really shine.

Please take advantage of these as much as possible!

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.

Images

Images used in designs you distribute need to be created by the designer, or need to be explicitly known to be OK for redistribution (since you are not just using the stock image, but are then distributing to others). This means no trademarked images (like company logos). For content by others, there a number of approaches:


Here are some stock photo sites with good potential:

Font Sources

Fonts for Header Textual Images need to be redistributable if you (or Karelia) is to make your design available to others. Here are some potential sources of fonts; you will need to secure permission and possibly pay a licensing fee to the creator of the font if you are going to be distributing your 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.

How can we improve this page? Let us know.