What is Flipomatic? What can Flipomatic do? What can't Flipomatic do? Flipomatic speed Installing Flipomatic Installing on Unix/Linux servers Installing on Windows servers Installing on Macintosh servers Introduction to configuration files A word about nomenclature Flipomatic URL syntax Introduction to documents Introduction to templates Introduction to substitution variables Introduction to groups Advanced templates Advanced substitution variables Advanced groups Top 10 most useful Flipomatic tips Using CSS, Javascript and XSL Using Flipomatic with METS Using Flipomatic with databases Using Flipomatic with other arbitrary formats Frequently Asked Questions What is Flipomatic? =============================================== Flipomatic is essentially a template engine. It is a tool which provides the web designer or content provider the means to process generic multipart objects and generate HTML for display on the web. These multipart objects may consist of page images for a book or a letter, or individual photographs in a large pictorial collection or album. The Flipomatic program itself contains no HTML nor does it provide default behavior or functionality for navigating or viewing collections of images. Instead it provides the ability for web designers or content providers to create simple templates where they can specify their own appearance and provide whatever viewing and navigation functionality they feel serves their users best. And because Flipomatic supports any number of templates, the appearance and functionality can be vastly different between one type of data and another. Thus a Flipomatic interface for a book with hierarchical volumes and chapters can work differently than one for a small letter or one for a large album of photographs. Unlike many other image viewers, Flipomatic takes the programmer "out of the loop." The design and navigation for a particular set of data can rest in the hands of design and content professionals where it belongs. What can Flipomatic do? =============================================== Flipomatic provides a set of tools which designers can "plug in" to their HTML templates. These are some of the things flipomatic can do: 1. Flipomatic supports any data fields the user chooses. Designers and content providers are not limited to a specific set of Flipomatic data fields. Data can consist of as many fields of whatever type the designer wishes. Additionally one type of object may have a completely different number and type of fields than another. A book may have chapter and part headings, page numbers, authors, while an album of photographs may have captions, dates, photographers, places, ... anything the user desires. 2. Flipomatic can search through an individual object such as a book, letter or album and retrieve results based on any criteria. It can also sort the results on any field the user chooses. 3. Flipomatic can retrieve documents located on other servers. A user can compile their own libraries or collections of documents, provided the hosting server makes this functionality available. 3. Flipomatic can act as a front end for databases consisting of large sets of data. 4. Since Flipomatic does not specify any particular viewing behavior, users can serve up images in whatever form they wish, including Mr. Sid. 5. Flipomatic's simple native text-delimited data format means users can easily convert data in almost any format into Flipomatic documents, from database files to arbitrary XML documents. In addition to its normal text-delimited data format, Flipomatic natively supports the METS Metadata Encoding and Transmission Standard using just about any extension schema the user wishes. What can't Flipomatic do? =============================================== 1. Although Flipomatic can search through individual documents or albums it cannot search across multiple documents. If you have a collection of books, it can search within an individual book but you'll need your own search engine to search across all of them. 2. You cannot embed your own code within a Flipomatic template. Most template programs you find, say on CPAN (Comprehensive Perl Archive Network), allow you to embed your own perl commands directly within an HTML template. For security reasons, Flipomatic does not allow this. Flipomatic does not work like ASP or JSP (although both of these technologies are excellent for building page viewers). Instead Flipomatic provides enough (it is hoped) "modules" in the form of substitution variables to allow you to build your own functionality. 3. Flipomatic cannot write to files or databases. At least not all by itself. If you need to store persistent data, say for the purposes of maintaining a user album or "shopping cart," you'll need to write your own cgi script to do it. Flipomatic is certainly capable of calling such a script via a URL and passing data it. However Flipomatic can write to cookies (since users are free to include any javascript code they wish in their templates). 4. Flipomatic cannot handle very large sets of data in a practical manner. Flipomatic is written in pure perl, but even perl has its limits. Flipomatic does not use a database and thus documents consisting of tens of thousands of images will probably be rendered by Flipomatic too slowly. The actual upper limit will vary depending on the speed and load for your server and the number and size of fields in any individual document. However Flipomatic can easily be used as a front end to a database consisting of any number of images. Flipomatic speed =============================================== I have tested Flipomatic with collections consisting of as many as 12,000 images with very satisfactory speed. But a few factors influence the speed at which Flipomatic renders HTML pages, the most important being the number of items returned per page. One of the most useful features of Flipomatic is its ability to easily "chunk" result sets into pages consisting of a manageable number of images. It won't overwhelm a user's internet connection with thousands of images per page (unless you tell it to). It turns out that Flipomatic's speed is very much related to the number of images you tell it to render at a time and, on my server at any rate, this number should be less than fifty. If you set up your configuration file to return more than fifty items you'll begin to notice a bit of sluggishness creeping in. This seems to be relatively independent of the total number of images in your collection. So whether your collection consists of an album of thousands of images or a book with hundreds of pages, restricting the number of images you display at a time to less than fifty will result in the fastest speed. The other major factor is the number of queries Flipomatic must process. This is mostly independent of page size and very dependent on the total number of images in your collection. While Flipomatic may be able to efficiently browse a collection of 12,000 images, searching within it is quite a different matter. You will find that the more queries you create the smaller your total collection size has to be in order to retrieve them at an acceptable speed. On our server (your results may vary) searching for a single word in a 12,000-image collection requires 2 or 3 seconds to display each page. Searching for 2 words takes 4 or 5 seconds, searching for 3 words takes still a bit more time. For smaller collections, under 7,000 or so items, searching for any number of words should work quite fast. Installing Flipomatic =============================================== Flipomatic is a cgi script and, provided your server can already execute cgi scripts written in perl, no complicated installation steps are needed beyond copying it to your cgi-bin directory. If you are not familiar with cgi programming you should have your system administrator do this as they are familiar with the permissions requirements such scripts have. In addition to copying it to your cgi-bin directory you'll need a directory in which to put your data. Flipomatic always reads three configuration files when it executes a request. The first is the _default.cfg configuration file which contains, among other thing, instructions on what Flipomatic should do when it encounters errors (such as not being able to find or read the other configuration files), but we'll return to the _default.cfg file later. The second configuration file is the collection file. The collection file contains the HTML templates designers use to build their flipomatic site. All collection configuration files must be located together in the same directory. This is the directory you'll need to create when you install Flipomatic. It should NOT be located in your web data directory (the directory tree your webserver uses to serve out HTML pages) but it SHOULD be readable by your web server (e.g., group "nobody", etc.). It is also a good idea to make this directory and its files writable by your web designers. Once you have decided on a directory, copy _default.cfg (which ships with this program) into that directory. Flipomatic also ships with several sample configuration files and configuration files used in the tutorial. Copy these files there as well if you wish. You may want to remove them later when you begin creating your own collection sites. Finally there is a single line within the Flipomatic perl program itself which you must change. This is the line which points to the configuration file directory which you created above. Edit it to point to this directory. While you are editing this line of the program note the copyright, use, and liability restrictions explicitely stated at the top of the program. There. Now you can't sue me. Installing on Unix/Linux servers -------------------------------- Installation on Unix or Linux should be very easy since almost all such machines have perl installed and can run perl cgi-scripts. Just: 1. Create a configuration file directory 2. Edit Flipomatic to point to this directory 3. Copy Flipomatic to your cgi-bin directory 4. Make it executable, change the #! perl path if necessary 5. Copy _default.cfg and optionally the sample and tutorial templates to the configuration file directory 6. Test it! Installing on Windows servers -------------------------------- Windows servers may prove more problematic since they generally do not ship with perl nor is the IIS webserver configured to run perl scripts. You may have to install ActiveState perlIIS first. Flipomatic does not ship with a file extension, that is, the script is named "flipomatic" and not "flipomatic.pl" (this is in keeping with my philosophy that URLs should be clean and easy to read and type). When installing on a Windows server though, you will likely need to add a file extension, e.g., ".plx", or ".cgi" and configure the web server to recognize this as a perl script. Search the Microsoft website for more information on configuring IIS to run perl cgi scripts. If you can't get Flipomatic to run on your webserver, first verify you can run any perl cgi scripts at all by executing a simple "Hello World," e.g., print "Content-type: text/html\n\n"; print "Hello World!\n"; Installing on Macintosh servers -------------------------------- Unfortunately Flipomatic has not been tested on the Mac nor do I have a Macintosh server on which to test it. However, provided your Mac server can already run cgi scripts written in perl, I see no reason why Flipomatic shouldn't run on it as well. Introduction to configuration files =============================================== In a proper correct transaction, Flipomatic should always read a total of three files before rendering a page: 1. The _default.cfg file 2. The collection configuration file 3. The document data file The first file is always read while the other two vary depending on the collection and the specific document. The collection and document files are specified in the URL (see "Flipomatic URL syntax" below for details). The first file, _default.cfg, is used mainly to specify Flipomatic's behavior upon encountering errors. You'll likely never change this file. The second file, the collection configuration file, is where you will create your HTML interface. The collection configuration file contains templates where you put your HTML to specify a particular collection's appearance and behavior. You can have as many collection configuration files as you wish, allowing you create a different appearance and behavior for a variety of different documents. All collection configuration files must reside in the same directory (this is the directory you originally created when you installed Flipomatic). The third configuration file is the document data file itself. For METS documents this is a METS XML file, while for non-METS documents it is a configuration file identical in form to both the _default.cfg and collection configuration file. We will deal with METS documents as a special case much later but for now and throughout the rest of this manual we will assume non-METS, "native" Flipomatic documents. For those familiar with such concepts, the collection configuration file acts like a stylesheet while the document file acts as an individual instance. Just as with XML, you can use a single stylesheet and apply it to many XML instances, and can apply different stylesheets to the same XML instance. You can see what a typical collection configuration file looks like here. Top 10 most useful Flipomatic tips =============================================== 1. Flipomatic doesn't support nested related text, i.e., you can't put one set of $[ ]$ inside of another: $[Some related text $[A label {VAR1}]$ some more text {VAR2}]$ If you find you really need to do something like this remember you can always accomplish the same task using Flipomatic's powerful "if-else if" form of related text often coupled with flags {|VAR|} and or multiflags {|VAR1|VAR2|VAR3|}. In the example above, it seems the user wants the entire line to disappear if VAR2 doesn't exist. If it does exist, the line prints and if VAR1 exists it prints as well with its associated label. But nothing prints, not even VAR1 if VAR2 doesn't exist. The solution here is to use flags. It's ugly but it works: $[{|VAR2|}Some related text ]$$[{|VAR2|}A label {VAR1}]$$[ some more text {VAR2}]$