Snippet Mind - Layout Plug-In SDK

Snippet Mind - Layout Plug-In Development Kit

Version 1.0

Welcome

Welcome to the Snippet Mind Layout Plug-In SDK. Snippet Mind comes with a number of pre-defined layouts, and with some knowledge of HTML, CSS, XSLT and the help of this Layout Plug-In SDK you may build your own layouts too. The knowledge needed to build a plug-in varies depending on the result you would like to achieve.

For example, your goal is to replace the cycling pictures at the top of the Gallery layout with some pictures of your own. To achieve this you just need to duplicate the original layout plug-in and change the gallery pictures in the images folder.

On the other hand, if you want to replace the HTML generated by a Snippet Mind standard plug-in and give the HTML output a whole new structure you need some fair knowledge of the XSLT transformation process.

But for most tasks some CSS and HTML knowledge will be enough to accomplish most layout design goals.

Overview

Plug-In Development: A step by step approach to build your own layout plug-in.
Layout Plug-In Architecture: This section describes the parts a layout plug-in is build of and the way Snippet Mind uses plug-ins in the publishing process.
Appendices: The last section shows how to reach Zykloid Software support, some references to useful sources of information and the history of this document.

Plug-In Development

Develop you CSS

The easiest way to start building a Layout Plug-In is to setup a local sample blog and use it as your playground for further CSS and layout development.

Start Snippet Mind, create a new journal named "Playground" and add some sample entries.
Open the Publishers dialog by choosing "Publisher Setup..." from the "File" menu.
Create a new publisher. Name it "Playground". Fill in some details under the Feed tab.
Choose the "Playground" journal under the Contents tab.
Go to the Account tab and set the Type to "Local Volume". As the Destination Folder choose for example ~/Desktop/Playground and as the Base URL choose file:///Users/<your account name goes here>/Desktop/Playground. See chapter Publisher Setup in the online help on how to setup a playground publisher.
Got to the Layout tab and choose one of the existing layouts to start with.
Select the publisher in the table on the left side of the Publisher Setup window.
CTRL-click on the publisher in the table and choose "Publish..." from the context menu to publish your journal. Your playground blog now exists on your computer's desktop in the "Playground" folder.
Choose "Open Blog" from the context menu. You default browser opens and shows your blog.

Now you have got a sample blog to play with. Go to ~/Desktop/Playground/styles and change the CSS file main.css with your favorite CSS editor. Or add your images to the ~/Desktop/Playground/images folder. Once you are done building your CSS go to the next section Create a Plug-In.

If you need to change the HTML structure, have a look at How the publishing process works.

Create a Plug-In

Copy the Sample plug-in provided in the Layout Plug-In SDK and rename it.
Open the plug-in by by ctrl-clicking on the plug-in file and choosing "Show Package Contents" from the Finder context menu.
Substitute your own resources, XSLT stylesheets and CSS files. See The Plug-In Package to understand which resources go into which place.
Open the Info.plist file in a text editor and supply your own information. See Info.plist on details.

Installation

You may install a Snippet Mind layout plug-in into one of several places:

Into the Snippet Mind application. Use the Finder info dialog to do this.
Under /Library/Application Support/Snippet Mind/Plug-Ins. Plug-Ins installed in this location are available to all users.
Under ~/Library/Application Support/Snippet Mind/Plug-Ins. The '~' character denotes your home folder. Plug-Ins installed in this location are available to the current user.

If the folder does not exist, create it. From all these places we suggest to use the last alternative.

Test Your Layout Plug-In

Open the Console application which resides in the Utilities folder to watch out for error messages from Snippet Mind.
Watch out for error messages on application startup to see if your plug-in has been loaded correctly.
Choose your layout under the Layout tab in the Publishers dialog.
Reset the publisher and start the publishing process.
Problems encountered during the publishing process - especially XSLT stylesheet errors - can be found in the system log of the Console application.
Test your layout under different web browsers like: Camino, Firefox, Internet Explorer, Mozilla, OmniWeb, Opera, Safari ... And don't forget the Linux and Windows counterparts ;-)

Layout Plug-In Architecture

The Plug-In Package

Technically the plug-in is a file package which can be opened by ctrl-clicking on the plug-in file and choosing "Show Package Contents" from the Finder context menu. The package is structured similar to an application bundle:

Sample.ltlayout
+- Contents/
|  +- Info.plist
|  +- PkgInfo
|  +- Resources/
|  |  +- Site/
|  |  +- Styles/

Info.plist

The file Info.plist holds the plug-in configuration information in Apple's Property List XML format. The following keys are used by Snippet Mind:

LTLayoutInterfaceVersion

The layout plug-in interface version. The only allowed value for this key is 1.0. If this key is omitted, a version of 1.0 is assumed.

LTLayoutID

The value should uniquely identify your plug-in. Use a revers canonical form of your domain name and add a unique plug-in identifier to create this id. For example: com.zykloid.layout-plugin.retro

LTLayoutName

The display name of the layout plug-in. If this key is omitted, the plug-in file name is used.

LTLayoutVersion

The version of your layout plug-in. Snippet Mind will use this key to distinguish between different plug-in versions. If this key is omitted, a version of 1.0 is assumed.

LTLayoutTarget

The target of your plug-in. Allowed values are: web-site or iPod. If this key is omitted, a value of web-site is assumed.

LTLayoutCreatorName

Your name or company name. This information is optional.

LTLayoutCreatorEmail

Your email address. This information is optional.

LTLayoutCreatorWebSite

Your web site. This information is optional.

LTLayoutThemes

An array of dictionaries holding LTLayoutThemeName and LTLayoutThemeValue pairs to specify the different themes. The value of the key LTLayoutThemeName specifies the display name of the theme. The display name is used by Snippet Mind to populate the theme popup menu. The value of the corresponding LTLayoutThemeValue key lies in your domain. For example, you may hold the name of a CSS file here or the name of a CSS style class.

Use themes to handle different color and background schemes or "skins" of your plug-in. Don't use themes for major changes in the layout and structure of the resulting HTML pages.

Layout themes are optional.

For an example use of layout themes have a look at the Retro layout plug-in.

LTLayoutDefaultTheme

The name of the default theme is specified under this key. This information is optional.

For example, the sample layout plug-in defines the following properties:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>LTLayoutInterfaceVersion</key>
  <string>1.0</string>
  <key>LTLayoutVersion</key>
  <string>1.0</string>
  <key>LTLayoutTarget</key>
  <string>web-site</string>

  <key>LTLayoutCreatorWebSite</key>
  <string>http://zykloid.com</string>
  <key>LTLayoutCreatorName</key>
  <string>Zykloid Software</string>

  <key>LTLayoutDefaultTheme</key>
  <string>Lilac</string>
  <key>LTLayoutThemes</key>
  <array>
    <dict>
      <key>LTLayoutThemeName</key>
      <string>Blue</string>
      <key>LTLayoutThemeValue</key>
      <string>themeBlue</string>
    </dict>
    <dict>
      <key>LTLayoutThemeName</key>
      <string>Green</string>
      <key>LTLayoutThemeValue</key>
      <string>themeGreen</string>
    </dict>
    <dict>
      <key>LTLayoutThemeName</key>
      <string>Lilac</string>
      <key>LTLayoutThemeValue</key>
      <string>themeLilac</string>
    </dict>
    <dict>
      <key>LTLayoutThemeName</key>
      <string>Orange</string>
      <key>LTLayoutThemeValue</key>
      <string>themeOrange</string>
    </dict>
  </array>
</dict>
</plist>

Site

The Site folder holds the basic web-site file and folder structure. You can think of the Site folder as being the weblog's root folder. All the static resources needed by your layout go into this place. The general structure of this folder looks like this:

...
+- Site/
|  +- archive/
|  +- categories/
|  +- images/
|  +- styles/

The folders archive and categories are used by Snippet Mind to store the entry web pages and monthly archive indices. Create additional folders as needed by your layout. You are free to place your layout's images, CSS and JavaScript files into these places.

At the beginning of the first publishing process and after a publisher has been reset the whole contents of this folder is copied to the destination site.

Styles

The Styles folder holds the XSLT stylesheet files used by Snippet Mind to publish a journal. Snippet Mind assumes at least a XSLT stylesheet file named stylesheet.xsl in this place.

The sample plug-in uses two stylesheet files, stylesheet.xsl and basic.xsl. stylesheet.xsl generates the general HTML page structure and basic.xsl holds a set of reusable declarations and templates. Have a look at these two files two get an impression of the XSLT transformation process.

If you plan to write your own XSLT stylesheet, have a look at the XML data files generated by Snippet Mind during the publishing process. See How the publishing process works for a description on where to find those files.

Localization

The layout plug-in may use a simple dictionary to translate some common terms. The sample layout plug-in shows how to use the dictionary. Just follow the parameter named lt_translations_document. See translations.xml on the top level of the Layout Plug-In SDK for a sample dictionary.

This topic is still experimental and we are open for your thoughts and ideas. If your language is not yet part of the dictionary, feel free to fill in the holes and send an updated version of the translations.xml file to translations@zykloid.com.

How the publishing process works

The publishing process works like this:

The first time a weblog is published and every time the publisher is reset the contents of the Site folder is copied to the destination site.
Next Snippet Mind writes a XML site master file into a temporary folder. The site master files contains all basic configuration information and information about the categories and archives of the weblog. See site.xml for an example site master file.
After that a XML page file is written for every entry and index that needs to be published. See page.xml for an example page file.
The XSLT processor is started to transform the page file using the XSLT stylesheet found in the Styles folder. The resulting HTML file is copied to the destination site.
All temporary files are removed from the temporary folder.

There are some points worth mentioning here:

The content attribute of the page tag in a page.xml file may hold one of the following values depending on the page's contents: archive (a monthly archive), category (a category index), entry (an entry page), index (the main index) and root (the site's root page).
The site master file is passed as the global parameter lt_site_master_document.
The translations file is passed as the global parameter lt_translations_document.

To get an idea of this process open Snippet Mind, go to the Publisher Settings dialog and select a publisher of your choice. On the Expert tab switch off "Clear temporary products". Open the temporary folder by clicking on the "Reveal in Finder" button next to the path of the temporary folder.

Mark all entries hold by the publisher as "not-published" or reset the publisher. To do this, use the commands in the context menu of the action button - the one with the tooth-wheel - at the bottom of the publishers table. Make sure that the right publisher is selected. Now publish all entries using the "Publish" command.

You will find all intermediate files and final products in the temporary folder. Inspect them with a text editor of your choice.

References

HTML and CSS

http://www.csszengarden.com See "CSS Resources" section for CSS background information.
http://maczealots.com/tutorials/websites/ Creating Web-Sites on the Mac.
XHTML Tutorial
CSS Tutorial

XSLT Tutorials

http://www.w3schools.com/xsl/
http://www.topxml.com/xsl/tutorials/intro/
http://www.heise.de/ix/artikel/2001/01/167/ (English and German version)

Support

Staying Up To Date

Please subscript to our Zykloid Software News weblog to stay up to date about new releases, layouts and changes in Snippet Mind and the Layout Plug-In SDK.

Reporting Bugs and Feature Requests

If you encounter any problems in the process of developing a layout plug-in, with this description or in integrating your plug-in with Snippet Mind, please let us know. If you have any comments or questions that aren't answered in the documentation, contact Zykloid Software and steer your web browser to:

http://zykloid.com/feedback

or send an email to:

feedback@zykloid.com

Contact

Snippet Mind is a product of:

Zykloid Software (aka Priebe Software)
Schwilmengasse 3
89073 Ulm
Germany

fon://+49 (0) 731 / 159792-00

http://zykloid.com
http://zykloid.com/support
http://zykloid.com/contact

support@zykloid.com

History

2005-10-30, v1.0: - Version 1.0 of this document.
2005-09-19, v1.0b2: - Added details in section "Plug-In Development".
- Changed the order of some sections.
- Minor corrections.
2005-08-23, v1.0b1: - The first raw sketch of this document.