Kallery'> ]> Andras Mantia

amantia@freemail.hu

2001, 2002, 2005 Andras Mantia &FDLNotice; 11/02/2005 1.00.06 &kallery; is a highly configurable image gallery generator wizard. This version of the handbook is valid for Kallery 1.0.7. KDE graphics generator &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 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. 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. Here's a screenshot of &kapp; Screenshot 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. 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 up and down arrow buttons at the left of the image list. 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 Kallery what to do with thumbnails. Your choices are: Generate thumbnails - Kallery 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. Kallery will warn you about this, and won't let you go to the next page. Do not use thumbnails - There will ne 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. 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 arrow 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. You should always set the following: Output gallery file name - put here the filename (including the absolute path) of the target gallery file. Open this file (later) in your browser if you wish to view the generated gallery Fullsize image directory - Kallery will copy here the selected images.It will overwrite every file in this directory if it has the same name as one of the selected images. If you asked Kallery to generate thumbnails, then you must also specify a directory where it will put them. It cannot be the same as the fullsize image directory, because the thumbnails will have the same name as the fullsize images. A good idea is to use relative paths (default option), because by using them you can freely move your generated gallery on your hard drive, and on the Internet. The recommended directory structure for image galleries looks like: Gallery file: .../homepage/gallery.htm Fullsize image directory: .../homepage/fullsize/ Thumbnail directory: .../homepage/thumbnails/ Use relative path is checked. 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.) There is also a quick and dirty method to generate descriptions: use the filename (without extension) as a description. For this select the "Use the filenames as descriptions" option. 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. If Kallery 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. Kallery 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 copited to the fullsize target path and converted to: a new file format (select from the list). Remember that ImageMagick (and Kallery) 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 Kallery. Select the "Insert copyright..." option and enter the copyright text. By selecting the "Do not copy or convert the images" 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. This is automatically selected for a Generated project, because in this case the source files are already in right place and in the right format. 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. 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. It's possible to generate a gallery with frames. In this case the left frame will contain the thumbnails/descriptions, and the fullsize images will appear in the right frame. Check the "Frame on left" box, in order to get this result. It is recommended to set the "Number of columns" to one (1), if you use this feature. After the generation has ended, you will have a "blank.htm" file near your gallery file. This will be displayed as a default page in the right frame, so replace the content with something more useful. :) You should select the "Template when using frames" template to get the desired result. 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 shouldn't 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 Color section, you can select the background color, the color of the thumbnail holding table and the text color. These are valid both for the main gallery and the fullsize image holding htmls, if you don't select a separate CSS file for them. You should generate a html file for each image. If you don't so, then the fullsize image will not have description, you will not have navigation buttons, and the image will not be centered. So please, check the "Use html files 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 and the text 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 don't 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 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 don't like something. If everything's fine, press the Finish button (and read the next section). After you press the Finish button on the last page, Kallery 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, Kallery 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% Kallery will generate the htmls and the main gallery. This part is much faster than the first one. Of course, it's possible to cancel the generation process, if you think it's 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 Kallery and loading the saved project. Before the end, depending of your current project you may see another question about saving: If your project is a new one, or it is an Original (look at the titlebar) Kallery offers you to save another project file (a Generated file) with slightly modified options: the source files will be replaced with the ones where they were copied/converted the thumbnails will be loaded from the recently generated place the image conversion will be disabled by default This file will have the projectFileName_generated.kallery name. The original descriptions file is used, so if you modify the descriptions in one of the project file (Original or Generated), you can see the changes also in the other. This generated project is very useful, if you want to change only some - look and feel - options (eg. the fullsize template, colours, image order, descriptions, etc.) It will be much faster than loading the original saved project and (re)generate a new gallery with the changed options. If your project is a Generated one, it offers to syncronize with the Original project. This means, that all options, but the source image list and image/thumbnail conversion options are copied to the Original project. In this way you can regenerate your project (eg. you want to add new Copyright info, or you want to change the size/format of the images), and still keep the new look and feel options. Sometimes it is desired to save the Generated project under a new name. This may happen, if you use the Generated project to create a new gallery in another language, but with the same images, without reconverting the original image files, and without recreating the thumbnails. In this case simply give another name while saving, and it will automatically become an Original project, and the (new) descriptions will be saved under the newProjectName.descriptions file. In this way you won't lose the original descriptions, as it happened with version 0.3.1. The generation of html files is based on templates. Kallery 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 don't 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; Read forward to see how to make gallery and fullsize templates. 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 description of the image; <!-- 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. :) 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; %IMAGEDESC%: optional, will be replaced with the description of the image; %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; If you are lost, look at the default templates. :) &reporting.bugs; &updating.documentation; There is no questions and answers part in the current version of the document. &kapp; Program copyright 2001 - 2005 Andras Mantia amantia@freemail.hu Documentation copyright 2001, 2002, 2005 Andras Mantia amantia@freemail.hu &underFDL; &underGPL; &kallery; has a homepage at http://kallery.kdewebdev.org. Source tarballs are avaliable from here. 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 only special requirement is ImageMagick. At least 6.0.0 is required, but I've tested only with 6.1.8. I've tested Kallery on the following platforms: SuSE Linux 9.2, KDE 3.3.92, ImageMagick 6.1.8 You can find a list of changes at The Kallery homepage. In order to compile and install Kallery on your system, type the following in the base directory of the Kallery distribution: % make -f Makefile.dist % ./configure % make % make install Since Kallery uses autoconf and automake you should have not trouble compiling it. Should you run into problems please report them at the amantia@freemail.hu e-mail address. 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 Kallery 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;