Components and Options

Shared Options

[Shared 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.

[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…

[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).

[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

[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

__SELF__.gallery
Type: ZenWare\NovemberGallery\Classes\Gallery
Gallery class, holds the various properties of the gallery instance.

Property Type Description
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)
name  string Gallerz name (available for galleries created on the "Galleries" back-end page)
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)
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
System\Models\File
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)

 

__SELF__.galleryitems
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 %}

GalleryItem Properties

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. 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

__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.