Creating FotoMagico Web Export Themes
(for FotoMagico 2.2 or later)
Contents
1. Introduction
Version 2.2 of FotoMagico introduces the new plugin based Sharing Assistant. The web plugin offers the functionality to export the slideshow as a H.264 based QuickTime movie on a web page. FotoMagico uses themes (aka plugins) to generate those web pages. FotoMagico ships with 11 ready-to-use themes, but everybody can design his own themes.
This tutorial explains everything you need to know to create your own web theme plugins. However working knowledge of HTML and CSS coding is assumed.
2. Quickstart Guide: Contents of a Theme Plugin
To make it easier to understand this documentation, please download the Sample.fmwebtheme plugin, which you can inspect and modify to your needs.
- To use a web theme plugin copy it to the folder at ~/Library/Application Support/Boinx/FotoMagico/WebThemes. If it doesn't exist yet, then create it.
- Open the bundle by doing a Control-click (right click) on the Sample.fmwebtheme file in the Finder. Select the "Show Package Contents" command. Navigate to the Info.plist folder inside the "Contents" subfolder. Open this file with a text editor of your choice.
- Replace the CFBundleIdentifier string "com.mycompany.fotomagico.sample" after CFBundleIdentifier and the "Sample" string after CFBundleName, with string of your choice. Please note that the CFBundleIdentifier must be unique. Also open the InfoPlist.strings files inside the the Resources subfolders and provide localized English, French, and German names for CFBundleName. After you modified each file save and close it.
- To create a new theme you can modify the index.html and styles.css file inside the web folder. Add additional graphics files or other html or css files as required by your web page. This step requires detailed knowledge of web technology. Please do not modify the quicktime.js file.
- Launch FotoMagico, open a slideshow document, select "Share" from the "File" menu, and choose the "Web Movie" icon. Continue to the page called "Customize Webpage". The Theme popup menu should now contain an entry with the name of your theme.
- Congratulations - your first web theme for FotoMagico is ready to use!
3. Reference
3.1 Contents of a Theme Plugin
A web theme is bundled in a folder with the .fmtheme file extension. Bundles are a standard technique on Mac OS X to package related files into a single entity. So while a bundle technically is a folder that can contain many other files and folders, to the user it appears as a single file:
Open the bundle by doing a Control-click (right click) on the Sample.fmwebtheme file in the Finder. Select the "Show Package Contents" command. Inside the bundle you will find the following files and folders:
The structure of a bundle must look as depicted above. It must adhere to standard Cocoa conventions, i.e. the "Contents" subfolder and the "Info.plist" file are required. The Info.plist and InfoPlist.strings files provide the necessary information to FotoMagico to identify and load a web theme plugin.
The "Resources" folder with its subfolders is optional but highly recommended, to make sure that your theme shows up in the user interface with a localized name (English, French, or German). If you place a InfoPlist.strings file into a language specific subfolder, the CFBundleName and FMThemeRootFolder keys can be localized. Please note that InfoPlist.strings files should have UTF16 encoding.
There must be one folder that contains the theme files. In the example above this folder is called "Web" - but the name can be freely chosen, as long as its subpath is specified in the Info.plist file with the FMThemeRootFolder key. The files inside the "Web" folder are meat of you web theme. These files define the look of your web page and will be copied to your web server when a new web page is created.
Some files in the Web folder are required (index.html, quicktime.js, styles.css) while others (background.png, fotomagico.png) are optional, i.e. they are only needed if the html or css files of your theme require them.
3.2 Keys in the Info.plist file
The Info.plist file should contain the following keys:
CFBundleIdentifierThe bundle identifier is needed to identify instances of the same theme, should they be installed in multiple locations. Please pick a unique identifier string, e.g. your reverse domain name plus the name of the theme.
<key>CFBundleIdentifier</key>
<string>com.boinx.fotomagico.sample</string>
CFBundleName
The name is displayed in the popup menu. This key is localizable.
<key>CFBundleName</key>
<string>Black</string>
FMThemeDesignerName
This key is optional. It may be used in a later incarnation of the Web plugin to be displayed in the "Customize Webpage" pane.
<key>FMThemeDesignerName</key>
<string>Peter Baumgartner</string>
FMThemeDesignerURL
This key is optional. It may be used in a later incarnation of the Web plugin to be displayed in the "Customize Webpage" pane.
<key>FMThemeDesignerURL</key>
<string>http://www.boinx.com/fotomagico</string>
FMThemeRootFolder
This is the subpath to the folder inside the bundle. This self-contained folder contains all the files that are necessary to display a webpage. The files inside this folder will be copied to the destination folder once the export has successfully completed. Please note that the folder can itself contain subfolders, and that quite complex webpages are possible, as long as the folder contains all needed files and does not reference outside resources. f you want to create localized themes, then just duplicate the whole "Contents/Web" folder, rename it to "Contents/Web-en", "Contents/Web-de", Contents/Web-fr" etc, and then add the appropriate entries in the InfoPlist.strings files, so that the localized subpaths are available to the Web plugin.
<key>FMThemeRootFolder</key>
<string>Contents/Web</string>
FMThemeIndexFile
This is the filename of the main html file. It should usually be "index.html".
<key> FMThemeIndexFile</key>
<string>index.html</string>
FMThemeMovieFile
This is the filename of the QuickTime movie file that will be generated during the export process. It's name can be freely chosen.
<key>FMThemeMovieFile</key>
<string>slideshow.mov</string>
FMThemeImageFile
The name of the preview JPEG file which generated be the web plugin is specified with this key. Please note that this JPEG file is re-generated whenever the user pages through the slideshow in the "Select Options" pane. The JPEG file is used in preview.html, but it will also be copied to the finail export folder, should the theme wish to use it as a poster frame, before the QuickTime movie has loaded.
<key>FMThemeImageFile</key>
<string>preview.jpg</string>
FMThemeAddToMovieWidth/Height
The size of the export movie will be written to the HTML file. However, if the QuickTime movie should be displayed with a controller, the size needs to be 16 pixels higher. In this case FMThemeAddToMovieHeight should be 16, whereas FMThemeAddToMovieWidth can be left at 0.
<key>FMThemeAddToMovieWidth</key>
<integer>0</integer>
<key>FMThemeAddToMovieHeight</key>
<integer>16</integer>
3.3 Token Replacements
The index.html file in the theme should contain a few string tokens, which will be replaced by FotoMagico as the final HTML files are written to disk. In the future more tokens may be added.
%title%
This token will be replaced with the text that the user entered in the title field of the "Customize Webpage" pane.
%subtitle%
This token will be replaced with the text that the user entered in the subtitle field of the "Customize Webpage" pane.
%description%
This token will be replaced with the text that the user entered in the description field of the "Customize Webpage" pane.
%copyright%
This token will be replaced with the text that the user entered in the copyright field of the "Customize Webpage" pane.
%contacturl%
This token will be replaced with the text that the user entered in the contact url field of the "Customize Webpage" pane. Can be used to provide a link to the photographers website. Can also be used for mailto: URLs, but privacy concerns may be an issue here.
%author% and %organization%
These tokens will be replaced with the text that the user entered in the author and organization fields of the "Customize Webpage" pane. These tokens can be used in the head of an HTML file (for the benefit of search engines), or may be used in the body to display the name/organzation on the web page.
%content%
This is the relative url of the preview.jpg or slideshow.mov file that will be generated by FotoMagico.
%width% and %height%
This is the size of the generated movie or jpeg file. Please note that in the case of the movie additional constants are added to the size, if the FMThemeAddToMovieWidth and FMThemeAddToMovieHeight keys specified this in the Info.plist file. This is necessary if the movie is displayed with a controller (which requires additional vertical space).
<!--%begin_preview%-->, <!--%end_preview%-->, <!--%begin_movie%-->, <!--%end_movie%-->
These tokens have a special importance as they mark the preview and movie sections of a HTML file. When the web page gets displayed in the preview pane, only the code between the and tokens get displayed, while the code between and is ignored. When the final output HTML file is written it is the other way round. Unless you REALLY know what you are doing, you should not modify the following lines in your index.html file:
<!--%begin_movie%-->
<div class="slideshow"><script language="javascript" type="text/javascript"> QT_WriteOBJECT_XHTML('%content%','%width%','%height%','','autoplay','true', 'controller','true'); </script></div>
<!--%end_movie%-->
<!--%begin_preview%-->
<div class="slideshow"><img src="%content%" width=%width% height=%height%/></div>
<!--%end_preview%-->
3.4 Install Locations
Theme bundle are installed in a subfolder of Application Support. The usual search rules apply. If a theme with matching identifier is installed in multiple domains, the theme in the higher domain supersedes the theme in the lower one.
The folders in ascending order or importance are:
- FotoMagico.app/Contents/SharedSupport/WebThemes
- /Network/Library/Application Support/Boinx/FotoMagico/WebThemes
- /Library/Application Support/Boinx/FotoMagico/WebThemes
- ~/Library/Application Support/Boinx/FotoMagico/WebThemes
Thus user Application Support has the highest priority and overrides everything else.
