Project Structure

What you Create

(This really discusses creating an Element plug-in currently; we may update this later for other plug-ins.)

You'll need to create a project, and in that project, your class file for the appropriate "delegate" for your plug-in, which does your plug-in's work. You'll probably want a nib file for your inspector. You specify information about your plug-in via the project properties, and your Info.plist file.

You can create a project from scratch, or you can carefully "clone" one of our projects, or install and use an Xcode template file.

Name your project along the lines of "FooElement" (all one word).

Easy Setup

1. From our SDK download install the "Sandvox Element" template folder into the following path: ~/Library/Application Support/Developer/Shared/Xcode/Project Templates/.
2. Then, create a new project and choose the Sandvox Element template. Give the project a name such as "FoobarElement." This will automatically cause the correct classes to be generated for a minimal project.
3. Be sure to edit the Info.plist to set the appropriate options for your plug-in.

Manual Project Setup

If you are creating the project from scratch, not from a template or existing plug-in, follow these instructions.

1. Choose New Project → Mac OS X → Bundle → Cocoa Bundle
2. Name your project along the lines of "FooElement" (all one word).
3. Create a new delegate class. Make a New File → Cocoa → Objective-C Class. Call it something like "FooDelegate.m", and let Xcode create the ".h" file for you.
4. If necessary, insert your copyrights, etc. into the files.
5. To the .h file, add:
   • #import "SandvoxPlugin.h"
6. Make subclass descend from KTAbstractPluginDelegate.
7. Edit the project settings by double-clicking the project icon at the top of the source list.
8. Under the "General" Tab, make the Base SDK be Mac OS X 10.4 (needed?)
9. Edit the Info.plist file, using the sample at Info.plist. Specify either KTElementSupportsPageletUsage or KTElementSupportsPageUsage (or both).
10. Add in additional resources such as:
    • an icns file representing your element type.
    • Inspector nib file, e.g. Foo.nib (in the en.lproj directory to work with our internationalization style)
    • HTML Template, e.g. FooTemplate.html
    • CSS file, e.g. Foo.css
    • License.rtf (karelia only)
    • "Xcode configurations" group with two XCConfig Files: Debug.xcconfig and Release.xcconfig. You will want to remove the #include for Sandvox, and adjust USER_HEADER_SEARCH_PATHS and BUNDLE_LOADER to point to your installation of Sandvox. (KARELIA can keep the PrivateHeaders but not third-party) (Be sure these are not copied to the actual build project)
11. Edit InfoPlist.strings
    1. Please make the development language be 'en' (using inspector, change English to 'en')
    2. Add these keys:
       • KTPluginName = "Foo";
       • KTPluginUntitledName = "My Foo";
       • KTPluginDescription = "Foo Bar thing";
12. Add an empty Localizable.strings -- we will need to add these to the project for each language we support
13. Edit your target, set these values (none others actually needed here)
    • PRODUCT_NAME = Foo
    • WRAPPER_EXTENSION = svxElement
    • INFOPLIST_FILE = Info.plist
14. In the target inspector, In the lower left, set "Debug" based on Debug, "Release" based on Release
15. In the target in the site outline, Drag "Copy Bundle Resources" to bottom of list (speeds up compiles)
16. Add a new shell script build phase, call it 'Generate Localizable.strings' , check 'Run Script only when installing'; paste in:
    • echo "Generating Localizable.strings ..."
    • cd ${SRCROOT}
    • genstrings -littleEndian -q -u -s LocalizedStringInThisBundle -o en.lproj *.m
17. Add a custom executable to point to your installation of Sandvox so you can launch Sandvox from your project and debug it.

Useful things to put in the Delegate .m file

- (void)awakeFromNib
{
}
- (void) findMinimumDocType:(void *)aDocTypePointer forPage:(KTPage *)aPage
{
  if ( ... )
  {
    int *docType = (int *)aDocTypePointer;
    
    if (*docType > KTXHTMLTransitionalDocType)
    {
      *docType = KTXHTMLTransitionalDocType;
    }
  }
}

Linking against the Application

To build a Sandvox component, you need to reference against our Application to get access to Sandvox functionality and function headers. This is similar to linking to a framework, but a bit different. (And of course you will need to link to Cocoa, and any other frameworks you need).

This is done by a couple of lines in the Debug and Release ".xcconfig" files you should have put into your project:

USER_HEADER_SEARCH_PATHS =  "~/Applications/Sandvox.app/Contents/Headers"
BUNDLE_LOADER = /Users/dwood/Applications/Sandvox.app/Contents/MacOS/Sandvox

You can adjust these paths as you need.

Extension

Set the extension of the built product as follows:

Element	svxElement
Index	svxIndex

Info.plist

See our guide to the Info.plist for your plug-in project.

How can we improve this page? Let us know.