November Gallery Cookbook

A gallery plugin for OctoberCMS that tries to Keep It Simple and Stupid. 1. Upload your images using the Media Manager built into OctoberCMS 2. Drop November Gallery onto your page or partial 3. Select the folder you uploaded your images to and how you want them displayed

Introduction

The idea for this plugin came about while building my girlfriend's photography website. I wanted to implement an easy to use gallery that could mimic how sites like PixieSet display images - so basically how Masonry does it. I also wanted to just use the OctoberCMS media manager to upload my images, I didn't want to use a separate backend page for that. I checked out all of the current gallery plugins available for OctoberCMS and none of them hit the mark.

So, I found UniteGallery.js, and integrated that with a simple PHP function to cycle through all of the images uploaded into a folder using media manager - I actually have a blog article on how I did this.

Well, as I built more and more websites with OctoberCMS, I started working on a dedicated plugin to help me out. And here we are, with a working "November Gallery" plugin that (currently) supports two "visualization engines", UniteGallery JS and Swiper. 

I hope you find it as useful as I do!

I would like to ask you for one favor. I've worked long and hard to make this available for you, and you are welcome to use it for free for non-commercial purposes (there is also a paid "Professional" version). If you have any issues, please don't leave a review if you don't think this is a five-star product. Reach out to me first by raising an issue on github, or by adding a comment to this page. Give me a few days to respond - I may get busy with other stuff but I will get back to you. Thank you!

This plugin is available in two editions:

  1. The Personal Edition is a free plugin meant for non-profit use, such as:
    1. Building a personal website that is not offering a product or services for sale
    2. Academic use
    3. Use by non-profit organizations
  2. The Pro Edition is meant for commercial use, such as:
    1. A website selling or promoting products or services
    2. Use by a for-profit organization

In terms of functionality, the two plugins are identical. November Gallery Pro is available from the OctoberCMS Marketplace. The Personal Edition is available from GitHub. You will need to install it yourself - follow the README on the GitHub project page.

Be among the first 10 to purchase the plugin on the October marketplace and use code FIRST10 to get 10% off!

Want more? Get 40% off by being among the first 10 to answer my riddle. 

One of my favorite photographers had a famous anecdote about driving along a highway with his two assistants after a long and not particularly successful day of photography. It was dusk and he was driving fast when suddenly he realized that a perfect photographic moment was approaching. He quickly pulled over and set up his gear - but in the rush he couldn't find his light meter. Knowing that he has mere seconds to get it right he decided to calculate the exposure using a system that he had developed with a friend, a system that photographers use even today to help anticipate the final results of their shot. He had one point of reference that he was sure of: the moon. Knowing the brightness of the moon he quickly calculated the correct exposure and took the shot. Considering that the moment truly was special, he tried to flip his film over to take the second shot but by then the light was gone. 

So my riddle is: what is the name of the community where he took this iconic photograph? Enter it in all capital letters when purchasing the plugin to get the discount :-)

Offer expires November 30th, 2019. Limit 1 coupon per customer.

What is November Gallery?

November Gallery is essentially a scaffolding over various Javascript-based visualization libraries. JS is great for displaying the images because it runs in the user's browser and can immediately react to changes in its environment, for example, a user turning their phone from vertical to horizontal, or resizing their browser. What November Gallery does is provide a framework within OctoberCMS for managing your images and building templates that include gallery "definitions". From an admin's/site content editor's perspective, you (1) get a "Gallery" page in your "backend" (that sounds wrong) and (2) you get various components that you can drag-and-drop onto your CMS pages/partials. Additionally, it also provides (3) "Snippets" to use in your "Static" pages (if you have the Static Pages plugin installed), and (4) it also integrates with the RainLab Blog Component, if you have it. It also provides for various options on a back-end configuration page.

---

For rendering your galleries, November Gallery provides you with various options, but it makes use of two JS libraries to do so. The various components it makes available to you really just help with configuring how the JS scripts are run so that you get a "swiper" or a "popup" gallery etc. You do not have to understand how these JS libraries work, but reading about the available configuration options will enable you to customize your galleries further than if you just use the options available through the November Gallery component property pages. 

Use the Embedded Gallery for fix-size galleries or for showing clickable thumbnails arranged as tiles

Tiles
Combined
Slider

The Swiper Component

This makes use of Swiper. Use it 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..

The Swiper Component is really geared towards responsive galleries because by default it fills whatever container it is in. 

The Popup Lightbox Component

This makes use of a custom UniteGallery JS theme. Use it to create a pop-up lightbox of images that can be opened from a link or button (or any other clickable component) on the page. Two styles are available: "Wide" and "Compact".

Again, this makes use of UniteGallery JS. Use it to display videos inline. You can choose to upload your videos to your website or to show videos hosted on YouTube/Vimeo/Wistia.

Image List Only Component

Well, I probably could have given this component a better name. This component only loads the list of image files into a page variable, without rendering a gallery. Use this if you wish to write your own code for displaying the images, or if you wish to make use of some other JS library to render them.

Where to now?

The other pages in this book guide you in using the gallery. You also have several other resources available:

 

 

Installation / Deployment

Note: You must have a {% styles %} and {% scripts %} tag in your page header/footer so that the plugin can inject the required assets.

<head>
    ...
    {% styles %}
</head>
<body>
    ...
    {% scripts %}
</body>

For more information see the OctoberCMS docs!

Installation

OctoberCMS v2.x: you will have to first purchase the plugin from the Marketplace, and then run the following on your server as described in the docs:

php artisan project:sync

You can also manually install and/or update the plugin, but this will only work if you've previously purchased a license:

composer require zenware/novembergallery-plugins
composer update zenware/novembergallery-plugins
php artisan october:migrate

OctoberCMS v1.x / WinterCMS: To install from your site “backend”: go to Settings → Updates & Plugins → Install Plugins and then search for “November Gallery”. Or, add it to your project from the Marketplace, and then from the backend area of your site click the Check for updates button on the Settings → Updates & Plugins page to pull in the plugin.

To install from the repository (not recommended), you’d have to first install the imageresizer plugin.

Here’s an actual (abridged) transcript of an installation into a fresh install of October (all commands for Ubuntu, make sure adjust to your environment):

USER@SERVER:/var/www/novembergallery.zenware.io/public_html# sudo git clone https://github.com/toughdeveloper/oc-imageresizer-plugin.git plugins/toughdeveloper/imageresizer
Cloning into 'plugins/toughdeveloper/imageresizer'...
...
USER@SERVER:/var/www/novembergallery.zenware.io/public_html# sudo git clone https://github.com/lieszkol/november-gallery.git plugins/zenware/novembergallery
Cloning into 'plugins/zenware/novembergallery'...
...
USER@SERVER:/var/www/novembergallery.zenware.io/public_html# sudo chown -R www-data:www-data plugins/toughdeveloper/
USER@SERVER:/var/www/novembergallery.zenware.io/public_html# sudo chown -R www-data:www-data plugins/zenware/
USER@SERVER:/var/www/novembergallery.zenware.io/public_html# sudo -u www-data php artisan plugin:refresh toughdeveloper.imageresizer
Rolled back: ToughDeveloper.ImageResizer
Reinstalling plugin...
ToughDeveloper.ImageResizer
...
USER@SERVER:/var/www/novembergallery.zenware.io/public_html# sudo -u www-data php artisan plugin:refresh zenware.novembergallery
Rolled back: ZenWare.NovemberGallery
Reinstalling plugin...
ZenWare.NovemberGallery
- v1.0.1:  First version of NovemberGallery

You can also install the image resizer plugin if you wish to use that for thumbnail generation, for that you can run sudo -u www-data git clone https://github.com/toughdeveloper/oc-imageresizer-plugin.git plugins/toughdeveloper/imageresizer and sudo -u www-data php artisan plugin:refresh toughdeveloper.imageresizer.

Updates

OctoberCMS v2.x: 

You will have to use the command line to update the plugin:

composer require zenware/novembergallery-plugins
composer update zenware/novembergallery-plugins
php artisan october:migrate

 

OctoberCMS v1.x / WinterCMS:

For plugins installed from the marketplace, you can just do **Settings → Updates & Plugins → Check for Updates.

For plugin installed manually, you can run the following from your project root directory:

USER@SERVER:/var/www/vhost/public_html# sudo -u www-data git -C plugins/zenware/novembergallery/ pull 
remote: Enumerating objects: 14, done. 
... 
USER@SERVER:/var/www/vhost/public_html# sudo -u www-data php artisan october:up 
ZenWare.NovemberGallery - v1.0.4: Extend Rainlab Blog integration with support for images in media folders ...

Backend Plugin Configuration

Log into your “backend” and go to Settings → November Gallery to configure your defaults. Things to look out for:

Uploading Images

You have two options for uploading your images, each with different benefits:

Hint: The dedicated back-end November Gallery management page gives you more options for giving your images titles and subtitles, and you can also arrange the order easily; on the other hand, if you ever end up deleting the plugin, October will also delete all of your albums created there. Use the October built-in Media Manager to upload your images if you don't need the extra features provided by the November Gallery management page. Going the Media Manager route also allows you to upload hundreds of images using an FTP client or other file manager; this is not possible through the Gallery page.

Although the plugin will automatically generate thumbnails of your pictures, the full-size images will be displayed as-is. Therefore, it's a good idea to resize all of your pictures before uploading them to the gallery. A plethora of free options exist to help you with that, we ♥ FastStone Image Viewer (Windows), Fast Image Resizer (Windows), and Image Resizer for Windows. I'm sure there are great options for Mac as well - but watch a little Louis Rossmann to understand why Macs are evil so if you're on a Mac I'm sorry but I can't help you :-(

A typical screen resolution nowadays is around 1920 x 1680 pixels - so if you're looking to allow your users to see your pictures in top quality full-screen, then resize them to fit within these constraints.

Also, make sure that your photos are in a format that web browsers understand, such as .jpg or .png, or .gif (the latter is more suitable for graphics with fewer colors and geometric lines, such as charts or icons).

Finally, upload your pictures using the "Gallery" admin area, or through the October Media manager into the folders you created earlier.

 

1) Create Galleries in the "Galleries" Area

When you install November Gallery, it creates a new section in your site back-end. The "Galleries" page is fairly self-explanatory: you can create new galleries, and upload images into existing ones.

Click on any image to give it a title and a description:

On the "Advanced" tab you can set a publication date for your gallery, a description, as well as a preview image:

You can then select your uploaded galleries from the component inspector:

 

2) Upload using the OctoberCMS Media Manager

Alternatively, you can upload your galleries using the OctoberCMS built-in media manager.

Images must be organized into folders. Although you can use any folder structure that you'd like, we recommend that you create a folder and create separate folders underneath that folder to store your albums. You can optionally create a "root" folder to store (subfolders of) images, and a separate "root" folder to store videos, and even a third "root" folder to store images for your blog. We also recommend not to use spaces in folder names - it's better to use dashes or underscores instead. Also, it is customary to use lowercase when creating folders for publishing on the web.

So, your folder structure may look like this:

Finally, upload your pictures using the OctoberCMS Media manager into the folders you created earlier.

Here is a walk-through of the process:

Underneath your "root" folders, create sub-folders for each "gallery":

And upload the images there.

Go to your November Gallery Settings and select your "root" image folder:

You can also set separate root folders on the "Video Gallery" and the "Blog Integration" tabs.

You can then select your uploaded galleries from the component inspector (folders will be preceded with a "/"):

 

Uploading using FTP

This is the most robust way for uploading many pictures at once to your site. Use an FTP client such as FileZilla (Windows) or WinSCP (Windows) or Panic Transmit 5 (Mac) and connect to your server. Your media files will be located in public_html/storage/app/media. You can create new folders through FTP as well, and if you then use the back-end media manager, you'll see them.

Automatic Thumbnail Generation

The plugin will automatically generate thumbnails for your images. You can disable this functionality, or set some options (such as thumbnail jpg quality, and default width/height) in the plugin configuration page. A subdirectory named "thumbnails" will be created under each backend media folder whenever a viewer first visits the given gallery. If you upload new images, or re-upload existing ones, new thumbnails will be generated. You can also manually force the thumbnails to be re-generated by deleting each "thumbnails" subdirectory:

Adding a Gallery to a Page / Partial

You may benefit from this page if you are new to OctoberCMS.

It is super easy to add November Gallery to your page or partial. Simply drag-and-drop!

Then, you can use the component inspector to set your options:

You can include as many galleries on your page as you wish!

Known Issue

OctoberCMS has a known issue where if a component is dropped into a partial then any CSS that is added to the page by the partial is never actually rendered. This only occurs if the partial is directly inside of a layout, and if the {% styles %} tag is included before the partial. Workarounds:
- Add your {% styles %} after your {% partial "..." %}
- OR Put your partial inside of a page, and include the page in the layout
- OR Manually add the required CSS to your layout

Dynamic Gallery using URL Parameters

If you don't wish to "hard-code" exactly which gallery you wish to display on a given page by selecting a specific gallery using the component inspector, then you can use URL parameters to specify which gallery to show. This technique is also very useful if you wish to create a Gallery Hub page that shows links to all of your galleries, as explained on the Gallery Hub Demo Page. This is how you do it...

(1) Update your page URL

To set this up, first update the URL of your gallery page in the backend to follow this example:

/gallery/:gallery_code|^cute-cat-pics|ufo-sightings|my-bombisha-collection$

So if your page's URL is "gallery", then add "/:gallery_code" to it. This tells OctoberCMS that you are expecting a gallery code in the link to the page.

The last part (|^cute-cat-pics|ufo-sightings|my-bombisha-collection$) is for security. It is a regular expression that ensures that someone can't just pass any arbitrary expression to your page. In our example we are allowing three galleries named "cute-cat-pics", "ufo-sightings", and "my-bombisha-collection."

If you are not so paranoid, you can also use a more relaxed regex, for example something like this: 

/gallery/:gallery_code?|^[a-z0-9\-\_]+$

This will take any gallery code that contains only characters, numbers, or dash or underscore. 

If someone tries to open a gallery that doesn't match the validation rules, then October shows them a nice "doesn't exist" page:

You can read more about URL parameters in the the official docs.

(2) Update your Component Configuration

Now, in the component inspector, click the ">_" button on the "Media Folder or Gallery" line:

and enter the name that you gave your url parameter PREFIXED WITH A COLON!

In our example above we used "gallery_code" as the Url parameter, so we will have to enter: :gallery_code

(3) Try it out!

Save the page and try it out. Open your page and specify the gallery you wish to display. In our example our URL might look like this:

Q&A

How can you specify which gallery to show?

For galleries uploaded using the OctoberCMS media manager, You must enter the directory name:

For galleries created using the "Galleries" backend page, you must enter the gallery slug:

If you have both a folder with a given name as well as a gallery with the same slug, the plugin will show the images uploaded using the Gallery page.

 

<a href="{{ 'galleries/dynamic-gallery'|page({ gallery_code:"ufo-sightings" }) }}">They exist!</a>

 

→ Check out a live demo of this handy technique!

Adding a Gallery to a "Static" Page

This is super simple!

Open up your "static" page from the Pages area in your website back-end:

And then find the gallery component you wish to add to the page from the "Snippets" list on the left. Click on it (do not drag-and-drop it onto the page!).

Then, click on the component that has been added to your page to bring up the configuration dialog:

Select your images, and set a layout etc. And - you're done!

Note that you can also edit your static page from the CMS area of your site, but you cannot access the component property page there (in other words, the component inspector won't work there).

You can see a demo of November Gallery working in a static page on the November Gallery demo website.

Adding a Gallery to a Blog

For this to work, of course you will need to install the RainLab Blog plugin.

You may also want to read our OctoberCMS Blog Quick Start Guide if you haven't yet set up a CMS page to display your blog posts.

Open one of the posts on your blog and you can see that there is a new "Galleries" tab:

Here you can select one or more galleries created on the Galleries backend page, or one media folder. 

Note that you are only shown those folders which are subfolders of the root folder you set for the blog component on the November Gallery settings page:

Drop any November Gallery component onto the CMS page or layout that displays your blog pages, and from the component inspector, set "> Take from RainLab Post" as the "Media Folder or Gallery" to display:

And voila, your blog includes images (this is a demo page, fairly ugly but that's not the point):

You can see the above page live on the demo site

Adding a Gallery to a Theme with "Blocks"

One of our clients got in touch with us because he was having trouble adding the gallery to a theme with predefined template "blocks". Such themes are very easy to get started with but in general we do not recommend them because it becomes quite difficult to add any kind of dynamic functionality, such as November Gallery. In fact, please keep in mind that November Gallery is NOT compatible with custom content blocks provided by such "creator" themes (for example the Ketikidis Creator Theme). If you wish to use such a theme, please do not purchase November Gallery because it will not be compatible. This is a limitation of OctoberCMS and the given theme, and there is nothing we can do about it.

If you are adamant about using a creator theme as well as NovemberGallery, then you may find some pointers in the email we sent to our client below...

Hello, could you help me with November Gallery integration to Ketikidis Creator theme? Ketikidis Creator Theme use a content blocks. Your plugin tutorial have a comment "Again, unfortunately, that's not how October works. You can only add "Snippets" to "Static" "Pages", not "Content" blocks." May i have another way to integrate your plug-in? Thank you in advance!
~ Dmitrij

Hi Dmitrij,

I investigated your situation...

Your other problem is that you are trying to use the plugin inside of the "content blocks" available with the Ketikidis Creator Theme. Unfortunately, it is not possible to use components inside of such content blocks. This is a limitation of OctoberCMS and the Ketikidis Creator Theme, and there is nothing I can do about it.

However, you have some options.

Option #1) The main problem is that the Ketikidis Creator Theme "hides" the "Content" tab of "Pages Pages" as shown here:

(by "Pages Pages" I mean the Pages area underneath the Pages menu as shown here, as opposed to the "Pages" you can see under the "CMS" header)

This is unfortunate because you could use the gallery components here as described in the NovemberGallery help docs.

So my first recommendation would be to get in touch with the author of the Ketidis Creator Theme and ask him to put an option in the theme to unhide the Pages-Pages "Content" tab. You could then easily drag-and-drop any snippet there, and it would show up underneath the "Blocks" generated by the Ketidis theme.

Option #2) If you are unable to get help from the author of the Ketidis Theme, then you can still use the gallery plugin but it is not simple. In fact you have two options.

Option #2a) Create copies of the "static.htm" layout and add the gallery to the layout file. Then, in the Pages-Page where you want that gallery shown, select the given layout. Here I show you how:

   1) First I installed the "Duplicate" plugin by Sozonov Alexey, this adds a little button to CMS pages with which you can create copies of a page. So you don't need to do this, I already added this plugin to your site.

   2) Go to CMS → Layouts → static.htm, and create a copy of it:

 

 

Go back to "Layouts" and you should see the copied layout with a funky name:

 

Open it, rename it, and add whatever gallery component you want to add to it and configure it as you need. Make sure to drag-and-drop the component right after the following lines:

<!-- Page -->
{% page %}

so drag it here:

 

configure the gallery:

give the layout a useful name as well as a description:

and save it.

Then, find the "Pages Page" where you want to use it, and change it to use this layout. For example, I changed your "Portfolio - Gallery" page to use this layout:

You can then click "Preview" to see it.

Option 2b: The above method is not ideal because you are hard-coding the gallery into the layout page. Another option is to create regular "CMS" Pages, add the gallery components there, and then add them to your menu. The drawback of this method is that you cannot use the "blocks" provided by the Ketidis theme. Here is how you would do it:

   1) go to CMS → Pages and create a new page

I created two examples for you to follow:

Just drag-and-drop whichever component you need here.

You will have to manually add any "header" or "link" or other HTML you want to show on the page.

You can then add the page to your menu:

go to Pages → Menus and select the menu (like Main menu)

Add a new menu item and select "CMS page" as the type:

 

and select the page from the "Reference" field.

I added the above two demo pages to your "Main menu", you can check it out on your site:

The hub works as well because I set the "Link URL" to "/galleries/%slug%" on the Gallery Hub component:

 

and named the URL of the other example page to be "/galleries/edgaras-ir-iveta":

 

if you click the first picture on the gallery hub page:

it takes you to that gallery page.

 

Dmitrij, I hope the above is helpful. I recommend you try and contact the author of the Ketidis theme as I described in option #1. But the other two options should work as well.

Good luck with your site!

Laszlo Lieszkovszky,
ZenSoft Hungary

Hello, Laszlo
Thank you very much for help, investigation and detailed problem description.
I understand everything, but galleries must be administered by a client, and it will be difficult.
Well, at night I remembered the option "Gallery in Blog". And November Gallery plug-in is working perfectly with blog pages;)
http://gaidelis.eu/portfolio
Blog administration will be easy for the client...
Thank you again for your support!
Dmitrij

Components and Options

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).
Components and Options

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.

Components and Options

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.

Components and Options

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.

Components and Options

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

Components and Options

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.

Components and Options

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

Components and Options

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

 

 

 

How to Customize your Gallery

How to Customize your Gallery

Overview

You have several options to customize how your gallery looks and behaves, depending on how deep you are willing to go down the rabbit hole:

  1. You can customize the gallery to some extent through the inspector; for example, you can set the gallery layout
  2. You can also add some custom options that will be passed onto the UniteGallery script via the inspector
  3. You can also add some CSS to control how the thumbnails are displayed
  4. You can adjust additional settings in the plugin back-end page, you can even completely override the generated script there.
  5. You can override the component partial

Regarding #2 - Setting Script Options

In each demo, you were also able to read about some possible additional options you can set on your galleries. It is important to understand which underlying JS library is used for each gallery. Currently, all galleries except for Swiper use UniteGallery. Swiper uses...Swiper.

So, for example, if you wish to make sure autoplay resumes even if there is any user interaction, then you can read up on the autoplay options in the Swiper API documentation. You can then set this in OctoberCMS in the component inspector for the Slider component, in the "Additional Swiper Options" parameter: autoplay: {disableOnInteraction=false}

Similarly, if you wish to disable the "full-screen" option on the UniteGallery slider, you can find the relevant option on the UniteGallery Slider docs. You can then set this in the component inspector for the Embedded Gallery component in "Script options" parameter: slider_enable_fullscreen_button: false

How to Customize your Gallery

Example 1: Set the thumbnail size for all galleries

Why?

If you know that you will be using a bunch of galleries throughout your site, and you also know that on most of these galleries, you will want to show thumbnails of a specific dimension, then it's easier to set it in one place instead of in every individual gallery component.

How?

You can set the thumbnail size on the plugin backend settings page: Settings → November Gallery → Thumbnails. If you want more control, go to Settings → Image Resizer Settings

How to Customize your Gallery

Example 2: Set the thumbnail size for an individual gallery

Why?

Because you may not want to use the default thumbnail size set for all galleries.

How?

You can set the thumbnail size for a specific gallery on the component properties page (a.k.a. “Inspector”).

You can also override many other settings (like gallery layout, size, etc.).

 

How to Customize your Gallery

Example 3: Set the gallery dimensions for the “combined” gallery

Why?

Because you wish to show images on your website in a gallery of a specific size, and you also want to control the size of the thumbnails in the navigator strip.

How?

In the combined gallery, a large image is displayed along with a row of thumbnails. First, set your thumbnail size using the inspector let’s say to 100.

Then check the relevant options available for the combined gallery on the UniteGallery plugin page. 

You can see that the “gallery_width” and “gallery_height” options control the overall size of the gallery. So enter something like the following into the Script options component option: gallery_width:900,gallery_height:700,thumb_fixed_size:false

The thumbnail size you defined using the inspector will control the size of the generated thumbnails, it will also automatically add a “thumb_height” option to the gallery. You can override this if you wish by manually adding a “thumb_height” option under Script options, but this should not be necessary. Additionally, the thumb_fixed_size:false setting enables dynamically sized thumbnails.

How to Customize your Gallery

Example 4: Set the spacing between tiled images

Why?

You wish to control exactly how your embedded "Tiles" gallery looks, including the space between thumbnails.

How?

First, review what options you have for the various tiled galleries on the UniteGallery website.

You can see that for the Tiles - Columns layout, you can control the spacing between the columns with the tiles_space_between_cols: 3 option – so add it to the Script options NovemberGallery component option!

How to Customize your Gallery

Example 5: Override the component partial

See the live demo for this recipe in action!

The official OctoberCMS docs provide an in-depth explanation on how you can override component partials. Here we will describe why you would want to do so with November Gallery, as well as how. 

Why?

If you are well-versed in October, then skip this section and go to "How?"!

How?

These code-generation templates are called "Partials" in October lingo, and they can be found in your filesystem after you install November Gallery under the following directory: plugins/zenware/novembergallery. Alternatively, you can find the source code on GitHub (go to components, then check out any of the subfolders).

You then need to create a file in your OctoberCMS backend, in the "CMS" area, on the "Partials" page, with the same name as the partial. The file must be "placed" in a directory that has the same name as your component alias. 

Let's go through this step-by-step. Let's say we wish to override the template for generating a swiper component. We've already dropped the component onto our page. Although this isn't necessary, for the sake of this tutorial let's change the component alias to "mySwiperGallery":

Remember, swiper needs to be inside of an element that has a width and a height - so we put it inside of a div that covers the whole viewport. Also, make sure to also rename your component in your page:

We then go to "Partials" and create a file called "mySwiperGallery/default.htm" and set copy-paste the original source code for this partial from GitHub.

We are going to completely override the javascript that is used to initialize Swiper. We will implement the "Multiple Slides Per View" demo on the Swiper demo website. The source code for that demo is available here.

You may in fact find that it's easier to take the demo and copy-paste that into our partial, and replace the needed bits only. You will have to:

{% for galleryitem in gallery.items.sortBy('fileName') %}
	<div class="swiper-slide" style="background-image:url({{ galleryitem.url }})"></div>
{% endfor %}

Our final complete page looks like this:

{% set galleryitems = __SELF__.gallery.items %}

{% if __SELF__.error %}
	<div class="alert zen-alert">{{ __SELF__.error }}</div>
{% endif %}

{% put styles %}
<style>
    html, body {
      position: relative;
      height: 100%;
    }
    body {
      background: #eee;
      font-family: Helvetica Neue, Helvetica, Arial, sans-serif;
      font-size: 14px;
      color:#000;
      margin: 0;
      padding: 0;
    }
	.swiper-container {
      width: 100%;
      height: 100%;
    }
    .swiper-slide {
      text-align: center;
      font-size: 18px;
      background: #fff;
      /* Center slide text vertically */
      display: -webkit-box;
      display: -ms-flexbox;
      display: -webkit-flex;
      display: flex;
      -webkit-box-pack: center;
      -ms-flex-pack: center;
      -webkit-justify-content: center;
      justify-content: center;
      -webkit-box-align: center;
      -ms-flex-align: center;
      -webkit-align-items: center;
      align-items: center;
    }
</style>
{% endput %}

<!-- Swiper -->
<div class="swiper-container">
    <div class="swiper-wrapper">
        {% for galleryitem in galleryitems.sortBy('fileName') %}
		<div class="swiper-slide" style="background-image:url({{ galleryitem.url }})"></div>
	    {% endfor %}	
    </div>
    <!-- Add Pagination -->
    <div class="swiper-pagination"></div>
</div>

<!-- Initialize Swiper -->
{% put scripts %}
<script>
var swiper = new Swiper('.swiper-container', {
  slidesPerView: 3,
  spaceBetween: 30,
  pagination: {
    el: '.swiper-pagination',
    clickable: true,
  },
});
</script>
{% endput %}

And voila, you can see that we've gotten the demo up and running using our gallery of images! You can see the demo in action at https://novembergallery.zenware.hu/cookbook/overriding-partials

Default Partials Source Code

You can find the source code for the partials used by the various November Gallery components below:

How to Customize your Gallery

Example 6: Add a "Download" Button to the Lightbox

Why?

One of our users asked: 

Endi Hariadi @EndiHariadi43 Sep 28 06:40
I want to add a download button to each image. How to do it? I have tried and failed.

How?

Endi is using the Embedded Gallery component, so that is what we will focus on. There are various ways to approach this problem.

  1. You could dive into the source code of the underlying component, UniteGallery and customize it to your needs. However, this would require quite an effort.
  2. Or, you could attempt to use the UniteGallery API. However, in our experience, the API is not very mature and in this case not usable (the "item_change" event could work, but unfortunately it isn't triggered when the first image is clicked on and the lightbox first shown, only when the user changes slides). 
  3. You could create your own UniteGallery skin- but again, this would require several hours of research and programming. 
  4. Or you cold just run with a quick-and-dirty jQuery hack

We'll go with #4 :-)

If you inspect the html behind a lightbox in your browser, you can see that the structure is as follows:

The img block is replaced dynamically, and the three ug-slider-wrapper components are manipulated so that it looks like images slide into and out of the user's viewport. We are going to insert a link button inside each div.ug-slider-wrapper element, which will dynamically tell the browser to download the image that is currently being shown. We will make use of the new HTML5 "download" attribute. For some background, read this great tutorial. The generated link will then use javascript to dynamically find the div.ug-item-wrapper element that is before it, and the img element inside of the div.ug-item-wrapper element. So, our link button will look like this:

<a href="https://novembergallery.zenware.hu/storage/app/media/galleries/budapest/0308M03_cropped.jpg" 
   style="position: absolute; width: 100px; left: calc(50% - 50px); bottom: 12px; display: block; background-color: transparent; border: 3px solid white; border-radius: 5px; color: white; font-weight: bold; text-align: center; font-size: 14px; z-index: 100;" 
   onclick="this.href = this.parentElement.children[0].children[0].src;" 
   download="">DOWNLOAD</a>

And it will be inserted into our page as follows:

Get to the point!

So in the end this is all you need to add into your OctoberCMS page to add a download button to each image:

<div class="panel-body">
	{% component 'embeddedGallery' %}
	{% put scripts %}
	<script type="text/javascript">
		$(document).ready(function(){
			$(".ug-slide-wrapper").append('<a href="#" style="position: absolute; width: 100px; left: calc(50% - 50px); bottom: 12px; display: block; background-color: transparent; border: 3px solid white; border-radius: 5px; color: white; font-weight: bold; text-align: center; font-size: 14px; z-index: 100;" onclick="this.href = this.parentElement.children[0].children[0].src;" download>DOWNLOAD</a>');
})
	</script>
	{% endput %}
</div>

and this is how it looks:

You can check out the first gallery on the November Gallery Demo site for a working example!

Of course this is not the perfect solution to this problem but it works. You can improve upon it by removing the inline-css and perhaps adjust it so that the button doesn't become invisible on a white background. The button only works with browsers that support the download attribute - if you wanted to support older browsers, you could add some checks to the button OnClick handler and handle such cases as well. You could replace the button with an image, or move it to some other part of the page. 

Good luck and have fun coding!

How to Customize your Gallery

Customize your Gallery with CSS!

You can easily add CSS to your page or layout to affect how your gallery looks. How to do so is really beyond the scope of this manual. Instead we will share some hidden tricks to add style to your gallery.

Trick #1 for Swiper Gallery: style one specific image

{% put styles %}
<style>
	.cute-cat-pic-1 {
		background-blend-mode: luminosity;
	}
</style>
{% endput %}

Trick #2 for Swiper Gallery: Style all horizontal images

{% put styles %}
<style>
    .swiper-slide {
        background-size: cover;
        background-position: center center;
        background-repeat: no-repeat;
    }
	@media screen and (min-width: 766px) and (orientation: landscape) {
        .swiper-slide-vertical {
            background-size: contain;
            background-position: center center;
            background-repeat: no-repeat;
        }
    }
</style>
{% endput %}

Recipes

Gallery concoctions to make your visitors go aaaah

Recipes

Responsive Full-Screen Gallery with Image Focal Point

The aim is to have a full-screen gallery that works both on desktop as well as mobile devices. The main issue is that mobile devices are often held in a portrait orientation, while desktop devices are landscape. 

See the live demo of this recipe in action!

A quick brainstorm reveals that:

  1. Some landscape images work both on desktop and mobile, however, on mobile we wish to shift them to either side because the image focal point is not in the center. Here is an example:

    This image looks fine on a desktop/laptop screen, but we only wish to show the area in the red square on mobile devices.

  2. Vertical images only look good on a mobile, so we don't wish to show them on a desktop at all, while some horizontal images only look good on the desktop (or mobile devices being held horizontally).

To achieve the above two aims, we can make use of "Description is Style" and "Media Query" properties of the Swiper Gallery component.

Step 1: Upload your photos

Log into your backend and go to Galleries → New Gallery

Upload your photos and make sure to save your gallery!

For each photo, add custom CSS that will only apply for small devices that are being held in a vertical position. Particularly, use the background-position rule to shift the image left or right. You can also play around with the background-size (set it to contain or cover). Some examples:

Step 2: Drop the swiper gallery to your page

Drop the component onto your page and check "Description is Style":

Also set "Media Query" to @media screen and (max-width: 766px) and (orientation: portrait) - this will ensure that the CSS that you include in your image descriptions is only applied to mobile devices in a portrait orientation.

You can also put your swiper inside of a div and set some styles to make sure that the images are displayed full screen, so your final page looks like:

{% put styles %}
<style>
	body {
    	background-color: black;
    	margin: 0;
    	padding: 0;
    }
	#home-gallery {
		height: 100vh;
		width: 100%;
	}
	#home-gallery .swiper-slide {
		text-align: center;
		font-size: 18px;
		background: #000;
	}
	#home-gallery .swiper-slide {
		background-size: cover;
		background-position: center center;
		background-repeat: no-repeat;
	}
	@media screen and (min-width: 766px) and (orientation: landscape) {
		#home-gallery .swiper-slide-vertical {
			background-size: contain;
			background-position: center center;
			background-repeat: no-repeat;
		}
	}
	@media screen and (orientation: portrait) {
		.android #home-gallery {
			height: calc(100vh - 56px) !important;
		}
		.android #home-gallery .swiper-button-next,
		.android #home-gallery .swiper-button-prev {
			display: none;
		}
	}
</style>
{% endput %}

<div id="home-gallery">
    {% component 'swiperGallery' %}
</div>

You might have noticed that in the above CSS we make use of the Orientation CSS media feature. You can read more about that on mozilla.org. We also have a rule for swiper-slide-vertical: this is a class that is added to all vertical images.

We also have some rules that are specific to android devices. For that to work, you must add Matthew Hudson's excellent "current device" script to your layout:

<!-- Mobile detection -->
<script src="https://cdn.jsdelivr.net/npm/current-device@0.8.2/umd/current-device.min.js"></script>

Step 3: Hide vertical images on horizontal screens

For this we will revert to some javascript! Add the following to your page:

 {% put scripts %}
    <script>        
        $(document).ready(function($) {
            if(window.innerHeight < window.innerWidth) {
                var mySwiper = document.querySelector('#home-gallery .swiper-container').swiper;
                if (typeof(mySwiper) != 'undefined' && mySwiper != null) {
                    var slidesToRemove = [];
                    var slides = mySwiper.slides;
                    for (var i = 0, l = slides.length; i < l; i++) {
                      if (slides[i].classList.contains('swiper-slide-vertical')) {
                          slidesToRemove.push(i);
                      }
                    }
                    if (slidesToRemove.length > 0) {
                        mySwiper.removeSlide(slidesToRemove);
                        mySwiper.update();
                    }
                }
            }
        });
      </script>
    {% endput %}

What are we doing here? We loop through all of the slides in the swiper, and if any of them are vertical, we remove them from swiper. Read the Swiper docs for more information on swiper's API.

 

Troubleshooting

Nothing works!

Things to check:

  1. Make sure that your layout file has {% styles %} and {% scripts %} tags as explained in Installation / Deployment
  2. Have you created a folder of images and selected that folder in the component inspector?

I added the Popup Lightbox component but can't see anything!

Make sure that you've created an element on the page to attach the lightbox to, and set the ID of that element in the "Attach to" property using the component inspector.

My Swiper is uuugly!

Swiper will fill whatever it is in. So, you ought to put it in a div with a specific width or height (which can be 100% or 100vw / 100vh if you wish to fill the whole browser window).

Well, unfortunately, that's not how October works. If you want your gallery to work, you have to add your page to a layout and then you can view the page use the preview button to see your static page in action.

A quick rundown of how to set up static pages:
1. Create a layout, the simplest you can make would be like this:
<html><head>{% styles %}</head>
<body>{% component 'staticPage' %}{% scripts %}</body>
</html>
2. Go to your page and select the newly created layout as the layout
3. Click "Preview" to see your page

I want to add a gallery to a "Content" page on the Static Pages menu...

Again, unfortunately, that's not how October works. You can only add "Snippets" to "Static" "Pages", not "Content" blocks.