I thought a practical example might help.
When you use an asset, there are three things to do:
- Add the file to the Resources directory.
- Add the item to the assets array in the plist.
- Use the asset in the html template.
This is where you place all the files assocated with your stack like the assets, the html template, and the icon. In my example, I’ve added a script and an image. Here’s how it looks:
Click to View Larger
There’s not much to it, just drop in your assets. Do note that these files will be uploaded as-is, Stacks will not try to resolve name conflicts or url-encode anything. In that case, perhaps image.png and script.js should be more creatively named.The plist
Stacks will not simply upload everything it finds in the resources directory — this helps prevent .DS_Store and other accidental files that users wouldn’t want to be published.
To let Stacks know that a file should be published you add it to the plist. Let’s look at my example:
Click to View Larger
Pay close attention, this part is a bit trickier than it seems. At first glance it may appear to simply be a simple array of items. Instead, each element of the array is a dictionary and each dictionary contains a string which is the filename.
This extra bit of complexity is to allow for other asset meta data in the API in the future.
In this example I’ve declared assets and each has a dictionary and each dictionary has a fileName entry.Using the Asset
OK, we’re done with the hard part. Now we just need to use these assets in the HTML for the stack. To do this you’ll just need to refer to the asset with its filename and use a template variable to complete the URL. Here’s how I could use the assets from my previous examples. Let’s do the image first:
<img src=’src=’%assetPath%/image.png’ />
And here’s the script:
NB: You’d probably want alt properties for images and the mimetype for the script to make things validate. I’ve omitted them for brevity.
In both snippets of code I use the %assetPath% template variable to complete the URL. This variable will be replaced with the correct path to the asset when the page is published.Feedback
I hope that helps ease the process a bit, please let me know if there are things that could be improved, features that could be added, or documentation that could be clarified. My goal is to make this as simple and painless as possible.