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 plugins should be familiar with Cocoa development, and especially bindings.
Download the Sandvox Plugin SDK (includes source code to all of our plugins). Warning: We are making some significant architectural changes to Sandvox, so these will be a bit out of date for building plugins that will be compatible with the next major release of Sandvox. Please contact us if you would like early access to the new architecture information.
Using the Sandvox SDK, developers can add their own:
- Data Sources
- Handlers for drag-and-drop to make pagelets or pages
- Pages
- New types of entire pages, with their own inspector
- Pagelets
- Content that goes into a page's sidebar (or callout)
- Elements
- Support objects that are shared by Pages and Pagelets.
- Indexes
- Listing of a collection's content pages
A good way to get an understanding of building your own plugins is by looking at the source code (warts and all) of the plugins that come with Sandvox. These are all open-source, available above.
There are also "tutorials" available:
- Creating a Google AdSense Pagelet from the Flickr Pagelet
- A brief guide to generating new Pagelet plugins directly from examples in the SDK.
Terminology
We use the term "Plugin" generically, meaning any of the objects that plug into Sandvox, even though they have different functions. A better term is probably "Component" which means a plugin that generates a piece of the site. A Data Source is not really a component.
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 plugins. Rather than subclassing some abstract class that represents a plugin, we instead have the notion of a Plugin Delegate, which is the class you will implement.
(It's actually possible to create a plugin 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 plugin are stored in the Sandvox file by means of an NSDictionary-like object, the plugin properties.
Your plugin 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 plugin is parsed, and that template makes requests of the plugin's accessor methods, or just lookups in the plugin properties dictionary, to generate the required HTML.
Project Structure
See our Project Structure page for details on this.
Installation
Your custom Sandvox plugins 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.
Hint: Soft-link one of these directories to your "build" directory as part of your development cycle so your plugins are always up to date.
