Sandvox Advanced¶
2181 words on Software
I wrote about the newly released Sandvox web site creation tool for the Mac last week. And my conclusion about it was along the lines that it’s a great idea but still needs some finishing touches here and there. And that there’s a lot of potential in it as most of the application’s output is implemented by plugins which you can also create yourself to extend Sandvox’ power.
There are several types of plugins for Sandvox. One of them are designs. As I worked on the designs for Karelia, I am comfortable with those. And their scope is easy to understand: Sandvox will generate HTML code and the design plugins supply the graphics, style sheets and fancy replacement graphics.
But what about the other plugin types? Those for pages, indices or pagelets. Those which can change the actual page structure? Obviously those are powerful enough to let Karelia do their own plugins for Sandvox’ standard features. But what about doing things that aren’t within Sandvox’s standard scope? Was the plugin interface designed just to suit Karelia’s needs? Or is it liberal enough to let me do whatever silly things I can come up with as well?
I found that hard to tell just from looking at things. So I decided to just try it out and see how things go. I’ll illustrate my first steps here and in case there’ll be further steps I’ll share them as well as they are made.
Aim
My aim isn’t particularly ambitious. All I want is a proper, simple and convenient photo album. By that I mean a single web page containing a dozen photos or so. I find that I often have a small number of photos to share with friends. I also tend to think that the popular shape of photo albums – the one where every photo lives on a separate page – is a bad idea. It’s just inconvenient to use as the viewer has to click and wait for a pageload for every single photo in there. Having everything on a single page seems more convenient to me and I have made a number of photo pages along those lines already.
And what can I say, I simply dig my own design for this. It features very simple HTML and even presents the photo album as a list. It’s playful with many colours and some hover effects and it tries to get the best of styles and worst for the stereotypical Windows user by employing transparency as well as Zapfino… Finally, I made a number of graphics to match my photo albums for use as a background on those pages.
So my aim is to generate such a photo album in Sandvox.
Technically this shouldn’t be a big deal because all I need is access to photos and a page which gives me a list item for each one of them. This should be the least that Sandvox’ plugin architecture can handle.
First Steps
To get started, it’s worth feeling familiar with Sandvox itself and to look at the Developer Guide which gives some information on the topic. Documentation here could be much more detailed and explicit – but keeping in mind that at this stage Sandvox doesn’t even have a proper user guide, a good developer guide is nothing we can expect.
What we can access, though, is the plugin SDK which contains the source code of all the plugins shipping with Sandvox. That’s great as we don’t just get to see baby examples this way but ‘the real thing’. And I entered with the full intent of just tweaking things a bit in one of the supplied plugins, rather than writing everything from scratch. You’ll need to have Apple’s developer tools installed to be able to use the SDK though.
And before starting I needed a plan on how to achieve my aim. Basically Sandvox seems to wrap each page in a predefined setup of HTML which generates the relevant head tag for the page and some additional bits with the title, site menu and other standard elements. There seems to be no reasonable way around that. Then there are different page types – as seen in the ‘New Page’ menu or in the .svxPage plugins. Those define the structure of a page. And similarly there are plugins for pagelets (.svxPagelet) and index pages (.svxIndex).
I guess each of those could have been used to achieve my goal: I could have made a simple page where only the photos needed to be inserted. I could have defined – or even just slightly modified – an image pagelet to be really wide and made my photo album a page with many of these pagelets. Or I could try to define an index page which doesn’t just display small preview thumbnails as the existing photo grid does but full size images instead.
I decided to go the last way. This uses Sandvox’ hierarchical collection structure and has the disadvantage of creating HTML pages for each of the images on its own as well as the main index page, thus adding superfluous bulk to the whole site. But it has the advantage of making the setup of each photo album a simple exercise in dragging things around in Sandvox’ hierarchical site outline, rather than having to drag images around within a page. So it should be much easier to use, not only in principle but also for the practical reason that Sandvox’ performance when dealing with several potentially large images at the same time might make other ways of moving things around rather painful and slow.
The index page
So first I made a new index page plugin. I started with the ‘PhotoGrid.svxIndex’ plugin for that. And first did some renaming and editing to the ‘Info.plist’ file to ensure my new plugin has a name and bundle identifier of its own and does actually show up in Sandvox’ user interface. As the original PhotoGrid plugin provides two types of index pages (for photo albums and photo weblogs), I simplified things a little more by deleting one of those presets.
After these boring preparations, let’s move to the real work. Luckily this plugin is so simple that all of its magic is provided by the ‘PhotoGridIndexTemplate.html’ file which is a key part of Sandvox’ plugin architecture and goes by the name of HTML template. In these files you can provide a mix of HTML and special macros as well as key paths to Sandvox’ data structures. Sandvox will then process those macros and fill in the actual data as it is running. While those macros are somewhat unusual there aren’t many of them. The original HTML template file for the photo grid looks like this:
<!-- PhotoGrid Index --> [[foreach page.sortedChildrenInIndex item collectionMaxIndexItemsInherited]] <div class="gridItem [[i]] [[eo]]"> [[if item.thumbnail]] <a href="[[path item]]"><img[[idClass entity:Page property:image flags:"anchor" id:item.uniqueID]] src="[[mediapath item.thumbnail.thumbnailImage]]" alt="[[=&item.titleText]]" width="[[=&item.thumbnail.thumbnailImage.width]]" height="[[=&item.thumbnail.thumbnailImage.height]]" /></a> [[else]] <div style="width:128px; height:128px;"> </div> <!-- no image, just a placeholder --> [[endif]] <h3[[idClass entity:Page property:titleHTML flags:"line copy" id:item.uniqueID]]><a href="[[path item]]"><span class="in">[[=item.titleHTML]]</span></a></h3> </div> [[endForEach]] <!-- /PhotoGrid Index -->
Luckily this isn’t too hard to understand: All we do is cycle through each child element of our collection and if there is an image thumbnail for it, we display that at thumbnail size along with the relevant title which we’ll display in any case.
So how do we change this? We do the same cycling, but instead of using divs we use lis. And we use a larger image. Figuring out how to get the larger image was the hardest part here. And only knowing the whole CoreData / Bindings / key paths thing from reading about it rather than from using it in real projects, along with not really knowing Sandvox’ data structures other than by looking at code and examples, didn’t help here. Luckily Dan did help out (thanks!) and told me that there is a key path ending in appropriateScaledImage which will provide an adequate image size. So I replaced the previous file by this:
<!-- Photo Album --> <ul class="bilder"> [[foreach page.sortedChildrenInIndex item collectionMaxIndexItemsInherited]] <li class="ssppphoto [[i]] [[eo]]"> <img[[idClass entity:Page property:image flags:"anchor" id:item.uniqueID]] src="[[mediapath item.appropriateScaledImage]]" alt="[[=&item.titleText]]" width="[[=&item.appropriateScaledImage.width]]" height="[[=&item.appropriateScaledImage.height]]" /> <h3[[idClass entity:Page property:titleHTML flags:"line copy" id:item.uniqueID]]> <span class="in">[[=item.titleHTML]]</span> </h3> </li> [[endForEach]] </ul> <!-- /Photo Album -->
And this is pretty much all it took! I now have the HTML I wanted within the constraints Sandvox places on me. Now all that remains to do is a design to go with it.
The design
As I have just made a plugin that will cause Sandvox to generate HTML which is significantly different from the HTML usually found, I cannot expect the existing designs to handle this gracefully. But I don’t care. I wanted my specific look anyway. So I’ll just have to create a design to do that. As all of my previous photo albums were based on CSS already, doing this just required setting up a new Sandvox design with a unique name and bundle identifier and pasting my CSS over.
I am taking a very rough approach here. Any pagelet context will just be hidden. And things will just look better if you leave Sandvox fields like the site sub-title empty. But it’s getting the job done, pretty much to the same degree as my previously hand-generated pages did.
Conclusion
I did achieve my initial goal: creating pages that look like my beloved photo albums. Doing this wasn’t too hard but I did create a page type and a design which break several of Sandvox’ concepts and aren’t compatible with all the other page types or designs. So from my point of view I’m quite happy with that as it’s pretty much the best I could hope for. It’s just nothing that unexperienced users should be allowed to run into.
At this stage I also doubt that Sandvox will actually make the creation of those photo albums quicker. As its photo handling is still somewhat sluggish at this time and the HTML I use for those photo albums was designed to be minimal, I suspect that two lines of AppleScript together with GraphicConverter and a text editor may still be the quicker tools.
Going further
Of course the last word on this topic isn’t spoken yet. There are some more things which I’d like to do and haven’t done yet. Either because I didn’t understand things well enough or because I didn’t get round to doing it yet. I’ll just list them here:
- Arbitrary image sizes
- I’ve used the magic appropriateScaledImage key above. This gives me images at the sizes pre-determined by Sandvox and its standard page design guidelines. How can I get images at exactly the sizes I want?.
- Links
- My plan was to include links to the full size images on my photo album pages. I hoped that adding something like
<a href="[[mediapath item.largeImage]]"> ... </a>
around my images would do the trick. But it didn’t, Sandvox just displays empty links with that. So I may not have understood the key paths properly yet. - Menu
- Actually my CSS supports the site menu as well, as I’ve also done more complex photo albums with a site menu in the past. However, Sandvox will only place a site menu at the top of the page, so you only get half the deal. Which is particularly inconvenient when using the longish photo album pages I want. While this wouldn’t be particularly elegant, perhaps some JavaScript magic can be used to copy the site menu to the bottom of the page as well.
- Settings
- In case you looked at my old photo albums, you’ll have noticed that all of them have the same structure but have different colour schemes, frames and backgrounds. Of course I could create a separate design for each one of them. But, err, that’s somewhat inelegant, just as having those four ‘Simply’ designs is. I’d really like to cheat a little bit here and just sneak some extra CSS into the page, the specification of which could be changed by some menu. I still don’t really understand which plugins can add panes to the inspector. If it were possible for an index plugin to add some settings pane to the inspector, I guess I could do exactly what I want… but I don’t understand this too well either.
- Prettyfication
- Finally, my current design just uses stuff like Zapfino and drop shadows for its good looks. So it reaches its full potential on a small number of systems only. I could have used Sandvox’ replacement graphics here to supply a better experience for non-Mac users who don’t use IE either.
The Goods
Finally, for this not being a mere woffle, be sure to grab a copy of the plugins I made. Note: This version of the plugin only works with Sandvox versions up to 1.2.8.
It’s work in progress, so let me know what you think, how it could be improved or how those last questions of mine are answered.
