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.

Download the Sandvox Plug-in SDK
Read the release notes for the SDK
Participate in our online Sandvox Developer Forum

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:

Make sure that you build "universal" for your "release" build.
To aid with debugging, it helps to specify a -seg1addr value (even though prebinding no longer happens in Tiger or Later) as one of the OTHER_LDFLAGS values. If the addresses used for the various executables (application, frameworks, plug-ins, etc.) running as part of Sandvox, it will be easier to interpret crash logs, exception backtraces, and so on. For third-party plug-ins, our suggestion is to pick an arbitrary value >= 0x40000000 and < 0x50000000 that is an increment of 0x00020000.

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:

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

Installation

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

~/Library/Application Support/Sandvox/PlugIns/
~/Library/Application Support/Sandvox/
Library/Application Support/Sandvox/PlugIns/
Library/Application Support/Sandvox/

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.