Galleria

Overview

2023-03-27T00:00:00+02:00

Galleria is a plugin for pelican, a static site generator written in python.

Observe it first in action here: try to resize the window of our web browser and observe the flexible rearrangement of the following images.

Mycenaean Watercolor, from a fresco in Tiryns
Watercolor, also a fresco from Akrotiri
Watercolor, from a fresco from Akrotiri
Watercolor, the Caryatid porch at the Acropolis

The galleria plugin implements a reStructuredText directive for defining galleries in an intuitive way. Observe some real-life application of this plugin: just have a look at the Greuze-Cottave web site or the present author's Pirogh site.

The previous galleria shows four watercolors from 2022 by Pirogh, which is also the author of the present plugin. The original models was three Mycenaean fresco from the ancient Greece done between 1400 and 1200 BC, which could be observed in the archaeological museum in Athens, and the last is a watercolor on the motif that represents the Caryatid porch at the Acropolis.

Try to resize your window browser: observe the flexible rearrangement of the images. This is possible thanks to the flex container feature implemented by the galleria plugin. This is especially useful when displaying on mobile phones. Moreover, this plugin is able to automatically minimize the overall page weight: it save you a trip to gimp each time you include an image in your post. It also makes it easy to create responsive images using the html5 srcset attribute and <picture> tag. It does this by automatically generating multiple derivative images from one or more sources. It is possible efficiently to manage web site with thousands of large images, and each gallery could displays hundred of images: the result will optimize the bandwidth of the connection, depending upon the resolution of the user's display. Finally the thumbnail's image resolution itself is also responsive, in the sense that it takes into account the physical resolution of our window and screen resolution. When you click on a thumbnail of a picture, a full resolution version of this picture is displayed. The galleria will never overwrite your original images.

You're interested? Fascinated? Let's start! First, download and install the plugin:

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/internet/galleria

The galleria directive

2023-02-27T00:00:00+01:00

A "galleria" consists of list of image file names, one per line, followed by a list of options, one per line, and then an optional caption paragraph. There must be blank lines before the caption and target paragraph. Here is an example, corresponding to the illustration of the introduction section:

.. galleria::
  tiryns.jpg
      :caption:  Mycenaean Watercolor, from a fresco in `Tiryns`_
      :target:   https://en.wikipedia.org/wiki/Tiryns
  boxers.jpg
      :caption:  Watercolor, also a fresco from `Akrotiri`_
      :target:   `Akrotiri`_
  swallows.jpg
      :caption:  Watercolor, from a fresco from `Akrotiri`_
  caryatid.jpg
      :caption:  Watercolor, the `Caryatid`_ porch at the `Acropolis`_
      :target:
  :max-height: 350px

Options

The galleria block could contain options.

class name

The name argument is a class name defined in the GALLERIA_PROCESS dictionary variable of the pelicanconf.py file.
flex-wrap value

This option manages the flex-wrap property of the html flexible container used by the galleria directive. The value is one of nowrap, wrap, wrap-reverse. With nowrap, all the image are displayed on one line. The wrap value specifies that the flexible items will wrap if necessary: this is the default value for the galleria directive. With wrap-reverse, the flexible items will wrap, if necessary, but lines of the container appear in reverse order.
max-height length

The maximal height of the image. Used to scale the image vertically. When unspecified, the default value is given by the GALLERIA_DEFAULT_MAX_HEIGHT variable of the pelicanconf.py file.
column-gap length

It defines the value of the column-gap property of the html flexible container used by the galleria directive.

Caption and target paragraph

There must be blank lines before the caption and target paragraph. Each line start either by !caption! or !target!, followed by the file name and a one-line argument. For a target, the argument is considered as a clickable link associated to the image. When there is no target for an image, by default the image is clickable and the link is the full resolution image. Both links and caption could involve links such as `pelican`_, that are solved by the parser as pelican.

In the previous example, for the first image, the target is explicit, for the second one, it involves a solved link for the third one, there is no declared target, and for the last, there is explicitly an empty target. When there is no declared target, the image is automatically clickable and points to the full resolution version of the image: observe that the cursor changed to zoom-in. Conversely, when there is explicitly an empty target, the image is not clickable: observe that the cursor do not change.

The file pelicanconf.py

2023-01-14T00:00:00+01:00

Here is a complete example of the pelicanconf.py file, as used for the present documentation of the theme. It starts by setting some standard pelican variables, as usual. Then, come the theme's and the optional plugins.

# =============================
# 1. standard pelican variables
# =============================
SITEURL      = 'http://galleria.artliba.org'
SITENAME     = 'Galleria'
AUTHOR       = 'Pirogh Hesse'
SITESUBTITLE = 'A responsive pelican gallery plugin'
TIMEZONE     = 'Europe/Paris'
DEFAULT_LANG = 'en'
LOCALE       = 'C'

PATH         = 'content'
STATIC_PATHS = ['images', 'theme']

OUTPUT_PATH  = 'output'

DISPLAY_CATEGORIES_ON_MENU = False # choose a custom top menu here
MENUITEMS = (
  ('About',      'about.html'),
  ('All',        'index.html'),
  ('Overview',   '1a-getting-started.html'),
  ('Directive',  '1b-directive.html'),
  ('Config',     '1c-pelicanconf.html'),
  ('#Tags',      'tags.html'),
)
DEFAULT_PAGINATION =   6; # article summaries per page
SUMMARY_MAX_LENGTH = 100; # counted in words

RELATIVE_URLS                    = True
SLUGIFY_SOURCE                   = 'basename' 
ARTICLE_URL   = ARTICLE_SAVE_AS  = '{slug}.html'
CATEGORY_URL  = CATEGORY_SAVE_AS = '{slug}.html'
TAG_URL       = TAG_SAVE_AS      = '{slug}.html'
AUTHOR_URL    = AUTHOR_SAVE_AS   = '{slug}.html'
ARCHIVES_SAVE_AS                 = 'archives.html'
YEAR_ARCHIVE_SAVE_AS             = 'archive_{date:%Y}.html'
MONTH_ARCHIVE_SAVE_AS            = 'archive_{date:%Y}_{date:%m}.html'
# =============================
# 2. Lepagito theme
# =============================
THEME = '/home/hesse/dvt-perso/lepagito'
#TAGS_BY_GROUPS = (
#  ('Pelican',       ('tag-group', 'navigation', 'plugin', 'pelicanconf.py')),
#)
FOOTERMENUITEMS = (
  ('About',    'about.html'),
  ('License',  'about.html#license-1'),
)
LEPAGITO_NAVIGATION_SWAP = True
# =============================
# 3. plugins
# =============================
PLUGIN_PATHS  = ['/home/hesse/dvt-perso/theme-config/pelican/plugins',
                 '/home/hesse/dvt-perso/galleria/pelican/plugins',
                 '/home/hesse/pelican-plugins/search/pelican/plugins']
PLUGINS = ['theme_config', 'neighbors', 'galleria', 'search']
LEPAGITO_HAVE_SEARCH_MENU = ('search' in PLUGINS) # activate search menu

# =============================
# 4. configuration
# =============================
GALLERIA_LIBRARY_PATH          = ['/home/hesse/dvt-perso/galleria/doc/content']
LEPAGITO_GALLERY_CSS_FILE      = 'galleria.css'
GALLERIA_PROCESS = {
    'image-icon': {
        'type': 'image',
        'ops': ['50x50', '+profile "*"'],
    },
    'image-medium': {
        'type': 'image',
        'ops': ['300x300', '+profile "*"'],
    },
    'crisp': {
        'type': 'responsive-image',
        'srcset': [
            ('1x', [ '300x225', '+profile "*"']),
            ('2x', [ '600x450', '+profile "*"']),
            ('3x', ['1200x900', '+profile "*"']),
        ],
        'default': '1x',
    },
    'responsive-medium': {
        'type': 'responsive-image',
        'sizes': (
            '(min-width: 768px) 650px, '
            '(min-width: 1200px) 800px, '
            '100vw'
        ),
        'srcset': [
            ('600w', ['600x450', '+profile "*"']),
            ('800w', ['800x600', '+profile "*"']),
        ],
        'default': '800w',
    },
    # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture
   'picture-tag': {
       'type': 'picture',
       'sources': [
           {
               'name': 'default',
               'media': '(min-width: 640px)',
               'srcset': [
                   ( '640w', [ '640x480',  '+profile "*"']),
                   ('1024w', ['1024x683',  '+profile "*"']),
                   ('1600w', ['1600x1200', '+profile "*"']),
               ],
               'sizes': '100vw',
           },
           {
               'name': 'source-1',
               'srcset': [
                   ('1x', ['200x200']),
                   ('2x', ['300x300']),
               ]
           },
       ],
       'default': ('default', '640w'),
   },
}
GALLERIA_DEFAULT_CLASS      = 'picture-tag' # should be defined
GALLERIA_DEFAULT_MAX_HEIGHT = '600px'
GALLERIA_ICON_CLASS         = 'image-icon'  # idem
GALLERIA_PROCESS_DIR        = "process"
GALLERIA_RESIZE_JOBS        = 10

Remark in the first that all URLs are chosen as relative here:

RELATIVE_URLS = True
ARTICLE_URL   = ARTICLE_SAVE_AS  = '{slug}.html'
CATEGORY_URL  = CATEGORY_SAVE_AS = '{slug}.html'

Also, all output files (articles, categories, tags, ...) are written in the same "output/" directory, without any hierarchy. This setting is convenient, since it allows to develop and fully test the blog off-line before to upload it on its final destination: relative URLs, such as in the MENUITEMS, work both in off-line and in-line modes.

The second part of the configuration file contains the specific settings of the lepagito theme: see the lepagito documentation for more.

Finally, the third part of the pelicanconf.py file sets the galleria plugin. The GALLERIA_LIBRARY_PATH furnishes a list of directories for searching image files recursively. The THEME_TEMPLATES_OVERRIDES pelican variable indicates where to find the template files such as galleria.html. The LEPAGITO_GALLERY_CSS_FILE furnishes the name of the galleria css file: the lepagito theme will include it. Note that its default value is galleria.css, so this line is optional.

Now comes the most step in configuring this plugin: we have to define the image transformations in the pelicanconf.py file. Transformations are defined in the GALLERIA_PROCESS dictionary, mapping a transformation name to a list of operations. There are three types of transformations: image replacement, responsive image, and picture set.

Image replacement

The simplest image processing will replace the original image by a new, transformed image computed from the original. You may use this, for example, to ensure that all images are of the same size, or to compute an icon or a medium image for an article:

GALLERIA_PROCESS = {
  'image-icon': {
      'type': 'image',
      'ops': ['50x50', '+profile "*"'],
  },
  'image-medium': {
      'type': 'image',
      'ops': ['300x300', '+profile "*"'],
  },
}

Here, we define two classes of transformation, with the labels: image-icon for thumbnails and image-medium for articles. Both have the type image, which is a keyword that means image transformation. Then comes the ops field, which is a list of two elements. The first one is the transformed image size. The transformed image will be obtained from original one by using the gm convert command. The second element of the list is a string containing any options to transmit to the gm convert command. So, any transformation, such as rotating, cropping, ... could be also specified here. The generic gm convert command used here writes:

gm convert -size <wxh> <orig-img> -resize <wxh> <options> <trsf-img>

In the previous GALLERIA_PROCESS example, we use the string +profile "*": this gm convert option removes any ICM, EXIF, IPTC, or other profiles that might be present in the original image and aren't needed in the transformed one. The chosen transformation could be selected by using the :class: optional field of the galleria directive, e.g.:

.. galleria::
   tiryns.jpg
   boxers.jpg
   swallows.jpg
   caryatid.jpg
   :class: image-medium

It gives:

Observe that, when decreasing the window width, the image layout still is dynamically rearranged, but the image size is now fixed: it is maximized so that both width and height are bounded to 300 pixels. Note that the reStructuredText reader will convert underscores (_) to dashes (-) in class names, so to make sure everything runs smoothly, do not use underscores in your transformation names.

Responsive image

Let us increase the sophistication: you can use galleria to automatically generate one time for all a set of images that will be automatically selected for display by browsers according to the viewport width or according to the device resolution. To accomplish this, galleria will add to the html <img> tag both a srcset and style attributes, and optionally sizes attribute.

html5 supports two types of responsive image sets. The first one is device-pixel-ratio-based, selecting higher resolution images for higher resolution devices. The second one is viewport-based, selecting images according to the viewport size. You can read more about html5 responsive images for a gentle introduction to the srcset and <picture> syntaxes.

To tell galleria to generate a responsive image, add a responsive-image transformation to your your GALLERIA_PROCESS dictionary, with the following syntax:

GALLERIA_PROCESS = {
  'crisp': {
      'type': 'responsive-image',
      'srcset': [
          ('1x', ['300x225', '+profile "*"']),
          ('2x', ['600x450', '+profile "*"']),
          ('2x', ['1200x900', '+profile "*"']),
      ],
      'default': '1x',
  },
  'responsive-medium': {
      'type': 'responsive-image',
      'sizes': (
          '(min-width: 768px) 650px, '
          '(min-width: 1200px) 800px, '
          '100vw'
      ),
      'srcset': [
          ('600w', ['600x450', '+profile "*"']),
          ('800w', ['800x600', '+profile "*"']),
      ],
      'default': '800w',
  },
}

Device-based responsive image

The crisp transformation is an example of a transformation enabling device-pixel-ratio-based selection. The srcset is a list of tuples, each tuple containing the image description ('1x', '2x', etc.) and the list of operations to generate the derivative image from the original image. The original image is the value of the src attribute of the <img>. Image descriptions are hints about the resolution of the associated image and must have the suffix x. The default setting specifies the image to use to replace the src attribute of the image. This is the image that will be displayed by browsers that do not support the srcset syntax.

In the two examples above, the default setting is a string referring to one of the images in the srcset. However, the default value could also be a list of operations to generate a different derivative image.

Let us modify the :class: optional field of the galleria directive:

.. galleria::
   tiryns.jpg
   boxers.jpg
   swallows.jpg
   caryatid.jpg
   :class: crisp

We obtain:

Viewport-based responsive image

The responsive-medium transformation is an example of a transformation enabling viewport-based selection. The sizes contains a rule to compute the width of the displayed image from the width of the viewport. Once the browser knows the image width, it will select an image source from the srcset. The srcset is a list of tuple, each tuple containing the image description ('600w', '800w', etc.) and the list of operations to generate the derivative image from the original image. The original image is the value of the src attribute of the <img>. Image descriptions are hints about the width in pixels of the associated image and must have the suffix w. The default setting specifies the image to use to replace the src attribute of the image by a pre-computed one.

Let us modify again the :class: optional field of the galleria directive:

.. galleria::
   tiryns.jpg
   boxers.jpg
   swallows.jpg
   caryatid.jpg
   :class: responsive-medium

We obtain:

Observe that, when decreasing the window width, both the image layout and the image resolution are adapted dynamically.

Picture set

Galleria can be used to generate the images used by a <picture> tag. The <picture> syntax allows for more flexibility in providing a choice of image to the browser. Again, you can read more about the picture tag for a gentle introduction to the srcset and <picture> syntaxes.

To tell galleria to generate the images for a <picture>, add a picture entry to your GALLERIA_PROCESS dictionary with the following syntax:

GALLERIA_PROCESS = {
  'picture-tag': {
     'type': 'picture',
     'sources': [
         {
             'name': 'default',
             'media': '(min-width: 640px)',
             'srcset': [
                 ( '640w', [ '640x480',  '+profile "*"']),
                 ('1024w', ['1024x683',  '+profile "*"']),
                 ('1600w', ['1600x1200', '+profile "*"']),
             ],
             'sizes': '100vw',
         },
         {
             'name': 'source-1',
             'srcset': [
                 ('1x', ['200x200']),
                 ('2x', ['300x300']),
             ]
         },
     ],
     'default': ('default', '640w'),
  },
}

Each of the sources entries is very similar to the responsive-image describe above. Here, each source must have a name, which will be used to find the url of the original image for this source in your article. The source may also have a media, which contains a rule used by the browser to select the active source. The default setting specifies the image to use to replace the src attribute of the <img> inside the <picture>. This is the image that will be displayed by browsers that do not support the <picture> syntax. In this example, it will use the image 640w from the source default. A list of operations could have been specified instead of 640w.

Let us modify again the :class: optional field of the galleria directive:

.. galleria::
   tiryns.jpg
   boxers.jpg
   swallows.jpg
   caryatid.jpg
   :class: picture-tag

and we obtain the illustration presented at the beginning of the introduction section.

Additional settings

When no class is specified in a galleria directive, a class defined in the GALLERIA_PROCESS dictionary is used by default: this user-defined default class should be specified in the GALLERIA_DEFAULT_CLASS variable of the pelicanconf.py file.

The galleria directive has a max-height option. When this option is not specified, the default value is provided by the GALLERIA_DEFAULT_MAX_HEIGHT variable.

Pelican pages and article could provide an :image: in the meta-data section. Themes such as lepagito use this image to automatically produce an icon associated to this page or article, and this icon is then used in the archive section. This icon is automatically generated from an original image by specifying its class in the GALLERIA_ICON_CLASS variable.

By default, the new images will be stored in a directory named output/process/<class-name> in the output folder. All the transformations are written in the output directory in order to avoid confusion with the source files or if we test multiple transformations. You can replace the directory name process by something else using the GALLERIA_PROCESS_DIR variable.

Galleria is able to efficiently process all the image transformation in parallel: use the GALLERIA_RESIZE_JOBS variable to do that. Its default value is 1 and then no parallel computations are done. Setting it to 0 means that the number of parallel process is determined automatically, depending on your computer. Also, you could fix it directly, e.g. to 10.