Carousel slideshow and Gallery widgets July update

Recently I completely rebuild Html Carousel slideshow and Gallery components for websites and merge some basic features into the single base component with other derivatives. This approach brings many benefits to development. Now I’ll introduce you to these innovations of new version 1.2.0.

First of all, I apologize for not being able to respond to your questions in time. I read your questions carefully and I am glad for your comments.

What’s the news?

The main change is a merge of all into the single decorator. You can now use only one script and use one of the available components: Carousel slideshow, (Simple Gallery), Gallery player. New is the use of media items, which allow you to set special parameters for each image separately.

MediaItems

Each component contains a list of MediaItems. These represent each of image of carousel or galleries and have separated configuration.

Each MediaItem represents one image of a carousel or gallery. You can set special attributes for each image separately as size, stretch, description, etc.

Every frame now supports multi-resolution image for loading optimizing. You can set up many image size for different canvas size.

It is also possible to disable stretch mode, enlarge or set cover mode. You can set up these modes for all MediaItems globally by default or for each MediaItem individually.

How to choose the right widget type

Each of the two widgets described is useful for different things. My original intention was to create a photo viewer (working with Google Photos).

Carousel slideshow widget is a simple component designed for displaying images on the website without some benefits of the gallery. It’s a good additional tool for embed carousel for web design. Or if you can show a limited quantity of images on webpage. Carousel widget support autoplay on startup and autorepeat. But, it does not support full-page or fullscreen mode.

Gallery player is a complete photo album viewer. It’s designed like a player, such as YouTube video player or PowerPoint embedded presentation. It’s an easy way to embed the gallery into a website. If you want, you can use a code generator for embed Google photos album.

Neither component has any limitations on the MediaItems used. But, I recommend always consider how many images you want your visitors to present. In my opinion, no one wants to flip through 500 shots 🙂

How to properly use widgets

First, insert a javascript link into the page code. Javascript is stored in CDN and optimized for performance. If you look at the source code, you will find the script version information on the first line.

<script src="https://cdn.jsdelivr.net/npm/publicalbum@latest/embed-ui.min.js" async></script>

Elements must contain specific class names to automatic decorate. If the script is loaded asynchronously (I recommend), the decoration is performed immediately after the upload and then again when onContentLoaded.

Here are supported class names to recognizing what type of widget will decorate:
pa-carousel-widget – Carousel slideshow widget
pa-gallery-player-widget – Gallery player widget

Preparing widget code

Here is a basic structure of HTML elements of widget for embed carousel or gallery player into a website.

<div class="pa-carousel-widget"
  style="width: 100%; height: 480px; display: none;"
  data-link="https://photos.app.goo.gl/CSV7NDstShTUwUZq5"
  data-title="Mr. Monstro">
    <img data-src="https://...image1.jpg" />
    <img data-src="https://...image2.jpg" />
    <img data-src="https://...image3.jpg" />
</div>

And don’t forget insert javascript with decorators first. You can use async or insert at bottom of the page.

Carousel slideshow widget

The API interface of the carousel widget component has not changed much. See to my previous post to check how to embed Carousel and setup then. Here are summaries of the currently available settings:

The div container of Carousel slideshow widget contains the follow attributes since version 1.2.0:

• class – Contain class name pa-carousel-widget for identification.
• style – Additional style to block widget before decorating.
• data-title – The caption of the carousel. If you want to disable title, not fill or set to empty string.
• data-link – Album link, or website, if available. If you using Google Photos album generator, link to the original shared album will be used.
• data-show-link-button – If the link is available, you can turn on/off button with a link. Set to true/false, the default value is false.
• data-delay – Delay between frames in seconds. Default is 5 sec.
• data-autorepeat – Repeat all the time. Set true/false. Default true.
• data-background-color – This is a hexadecimal code of color for background color setup. The default is #000000(black).
• data-show-download-button – Enable/disable button to direct link to the current image for download. Set true/false. Default false.

Gallery widget with “player” feature

Gallery player has a little bit different architecture. The input parameters are the same except for some new ones. There are:

• class – Contain class name pa-gallery-player-widget for identification and some user defined class if you can.

style, data-title, data-link, show-button-link, data-delay, data-autorepeat, data-background-color, data-show-download-button are same as previous Carousel widget.

• data-show-repeat-switch – Show or hide repeat switch on left bottom coner and support this feature. Set true/false. Default true.
• data-show-fullpage-switch – Enable or disable fullpage mode – cover full browser window. Set true/false. Default true.
• data-show-fullscreen-switch – Enable or disable browser fullscreen mode. Similar as F11/Esc. Set true/false. Default true.
• data-fullpage-autoplay – Special on player widget, auto switch browsing of photo album to “fullpage” mode. If you want to disable fullpage on initial play button press, set it to false. Set to true/false, default value is true.

And some default for media items:

• data-mediaitems-aspect-ratio – Setup default aspect ratio for all MediaItems. Set true/false. Default true.
• data-mediaitems-stretch – Stretch. Set true/false. Default true.
• data-mediaitems-enlarge – Auto-enlarge images. Set true/false. Default true.
• data-mediaitems-cover – Cover full canvas. Set true/false. Default false.

Setup images individual with MediaItems

Every image is possible to set up individual – size, stretch mode, description and others. Individual images as represent by <img /> elements. Here are supported attributes of image element:

• src – Empty default attribute if necessery.
• alt – Same as src.
• data-src – Absolute or relative URLto real full-size image.
• data-initial-src – If you have a thumbnail, you can put it into this. How to set it up exactly in one of the next articles.
• data-width, data-height – Setup custom width or height.
• data-aspect-ratio – Keep the aspect ratio of image dimensions. Set true/false. Default true.
• data-stretch – Auto-stretch image. Set true/false. Default true.
• data-enlarge – Auto-enlarge image. Set true/false. Default true.
• data-cover – Cover full canvas. Combine with aspectRatio. Set true/false. Default false.
• data-description – Additional description of the image. For line you can use \n symbol.

Tiny widget API

If you need to decorate widgets manually you can you tiny API.

Change class name pa-* (for example, set to pa-custom-gallery-player) to another name to disable auto-decorator. Setup element ID (in this case set to widget1).

Decorate widget with the following javascript code (for gallery player):

var player = new GalleryPlayerWidget();
player.decorate(document.getElementById('widget1'));

After Public album Embed UI script loaded, there are following object constructors are available: CarouselWidget, GalleryPlayerWidget.

And supported methods:
.decorate(Element element) – decorate element with widget data
.update() – update widget completely
.refresh() – update widget dimensions only, when size changed or etc.

Here is a small example: decorate-widget-onclick.html.

How to embed carousel slideshow or gallery player into a website?

The basic option is to insert everything manually.

For easier code creation, you can use my tool to generate and embed Google Photos album. The tool can set the output for carousel or gallery. Here are the links:

• Embed photos as a slideshow with carousel widget
• How do I embed a Google Photos album into a website?

If you set up additional settings, such as MediaItems or another, you must be added then into code manually. So far I have not implemented these options in any tool, but I will certainly make up for that 😉