Info.plist Properties

ID

CFBundleIdentifier Bundle Identifier

String

Description

If you are using Apples Property List Editor application this item is referred to by the pneumonic "Bundle Identifier". If you're working in a text editor the key is called "CFBundleIdentifier" This should be a string consisting of just lowercase characters, no spaces and should uniquely identify your stack. You can use reverse DNS format to ensure uniqueness.
This value is used to bind the user's content to your stack's template so it's critical that the ID never changes.

Version

CFBundleShortVersionString Bundle version string, short

String

(Available: Stacks API 2+)

Description

If you are using Apples Property List Editor application this item is referred to by the pneumonic "Bundle version string, short". If you're working in a text editor the key is called "CFBundleShortVersionString" This should be a string in the standard version format, "1.2.3". When a version number is available it will be displayed in the Stacks Info HUD.

Sparkle Appcast URL

SUFeedURL

String

(Available: Stacks API 2+)

Description

You can provide a URL to an XML appcast on your own server. The appcast will be read and compared to the version information in the currently installed stack. If the appcast version is newer, then the appcast provided URL will be used to download the newer version of your stack and the newer version will be installed.

You can find more information about creating an appcast and publishing an update on the [Sparkle website] (http://wiki.github.com/andymatuschak/Sparkle/publishing-an-update).

Note: Setting up an appcast for the first time can ben challenging. Stacks will output some information about update failures to the Console application. If you need help getting things set up please post of the Stack Developers Group with details and questions. Others have been through the process and can offer some assistance.

Minimum Stacks API Version

minAPIVersion

Number

(Available: Stacks 1.2.4+)

Description

You can use the minimum version to detect a specific version of the API that your stack requires. Values should be a simple integer of the major version number required. If you are using the Stacks API 2.0 features, you should set the minAPIVersion to 2.

Warning: Only use a min or max API version if there is a known incompatibility. Do not blindly add min and max limits.

Maximum Stacks API Version

maxAPIVersion

Number

(Available: Stacks 1.2.4+)

Description

You can use the maximum version to detect a specific version of the API that your stack requires. Values should be a simple integer of the major version number required.

Warning: Only use a min or max API version if there is a known incompatibility. Do not blindly add min and max limits. There is currently no reason to use this feature since no parts of the Stacks API have been deprecated. It's included for completeness and future enhancement.

Title

title

String

Description

The title is the what is displayed in the Stacks Library interface underneath your library element's icon. There is just enough space for the words "Right Floating Image" but not much more. Please keep it simple.

Information URL

infoURL

String

(Available: Stacks API 2+)

Description

If an InfoURL is present then the user will be presented with a way to get info on your stack. When the user chooses this, they'll be sent to this URL.

Help URL

helpURL

String

(Available: Stacks API 2+)

Description

If a help URL is present then it will be used for the Help button in the Stacks Info HUD. It's recommended that you set the helpURL to your product help pages or FAQ. If the stack doesn't have a permanent location for this information, then simply omit this key, Stacks will not display the help button in that case.

Group

group

String

(Available: Stacks API 3+)

Description

Stacks libraries are organized by group. You can specify the group your stack should be placed in by adding the group property. Stacks without a group property are placed into the "Other Stacks" group by default.

CSS Template

cssFile

String

(Available: Stacks API 2+)

Description

This is the name of the file in the Resources folder that contains the CSS template. No path information should be included, just the file name alone.
The syntax of the template file is CSS with special Stacks specific keywords. You can learn more about the syntax in the HTML/CSS Template document.
The contents of the this file will be combined with the other CSS templates of the other stacks on the page and placed into a combined CSS file called stacks_page_uid.css when the page is published.

Note: You should preface the styles for you stack with selectors that limit their scope to just your stack. you can use the %id% template variable to do so.

Example

#%id% a:link {color:red} /* make all links in my stack red */

PHP Template

phpFile

String

(Available: Stacks API 3+)

Description

This is the name of the file in the Resources folder that contains the PHP template. No path information should be included, just the file name alone.
The syntax of the template file is PHP with special Stacks specific keywords. You can learn more about the syntax in the Template document.
The contents of the this file will be combined with the other PHP templates of the other stacks on the page and placed into a combined PHP file called stacks_page_uid.php when the page is published.

Note: To reduce conflicts in global names, you can preface global variables and function names with your stack's id using the %id% template variable.

Example

$%id%_userName = "John Lydon"; /* set the user name variable to Johnny Rotten */

PHP Session Enable

phpSession

Boolean

(Available: Stacks API 3+)

Description

This will add the call to the php session_start function to the included php file as well as the top of the page. You can get more information about how to use php sessions and the session_start function on the php reference page.

Javascript Library Include

javascriptLib

String

(Available: Stacks API 2+)

Description

Stacks can include a Javascript base library for your code to use. You can do this by setting the javascriptLib entry to the name of the library. Currently, there are two supported libraries:

• jQuery
• MooTools
• jQuery UI (Available: Stacks 3+)

Note: please ensure that you enter the values exactly as shown.

The library will be included by using the Google AJAX Libraries API. This is a convenient and reliable source of the most recently released versions of the libraries. However it does come with some important implications:

• Versioning - The version of the library included is specified to the the major version (jQuery v1.x.x and MooTools v1.2.x), but the minor version (the x) will always take the latest release that Google is currently hosting. This is great because Stacks will never be a bottleneck to getting the latest fixes, but it does mean unexpected updates can appear at any time.
• Availability - Google is only available when the machine is connected to the internet.

More

If you are looking for more assistance in building stacks with Javascript. Please see this blog post:
http://yourhead.tumblr.com/post/778524642/using-the-stacks-api

Javascript Template

javascriptFile

String

(Available: Stacks API 2+)

Description

This is the name of the file in the Resources folder that contains the Javascript template. No path information should be included, just the file name alone.
The syntax of the template file is Javascript with special Stacks specific keywords. You can learn more about the syntax in the Templates document.
The contents of the this file will be combined with the other Javascript templates of the other stacks on the page and placed into a combined Javascript file called stacks_page_uid.js when the page is published.

Javascript Closure

By default each stacks Javascript will be placed into a closure wrapped in a Javascript anonymous function. This ensures that the variables/functions/objects defined in your Javascript will not interfere with the scripts in other stacks on the same page. However it also means that you will not be able to access local variables or functions in your script from the page directly. However you can reach your functions by using the stacks global: stack.%id%.your_object

More

If you are looking for more assistance in building stacks with Javascript. Please see this blog post:
http://yourhead.tumblr.com/post/778524642/using-the-stacks-api

Javascript Closure Disable

javascriptClosure

Boolean

(Available: Stacks API 2+)

Description

Javascript closures (see above) are enabled by default. If you would like to disable them you can set this plist entry to false.

Warning: Please only disable closures if you fully understand the consequences and have no other alternative.

HTML Template

templateFile

String

Description

This is the name of the file in the Resources folder that contains the HTML template. No path information should be included, just the file name alone.
The syntax of the template file is HTML with special stacks specific keywords. You can learn more about the syntax in the HTML/CSS Template document.

Icon Name

icon

String

(Available: Stacks API 3+)

Description

In Stacks 2.0.0 a new icon format was introduced. It uses an individual icon file for each required icon dimension, rather than a single file with all images.

Each icon file should be PNG format with a transparent background. It is recommended, but not required, that icons have a dark outer edge and rounded square look. A small drop shadow will be added to icons, so other shadows should be avoided.

More detailed information about the icon file, the required sizes, and more can be found here.

The file names for the icons should be in the format:

'''' @.png
''''

base_name is the name that you provide in the property.

size is the width of the image.

Library Icon

libraryImageFile

String

(Deprecated)

Description

This is the name of the icon file in the Resources folder. No path information should be included, just the file name alone. It should be an ICNS file.

Library Icon Cropping

imageCrop

Number

(Unused in Stacks 2.0.0+) (Deprecated)

Description

This is a decimal value between 0 and 1. It will tell Stacks how much of the image should be displayed in the library user interface. An image crop of 0.75 will display the top 75% of the image and crop off the bottom 25%. An image crop of 1.0 will display the entire image.
This property is provided to allow you to zoom in to the icon to help the user identify it more clearly.

Assets

assets

Array

Description

Your library element can include other files that will be published along with the content. These files will be published as-is, without templating, HTML conversion, or image optimization. Each item in the array corresponds to a file. Each item is a dictionary and has its own properties. You can learn more about the properties in the Assets Dictionary document.

Note: It's up to you to ensure that the items have acceptable web-friendly naming and do not conflict with other files that might be present in other elements.

Custom User Interface

customItems

Array

Description

The custom items array is a list of the custom user interface additions and calculations that your library element will add to the Info HUD in Stacks. Each item in the array corresponds to a UI addition or a calculation. Each item is a dictionary and has its own properties. You can learn more about the properties in the Custom UI Dictionary document.

Note: There is a limited amount of space available for settings. This limitation is intentional and corresponds well to a limited tolerance for complexity of the user. Do not put so many UI elements in the HUD that it fills the entire screen. If you find that you need more, then it's a good sign that you need to simplify your stack.