Sandvox Developers Guide

Sandvox is extremely modular in that third-party developers can produce bundles of code that extend the functionality of the program.

Developers who wish to build Sandvox plug-ins should be familiar with Cocoa development, and especially bindings.

Getting the SDK

A good way to get an understanding of building your own plug-ins is by looking at the source code (warts and all) of the plug-ins that come with Sandvox. Most of these are open-source and are available in the download below.

Terminology

We use the term "plug-in" generically, meaning any of the objects that plug into Sandvox, even though they have different functions (including site designs, which have no code at all).

Using the Sandvox SDK, developers can add their own:

Elements 
Objects used for Pages and Pagelets.
Indexes 
Listing of a collection's content pages

Implementation Overview

Because Sandvox uses Core Data, and there are some limitations to Core Data and plug-ins, we have come up with a mechanism for implementing plug-ins. Rather than subclassing some abstract class that represents a plug-in, we instead have the notion of a Plugin Delegate, which is the class you will implement.

(It's actually possible to create a plug-in without any delegate class, if there is no program logic, and you are able to do all properties configuration through bindings. However, this is only theoretical; we have generally found some reason to implement some code.)

Data for your plug-in are stored in the Sandvox file by means of an NSDictionary-like object, the plugin properties.

Your plug-in Delegate will generally initialize these properties via the KTPluginInitialProperties info.plist key, or in code, by implementing - (void)awakeFromBundleAsNewlyCreatedObject:(BOOL)isNewObject.

When a page is generated, either by selecting a page in the Site Outline on Sandvox, or reloading that page, or publishing the page, the HTML Template for your plug-in is parsed, and that template makes requests of the plug-in's accessor methods, or just lookups in the plug-in properties dictionary, to generate the required HTML.

Project Structure

See our Project Structure page for details on this.

Building Tips

A couple of points to keep in mind:

Debugging

Be sure to enable the Debug Menu when developing Sandvox plug-ins.

For your plug-in to work, it should be found in the ~/Library/Application Support/Sandvox/ directory. We recommend for development that you make a soft-link with the source being your Xcode build directory's "Debug" directory, so that your build versions

If you have set up a custom executable to Sandvox, you can just launch Sandvox with the debugger, directly from your project, and debug your code. Here is how:

  1. In Xcode, choose "Project → New Custom Executable…"
  2. Name the executable "Sandvox" and select the Sandvox application.

Installation

Your custom Sandvox plug-ins can be put into any of the following directories:

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

Installation on a non-development machine is easy; just double-click the plug-in package. It will be opened with Sandvox and then copied into the ~/Library/Application Support/Sandvox/ directory.

How can we improve this page? Let us know.