HTML Gallery ¶

Panoramica ¶

The HTML Gallery is a tool for exporting a set of albums or images to an HTML page.

This powerful tool can export your albums into an HTML-compliant web image gallery. You can easily select the images or the albums to export in an HTML page and set many designs and parameters for the HTML rendering. UTF-8 encoding is used for the best internationalization.

Usare la procedura guidata ¶

La modalità di selezione della Galleria HTML¶

To launch the tool, uses Tools ‣ Create Html gallery Ctrl+Alt+Shift+H menu entry, or the corresponding icon from the Tools tab in Right Sidebar. The tool will display a view to select the contents to export, either from current items selection, or from a list of albums. The Albums selection mode allows you to select items from albums that you want to export to HTML. Just check the respective albums from the hierarchical nested list. You can use the next three tabs Tags, Searches, and Labels to refine your selection based on tags, labels, or previous search results in digiKam.

La pagina della Galleria HTML per selezionare gli elementi¶

The next step is to select a Theme to generate the gallery.

La pagina della Galleria HTML per selezionare il tema¶

A seconda del tema scelto, potrebbero comparire ulteriori opzioni per regolare in modo preciso l’aspetto della galleria.

La schermata che segue mostra la configurazione dei parametri del tema (in questo caso, per esempio, il tema Classico).

La pagina della Galleria HTML per regolare i parametri del tema¶

Per tutti i temi selezionati è possibile regolare le impostazioni per le immagini e le miniature della galleria.

La pagina della Galleria HTML per regolare le proprietà delle immagini e delle miniature¶

In the Full Image Properties section you can either Save modified images or Use original image.

For modified images you can select as output format JPEG (smallest file-size, but lossy) and PNG (lossless and license free) and set specific image compression features. If disk space is of concern, check the target image compression and lower the compression level from the host application default value.

Checking the Max. size box you can fix the maximum target image size (in pixels) with the spin-box at the right. Images bigger than this value will be scaled down, but smaller images will not be modified.

Nota

Se, per ridimensionare le immagini da generare, viene selezionato il formato di file JPEG, tutte le informazioni Exif verranno mantenute dai file JPEG originali.

The Thumbnail Properties section allows you to set the Format, Quality and Size for the thumbnails in the gallery.

La pagina della Galleria HTML per configurare il risultato¶

This page defines the settings of where and how to store the gallery with all its associated images. Select a folder or add a new folder with write access where you want the gallery to be written. Two sub-folders with the name of your album folder and the theme name will be created containing everything.

A progress dialog is displayed to provide feedback to the user. Press the Cancel button if you want to abort the process during this stage.

La pagina della Galleria HTML che mostra l’avanzamento della generazione della galleria¶

Infine, la galleria HTML generata verrà visualizzata in un a browser.

Il browser che visualizza la galleria HTML finale¶

Creare di un nuovo tema ¶

The HTML Gallery tool can easily produce very different sites based on themes. This section explains how to create a new theme.

Primi passi ¶

Un tema è una cartella che contiene almeno due file:

A Desktop File describing the theme.

un file template.xsl per generare i file HTML

Quando lo strumento è in esecuzione, esegue le operazioni seguenti:

Creates an output folder.

per ciascuna raccolta di immagini:

Creates a folder.

Generates thumbnails (square by default).

Generates full images.

Optionally copies original images.

Copies the theme folder to the output folder.

Generates an XML file describing the image collections: gallery.xml.

Generates the HTML files by applying template.xsl to gallery.xml.

Il file Desktop ¶

Il file desktop descrive il tema. Le informazioni che contiene vengono utilizzate nella pagina di selezione del tema dello strumento.

È un file INI e assomiglia a questo:

[Desktop Entry]
Type=Theme
Name=Hello World
Comment=A demonstration theme

[X-HTMLGallery Author]
Name=The Author
Url=http://example.com/themes/helloworld

[X-HTMLGallery Preview]
Name=Preview's Caption
Url=preview.png

Per facilitare le traduzioni delle voci viene utilizzato un formato di file desktop. Se guardi un file desktop di uno dei temi distribuiti con lo strumento, osserverai qualcosa di simile a questo:

[Desktop Entry]
Name=Simple
Name[br]=Eeun
Name[cs]=Jednoduchý
Name[cy]=Syml
Name[da]=Simpel
...

The nice thing is that when your theme gets integrated into the HTML Gallery default themes, translators will internationalize the desktop file for you.

The image preview file used to illustrate the theme in the wizard will be placed in the root theme folder.

Creating a new Theme from Another One ¶

The easiest way to get started is to copy one theme and modify it. Folders can be found usually under Linux at /usr/share/apps/digikam/themes/. Writing in this folder requires root access, so we will not create our theme there - instead do the following from a console:

Creazione di una cartella del tema nella tua cartella home:

mkdir -p ~/.local/share/digikam/themes/

Vai alla cartella:

cd ~/.local/share/digikam/themes/

Copia il tema snow in questa cartella, con il nuovo nome snow2:

cp -r /usr/share/apps/digikam/themes/snow snow2

Rinomina di conseguenza il file desktop:

cd snow2
mv snow.desktop snow2.desktop

Modifica snow2.desktop per rimuovere tutte le voci Name[…] e sostituire Name=Snow con Name=Snow 2.

Finito, puoi aprire digiKam e avviare lo strumento Galleria HTML: il tema Snow 2 sarà visualizzato nell’elenco dei temi.

Generare codice HTML utilizzando le regole XSL ¶

Il file template.xsl è responsabile della generazione dei file HTML a partire dal file gallery.xml. È un file in stile ini standard e assomiglia a questo:

<?xml version="1.0" encoding="UTF-8"?>
<collections>
 <collection>
  <name>Name of first collection</name>
  <fileName>collection_folder</fileName>
  <comment>Collection comment</comment>
  <image>
   <title>Image Title</title>
   <description>Image Description</description>
   <date>2009-08-27T09:53:26</date>
   <full fileName="pict1279.jpeg" height="450" width="600"/>
   <thumbnail fileName="thumb_pict1279.jpeg" height="80" width="80"/>
   <!-- If there is an original image, you will get the 'original' tag -->
   <original fileName="original_pict1279.jpeg" height="3000" width="4000"/>

  </image>
  <image>
   <title>Image Title</title>
   <date>2009-08-27T09:55:33</date>
   <description>Image Description</description>
   <full fileName="pict1280.jpeg" height="450" width="600"/>
   <thumbnail fileName="thumb_pict1280.jpeg" height="80" width="80"/>
   <original fileName="original_pict1279.jpeg" height="3000" width="4000"/>
  </image>
  ...
 </collection>

 <collection>
  <name>Name of second collection</name>
  ...
 </collection>
</collections>

We won’t explain XSLT syntax here, you should be able to find the documentation you need on the Internet. We recommend the XSLT tutorial here for learning XSLT.

Nevertheless, it’s worth noting that you can make use of EXSLT, a set of extensions to XSLT. In particular, the exslt:document element is extremely useful because it allows you to generate multiple documents from the same file.

HTML Gallery tool imposes no constraint on the organization of HTML files. You can generate one file per image, or only one per collection. One could imagine a theme which would only contains one HTML file and uses JavaScript to show the different images. There is already one theme using frames. You can even generate CSS files on the fly if you want to.

Informazioni sulle traduzioni ¶

You should not hardcode any text in the template, but you should instead use the i18n parameters. For example instead of using this:

<a href="previous">Previous</a>
| <a href="next">Next</a>

Fai questo:

<a href="previous"><xsl:value-of select="$i18nPrevious"/></a>
| <a href="next"><xsl:value-of select="$i18nNext"/></a>

It’s a lot more verbose, but this way your user will get localized HTML output.

Se vuoi utilizzare i parametri i18n negli attributi, fai questo:

<a href="previous" title="{$i18nPrevious}"><img src="previous.png"/></a>
| <a href="next" title="{$i18nNext}"><img src="next.png"/></a>

Attualmente, i parametri i18n generali disponibili sono:

i18nPrevious

i18nNext

i18nCollectionList

i18nOriginalImage

i18nUp

And the image properties are:

i18nexifimagemake («Produttore»)

i18nexifimagemodel («Modello»)

i18nexifimageorientation («Orientazione dell’immagine»)

i18nexifimagexresolution («Risoluzione X dell’immagine»)

i18nexifimageyresolution («Risoluzione Y dell’immagine»)

i18nexifimageresolutionunit («Unità di risoluzione dell’immagine»)

i18nexifimagedatetime («Data e ora dell’immagine»)

i18nexifimageycbcrpositioning («Posizionamento YCBCR»)

i18nexifphotoexposuretime («Tempo di esposizione»)

i18nexifphotofnumber («Numero F»)

i18nexifphotoexposureprogram («Indice di esposizione»)

i18nexifphotoisospeedratings («velocità ISO»)

i18nexifphotoshutterspeedvalue («Valore di velocità dell’otturatore»)

i18nexifphotoaperturevalue («Diaframma»)

i18nexifphotofocallength («Lunghezza focale»)

If you need more i18n parameters, please submit a request to the Project Team.

Immagini e file CSS ¶

You are free to use images, CSS files or other files in your theme. Just put them in the theme folder and the tool will copy them into the output folder.

Immagini originali ¶

Come spiegato in precedenza, se l’utente seleziona l’opzione Includi le immagini originali, il file gallery.xml conterrà i tag <original />. Se è presente questo tag, la pagina dell’immagine conterrà un collegamento per scaricare l’immagine originale.

Ecco un esempio:

<xsl:if test="original/@fileName != ''">
      <p>
           <a href="{original/@fileName}"><xsl:value-of select="$i18nOriginalImage"/></a>
      </p>
 </xsl:if>

Miniature non quadrate ¶

Per impostazione predefinita, le miniature vengono ritagliate in modo da apparire quadrate e di dimensione identica. Ciò semplifica la creazione dello stile HTML/CSS. Tuttavia, se il tuo tema è pronto per gestire miniature di dimensioni diverse, aggiungi questo pezzo di codice al tuo file desktop:

[X-HTMLGallery Options]
Allow-non-square-thumbnails=true

L’utente potrà così selezionare se i quadrati non debbano essere quadrati. Per le miniature non quadrate, la dimensione specificata è ricavata da quella del lato più grande della miniatura.

Parametri del tema ¶

Nel caso volessi fornire all’utente un modo per personalizzare il tuo tema, potresti offrire, per esempio, alcuni file CSS alternativi, oppure permettere all’utente di personalizzare il colore di sfondo. facile da eseguire.

Dichiarare un parametro ¶

Per prima cosa, devi dichiarare il parametro. Modifica il file desktop e aggiungi qualcosa tipo questa:

[X-HTMLGallery Parameter bgColor]
Name=Background Color
Type=color
Default=#123456

Ora avvia lo strumento e seleziona il tuo tema, dopo aver premuto il pulsante Successivo, dovresti vedere un’opzione con un pulsante del colore inizializzato al colore #123456.

Usare il valore del parametro ¶

In template.xsl, puoi ottenere il valore del tuo parametro così:

<xsl:value-of select="$bgColor"/>

Per cambiare il colore di sfondo del tag body, dovresti scrivere qualcosa tipo questo:

<body bgcolor="{$bgColor}">
...
</body>

Riferimento del parametro ¶

Di seguito una descrizione più dettagliata per dichiarare i parametri. Un parametro viene dichiarato da una sezione chiamata X-HTMLGallery Parameter Un_Nome. Un_Nome va sostituito col nome che vuoi utilizzare nel file template.xsl.

La chiave Name definisce il testo che verrà mostrato nella pagina delle opzioni. Dato che è un file desktop, può essere tradotto come le altre chiavi.
La chiave Type definisce il tipo di parametro. Attualmente può essere:
- caption
- string
- color
- list
- int
La chiave Default definisce il valore predefinito del parametro.

Chiavi del parametro List ¶

Un parametro di elenco permette all’utente di selezionare un elemento da un elenco. Per dichiarare gli elementi disponibili, devi utilizzare due gruppi di chiavi: Value-N e Caption-N, dove N è la posizione dell’elemento, che inizia da 0.

Value-N è il valore interno dell’elemento. È il valore che sarà impostato nel parametro.

Caption-N è il valore visualizzato dell’elemento. È il testo che verrà mostrato nell’elenco.

Ecco un esempio: il parametro stile dal tema Simple:

[X-HTMLGallery Parameter style]
Name=Style
Type=list
Default=natural.css
Value-0=natural.css
Caption-0=Natural
Value-1=dark.css
Caption-1=Dark

Come puoi osservare, l’utente potrà scegliere o Natural o Dark. A seconda della scelta dell’utente, il valore <xsl:value-of select=”$style”/> si estenderà al file natural.css o dark.css.

Chiavi del parametro Int ¶

Un parametro int permette all’utente di selezionare un valore intero utilizzando una casella numerica. In aggiunta al valore predefinito, puoi definire il valore massimo e minimo, utilizzando le chiavi Min e Max.

Ecco un esempio:

[X-HTMLGallery Parameter size]
Name=Size
Type=int
Default=12
Min=4
Max=28

Chiavi del parametro String e Caption ¶

Un parametro string permette all’utente di digitare una stringa singola per impostare, per esempio, delle regole di configurazione. Un parametro caption permette all’utente di digitare una stringa a più righe con supporto di correzione ortografica per impostare una Descrizione o un Titolo.

Considerazioni finali ¶

This is the end of this chapter, so now is the time for you to get creative and start adding new themes.

When you are done, do not hesitate to submit your work for official integration in digiKam. Think of how proud you will be to see your new theme included in the official list. See the Contribute page from the digiKam project web-site for details.