# User manual

JAlbum is based on a single window with a couple of fields and buttons divided into two tab pages. There are quite many buttons and settings here, but you generally only have to do a couple of steps in order to create and view an album. If you haven't yet created an album, look at the Quick start first. Now let's go through each and every element of the interface.

## The Main page

This is the central section of JAlbum. Here you can select image directory, output directory, common album settings and control album generation.

- Image directory -Drag and drop a folder containing JPEG images here
- Output directory -Specify another location for the output
- Output to image directory -Put the resulting album in the image directory
- Copy originals -Copy original images to output directory
- Process subdirectories -Make a web of a hierachy of image folders
- Make slides -Make a slide show with next/previous buttons and display of image details
- Link to originals -Link directly to original images from index page or slide show. Usually produces large albums
- Link to originals via scaled images -Produce smaller images that are displayed first. Practical for the web
- Link to scaled-down images only -Produce smaller images. Don't link to original images. Makes the smallest albums
- Thumbnail bounds -Specifies bounding box. Images will maintain aspect ratio
- Image bounds -Image bounding box. Images will maintain aspect ratio
- Columns -Number of image columns in the index page(s)
- Rows -Number of rows in the index page(s). Will produce several index pages if no-fit
- Image ordering -Specify either chronoligical, numeric-alphabetical ordering or simple alphabetical ordering. Directories are put first and always in alphabetical order
- Directories first -Put subdirectories before images
- Reverse -Reverse image ordering
- Edit image ordering button -Select custom image/directory ordering for the current image directory
- Skin -Select overall apperance of your album
- Style -Select color theme and look of your album
- Preview skin -Open a preview window showing an example of the current skin
- Edit skin button -Open directory of current skin for editing (Windows only)
- Rebuild album -Create a web album by rescaling all images (slower)
- Make album -Create a web album but don't rescale existing or unchanged images (a lot faster). Select this when image size need not be changed
- View album -Preview resulting web album in your browser

## The Skin page

This section only shows if the selected skin has a custom user interface (JAlbum 4.1). Its functionality is entirely defined by the skin itself and not documented here. Here is an example of the custom user interface for the "ShowOff" skin. Its functionality is explained by "tool tips" if you hover the mouse over the controls.

## The Edit page

This section allows you to easily add comments/annotations to images and to perform lossless JPEG rotation. The functions here apply directly to the original images, so keeping backups of your original images is always recommended in case something would go wrong.

The operations in this section preserve the original file date so image ordering on file date stays intact.

- "Get images from album" button -Loads the images from the current album for editing (the root album folder). You can also drag and drop folders and images onto this section for editing. Dragging and dropping images does not add the images to the album itself, it just allows editing.
- Scroll bar -Use the scroll bar to the right to browse through the images you have loaded for editing.
- Label field -Displays the base file name (without extension) and allows for simple renaming of files.
- Rename button -Rename files to new name entered in the label field
- Lossless manipulation buttons -Rotates, mirrors and flips JPEG images losslessly. Note! These operations apply directly to the original images. If an image ends up distorted (can happen), use the undo button. Keeping backup copies of your original images is also recommended before using these functions.
- Comment extraction buttons -Comments can be stored in several "standardized" ways and JAlbum handles four types, "File" being comments stored in separate files bearing the same base name as the image file but with a ".txt" extension (used for non-jpeg images).
- Comment field -Enter comments/annotations to images here. Comments are automatically being written to an external text file as you move between images.
- Write comment button -Store comments/annotations inside the "JPEG comment" section of JPEG images. This is a standardized way to store comments and is practical as the comment is carried along with the image instead of being stored in some proprietary config file (as some other generators do). Non-jpeg images will have their comments stored in separate .txt files instead.

Remember to go to the "Main" section and press "Make album" after making changes here in order to have them show up in your generated album. If you have rotated images in a previously generated album, you will have to use "Rebuild all" too.

If you drag and drop many large images onto this section, the program might seem sluggish and slow. This is because scaled-down previews are created in the background for fast browsing using the scroll bar. If this bothers you, just flip quickly back and forth between this section and the "Main" section and the background processing will stop.

## The Publish page

JAlbum has an integrated FTP client that makes publishing your album on a server a snap. JAlbum Attempts to speed up uploading by only uploading files with different sizes. You are able to fully continue using JAlbum during upload. Remember: You can use any other ftp client to publish your albums if you don't get along with this one.

- Create account... -Start the JAlbum web host signup wizard that makes it really easy to get a web hosting account with ftp access (unless you already have one) and have all ftp connection settings below automatically filled in.
- Accounts... -Open a popup window that allows you to add, remove and select among multiple FTP account profiles (settings). The profiles are automatically stored in the users' home directory
- FTP server -Host name of FTP server to upload album to, for example "ftp.myserver.com"
- Username -Username of FTP account
- Password -Password of FTP account
- Remote directory -Directory on FTP server where to upload album to. Note that the "Web directory" (see below) will be prepended to the remote directory
- Web directory -Directory under ftp directory that is web published (leave blank if same directory)
- Passive mode -Use this switch if you are having trouble connecting through a firewall
- Save password -Store password in with JAlbum project. Currently not enabled - will store password if project is saved.
- Force UTF-8 -Force UTF-8 file name encoding nomatter what the server reports
- Test connection -Attempt to log in and go to remote directory, will propose to create directory if not exists
- Always upload pages -Always upload html pages even if size of local file equals size of remote file, see "Smart upload" below
- Web root URL -URL to root of web site hosting the images. (For the preview link below)
- Preview linkL -Link that links you directly to the album on-site
- Upload all -Upload contents of output directory (the album) to FTP server
- Smart upload -Attempts to speed up uploading by only uploading files with different sizes

## The Advanced page

Need more detailed control? Well some of those controls are present in this section, but remember JAlbum doesn't aim to have a button for each imaginable type of option, instead JAlbum gains its power from its ability to interpret user defined skins, containing variables, special flow control elements and BeanShell scripts. This page is divided into four sections. "Main", "Naming", "User variables" and "Preferences"

### The Main section

Settings that don't fit in the other three sections go here

- Text encoding -Set the text encoding to use for reading and generating files and comments. Note: JAlbum will auto-sense UTF-8 and UTF-16 encodings no matter this setting (given that those files/comments contain a "signature marker" for those encodings). Some text encodings require you to run JAlbum on top of an international Java. The embedded Java (Windows only) is not international and only supports a few encodings. It is recommended that you use the international Java from Sun with JAlbum (select "JRE").
- Write UTF-8 -Generate files and store comments using UTF-8 encoding no matter the "Text encoding" setting below. It is recommended to keep this checkbox checked as UTF-8 enables you to use any combination of characters in a web page but make sure that your web server passes the correct encoding too.
- Date format -Display format for date/time. Defaults to the format for your region. You can get any imaginable date formatting by entering a custom made "pattern" here. Here is a guide:

  >     Symbol   Meaning                 Presentation        Example
  >     ------   -------                 ------------        -------
  >     G        era designator          (Text)              AD
  >     y        year                    (Number)            1996
  >     M        month in year           (Text & Number)     July & 07
  >     d        day in month            (Number)            10
  >     h        hour in am/pm (1~12)    (Number)            12
  >     H        hour in day (0~23)      (Number)            0
  >     m        minute in hour          (Number)            30
  >     s        second in minute        (Number)            55
  >     S        millisecond             (Number)            978
  >     E        day in week             (Text)              Tuesday
  >     D        day in year             (Number)            189
  >     F        day of week in month    (Number)            2 (2nd Wed in July)
  >     w        week in year            (Number)            27
  >     W        week in month           (Number)            2
  >     a        am/pm marker            (Text)              PM
  >     k        hour in day (1~24)      (Number)            24
  >     K        hour in am/pm (0~11)    (Number)            0
  >     z        time zone               (Text)              Pacific Standard Time
  >     '        escape for text         (Delimiter)
  >     ''       single quote            (Literal)           '

- Extract photographic data -Adds image meta information (shutter speed, aperture etc) if found
- Include subdirectories in index pages -Create icons and links to subdirectories (if present)
- Process only updated subdirectories -Skip subdirectories that haven't been touched since the last album build (makes a deep file date comparison). This option speeds up updates of large album structures significantly.
- JPEG quality (%) -Balance file size / image quality
- High quality scaling -Smoother but slower image scaling
- High quality thumbnails -Smoother and almost as fast thumbnail image scaling
- Ignore pattern -Regular expression for files and directories to ignore during album processing. This option is mainly relevant when processing big directory trees where one wants to ignore certain "system directories" that some camera makers add. Here are some examples of valid regular expressions and their meaning:

  >     Pattern            Meaning
  >     -------            -------
  >     .*\.gif            All gif files
  >     (system|meta)      The directories (files) system or meta
  >     \..*               All files or directories beginning with a dot
  >     (\.|_).*           All files or directories beginning with a dot or underscore

  For more details on regular expressions, please refer to the many tutorials and examples available on the Internet.
- Comment sources -Controls locations to pick image comments from (listed in order of precedence)

### The Naming section

This section allows you to set the names and directories of generated files. Note, the directory selection is still fixed but will be user definable in future versions. In the meantime, skin authors are encouraged to use the engine/AlbumBean getXXX methods to get these directory names instead of using hardcoded strings like "thumbs" and "slides".

- URL encoding -Toggle encoding of spaces and foreign characters in links. Should be used for web albums, and not used for local (harddisk/CD-ROM) albums containing foreign characters
- Index page name -File name of the index page(s) with thumbnails that gets created in the image directory
- Page extension -File name extension of the html pages that are generated. Is usually .html or .htm
- Thumbnails directory -Where to put thumbnail image files
- Closeups directory -Where to put closeup (scaled) image files
- Slides directory -Where to put slide files (usually html)
- Thumbnail prefix -Prefix to add in front of each thumbnail file
- Closeup prefix -Prefix to add in front of each closeup (scaled) file

### The User variables section

Variables to be replaced or overridden during album generation. For example: Override "title" in order to set your own page title or add a homepage variable and have all occurances of $homepage in the skin template files replaced by this variable. ($homepage is not defined for most skins, but you may add it by editing the skins. See the "creating skins" section).

### The Preferences section

These are environmental settings that doesn't directly affect the generated album. The settings here are not included in JAlbum projects. Remember to use "Save as default" from the File menu in order to make changes here permanent.

- Language -Sets the preferred language of JAlbum. If you're missing your language, please see the "texts" directory of JAlbum for how to translate JAlbum to your language.
- Look And Feel -Sets the look and feel (visual appearance) of the JAlbum user interface. New "Look And Feels" can be downloaded into the Java environment that JAlbum uses and then used by JAlbum.
- Debug mode -Make JAlbum stop for minor image processing errors and display a stack trace
- Use layout hints -If to allow a skin to change the program settings (image size etc)
- Auto write comments -If JAlbum is to automatically write comment changes to the image file when moving between images in the Edit section.
- Show warning dialogues -If JAlbum is to show warning dialogues for settings that may lead to a less than perfect album result.
- Allow blinking hints -If to allow, for example, the "Drag and drop" reminder to blink when hovering the mouse over the directory selector.

## The File menu

The ability to save album project settings saves a lot of time keeping your albums updated when new images arrive. Simply start JAlbum and reload the settings for a previously created album.

- New project -Clear current settings and load default settings
- Open project... -Open a previously saved JAlbum project
- Recent projects -Open a recent JAlbum project from this sub menu
- Save project -Save current settings for current project.
- Save project as... -Save current settings under given name
- Save project in image directory -Save current settings inside image directory. When you re-visit this directory, you will automatically be prompted for reloading the stored settings
- Save project in album -Same as above but saves current settings inside the output directory instead.
- Save as default -Make the current settings the default settings
- Exit -Leave JAlbum

## The Presets menu

To quickly get the settings right for different types of albums, the presets menu provides the following ready made settings:

- Small size web album from large originals -Make an album with scaled-down images without links to original images. URL encode links.
- High quality web album from large originals -Make an album with scaled-down images with links to original images. URL encode links.
- Web album from small originals - Make an album using the original images only. URL encode links.
- Index with links to CD-ROM originals -Make an album with absolute links to original images (works across devices). Do not URL encode links.
- Local (hard disk) album -Make an album with scaled-down images with links to original images. Do not URL encode links.

URL encoding is the replacement of foreign characters like ÅÄÖ and spaces in links with %<hexcode>. Spaces for example, are replaced with %20 sequences. This is neccesary for such links to work when accessed through a web server. However, the opposite hold true for local (hard disk) browsing. Therefore it is important to get this setting right depending on if you want to access the album locally or through a web server. To make the album work in all environments, skip spaces and foreign characters in file and directory names. Finally, the presets menu provides quick settings for small, medium and large sized index pages.

## The Tools menu

This menu contains general handy tools and is user extensible (therefore not translated). A "Tool" is actually a "BeanShell script" that is put in the tools directory of the JAlbum install directory. Hopefully people will contribute with more tools as time goes by. Here are the existing tools so far:

- Reset file date to camera date -Go through all images specified in the image directory (and its subdirectories) and reset the file date to the EXIF camera date as written by the camera. JAlbum orders images after file date, not camera date, so running this tool if a file has been touched can be helpful in order to get the image ordered chronologically again.
- Adjust image orientation -Go through all images specified in the image directory (and its subdirectories) and, if neccesary, rotate them to correct angle by reading the EXIF rotation information as written by some cameras.

## The Help menu

- Check for updates -Connect to the JAlbum web site and check if there has been updates to JAlbum.
- Help topics -Open the local JAlbum help web
- JAlbum on the Web -Open the official JAlbum web
- System console -Open the "system console" window which allows you to see debug output from skins (System.out.println output) and also to evaluate BeanShell expressions interactively.
- About -Display info about this JAlbum version and the underlying Java engine.

## Image filters

Image filters can be plugged in to enhance images during album generation, adding watermarking, logos etc. An open API and source code example are provided so developers easily can add new filters. Currently there is no graphical user interface for image filters, but with some fairly simple settings in the "User defined variables" section of the Advanced page, they can be controlled.

## Console mode

JAlbum can also be controlled from the command line. It accepts the same parameters as you are able to set through the graphical user interface.
Issue `java -jar JAlbum.jar -help` in the same directory as JAlbum is installed in and JAlbum will list all allowed parameters. User defined variables are passed as `-user.yourVariable "Value"`. Command line mode is great for automated album generation and updates. Webmasters can make scripts that call JAlbum regularly to update server albums etc.

Here is an example that updates an album out of files in D:\Nature and grabs other settings from the nature.jap project file: ``

    java -jar JAlbum.jar -directory D:\Nature -sameDirectory -projectFile nature.jap -appendImages

Linux/UNIX users: To run JAlbum from the command line in a plain server system (with no access to the X windowing system) add the `-Djava.awt.headless=true` command line switch.