Web publishing template for Ant Movie Catalog
Created by Bergware International
Version 0.91
Date: 16 March 2008

INTRODUCTION
This template is based on Twinks excellent template beta version 0.8. Several fixes and speed improvements are included in this release to overcome the known issues in the original template. This template has been tested with Internet Explorer and Mozilla Firefox, other browsers might work too.

This template introduces a dynamic web page construction which allows you to change the displayed output on-the-fly yourself to suit your needs. XML files are used to give an easy way to setup a customized layout at web creation time.

This template requires the export of the AMC database in XML format.

GETTING STARTED
Follow the instructions given below to setup your export folder which contains the information suitable for your browser to display. Once you have it running with the default settings, you may want to customize the look to your own liking.

THE EXPORT FOLDER
Copy the following files and folders from this package to your export folder:
/flags/*	this folder contains the country flag images
/images/*	this folder contains the GIF images
/themes/*	this folder contains the style sheet files
layout?.xml	these are the XML layout files numbered 1 to 5
countries.xml	these are the country ISO notations, see below
movies.js	this is the javascript source file

You must do the next two steps within the AMC application:

1. Do a "save as" function and select the XML format. Save the file as "movies.xml" to your export folder and make sure the pictures are copied as separate files together with the export. In the preferences of AMC have the following settings selected:
 - Movie Information -> Picture Importation -> Use movie number
 - Movie Information -> Picture Importation -> Use catalog name as prefix for the picture name

2. Do a "HTML export" function and use the template 'movies.html' from this package to create the necessary HTML output file; for example name it "index.html". Make sure you have "Images - copy with exported file" NOT checked. This HTML output file must be placed in your export folder together with the files mentioned above.

You are now ready to view your online database by double clicking on the newly created HTML file or by directing your browser to the web site.

THEMES
Using the .css files found in the "themes" directory the colours of the table can be changed. Four themes/styles are included with this template: cyan (default), blue, black and orange. In Mozilla or Netscape, when the exported movie list is opened, you can change styles on the fly by selecting View -> Page Style -> name.

Unfortunately this is not possible in Internet Explorer, it can only use the default style. You can change the default style by changing the preferred style to << rel="stylesheet" >> while the remaining styles must get the setting << rel="alternate stylesheet" >>.

CUSTOMIZE OUTPUT
The layout.xml files are used to define the generated output format. The default output format is layout1.xml, but this can be changed in the "movies.html" file. Output formats can be changed on-the-fly once the web page is displayed. Cookies are used to remember the personal settings.

It is possible to adjust the existing output formats to suit your own needs or create a new layout.xml file all together (e.g. layout6.xml). Note that when creating a new layout file you must give it a corresponding display name, which is defined in the array 'formats' within the javascript source file. As long as no name is given, it won't appear in the list of available choices.

The contents of the layout.xml file is divided in several sections

1. Options
This line overwrites the default values of the javascript source file. The following are allowed:
 * category	defines which category is displayed at startup, default is ALL
 * pagesize	defines the number of rows displayed per page, default is 10
 * sortkey	defines which column is used as initial sorting index, default is NONE
 * searchkey	defines which fields are included in the search function, default is the DESCRIPTION field
 * separator	defines whether a colored line is used between movie titles, default is FALSE

2. Groups
This section defines the selectable categories (see the settings menu on the web page). For each category the script will automatically find the available entries. Use the "checked=true" option to have a category included as default item on display. Category names are customizable with the movie attributes available within the AMC application.

Unplaceable entries are stored under the main category name. This can happen because a given category is not present (e.g. length field is empty) or a none existing category is specified as setting; eg. <group name="MyCategory" setting="getAttribute('NonExistingField')"/>

3. Default
Set the default value of a given parameter. Currently only "image" is supported. This setting specifies the file to take when the source picture file is not present.

4. Row/Cell
This section defines the actual layout of the web page. The row and cell tags are used to build the table format. Study the existing layout files to understand their functioning!

The following options can be given to a row definition:
 * hover	defines highlighting of rows when moving the mouse over them
		(does not work in IE5.5)
 * thumbnails	defines this row contains only images and it must be the first
		row. The only allowed cell content is the "img" type.
		Optionally the image can be given an 'alt' attribute which
		displays customizable information when hovering over an image
 * pin		defines the reference to a hidden row as a row action
 * popup	defines the reference to a popup window as a row action
 * hide		defines if the row is initially visible or not, default is
		false; hidden rows MUST have an 'id' associated with them
		(see 'id' item next)
 * id		sets the identification of a hidden row (used by reference
		options) subsequent hidden rows need an additional
		level setting (1-26), see layout2.xml and layout3.xml

The following options can be given to a cell definition:
 * align	defines the horizontal alignment (left,right,center), default is left
 * valign	defines the vertical alignment (top,bottom,center), default is center
 * rowspan	defines how many rows are spanned, default is 1
 * colspan	defines how many columns are spanned, default is 1
 * title	defines the title to be displayed in the cell (applicable only
		to the header row)
 * sortby	defines the initial category used for sorting (applicable only
		to the header row)
 * pin		defines the reference to a hidden row as an individual cell
		action (see also row)
 * popup	defines the reference to a popup window as an individual cell
		action (see also row)

5. Cell content
The content of a cell can be one of the following tags:
 * <text>	creates a text message, literal text must be given between
		quotes. Text may have the following optional attributes:
   - bold	text is displayed in bold
   - underline	text is displayed as underlined
   - italic	text is displayed in italics
   - url	specifies a link to an external site
   - alt	adds a plain text tooltip to the url reference
   # rowindex	this keyword is used to display a sequence number as text
 * <img>	creates an image reference with optional attributes
   - width	specifies the width of the picture in pixels
   - height	specifies the height of the picture in pixels
   - url	specifies a link reference to another webpage
   - target	specifies how links are opened
   - alt	specifies the content of a tooltip as plain text
   		When used in combination with the "thumbnails" setting
		it refers to a customizable tooltip similar to pin and popup.
 * <br/>	inserts a line break character
 * <sp/>	inserts a none breaking space

6. Helper functions
There are several helper functions available made for the XML layout file:
 * round()	rounds decimal numbers to the nearest integer or returns 0
		when the source does not exist. This function is used for
		translating the rating value into a picture index
 * append()	append individual items together, if any of these items is
		'null' then an empty string is returned. This function is
		useful for items which do not have content all the time, and
		must be suppressed when they are empty
 * format()	formats the standard movie duration in minutes to something
		else. The following formats are supported:
		h -> "h:mm hour"
		m -> "mm min"
		s -> "ss sec"
		  -> "mm"
 * getIsoCode()	gets the ISO code equivalent of a localized country name. This
		conversion is used when flags instead of country names must be
		displayed. See for more explanation below

7. Flags instead of country names
In order to display flags the function "getIsoCode" is used for translating a local country name into a 2 letter ISO code, which serves as the flag image name. The flags folder contains images for the most common countries but this can be expanded if needed.

The getIsoCode function uses the "countries.xml" file to make the necessary translations. For the flags to appear correctly you must edit the countries.xml file and add the local names of the countries as they appear in your database. It is allowed to put multiple translations under the same ISO (cc) code (default are english names). The following example shows how to build a multi-language translation file (names are non case sensitive):
  <cc id="us">
   <map>united states</map>
   <map>etats-unis</map>
   <map>vereinigte staaten</map>
   <map>verenigde staten</map>
  </cc>
  <cc id="be">
   <map>belgium</map>
   <map>belgique</map>
   <map>belgien</map>
   <map>belgi</map>
  </cc>

8. Movie Attributes
All of the available movie attributes known by AMC can be used in your layout file. Remember that attribute names are case sensitive. Refer to AMC to see the possible values.

TRANSLATIONS
Obviously the content of the database will be displayed as is stored originally. Any localization in here you must do yourself before exporting it to XML.

If you want to localize the web output to your own language, there are three places where to make changes:

a>	In the layout.XML files you have to adjust the "name", "title" and "text" settings
b>	In the movies.HTML file you need to search for the literal text items and
	translate them accordingly
c>	In the JAVA source file you need to change the variables at the top of the file

Both the XML and HTML files use the character code set ISO-8859-1 which will work with most languages, for other languages you might need to change this code set to the one which supports your character set.

FEATURES
* Interactive list display
* Customizable output format (5 formats are included)
* Changeable number of rows per page
* Changeable category selection
* Search function
* Goto function
* Multiple category support (titles appear in all sub-categories)
* Per category display
* Empty or unknown category support
* Sorting on different columns both ascending and descending
* On-the-fly changeable layout
* Thumbnail view with customizable tooltip
* Concealed information as row(s) or popup
* Mouse hover function
* CSS/style support (4 styles are included)
* Internet Explorer and Mozilla support
* Remember personal settings when page is re-opened
* Rating with 5 stars indication
* Quick show/hide buttons for additional information display
* Selectable time format for film duration
* Flags display for country names
* Information function
* About function
* Page loading indicator

NEW IN VERSION 0.90
* Ability to dynamically change layout (choose layout in settings menu)
* Shows sorted field (small triangle in column title)
* Added "sortkey" field to Options in layout.xml files
* Added "searchkey" field to Options in layout.xml files
* Setting pagesize to 0 shows all movies in the category (use with care)
* Simplified support in layout.xml file for multiple hidden rows
* New popup view with customizable moving window (see layout3)
* New thumbnail view with customizable tooltip (see layout4)
* New GoTo function with page browser function
* New bottom control bar with fixed size cells
* New page controls to go to first or last page immediately
* New category groups construction (improved readability)
* New buttons for showing/hiding concealed information
* New mouse hover function to highlight the selected row
* New helper functions to allow easy XML construction
* Cookie support to remember user personal settings
* Different time formats for the movie duration
* Show country flags with multi-language support
* Speed optimizations allow for faster browsing and operation
* Easy way to include new layout.xml files
* Separated javascript source, XML database and HTML webpage
* Fixed persistent sorting when changing categories
* Fixed handling of groups with spaces in their name. e.g. "United States"
* Fixed column span calculation
* Fixed sorting by numbers
* Fixed click text not cell (event handler)
* Fixed next/previous page move to top
* Fixed current page and total pages counters display
* Fixed cursor change to 'hand' in Mozilla
* Fixed rating display (stars) when fractional ratings are used
* Fixed dynamic loading of XML files
* Fixed table width always set to 100%
* Fixed grouping movie titles when upper- and lowercase characters are used

NEW IN VERSION 0.91
* Fixed numeric/alphabetic sorting on all possible AMC attribute fields
* Fixed display of categories with multiple spaces in their name
* Added both "alt=" or "title=" as tooltip indicator are allowed
* Some code optimizations

KNOWN ISSUES
* It may happen that the XML file is not accepted by your browser because some 'corrupting' characters appear in the content. The easiest way to verify the correctness of the XML file is by opening it directly in your browser. Any error messages will be given referring to the offending part(s). Please correct them! Specially Mozilla is very strict and doesn't display anything as long as the XML file is not recognized as a proper file. Internet Explorer seems to be a bit more relaxed, it will usually display the XML file even though some errors are present; however it is recommended to fix them anyway.

* Very long lists may take some time to load (choose the page size carefully), the browser may appear to be hanging because no visual feedback is given.

OTHER NOTES
The bookmark functionality of the original beta version 0.8 is not present anymore. Also not displayed is "search" as an individual entry (searching is still possible ofcourse)

More optimized script speeds can be achieved by compressing the script source file with the many online available javascript compressor tools. See for example:http://www.codeandcoffee.com/2006/10/02/compress-your-javascript/ (use the compression level MEDIUM to get a workable output)

Flag images can be downloaded from the Internet. A good source is http://www.flags.net. Included in this package are the most common country flags.
