# The &kapp; Handbook

Andras
Mantia

    amantia@kdewebdev.org

2001, 2002, 2005, 2006
Andras Mantia
&FDLNotice;
21/11/2006
1.2.0

&kallery; is a highly configurable image gallery generator wizard.

This version of the handbook is valid for &kapp; 1.2.0.

KDE
graphics
generator

## Introduction

&kapp; is an easy to use image gallery generator application with a wizard-like interfaces. You can create nicely looking, ready-to-publish web pages from your digitally stored images. Some of the most important features are:

- handles a lot of image formats, thanks to ImageMagick

- automatically generates thumbnails with the help of ImageMagick

- converts the images in other formats (eg. JPEG)

- it's possible to create descriptions for images or load them from the image files themselves

- the output HTML gallery is highly configurable

- uses templates for the gallery

- save and load of the project files, so you can regenerate the gallery later with the same or different settings.

## Using &kapp;

It's easy to use. Due to the wizard type interface, there are no menus, but ten option pages. You can go back and forward on the pages, just remember one thing: if you make some changes on a page and you go back to the previous page, you may lose the settings made. If you've already went to the next page, then you can safely go back. Think about the Next button, as a save button for the current page. This chapter will desribe what can you do and set on each page.

### Getting started

After you've started the application, on the very first page you can:

- start a new project

- open a saved project, so you can modify the old settings and create/recreate the image gallery. The project name will appear in the window caption. Clicking on the Open saved project option will open you a file selection dialog.

### Select the sources

The first thing that you must do is to select the images for the gallery. You can add new images with the Add button, remove from the list the selected ones with the Remove button. You can also modify their order in the gallery with the Top, Up, Down and Bottom buttons at the left of the image list.

### Thumbnails

In most cases you will generate a list of thumbnails, so the visitor of your gallery can see the small images, and click on one of them, if he/she wants to view that image in larger form. On this page you can tell &kapp; what to do with thumbnails. Your choices are:

- Generate thumbnails - &kapp; will generate a thumbnail for each image

- Load thumbnails - if you have somewhere already thumbnails for the images, you can use them. The list of the loaded thumbnails is below, you can Add and Remove thumbnails. If you have selected this options, be careful, that the number of loaded thumbnails must be equal with the number of selected images. &kapp; will warn you about this, and will not let you go to the next page if the numbers are not equal.

- Do not use thumbnails - There will be no thumbnail list for your gallery, the visitor can click on the descriptions on the main page, if he/she wants to view the image. Some templates do not have descriptions on the main page, so be careful.

### Match image and thumbnail files

You will see this page only if you choose before to Load thumbnails. In this case you can match the image-thumbnails pairs, and you can also modify the order of the images (and of course of the thumbnails). Use the buttons near the list boxes to modify the image or thumbnail order in the list. By clicking on an item in one of the lists, the pair of that item will be also selected in the other list.

### Target paths

Here you can select the place where your gallery will be.

- Output gallery file name - put here the filename - including the absolute path to it - of the target gallery file. This is your main file that you will have to open in your web browser to view the gallery.

- Fullsize image folder - &kapp; will copy here the selected images.It will overwrite every file in this folder if it has the same name as one of the selected images. It is recommended to use a relative path to the main folder, instead of an absolute path.

If you asked &kapp; to generate thumbnails, then you must also specify a folder where it will put them. It cannot be the same as the fullsize image folder, because the thumbnails will have the same name as the fullsize images.

A good idea is to use relative paths - this is the default option -, because by using them you can freely move your generated gallery on your hard drive, and on the Internet. If you for whatever reason want to use absolute paths in links, check the Use absolute paths in the links checkbox.

The recommended directory structure for image galleries looks like:

- Gallery file: .../homepage/gallery.htm

- Fullsize image folder: .../homepage/fullsize/

- Thumbnail directory: .../homepage/thumbnails/

- Use absolute paths in the links is not checked.

### Describe the images

You have the possibility to add a description for each image. In this case select the Edit descriptions, and enter the description in the edit box for the image. You can see the image filename above the edit box. To go to the next/previous image, use the buttons near the edit box.

You can also Load the description from a file. Each line of the (text) file is treated as a description for one image. (The first line describes the first image in the list, the second line the second image, etc.)

The default option is to read the description from the file itself. Not all file formats support comments, but the most used JPG files have support for them, so you can let &kapp; read the comments and other information from the files. For this select the Read information from the images option. After selecting this option you will have the possibility to select what kind of information should be extracted from the files:

- Image comment:extract comments

- File size:the size of the file in bytes

- Image dimensions:the dimension of the image in pixels

- Shooting date:the date when the picture was created

- Exposure information:information about the camera, exposure time and aperture used to take the picture

Checking one of the boxes does not mean that those information will be available on the generated pages, as it depends on the template used what information appears there. Unchecking an option means that the information will not appear on the pages, even if the template instructs to show them.

If you want, you can generate a gallery without any description, however generating a gallery without thumbnails AND without descriptions is not a good idea.

### Image options

If &kapp; will generate thumbnails, you should specify the file format of the thumbnails - select from the list -, and the thumbnail size in pixels. The aspect ratio of the image will be kept.

&kapp; is useful not only to generate image galleries, but it can also do some kind of batch conversion of image files. If you selected the Convert fullsize images as follows option, then your images will be copied to the fullsize target path and converted to:

- a new file format - select from the list. Remember that ImageMagick (and &kapp;) cannot convert from every type of input format in every type of output format. The quality setting (you can change it with the slidebar, where 0% is the worst quality, 100% is the best) is valid for some image formats like JPG, PNG, MIFF.

- a new size format - this is optional. If the Keep aspect ratio is not checked, the images will have exact the chosen size.

You may whish to put copyright text to each image, and of course you can do it inside &kapp;. Select the Insert copyright text option and enter the copyright text. The inserted text will appear in the lower right part of the fullsize images.

By selecting the Link images from their original path option, your images will be linked to the gallery web pages directly from their current places (by using absolute paths), so it's better not to select this.

The Copy the images to the target path without conversion is useful, if you want to keep your images in the current format and wish to get a portable (and useful) gallery. The images will be copied to the target path, but no conversion will be done.

The Use existing images from the fullsize folder option is useful if you already converted and copied your images to the target folder either with &kapp; or an other application, and you want to use them from there. This is especialy useful if you generate a gallery and you want to fine-tune some look and feel options later: you do not need to convert and copy your fullsize images again.

### Gallery look and feel

This is the first of the look and feel pages. You can (and should):

- add a title to your gallery (Page title)

- select the Number of columns of the table which will hold the thumbnails and the descriptions. The special value of 0 means that the thumbnails will be layed out in only one row and as many columns as many pictures you have selected. This number is preset in some templates, so it is normal that it changes if you select another template.

- set the Country/Language. This is useful when you build multi-language galleries. All language dependent files (eg. htmls for images, because they contain descriptions) will have an "_COUNTRYID" (eg. "_hu") part in their name, so one image file can have several desciprtion/html files, and there won't be any conflict.

- set the Output encoding. For English and other languages without special characters, you can use Locale or Latin1. For the other the best is to select Unicode (utf16 or utf8), altough the files size will be larger (double), and some OS-s, browsers may not support them. The htmls and the description file will be saved using this encoding.

- select a template for the main gallery file. Read more about the templates in the next chapter.

You can put some text before or after the thumbnail table list. You have to specify two files: one containing the text that will appear before the tables and the other containing the text to appear after the table. This files must be text files, and they may contain HTML formatted text, altough the header part ("head" tag) and the "body" releated tags should not be present in them, because the content of those files will be entirely copied in the generated gallery html file.

What about CSS? It's supported, so if you have a CSS file, specify it, and it will be imported in the main gallery file. In this case the color settings are useless. The CSS file will not be copied anywhere, so if you move your gallery site, be sure to move also the CSS file. The relative path between the gallery file and the CSS file should not change (or you must otherwise modify by hand the gallery html, or you must regenerate the gallery, by loading again the CSS file).

In the Colors section, you can select the background color, the color of the thumbnail holding table, the text color (used for links as well) and the color for visited links.

### Fullsize image look and feel

You should generate a html file for each image. If you do not do so, then the fullsize image will not have descriptions, you will not have navigation buttons, and the image will not be centered. So please, check the Create individual html pages for images box (otherwise you cannot change these nice options). :)

These htmls are also based on templates. By default you have the following choices:

- Buttons above the image: the description and navigation buttons are above the image.

- Buttons below the image: the description is above, the navigation buttons are below the image.

- Buttons above and below. No Back button.: the description and the Previous button is above, the Next button below the image. There will be no Back button.

- Buttons near the image: the description is above, the Previous button is at the left, the Next button is at the right of the image. The Back button is below the image.

Read the next chapter to learn how to use your own templates.

There is also an option to load a CSS file. It will be used for every image-html in the gallery. Read the previous section, to find out more about CSS support.

Should you not use CSS, you can still specify the background, the text/link and visited link color.

As you saw, the images can contain navigation buttons around them. You can have Text or Graphical buttons. In the first case you can enter the text for each button, in the second case you can use the default buttons, or load your own button. The buttons will be copied to the same directory as the fullsize images, and their name will contain the "_languagecode" tag. For example, "back.png" becomes "back_hu.png", if the selected language was Hungarian (hu).

If you do not want to have a button, in the case of text buttons delete the button text, and in the case of graphical buttons, try to load an invalid (non existent) file as the button.

The meaning of the buttons are:

- Next - go to the next image in the gallery

- Previous - go to the previous image in the gallery

- Back - go back to the main gallery page

### Review the options

Before you start the generation, you can take a look again to the most important options that you have chosen, and go back to modify them if you do not like something. If everything is fine, press the Finish button.

### The generation process, saving your work

After you press the Finish button on the last page, &kapp; will offer to save the selected options in a project file. The file should have the .kallery extension (this will be added automatically to the filename, if it doesn't contain already an extension). In the same directory, &kapp; will save the descriptions under "projectFileName.descriptions" name.

After saving the project (or if you selected not to save), the generation will start. You can see a dialog indicating the current progress status. During the first 50% the images will be converted, copied and the thumbnails will be created (you can see the name of the currently processed image file). After the 50% &kapp; will generate the htmls and the main gallery. This part is much faster than the first one. Of course, it is possible to cancel the generation process, if you think it is too slow (it takes about 20 minutes on a Pentium II 550Mhz, 196MB memory to fully process 400 images), or you forgot something, and want to change your settings. You can do this by restarting &kapp; and loading the saved project.

## What about templates?

The generation of html files is based on templates. &kapp; takes a skeleton of the html (this is the template file), and replaces some special tags, and places some extra text in them to get the desired html files. You can find the templates in the `$KDEDIR/share/apps/kallery/templates/gallery` and `$KDEDIR/share/apps/kallery/templates/fullsize` directories, they have the .template extension. If you want, you can create your own templates and put in those directories, or - if you do not have permissions to put them there - put in your ``$KDEHOME`/share/apps/kallery/templates/gallery` and ``$KDEHOME`/share/apps/kallery/templates/fullsize`. They MUST have the .template extension. The `$KDEHOME` is usually the .kde (or .kde2) directory in your `$HOME`. To create templates, follow these rules:

- the first line should contain the html document type description (eg. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"\>);

- exactly the second line must contain the template name, in html comment (eg. <!--Default template-->). This is important, because it is used as an identifier;

- the following lines may contain special commands in html comments. The syntax of them is:

      <!
      VARIABLE=value
      >

  Supported variables are:

  - MAINFRAMEFILE:value is a html file located in the `$KDEDIR/share/apps/kallery/htmls` folder and is serving as the main frameset page containing the layout of the frames.

  - COLUMNS:value is a positive or zero number, specifying the default column value for this template

Read forward to see how to make gallery and fullsize templates.

### Templates for the main gallery file

After the header the file should be a normal html file, with the requried tags. Special tags in the gallery templates:

- %CHARSET%: optional, will be replaced with the selected character encodind;

- %CSSFILE%: optional, will be replaced with the CSS file for the gallery;

- %BACKCOLOR%: optional, will be replaced with the background color for the gallery;

- %TEXTCOLOR%: optional, will be replaced with the text color for the gallery;

- %TABLECOLOR%: optional, will be replaced with the text color for the gallery;

- %IMAGEREF%: recommended, the path to the fullsize image or fullsize image html;

- %MIMETYPE%: optional, text/html of image/imageformat;

- %IMAGESRC%: optional, the path to the thumbnail image;

- %ALTNAME%: optional, will be replaced with the filename of the image;

- %IMAGENAME%: optional, will be replaced with the filename of the image;

- %COMMENT%: optional, will be replaced with the description comment of the image;

- %FILESIZE%: optional, will be replaced with the size in bytes of the image file;

- %DIMENSION%: optional, will be replaced with the dimension of the image in pixels;

- %DATE%: optional, will be replaced with the shooting date;

- %EXPOSURE%: optional, will be replaced with some information about the creation of the image (camera model, exposure time and aperture used to take the picture);

- %IMAGEDESC%: optional, will be replaced with a combination of %COMMENT%, %DATE%, %DIMENSION% and %EXPOSURE% separated by a new line;

- <!-- Html formatted text before the table -->:recommended, will be replaced with the text from the selected file;

- <!-- Html formatted after before the table -->:recommended, will be replaced with the text from the selected file;

It is recommended to put a line defining a table (this will hold the thumbnails), after that put the <!-- Table begins here --> comment, and in the following line define a table cell (<td> tag, and use the above special tags.

If you are lost, look at the default templates. :)

### Templates for the fullsize image html files

Making templates for the fullsize images is easier and may make more sense. There are less special tags, and you have more freedom. The special tags are:

- %CHARSET%: optional, will be replaced with the selected character encodind;

- %CSSFILE%: optional, will be replaced with the CSS file for the fullsize images;

- %BACKCOLOR%: optional, will be replaced with the background color for the fullsize images;

- %TEXTCOLOR%: optional, will be replaced with the text color for the fullsize images;

- %IMAGENAME%: optional, the filename of the image;

- %PREVREF%: optional, will be replaced with the link to the previous the image;

- %PREVNAME%: optional, will be replaced with the "previous" text;

- %PREVBUTTON%: optional, will be replaced with the "previous" text or button;

- %NEXTREF%: optional, will be replaced with the link to the next the image;

- %NEXTNAME%: optional, will be replaced with the "next" text;

- %NEXTBUTTON%: optional, will be replaced with the "next" text or button;

- %BACKREF%: optional, will be replaced with the link to the main gallery;

- %BACKNAME%: optional, will be replaced with the "back" text;

- %BACKBUTTON%: optional, will be replaced with the "back" text or button;

- %BACKTARGET%: optional, will be replaced with "_self" if no frames are used, and "_parent", if you have generated a frame on left;

- %COMMENT%: optional, will be replaced with the description comment of the image;

- %FILESIZE%: optional, will be replaced with the size in bytes of the image file;

- %DIMENSION%: optional, will be replaced with the dimension of the image in pixels;

- %DATE%: optional, will be replaced with the shooting date;

- %EXPOSURE%: optional, will be replaced with some information about the creation of the image (camera model, exposure time and aperture used to take the picture);

- %IMAGEDESC%: optional, will be replaced with a combination of %COMMENT%, %DATE%, %DIMENSION% and %EXPOSURE% separated by a new line;

If you are lost, again look at the default templates. :)

## Questions and Answers

&reporting.bugs;

There is no questions and answers part in the current version of the document.

## Credits and License

&kapp;

Program copyright 2001 - 2006 Andras Mantia amantia@kdewebdev.org

Documentation copyright 2001, 2002, 2005, 2006 Andras Mantia amantia@kdewebdev.org

&underFDL; &underGPL;

## Installation

### How to obtain &kapp;

&kallery; has a homepage at http://kallery.kdewebdev.org. Source tarballs are avaliable from here.

### Requirements

In order to successfully use &kallery;, you need KDE 3.x. If your system can run KDE 3.x, than it can run also &kallery;. The tested version was the KDE 3.5 series, but theoretically 3.0 is enough to run it. Neverthless it is recommended to use the latest KDE for getting the latest bugfixes and new features . The only special requirement is ImageMagick. At least 6.0.0 is required, but I've tested only with 6.3.0. In case of compilation problems switch to ImageMagick 6.3.0 and test again.

I've tested &kapp; on the following platforms:

- SuSE Linux 10.2, KDE 3.5.5, ImageMagick 6.3.0

- Kubuntu 6.10, KDE 3.5.5, ImageMagick 6.3.0

You can find a list of changes at The &kapp; homepage.

### Compilation and Installation

In order to compile and install &kapp; on your system, type the following in the base directory of the &kapp; distribution:

    % make -f Makefile.cvs
    % ./configure
    % make
    % make install

The `make install` step should be usually done as root.

Since &kapp; uses autoconf and automake you should have not trouble compiling it. Should you run into problems please report them at the amantia@kdewebdev.org e-mail address.

### Configuration

Multiple version of ImageMagick can confuse the compilation and linking process, and the application can crash during runtime. Check the result of

Magick-config --ldflags

command and compare the library paths with the result of

ldd kallery

command, if the application crashes during the reading of image files.

Starting from version 0.3.1, if the ./configure script searches for the version of the ImageMagick, and also tries to compile and link a small program, which uses all the ImageMagick functions, that &kapp; uses. If one of this steps fails, than it means, that there's some problem with your ImageMagick installation, or the version is lower than expected.

&documentation.index;