This tutorial introduces you to writing your own themes for your HTML image exports from digiKam. Learn which components needed to theme HTML galleries in digiKam and to change the existing ones or create new ones. To create your own digiKam HTML theme, you need at least basic knowledge of HTML, XML, XSLT and CSS.
Everything you need to tweak the look and feel of digiKam's HTML
galleries can be found under the
/opt/kde3/hare/apps/kipiplugin_htmlexport/themes/
directory:theme_name
*.png
If your theme should contain graphical navigational elements like back and next icons, add these as PNG files.
template.xsl
digiKam exports all relevant information on the images of your
gallery using an XML file called gallery.xml
. This
XML file contains image file names, an optional description and the file
names for both the full size image and the preview thumbnail for each
image in your album. Using the XSL stylesheet, this information is
embedded in the HTML gallery pages.
style.css
The style to be applied to the HTML pages in your gallery.
theme
.desktop
Add minimal information on your new theme to this file, so this information is displayed in the digiKam gallery export dialog.
Avoid ending up submerged in heaps of CSS, XSL and HTML code and loosing focus of what you originally wanted to do by carefully planning the scope of your work:
You like the layout of the standard HTML pages, but want to apply different coloring? See the section called “Creating Your Own CSS” for details on some tweaks for CSS.
In this case, you are facing quite some work on the XSL side and
need to edit the template.xsl
file. Either start
from an existing stylesheet or start from scratch. For some examples,
see the section called “Adjusting the XSL Stylesheet”.
In addition to changing layout and structural aspects you can also choose to add your own icons to the layout. Create them using vector graphics editors like Inkscape and modify the HTML page structure via XSL to include the new graphics. See the section called “Creating Your Own Icon Set” for some more detail on icon editing and for an example.
For the sake of keeping this tutorial as simple as possible and avoiding to write an entire book on this topic, let us just assume you set out modifying an existing theme to match your taste and preference. Starting from scratch requires quite some knowledge of the languages involved and may be overkill for most of us.
Before you set out to create your own styles, decide on which level you want to apply the final result. You can either apply your new theme globally and make it available to all users of your system or you can apply the changes locally and just use them yourself.
If you want to apply the new theme globally, create a new directory in
/opt/kde3/share/apps/kipiplugin_htmlexport/themes/
that is named after your new theme and owned by root
with read, write
and execute permissions for root
and read and execute permissions for
all other users. Copy all the files listed in the section called “Important Files and Directories” into this directory and make set read and
write permissions for root
and read-only permissions for the rest of
the world.
If you want to apply the new theme locally and for your own personal
use only, create a
kipiplugin_htmlexport/themes/
folder under the mytheme
~/.kde/share/apps
directory and copy
all the files listed in the section called “Important Files and Directories” there. The
following examples are all based on a theme that is derived from
digiKam's default “Snow” theme. So you would copy the the
/opt/kde2/share/apps/kipiplugin_htmlexport/themes/snow
directory to your local KDE directory and rename it:
cp -a /opt/kde3/share/apps/kipiplugin_htmlexport/themes/snow \ ~/.kde/share/apps/kipiplugin_htmlexport/themes/ mv snow mytheme
You can always make your local changes available to the other users of your
system by copying your changes over to the system wide configuration
directory under
/opt/kde3/share/apps/kipiplugins_htmlexport/themes
. Of
course, you can also submit your theme to the digiKam developers via
e-mail or http://bugs.kde.org.
In order for digiKam to find and properly reference your theme in
the gallery creation dialog, make sure that the new theme directory
contains a .desktop
file with at least the following
content:
[Desktop Entry] Name=mytheme Comment=Tux's first self-made theme for digiKam [X-HTMLExport Author] Name=Tux Linux Url=mailto:tux@example.org
The desktop file's name should match the theme's name. So, for the
mytheme
theme, you should create a desktop file called
mytheme.desktop
. The content of the
Name
entry determines the name of your theme in the
theme selection dialog.
![]() | Tip |
---|---|
If you want to provide localized strings with your
Comment=Tux's first self-made theme for digiKam Comment[de]=Tux' erstes selbstgemachtes digiKam Theme |
Before you start editing the CSS associated with your theme, determine what exactly you want to achieve by analyzing the theme from which you intend to start:
![]() | Using Little Helpers for Web Designers |
---|---|
Firefox comes with several little extensions that are just perfect for anyone doing web design. If using Firefox, make sure you install the Web Developer Toolbar and Firebug extensions. |
At first glance, there are several elements to the design that can easily be changed to match your taste:
Do you need additional elements in the HTML source that you want to apply style to? See the section called “Creating Frames and Borders”.
Do you want to have all exported collections listed in a bullet list and possibly end up having to scroll for the collection of your choice? See the section called “Editing List Styles”.
Do you like the coloring? See the section called “Editing Font, Background and Color Style”.
Do you like the font and font size? See the section called “Editing Font, Background and Color Style”.
Do you like the use of icons? Do you want to keep a layout with icons or do you want to go for an entirely text-based layout? See the section called “Adjusting the XSL Stylesheet” for the necessary adjustments to the XSL stylesheet or see the section called “Creating Your Own Icon Set” for a short introduction to icon design.
Do you want to use a background graphic for your collection? See the section called “Editing Font, Background and Color Style”.
![]() | Disclaimer: Browser Compatibility |
---|---|
Please do not expect the following example to be entirely compatible to all Web browsers in the market. It has been tested against Firefox, Konqueror and Opera, but it may have serious flaws when viewed in other browsers. |
CSS can only apply style to already existing elements in the HTML source. Just developing a style without having any HTML structure to anchor it to does not work. So check your HTML first, before you dig into CSS code. You might, for example, want to add a little frame around all images both thumbnails and full-size images.
The HTML code related to thumbnails looks like the following example:
<div id="content">
<ul>
<li><a href="..."><img src="..." width="120" height="..."><br>Barden</a></li>
...
</ul>
</div>
Anchoring CSS code for a nice frame around your image is made possible
by the div id="content"
element. All that is required,
is to add a little more padding around the contents of the
li
element, add space between the items
(margin
), and select a color for the frames. If you want
additional borders around the frames, specify them as well:
#content li { background-color: #B0C4DE; float: left; text-align: center; margin: 10px; padding: 15px; border: #ffffff solid 1px; }
The HTML code related to the full-size view of your images looks
similar to the one of the thumbnail view looks similar to the one for
thumbnails. One div
element holds a list with just one
item holding the image. Unfortunately, the use of div
elements to hold the single image, does not allow us to align the image in
the center of the page and have a frame similar to the thumbnail page
around the images. You have to change create a workaround in the HTML code
to allow the image and its frame to be aligned in the center of the
page. To change the HTML, you need to modify the
template.xsl
stylesheet. The final HTML code could
look like the following:
table.myimage { margin-top: 60px; margin-left: auto; margin-right: auto; margin-bottom: 100px; background-color: #B0C4DE; padding: 10px; border: #ffffff solid 1px; } table.myimage td { text-align: center; }
For the necessary modifications to the XSL stylesheet, refer to the section called “Adjusting the XSL Stylesheet”. It basically boils down to using a table
instead of a div and a list environment and aligning the table cells to the
page center. Using a class
attribute with the table
allows you to anchor the CSS to this specific type of table.
Changing the representation of the collection items to a non-bulleted one that does not require scrolling is a very straightforward CSS edit:
/* Collection page */
#content ul {
list-style: none;
}
#collectionPage li {
display: block;
float: left;
text-align: center;
margin: 6px;
}
Adding the list-style: none
option removes the
bullets from all list items and allows them to be aligned horizontally.
New items are always added horizontally. If you resize your browser window
the layout is adjusted so that you can still view all items without any
need of horizontal scrolling.
Font, background and coloring issues are topics that are highly controversial and highly dependant on ones own personal taste. Therefore, you will not find any real recommendations here and are very much on your own. But it is good to keep a few things in mind before going for a particular style:
Coloring and fonts need to support your images and not distract the viewer's interest from the original purpose which is just presenting images. So an intricate work of art in the background of your photo collection page would probably add more to the viewer's distraction than to his viewing pleasure. Your actual images could end up playing second fiddle to the background image. The same applies to your choice of fonts and colors.
Keep your choice of colors simple enough to not distract the viewer from your images and choose colors that would blend harmonically with most type of images. For example, picking a color as fuchsia as your main style element when you are about to present your grandest shots of Ayers Rock or Bryce Canyon might not be a good idea, because the colors clash with each other. On the other hand avoid having your layout look too bleak.
When you have found a color that you like and that complements your design, make a list of elements which need coloring. Getting a good idea of a background color is one thing, but getting matching link colors, font colors, frames, borders etc. is another.
Remember to reflect your choice of color in any icons you use to make sure they match the overall design concept. Maintain your images in SVG format to be able to easily change the color scheme. Export to bitmap once you have the final version. See the section called “Creating Your Own Icon Set” for details on icon creation.
A Wikipedia page on the use of colors in HTML. Although you do not need to restrict yourself to “web-safe” colors anymore and can use pretty much any color you want to, this page helps you in picking the colors you want and in retrieving their exact names and color codes.
A collection of very helpful tutorials introducing you to Inkscape and to icon design in particular.
A terrific tutorial on designing simple icons—highly recommended.