Views
Stacks Library API
From YourHead
The Stack Library comes with a set of basic components that are good for general purpose layout. But if you are familiar with Mac OS X, HTML an CSS you can create your own components to add to the Stacks Library.
This document describes how to build your own library component and gives a reference to the available options in the API.
The Stacks API is a guide for creating new library components for Stacks.
Contents |
What is a Library Component
In Stacks each thing that can be added to a Stacks layout comes from the Stacks Library. Each item in the Library is a Library Component. And each Component comes from a bundle of files that reside either inside of Stacks or in the users Stacks folder (which is inside the RapidWeaver folder, inside the users Application Support folder).
Where do Library Components get installed
The default components reside inside of the Stacks plugin itself. You can view them (but you should not modify them) by right-clicking on the Stacks.rwplugin file and choosing Show Package Contents. The default Library Components will be the very first items listed in the Resources folder. To install your own components into the Stacks Library you should add them to the Stacks folder. The Stacks folder can be found in:
~/Library/Application Support/RapidWeaver/Stacks
If this folder doesn't yet exist, it will be created the first time you use Stacks.
What's inside a Library Component
A Stacks Library Component is built as a standard Mac OS X bundle. This means that it is a folder with a very specific structure. Inside the folder you'll find a Contents folder and inside of that you'll find the property list and the component's resources. You can use this reference to build your own from scratch, but it's probably easier to start from a copy of one of the default library components that comes inside of Stacks.
The file structure
The file structure of a Library Element follows the standard Mac OS X bundle structure. It looks like this:
- myStackName.stack
- Contents
- Info.plist
- Resources
- iconFile.icns
- template.html
- myAsset.css
- myOtherAsset.png
- Contents
The Info.plist
All of the properties that will be used for your library element are stored in the Info.plist. Details and examples of how to create a Info.plist file are kept in the Info.plist Reference.
The HTML Template
The content that each element produces is contained in the HTML template. Details and examples of how to create a template.html file are kept in the HTML Template Reference.
The Icon
The icon file stores the icons that will be used to display inside of Stacks and during the drag and drop operation.
The icon should be an ICNS icon file, just like the icon file for applications and files in Mac OS X.
This wikipedia article http://en.wikipedia.org/wiki/Apple_Icon_Image has more information on creating ICNS files.
The library can display all of your icon or just a portion. This allows you to get a zoomed in view of the icon in the library if that will assist in clarifying its function.
Assets
Your Library Component may include other files that you'd like to have published along with the content of the component. This allows you to include images, css, scripts, video, or other things required by your content. There are three parts to using an asset:
- Include the asset files in the Resources folder of you library component.
- Add the filenames to the Assets section in the Info.plist
- Use the Assets in the template.html
Adding assets can be a little tricky. There is a how-to post on our blog here: http://yourhead.tumblr.com/post/149061439/using-assets-in-a-custom-stack
