Components and Options
- Shared Options
- Component 1: Embedded Gallery
- Component 2: Swiper
- Component 3: Pop-up Lightbox
- Component 4: Video Gallery
- Component 5: Image List Only
- Page Properties for Gallery Components
- Component 6: Gallery Hub
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 / SliderCheck 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
Use this gallery to display videos inline. You can choose to upload your videos to your website or to show videos hosted on YouTube/Vimeo/Wistia.
[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 ThumbnailsCheck 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
Gallery Properties
__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 Docs, Illuminate\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:
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:
|
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 Docs, Illuminate\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:
%type% | Gallery type, can be NOVEMBER_GALLERY, OCTOBER_MEDIA_MANAGER_FOLDER, or BLOG_POST |
%url% | Gallery URL |
%slug% | Gallery slug* |
%folder% | Gallery description* |
%name% | Gallery name (or the folder name in case of galleries uploaded using the OctoberCMS media manager |
%description% | Gallery description* |
%keywords% | Gallery keywords* |
%created_at% | Gallery creation date* |
%updated_at% | Gallery last update date* |
%preview_image_url% | Preview image URL (if set)* |
%published% | Gallery is published or not* |
%preview_image_title% | Preview image title* |
%preview_image_description% | Preview image description* |
%preview_image_width% | Preview image width* |
%preview_image_height% | Preview image height* |
%preview_image_filename% | Preview image filename* |
%preview_image_filesize% | Preview image file size* |
%items_count% | Count of images |