Components and Options

Shared Options

The following options are available regardless of the gallery type (except for the Gallery Hub component, which does not have these options).

[Shared Component Inspector Options]

Property Inspector Name Description
alias Alias Standard OctoberCMS stuff, you refer to the component in your page via this unique identifier, the default is “embeddedGallery” but you can change it to anything you want (don’t use spaces or special characters though!)
maxItems Max Images The maximum number of images to display
mediaFolder Media Folder Select the folder that you uploaded the images to in the OctoberCMS Media manager. Only folders under the “Base Media Folder” set on the November Gallery settings page are valid.
sortBy Order by Order to display the gallery items in; note: Image Title, Description, and Sort Order only work for images uploaded using the Galleries page! Options are:
title / Image Title
description / Image Description
sortOrder / Image Order in Gallery
width / Image Width
height / Image Height
orientation / Image Orientation
fileName / Filename
fileSize / File Size
uploaded / Date/Time Uploaded;
and all options are also available in reverse order (append DESC onto the option code).

Component 1: Embedded Gallery

Use this if you wish to show a gallery of images within your page using various layouts, with optional full-screen (lightbox-style) viewing.

[Component Inspector Options]

The following are available in addition to the Shared Options described above:

Property Inspector Name Description
galleryLayout Gallery Layout Select a gallery layout; possible values are:
default / Default (use the gallery layout set on the plugin settings page)
gallery_tiles / Tiles
gallery_carousel / Carousel
gallery_combined / Combined
gallery_slider / Slider
Check out the demo site for live examples of each layout.
tilesLayout Tile Layout Only applicable if the Gallery Layout is set to “Tiles”; possible values are:
default / Default (use the default gallery layout set on the plugin settings page)
gallery_tiles_columns / Columns
gallery_tiles_justified / Justified
gallery_tiles_nested / Nested
gallery_tiles_grid / Grid
combinedLayout Thumbnails Layout Only applicable if the Gallery Layout is set to “Combined”; possible values are:
default / Default (use the default thumbnails layout set on the plugin settings page)
gallery_combined_default / Normal (default)
gallery_combined_compact / Compact
gallery_combined_grid / Grid
additionalGalleryOptions Script options Additional JS options that you want passed onto the UniteGallery script, for example: theme_panel_position: "bottom"
imageResizerWidth Thumbnail Width Width of the generated thumbnail; Leave empty or set to 0 to only constrain the image by height; leave both width and height empty to fall back on the values set on the backend plugin configuration page
imageResizerHeight Thumbnail Height Height of the generated thumbnail; Leave empty or set to 0 to only constrain the image by height; leave both width and height empty to fall back on the values set on the backend plugin configuration page
imageResizerMode Thumbnail Mode Select how to resize your images into thumbnails, or select “default” to use the thumbnail mode set on the plugin settings page; possible values are: 
- Default
- Exact
- Portrait
- Landscape
- Auto
- Crop
galleryWidth Gallery Width Can be a number (pixel lenght) or a percent (of the parent container). Leave empty to fall back on the values set on the backend plugin configuration page
galleryHeight Gallery Height Only applies to “Combined” and “Slider” galleries! Can be a number (pixel lenght) or a percent (of the parent container). Leave empty to fall back on the values set on the backend plugin configuration page

For an explanation of page propreties, see Page Properties.

Check out the Demo Site for live examples of the above.

Component 2: Swiper

Use this component to create a modern, responsive “swiper” that can be controlled easily from any device. Note that you can control any of the galleries by touch (or click-and-swipe using a mouse). Various transitions are available: “fade”, “slide”, “flip”, “cube”, etc…

[Component Inspector Options]

The following are available in addition to the Shared Options described above:

Property Inspector Name Description
effect Transition Effect Tranisition effect. Can be “slide”, “fade”, “cube”, “coverflow” or “flip”
direction Direction Can be “horizontal” or “vertical”
speed Transition Speed How long the transition effect lasts, in milliseconds. 1000 = 1 seconds.
lazyLoad Lazy-load images? Toggle ON to only load the images the user is looking at. Previous and next images are set to pre-load automatically.
addPagination Add pagination? Toggle ON to show bullets (or anything else) that enable to user to jump to any specific slide.
addNavigation Add navigation? Toggle ON to show previous-slide and next-slide navigational arrows.
autoplay Auto-play? Toggle ON to enable automatic advance on the slides. Set the delay below.
autoplayDelay Auto-play Delay How long each image is shown for, in milliseconds. 1000 = 1 seconds.
additionalGalleryOptions Script options Additional JS options that you want passed onto the Swiper script, for example: fadeEffect: {crossFade: true}
useDescriptionAsCSS Description is Style When “on” and the image description contains one or more colons, then the image description is injected as CSS for that image. If the image description does not contain a colon, it is injected as a CSS class. Note that this only works for images uploaded through the backend Gallery page.
mediaQuery Media Query Use in conjunction with "Description is Style". You can set a media query to only apply the style in certain circumstances. Do not include a trailing “{”. For example: @media screen and (max-width: 766px) and (orientation: portrait)

Example Page

<div style="width: 100%; height: calc(100vh - 70px);">
	{% component 'swiperGallery' %}
</div>

The swiper component by default fills whatever space it is in, in this case we set the container DIV to take up 100% of the viewport and be 100vh tall.

For examples on how to customize the gallery, see How to Customize your Gallery.

Check out the Demo Site for live examples of the above.

Component 3: Pop-up Lightbox

Use this if you wish to add a lightbox-style 'pop-up' gallery to your page that is only shown when the user clicks on an element (such as a link/button/image).

[Component Inspector Options]

The following are available in addition to the Shared Options described above:

Property Inspector Name Description
attachTo Attach to JQuery selector for the element(s) that the user can click on to open the lightbox; for example: #gallery-button
additionalLightboxOptions Script options Additional JS options that you want passed onto the UniteGallery script, for example: theme_panel_position: "bottom"

Example Page

{% component 'popupLightbox' %}
<button id="gallery-button">Click me!</button>

This is a simple example where you place a button onto the page. Select a folder of images from the “Media Folder” drop-down in your inspector, and set the gallery “Attach to” option to #gallery-button. Your button should then serve to open a lightbox gallery of all of the images in the selected folder.

For examples on how to customize the gallery, see How to Customize your Gallery.

Check out the Demo Site for live examples of the above.

Component 4: Video Gallery

[Component Inspector Options]

The following are available in addition to the Shared Options described above:

Property Inspector Name Description
videoGalleryItemsSelector Gallery Selector/ID JQuery selector for the element that holds the video items; for example: #videos
videoGalleryLayout Gallery Layout Select a gallery layout; possible values are:
default / Default (use the gallery layout set on the plugin settings page)
video_gallery_right_thumb / Thumbnails 
video_gallery_right_title_only / Titles Only
video_gallery_right_no_thumb / No Thumbnails
Check out the demo site for live examples of each layout.
additionalVideoGalleryOptions Script Options Additional JS options that you want passed onto the UniteGallery script, for example: theme_autoplay: true
imageResizerHeight Thumbnail Height Height of the generated thumbnail; Leave empty or set to 0 to only constrain the image by height; leave both width and height empty to fall back on the values set on the backend plugin configuration page
imageResizerMode Thumbnail Mode Select how to resize your images into thumbnails, or select “default” to use the thumbnail mode set on the plugin settings page; possible values are: 
- Default
- Exact
- Portrait
- Landscape
- Auto
- Crop
galleryWidth Gallery Width Can be a number (pixel lenght) or a percent (of the parent container). Leave empty to fall back on the values set on the backend plugin configuration page
galleryHeight Gallery Height Only applies to “Combined” and “Slider” galleries! Can be a number (pixel lenght) or a percent (of the parent container). Leave empty to fall back on the values set on the backend plugin configuration page

For examples on how to customize the gallery, see How to Customize your Gallery.

Check out the Demo Site for live examples of the above.

Component 5: Image List Only

Use this if you wish to write your own Twig script for displaying your images, and only need a list of images (that can be found in a given folder) to be loaded into a page variable.

The image list component does not have any options other than the Shared Options.

Example Page 1

<div style="display: flex; flex-wrap: wrap; justify-content: center; align-items: center;">
{% for galleryitem in customGallery.gallery.items %}
    <div>
        <a href="{{ galleryitem.url }}" target="_blank">
            <img src="{{ galleryitem.url | resize(280, false,  { mode: 'portrait', quality: '90', extension: 'png' }) }}" alt="{{ galleryitem.fileName }}" style="margin: 20px;" />
        </a>
    </div>
{% endfor %}
</div>

This example assumes that your gallery component has the alias “customGallery” and that you have the Image Resizer Plugin installed. Thumbnails are generated for the images and displayed in a flexbox, with each thumbnail providing a link to the full-resolution image.

Example Page 2

<div class="container-fluid">
{% for galleryitemchunk in customGallery.gallery.items.sortBy('fileName').chunk(3) %}
    <div class="row">
        {% for galleryitem in galleryitemchunk %}
            <div class="col-xs-4" style="text-align: center;">
                <a href="{{ galleryitem.url }}" target="_blank">
                    <img src="{{ galleryitem.url | resize(280, false,  { mode: 'portrait', quality: '90', extension: 'png' }) }}" alt="{{ galleryitem.fileName }}" />
                </a>
            </div>
        {% endfor %}
    </div>
{% endfor %}
</div>

Again, we are assuming that your component has the alias “customGallery” and that you have the Image Resizer plugin installed. The images are sorted by filename and “chunked” into groups of 3 images, which are then displayed using the Bootstrap grid layout.

Check out the Demo Site for live examples of the above.

Page Properties for Gallery Components

__SELF__.gallery (in overridden component template) or componentAlias.gallery (in a CMS page)
Type: ZenWare\NovemberGallery\Classes\Gallery
Gallery class, holds the various properties of the gallery instance.

Property Type Description
type string Gallery type (indicates how the images were upladed & where they are stored), possible values are: NOVEMBER_GALLERY, OCTOBER_MEDIA_MANAGER_FOLDER, BLOG_POST
folder string
Folder where the images can be found (available for galleries created using the OctoberCMS "Media Manager")
items October\Rain\Support\Collection Collection of gallery items, see below.
sortBy
string The GalleryItem property by which the gallery should be sorted (as set in the component inspector)
url
string
Gallery URL (only available for galleries in the "Gallery Hub" component)
name  string
Gallery name as set on the Gallery form for galleries uploaded using the "Galleries" back-end page, for galleries uploaded using the OctoberCMS Media Manager this is set to the folder name
slug
string
Gallery slug (available for galleries created on the "Galleries" back-end page)
description
string
Gallery description (available for galleries created on the "Galleries" back-end page)
keywords
string
Gallery keywords (available for galleries created on the "Galleries" back-end page)
publishedAt
Carbon datetime
Gallery published on date (available for galleries created on the "Galleries" back-end page)
createdAt
Carbon datetime
Gallery created on date (available for galleries created on the "Galleries" back-end page)
updatedAt
Carbon datetime
Gallery updated on date (available for galleries created on the "Galleries" back-end page)
previewImage
GalleryItem
Gallery preview image (available for galleries created on the "Galleries" back-end page)
published
boolean
Gallery active (or not) (available for galleries created on the "Galleries" back-end page)
sortBy
string
Gallery items sort order
sortDirection
string
Can be "ASC" or "DESC" (like in SQL)

 

GalleryItem Properties

__SELF__.galleryitems(in overridden component template) or componentAlias.galleryitems (in a CMS page)
Type: October\Rain\Support\Collection
also see API DocsIlluminate\Database\Eloquent\Collection and Illuminate\Support\Collection

Collection of ZenWare\NovemberGallery\Classes\GalleryItem classes. Serving it as a collection gives access to a ton functionality that is not available with a simple array. For example, you could choose to sort the images by filename:

{% for galleryitem in customGallery.gallery.items.sortBy('fileName') %}
   <img src="{{ galleryitem.url }}" />
{% endfor %}

 

Property Type Description
title string Image title metadata, available for images uploaded using the backend gallery page only
description string Description metadata, available for images uploaded using the backend gallery page only
sortOrder string Image sort order, available for images uploaded using the backend gallery page only
file SplFileInfo A standard php file information object, only available for files uploaded using the Media Manager
octoberImageFile System\Models\File A standard php file information object, only available for files uploaded using the Media Manager
width integer Image width, see https://www.php.net/manual/en/function.getimagesize.php
height integer Image height, see https://www.php.net/manual/en/function.getimagesize.php
type string Image type, see https://www.php.net/manual/en/function.getimagesize.php
orientation string Will be "horizontal", "vertical", or "square" depending on whether the image is wider than it is tall
fileNameWithoutExtension string Base name of the file without extension, for example: picture-1
fileExtension string File extension, for example: jpg
fileName string Filename, for example: picture-1.jpg
filePath string Path without filename, for example: /var/www/mywebsite.com/public_html/storage/app/media/my-galleries/gallery-1
fileRealPath string Absolute path to file, for example: /var/www/mywebsite.com/public_html/storage/app/media/my-galleries/gallery-1/picture-1.jpg
fileSize string File size, in bytes, for example: 404779
relativeFilePath string Path to file relative to the website, for example: /storage/app/media/my-galleries/gallery-1/picture-1.jpg
uploaded string Last modified time for files uploaded using the Media Manager, or the upload time for files uploaded using the back-end gallery tab, you can then: $currentTime->format( 'c' );
url string URL to file, for example: https://www.mywebsite.com/storage/app/media/my-galleries/gallery-1/picture-1.jpg

 

Hint: To dig into the galleryItems (or any other) variable/collection, you have two options. You can simply add {{ dump(embeddedGallery.galleryitems.toArray) }} on your page after the component definition and it will print debug information about that variable straight in your page. Learn more aboud dump in the official Twig docs. Note that "the dump function won’t display anything if the debug option on the environment is not enabled". To enable debug mode on your site, edit the app.php config file in your config directory. Learn more about debug mode in the OctoberCMS docs!

Alternatively, you can install the Debugbar plugin and then add {{ debug(embeddedGallery.gallery.items) }} to your page to show debug information in the Laravel debugbar. Make sure to replace "embeddedGallery" with the alias of your component as set in the component options!

 

Additional Page Properties for Gallery Components

(not applicable to the GalleryHub component)

__SELF__.defaultgalleryoptions
Type: string
Used in the embedded gallery default template, this holds any custom script options set for the component in the “Script Options” property, along with any generated options (for example: gallery_theme: "tiles", tiles_type: "justified")

__SELF__.defaultLightboxOptions
Type: string
Used in the lightbox gallery default template, this holds any custom script options set for the component in the “Script Options” property, along with the following: gallery_theme: "lightbox"

__SELF__.customgalleryscript
Type: string
The “Custom Gallery Script” set on the plugin backend settings page, if the “Custom Gallery Script” toggle switch is set to “ON”.

__SELF__.customlightboxscript
Type: string
The “Custom Lightbox Script” set on the plugin backend settings page, if the “Custom Lightbox Script” toggle switch is set to “ON”.

__SELF__.error
Type: string
If the plugin encounters an error, you can find the error description here.

Component 6: Gallery Hub

This component loads a list of galleries without actually rendering any galleries. Use this if you wish to show a "hub" page with a link to all of your galleries.

For a good introduction to this component, please first check out the Demo Site.

[Component Inspector Options]

The following are available in the gallery inspector:

Property Inspector Name Description
hubType Hub Type
Leave blank to show a hub of all galleries, or select one of the options to only show certain galleries.

sortBy Order By

Possible values are:

  • title/ Gallery Title or Folder Name (default)
  • description/ Gallery Description
  • slug / Gallery Slug
  • publishedOn / Published On or Folder Creation Date

Note: Gallery Slug, Gallery Description, and Published On only work for images uploaded using the Galleries page!

maxItems Max Galleries The maximum number of galleries to display (leave blank to show all)
linkUrl Link URL Set the URL of your galleries. Include the following placeholder, which will be replaced with the "slug" of your gallery: %slug%'
openInNewTab Open in new tab? Should the link open in a new tab or in the current one?
visualization Display as

Choose one of the presets, or "template" if you wish to define your own template, or "custom" if you will write your own Twig code to render the gallery links! Possible values are:

  • default / Links with Preview Image
  • titleOnly / List of Links with Title Only
  • template / Set the Template Below
  • custom / Write your own Twig Code (links are not rendered)
template Link Template Choose "Set the Template Below" in "Display as" and set your template, tags such as %type%, %url%, %slug%, %folder%, %name%, %description%, %keywords%, %created_at%, %updated_at%, %preview_image_url% will be replaced with actual values.

 

[Page Properties]

__SELF__.galleries
Type: October\Rain\Support\Collection
also see API DocsIlluminate\Database\Eloquent\Collection and Illuminate\Support\Collection
Collection of matching galleries. Each item in the collection is an instance of the Gallery class (see above). For an explanation of the Gallery and GalleryItem class properties, see Page Properties.

__SELF__.dirs
Type: array of strings
This is the result of the File::directories() call that retrieves all subdirectories underneath your gallery root folder. Only populated when the "Hub Type" is set to "All Galleries".

__SELF__.hubType
Type: string
As set by the user in the component inspector, will be [ALL] if the user selected "All Galleries", or a keyword (which is used to limit the galleries shown)

__SELF__.keyword
Type: string
If the hub type is set to search by keywords, then this will be set to the selected keyword.

__SELF__.sortBy
Type: string
As set in the component inspector, can be one of: default, title, description, slug, publishedon

__SELF__.sortDirection
Type: string
As set in the component inspector, can be either "ASC" or "DESC"

__SELF__.maxItems
Type: int
Maximum number of galleries to show, as set in the component inspector

__SELF__.linkUrl
Type: string
Link URL template, as set in the component inspector. The placeholder %slug% will be replaced with the slug of the given gallery

__SELF__.openInNewTab
Type: boolean
As set in the component inspector

__SELF__.visualization
Type: string
How the galleries should be rendered, can be one of: default (unordered list of preview images), titleOnly (unordered list of gallery names), template (use a custom template), custom (no code is generated)

__SELF__.visualizationTemplate
Type: string
If "visualization" is set to "template", then the gallery items will be rendered using the template given here. The following placeholders are replaced with actual values: