News Examples Documentation Download Buy Forum Contact



XML Extensions


Third Party Software
for krpano

Responsive Scrollable Grid Photo Gallery rsgp_gallery.xml for HTML5 & Flash
by Maël Bathfield -


A photo gallery to smartly show 'classic' photographies.

The idea that led to the conception of this Responsive Scrollable Grid Photo Gallery (RSGP Gallery) was to go over the classical "thumbnails + one-photo display" layout.
At the opening of the gallery, all images are arranged in a responsive grid (with a minimum of 3 columns), and then a click on a picture changes the gallery into a one column scrollable layout displaying enlarged images. At any time, clicking again on an enlarged image permits to go back to the initial grid gallery.


  • Can handle any size and ratio of source images (automatic downscaling).
    The images are never upscaled.
  • Dual source images : possibility to use smaller images for mobile devices and larger images for nice display on large desktop screen.
    • Images for mobile must have the suffix '_s' (i.e. if url is 'img/myimage.jpg', a smaller image named 'myimage_s.jpg' must be in the same 'img' folder).
    • Automatic check for existence of smaller images.
    • If they do not exist, source images cannot be too large/heavy for avoiding memory overcharge on somes mobile devices.
  • Preloading process of images with loading progress bar for each gallery.
  • Various orientation pictures can be used in a same gallery.
  • Easy integration in virtual tour (see section 'Syntax / XML Usage Example' above).
  • Choice for the arrangement of grid gallery : fixed number of columns or fixed width for images.
  • Responsive layout : in 'fixed width' mode, if it is not possible to display at least 3 columns, it's switch automatically in 'fixed number of columns' mode (with 3 columns).
    In 'fixed number of columns' mode, the number of columns is automatically decreased by 2 unit on mobile devices.
  • Max. 999 images per gallery; Max. 99 galleries per pano/scene.
  • Independant parameters for each gallery : arrangement mode in the grid gallery, background color, size and color of images boder, display or not of various titles.
  • Double image title management (short_title/second_title).
  • Helping messages (displayed once).
  • Integrated slideshow function (automatic scrolling).
  • Minimal design option for more space to display enlarged images.
  • Testing Comboboxes: change the arrangement of the images before choosing your prefered parameters.
    [After changing the displaying mode (with the left combobox), confirm change by selecting a new value with the right combobox (displaying 'Row number' or 'Max image width')]


Initial grid gallery with landscape photos in 5 columns.

Enlarged image in the one column scrollable layout.

Initial grid gallery with portrait photos in 5 columns.

Initial grid gallery with various images ratios in 6 columns (minimal_design="true").


  • The plugin price is €40
  • The zip-archive 1 includes the ready-to-use simple example (including reduced images) and off-line documentation (~ 1 Mo).
  • The zip-archive 2 includes a more complex full example (including reduced images), and off-line documentation (~ 2.4 Mo).

After payment, I will send the 2 archive files (with a link to download 17.6 Mo of full-size images from the on-line complex example) to your e-mail within 24 hours.

Plugin Installation

  • Simply copy all the files included in the 'plugins' folder of the simple example into the 'plugins' folder of your tour.
  • Among these files, there are the following free plugins from krpano-1.19-pr14: scrollarea.js/.swf, showtext.xml, combobox.xml.
  • There is also the free plugin coded by Jordi Vallverdú (version of February 13th 2018): file_exist.xml
  • Take care to do not overwrite these files if you have some more recent ones in your 'plugins' folder.

Syntax / XML Usage

First, include the files plugin for the RSGP_gallery:
<include url="%SWFPATH%/plugins/rsgp_gallery.xml"/>   
<include url="%SWFPATH%/plugins/rsgp_gallery_style.xml"/> 

Optionally, add some global settings, change and/or translate them:
<gallery_settings slideshow_time="4"  />
<gallery_settings display_combobox="true"  /> 
<gallery_settings help_message1="Click on an image to enlarge it"
                  help_message2="Sweep screen up/down to change image"
                  help_message3="Click again on images to come back to gallery"
                  loading_text="Loading images..."
                  slideshow_text="Play / Stop Slideshow"/>  

Then, create a button to open the gallery by assigning the atttribute style 'gallery_button_style' and the atttribute galleryname 'galleryX' to a LAYER, e.g.:
<layer name="gallery_button1" url="gallery_icon.png"
    style="gallery_button_style|custom_style"  galleryname="gallery1" />  

or to a HOTSPOT, e.g.:
<hotspot name="gallery_hotspot1" url="gallery_icon.png"
    style="gallery_button_style|custom_style" galleryname="gallery1" />  

Finally, add the gallery data (attribute values of the simple example, see below):
<gallery name="gallery1"

         ratio="square" mode="fixedrow"
         maxlength="300" column_nbr="5"
         title="Animals photos"
         bgcolor="0x00000" border_size="1" border_color="0xFFFFFF"
         display_title="true" display_image_title="both" display_preload="true"
         minimal_design="false" display_slideshow="true" >  

<img name="img1" url="img/A1.jpg" short_title="Horse" second_title="Photo by..." />
<img name="img2" url="img/A2.jpg" short_title="Squirrel" second_title="Photo by..." />
<img name="img3" url="img/A3.jpg" short_title="Fox" second_title="Photo by..." />
<img name="img4" url="img/A4.jpg" short_title="Turtle" second_title="Photo by..." />

or with minimal attributes to have the default layout:
<gallery name="gallery1"

<img name="img1" url="img/A1.jpg"/>
<img name="img2" url="img/A2.jpg"/>
<img name="img3" url="img/A3.jpg"/>
<img name="img4" url="img/A4.jpg"/>

Plugin Attributes

Most of the plugin attributes are optional, but they allow a quite advanced customization for the final layout of the galleries.

GLOBAL ATTRIBUTES for galleries:
  • gallery_settings.slideshow_time
    • Timer in second for the slideshow function.
    • Default value = 4 sec.
  • gallery_settings.display_combobox  (optional)
    • true : display the Testing Comboboxes that allow to change gallery displaying mode and row number/maxlength.
    • Default = false
    • After changing the displaying mode (with the left combobox), confirm change by selecting a new value with the right combobox (displaying 'Row number' or 'Max image width').
    • The Testing Comboboxes are never display on mobile devices.
  • gallery_settings.help_messageX  (optional)
    • 3 instruction messages for shortly explaining the interface, they are displayed only once.
    • Change and/or translate them as you want (default messages in rsgp_gallery_style.xml).
    • Leave attributes empty for no display.
  • gallery_settings.loading_text  (optional)
    • Text displayed on the gallery button when loading the images of the corresponding gallery.
    • Change and/or translate it as you want (default message in rsgp_gallery_style.xml).
    • Leave attribute empty for no display.
  • gallery_settings.slideshow_text  (optional)
    • Text displayed when mouse is onhover the slideshow button.
    • Change and/or translate it as you want (default message in rsgp_gallery_style.xml).
    • Leave attribute empty for no display.

SPECIFIC ATTRIBUTES for each gallery:
    • IMPORTANT : name of gallery must be 'galleryX' , X being a increasing number.
    • For virtual tour, THE FIRST NUMBER MUST BE 1 within each scene.
  • gallery.ratio  (optional)
    • Fix the aspect ratio width/height of the rectangle of the grid, that influence empty space between images: using the adequate ratio according to images ratio limits empty spaces, that allows to display more images at the same time.
    • Possible value = panoramic / landscape / portrait / verticalpano / square.
    • panoramic: ratio = 2, suitable for a gallery of panoramic images.
    • landscape: ratio = 1.6, suitable for a gallery of images in landscape orientation.
    • portrait: ratio = 0.75, suitable for a gallery of images in portrait orientation.
    • verticalpano: ratio = 0.5, suitable for a gallery of vertical panoramic images.
    • square: ratio = 1, suitable for a gallery of square images or for various orientation / ratio.
    • Default = square
  • gallery.mode  (optional)
    • fixedlength: use the attribute maxlength to build the grid.
    • Note: with mode="fixedlength", if it is not possible to display at least 3 columns, it's switch automatically in mode="fixedrow" (with column_nbr="3").
    • fixedrow: use the attribute column_nbr to build the grid.
    • Default = fixedrow
  • gallery.maxlength  (almost optional)
    • Maximun width in pixels for images in the grid gallery. If this value is greater than source image width, the latter is chosen.
    • Required attribute if mode="fixedlength".
    • Skipped if mode="fixedrow".
  • gallery.column_nbr  (optional)
    • Fixed number of columns in the grid gallery for desktop/tablet devices, minimum value is 3.
    • This number is automatically decreased by 2 unit on mobile devices.
    • Default value = 5.
    • Skipped if mode="fixedlength".
  • gallery.title  (optional)
    • Gallery title displayed when mouse is onhover the corresponding gallery button.
    • Also displayed on the left top of the gallery if display_title="true" and minimal_design="false".
  • gallery.bgcolor  (optional)
    • Background color of the gallery.
    • Default = 0x000000 (black)
  • gallery.border_size  (optional)
    • Size in pixels of the border of the images.
    • Max value is 10 pixels; min value is 0.
    • Default = 0 (i.e. no border)
  • gallery.border_color  (optional)
    • Color of the border of the images.
    • Default = 0x000000 (black)
  • gallery.display_title  (optional)
    • true : display title of the gallery on the left top of the gallery when opened.
    • Attribute skipped if minimal_design="true".
    • Default = false
  • gallery.display_image_title  (optional)
    • Possible value = true / both / false.
    • true : permanently display short_titles on bottom of the image in the grid gallery.
    • both : display also short_titles in the 'one column scrollable' gallery.
    • false: do not permanently display short_titles, but they are displayed when mouse is onhover the image (or ontouch on mobile devices).
    • Default = true
  • gallery.display_preload  (optional)
    • true : display preload message (see global attribute 'loading_text') and progress bar on gallery opening buttons.
    • Note1 : the process of images preload cannot be disabled.
    • Note2 : The gallery opening buttons are not enabled/clickable until the preloading process is done, so if images are relatively heavy and the preloading process takes some time, set display_preload="true" is recommended.
    • Default = false
  • gallery.minimal_design  (optional)
    • true : do not display gallery title, images titles nor image number in the 'one column scrollable' gallery, and images are displayed a little bit larger.
    • Default = false
  • gallery.display_slideshow  (optional)
    • true : display a play button on the left to launch a slideshow.
    • See global attribute 'slideshow_time' for timer value.
    • Default = false

    • IMPORTANT : Name of image must be 'imgX' , X being a increasing number.
    • THE FIRST NUMBER MUST BE 1 within each gallery.
  • img.url
    • Path of the image file (relative to the pano/tour.xml in the examples).
    • Images for mobile must have the suffix '_s' (i.e. if url is 'img/myimage.jpg', a smaller image named 'myimage_s.jpg' must be in the same 'img' folder).
  • img.short_title  (optional)
    • Image title displayed on the image in the grid gallery (if display_image_title="true").
    • It is also displayed in the 'one column scrollable' gallery if display_image_title="both".
  • img.second_title  (optional)
    • Image title/comment displayed only in the 'one image scrollable' gallery

OTHER POSSIBLE CUSTOMIZATIONS: modify the content of the 'rsgp_gallery_style.xml' file.



See the RSGP Gallery Plugin Thread in the Forum for a more complex example with multiple galleries integrated in a virtual tour.