Jekyll One

The J1 Carousel Module is based on OWL Carousel V1 in the latest version of 1.3.3. OWL Carousel is a clean and neat jQuery plugin for creating fully responsive and touch-enabled carousels and simple slideshows.

Since November 2016, Owl Carousel V1, originally written by Bartosz Wojciechowski is not longer available on the Internet. The domain www.owlgraphic.com has been removed, the documentation and the sources are no longer available to the public. OWL Carousel V1 is (and will be) used for J1 Theme as the Carousel solution. If you have plans to extend the current functionality of the Carousel Module, check section Owl Carousel API for technical details.

If more functionality for e.g. a slideshow is needed that cannot offered by a the Carousel Module, you should go for Master Slider available with J1 Theme as well.

J1 Carousel

J1 Theme has fully integrated Owl Carousel V1. For the typical usage of a slide show with your content no manual configuration, no carousel initialization and no HTML code is needed. J1 Owl Carousel instances are created automatically based on a single configuration step with the Owl Carousel YAML file j1_carousel_mgr.yml.

Module sources

The sources for J1 OWL Carousel are stored within the asset path of J1Template. You’ll find all necessary data files under /assets/themes/j1/owl_carousel_v1:

Structure of the J1 OWL Carousel application tree (base components)
  ├───css
  │   │   owl.carousel.css
  │   │   owl.carousel.min.css
  │   │   owl.transitions.css
  │   │   owl.transitions.min.css
  │   │
  │   └───themes
  │           j1_template.css
  │           j1_samples.css
  ├───images
  │       ajax-loader.gif
  │       grabbing.png
  │       owl.video.play.png
  └───js
          owl.carousel.js
          owl.carousel.min.js

Initialization

As for all modules with J1 Theme, the initialization of an in-page application is done by a 3-step-sequence: Loading the CSS and JS code portions followed by a final setup phase to make the module ready to use (J1 Initializer).

CSS load

The first initialization step is to load the CSS data needed. Beside the base CSS styles provided by owl.carousel.css and the CSS transition definitions owl.transitions.css, custom styles are loaded for J1 Theme by j1_europe.css

Loading CSS data is automatically done by J1 Theme with the layout BASE for all content pages. The layout BASE runs the Liquid procedure base_loader on the HEAD section (region head) to load CSS data files based on the definitions specified with the CSS loader file /_includes/themes/j1/pages/css_loader.html.

 
  <!-- Styles for CAROUSEL Manager (OwlSlider V1) -->
  {% if page.owl_carousel_v1 and page.layout != 'app' and j1_modules.j1_carousel_mgr.enabled %}
  <link rel="stylesheet" href="{{ asset_path }}/owl_carousel_v1/css/owl.carousel.css" />
  <link rel="stylesheet" href="{{ asset_path }}/owl_carousel_v1/css/owl.transitions.css" />
  <!-- Custom CAROUSEL Styles for J1 Theme -->
  <link rel="stylesheet" href="{{ asset_path }}/owl_carousel_v1/css/themes/j1_template.css" />
  {% endif %}

JS load

The second phase covers the load of the Javascript portion. J1 Owl Carousel use a single library file owl.carousel.js for development or owl.carousel.js for production use.

Loading Javascript libraries is automatically done by J1 Theme with the layout BASE for all content pages. The layout BASE runs the Liquid procedure base_loader on the HTML section (region html-footer) to load JS data files based on the definitions specified with the JS Loader file /_includes/themes/j1/pages/js_loader.html.

  1. The Javascript portion of J1 Owl Carousel is included by the JS loader component at the bottom of a page, before the closing </HTML> tag:

Include the Javascript
  <!-- JS components for J1 CAROUSEL Manager (Owl Carousel V1) -->
  {% if page.owl_carousel_v1 and page.layout != 'app' and j1_modules.j1_carousel_mgr.enabled %}
  <!-- Enable JS components for Owl Carousel V1 -->
  <script src="{{ asset_path }}/owl_carousel_v1/js/owl.carousel.js"></script>
  {% endif %}

J1 Owl Carousel can be accessed and|or modified dynamically at runtime. Each carousel defined, an instance variable is declared (by it’s id) to access an carousel object later anywhere within your content. For more details see chapter Data methods later with this manual.

Initialize Carousel instance variables
<!-- Setup GLOBAL JS variables for J1 modules -->
  <script type="text/javascript">
  ...
  ...
  {% if page.owl_carousel_v1 and page.layout != 'app' and j1_modules.j1_carousel_mgr.enabled %}
<!-- Setup instance variables for J1 CAROUSEL Manager (Owl Carousel V1) -->
    {% assign config = site.data.modules.j1_carousel_mgr %}
    {% for item in config.carousel %}
    {% if item.show.enabled %}
      var {{item.show.id}};
    {% endif %}
    {% endfor %}
  {% assign config = nil %}
  {% endif %}
  ...
  ...
  </script>

JS initialization

Initializing jQuery based Javascript applications is done by J1 Theme using so-called Initializers. An J1 Initializer is a simple jQuery wrapper around an application to make all configurable options, given with the modules YAML file, available and standardize how a module is being setup.

Loading and running J1 Initializers are automatically done by J1 Theme by the layout BASE for all content pages. The layout BASE runs the Liquid procedure base_loader on the HTML section (region html-footer) to load the application init file based on the definitions specified by the JS Initializer file /_includes/themes/j1/pages/js_initializer.html.

Every J1 Initializer offers (at least) one method: init. All J1 modules are initialized by calling J1ApplicationName.init() on the document-ready event where J1ApplicationName is the name of the respective application (e.g. J1OwlCarouselMgr for the J1 Owl Gallery module. Initializers are stored under /assets/themes/j1/j1/js\initializers for all modules available with J1 Theme.

  1. Finally, J1 Owl Carousel library is being initialized by the JS Initializer component on the document-ready event.

Initialize the Javascript portion of Lightbox
<!-- ++++++++++++++ -->
<!-- Load J1 Initializers -->
<!-- ++++++++++++++++++++ -->
   ...
   ...
  {% if page.owl_carousel_v1 and page.layout != 'app' and j1_modules.j1_carousel_mgr.enabled %}
<!-- Enable Initializer for J1 CAROUSEL Manager (OwlSlider V1) -->
  <script type="text/javascript"
     src="{{ asset_path }}/{{site.template.name}}/js/initializers/j1_owl_carousel_v1.js">
  </script>
  {% endif %}
   ...
   ...
<!-- Run J1 Initializers on DocumentReady Event -->
<!-- ++++++++++++++++++++++++++++++++++++++++++ -->
  <script type="text/javascript">
  $(document).ready(function() {
   ...
   ...
<!-- J1 CAROUSEL Manager (Owl Carousel V1) -->
    {% if page.owl_carousel_v1 and page.layout != 'app' and j1_modules.j1_carousel_mgr.enabled %}
<!-- Initialize the J1 CAROUSEL Manager (Owl Carousel V1) -->
    J1OwlCarouselMgr.init();
    {% endif %}
    ...
    ...
  });
  </script>

Configuration

The default values used for the initialization are taken from the module.

YAML Data File

All modules provided by the J1Template are enabled by default on module level. As the carousel module, like other modules, is not used on each and every page, the module has to be switched-on on page level by enabling the library with the frontmatter by setting owl_carousel_v1 to true.

---
title:                  CAROUSEL Manager
tagline:                User Guide
description:            J1 CAROUSEL Manager
description:            J1 CAROUSEL Manager
...
owl_carousel_v1:        true
lightbox:               true
...

The Owl Carousel module can be enabled to use J1 Lightbox as a helper to enlarge images of a slideshow. By default, J1 Lightbox is enabled and initialized automatically. To use J1 Lightbox with J1 OWL Carousel, add lightbox: true to the frontmatter of the content page.

Customization

Quis aut ex repellat quia adipisci est sed aliquid enim hic. Voluptatem doloribus aperiam et dolorem dignissimos et nihil sit natus voluptatum ut laboriosam qui. Quo rem accusantium molestiae ut vero. Voluptas voluptatem dolorem eum. Praesentium voluptate est aliquam.

Set slides (window) height

The slides aren’t actually 100% height – it’s just based on the proportions of the images used. Change the proportions of the window and you’ll see the slider doesn’t adhere to the dimensions.

Your best bet for 100% height slides is using height: 100vh; on the Owl’s slide class (.owl-item). That way, they’ll alway match the window size.

.owl-carousel .owl-item {
    float: left;
    height: 80vh; /* limit height of a slide */
}

or

.owl-carousel .owl-item {
    float: left;
    height: 500px;
}

Carousel Examples

J1 Carousel is based on OWL Carousel V1 in the latest (and unfortuneatly last) version of 1.3.3. OWL Carousel is a clean and neat jQuery slider plugin for creating fully responsive and touch-enabled carousel sliders.

OWL Carousel V1 is not longer available on the Internet; for unknown reason. Anyway, J1 Theme is using this version of OWL Carousel as a build-in carousel module because the software does an excellent job, is based on a MIT license with no issues using them for private and business use. And offers a lot of great features!

Simple Text Carousel

A slider or carousel typically is used for displaying images but the implementation for J1 Theme support a lot more sources to be displayed as a slide show: simple text for example.

Parallax Text Carousel

A more eye-minded type of a text show is a parallax text slider. If you want to place emphasis on you personal statements focussing the meaning, this type of a slide show may be interesting. Image based slide shows may draw off the readers attention from the text, therefor a pure text based presentation may the better choice.

Parallax Carousel Example

Parallax text shows are can be placed as banners on a page. A lot of different animations can be used. Internally, J1 Theme is using some of the really great CSS styles offered by annimate.css.

Simple Image Carousel

Carousels are mostly used for pictures data to animate the images as series. Find with the following some examples how to use a carousel for your image data.

A simple image show is useful for example as an animated (or not animated) banner presenting interesting things of your site or the products offered.

Simple Image Carousel

Carousel + Caption + Lightbox

Carousels can be used for a quite compact form of image galleries. This example show some pictures having individual caption text and support a lightbox to enlarge images full size. For the example below, a quite simple lightbox is used: Lightbox V2; or short: lightbox.

Nice cats

The J1 module lightbox is a simple Lightbox but offers a bunch of interesting features for displaying images. For example, lightbox can display all images (of a carousel) as a group. If one picture is opened in the lightbox, all the other can browsed as well.

One Slide Carousel + Lightbox

The build-in Carousel carousel supports multiple and single image shows. Here you find an example of an single image slide show with controls enabled to browse all images back and forth. An indicator below the slider shows how many images the show contains.

Single Slide Carousel and a Lightbox

Owl Carousel API

Reprehenderit voluptatem tempore ipsa ea maiores temporibus pariatur dolor. Iusto maiores deleniti voluptatem dolorum possimus maxime odio a culpa dolor officia voluptas nihil. Ipsam dicta adipisci ipsa ipsa eius quia. Voluptatem et eum ut ipsum id dolorem eius aut vero et odio. Ducimus placeat non vel vel mollitia voluptatem occaecati recusandae nisi amet iusto autem aut nulla.

Initialization

The initialization of Owl Carousel is done by a 4-step-sequence: Loading the CSS (1) and JS code (2) portions, placing the HTML code of the carousel (3) followed by a final setup phase to make Owl Carousel instances ready to use (4).

CSS load

The first step of initialization is to load the CSS data. Beside the base CSS styles provided by owl.carousel.css, the CSS transition definitions owl.transitions.css are to be loaded.

  1. Load CSS files with the <HEAD> section:

Include the CSS
<link rel="stylesheet" href="path_to_css/owl.carousel.css" />
<link rel="stylesheet" href="path_to_css/owl.transitions.css" />

JS load

The second phase covers the load of the Javascript portion. Owl Carousel uses a single library file owl.carousel.js or owl.carousel.min.js for the minified version.

  1. The Javascript portion of Owl Carousel should be included at the bottom of a page, before the closing </HTML> tag:

Include the Javascript
<script src="path_to_js/owl.carousel.min.js"></script>

HTML Markup

Owl Carousel doesn’t use any special markup. The carousel works with any type of HTML block elements. The carousel data (content) needs to be wrapped inside the container element like this:

<div id="owl_carousel_id" class="owl-carousel">
The class owl-carousel is mandatory to apply proper styles that comes from owl.carousel.css CSS file.

  1. The HTML code of Owl Carousel including the content can be put anywhere within the `<BODY>`section.

Setup the HTML code of an Owl Carousel
<div id="owl" class="owl-carousel">
  <div> Your Content </div>
  ...
  ...
  <div> Your Content </div>
</div>

JS initialization

To make the carousel ready to use, the Owl Carousel instances are to be initialised using the options needed for your type and behaviour of Owl Carousel.

  1. Finally, Owl Carousel library is being initialized on the document-ready event for all carousel instances defined with the content.

Initialize the Javascript portion of Owl Carousel
<script type="text/javascript">
  $(document).ready(function() {
    $("#owl").owlCarousel({
      // Most important Owl Carousel features
      items:              5,
      itemsCustom:        false,
      itemsDesktop:       [1199,4],
      itemsDesktopSmall:  [980,3],
      itemsTablet:        [768,2],
      itemsTabletSmall:   false,
      itemsMobile:        [479,1],
      singleItem:         false,
      itemsScaleUp:       false
    });
  });
</script>

Options

Owl Carousel offers a large number of options to make the look and feel and the behaviour of your slide shows in a wide range customisable. All options can be used as static parameters at setup time or dynamically used by data methods (see chapter Data methods for more details).

Variable Default Type Description

items

5

int

This variable allows you to set the maximum amount of items displayed at a time with the widest browser width

itemsDesktop

array

This allows you to preset the number of slides visible with a particular browser width. The format is [x,y] whereby x=browser width and y=number of slides displayed. For example [1199,4] means that if(window⇐1199)\{ show 4 slides per page} Alternatively use itemsDesktop: false to override these settings.

itemsDesktopSmall

array

As above.

itemsTablet

array

As above.

itemsTabletSmall

false

array

As above. Default value is disabled.

itemsMobile

array

As above

itemsCustom

false

array

This allow you to add custom variations of items depending from the width If this option is set, itemsDeskop, itemsDesktopSmall, itemsTablet, itemsMobile etc. are disabled For better preview, order the arrays by screen size, but it’s not mandatory Don’t forget to include the lowest available screen size, otherwise it will take the default one for screens lower than lowest available.
Example:
[[0, 2], [400, 4], [700, 6], [1000, 8], [1200, 10], [1600, 16]]
For more information about structure of the internal arrays see itemsDesktop.

singleItem

false

boolean

Display only one item.

itemsScaleUp

false

boolean

Option to not stretch items when it is less than the supplied items.

slideSpeed

200

int

Slide speed in milliseconds

paginationSpeed

800

int

Pagination speed in milliseconds

rewindSpeed

1000

int

Rewind speed in milliseconds

autoPlay

false

int/boolean

Change to any integrer for example autoPlay : 5000 to play every 5 seconds. If you set autoPlay: true default speed will be 5 seconds.

stopOnHover

false

boolean

Stop autoplay on mouse hover

navigation

false

boolean

Display "next" and "prev" buttons.

navigationText

array

You can cusomize your own text for navigation. To get empty buttons use navigationText : false. Also HTML can be used here

rewindNav

true

boolean

Slide to first item. Use rewindSpeed to change animation speed.

scrollPerPage

false

boolean

Scroll per page not per item. This affect next/prev buttons and mouse/touch dragging.

pagination

true

boolean

Show pagination.

paginationNumbers

false

boolean

Show numbers inside pagination buttons

responsive

true

boolean

You can use Owl Carousel on desktop-only websites too! Just change that to "false" to disable resposive capabilities

responsiveRefreshRate

200

int

Check window width changes every 200ms for responsive actions

responsiveBaseWidth

window

jQuery selector

Owl Carousel check window for browser width changes. You can use any other jQuery element to check width changes for example ".owl-demo". Owl will change only if ".owl-demo" get new width.

baseClass

"owl-carousel"

string

Automaticly added class for base CSS styles. Best not to change it if you don’t need to.

theme

"owl-theme"

string

Default Owl CSS styles for navigation and buttons. Change it to match your own theme

lazyLoad

false

boolean

Delays loading of images. Images outside of viewport won’t be loaded before user scrolls to them. Great for mobile devices to speed up page loadings. IMG need special markup class="lazyOwl" and data-src="your img path". See an example with chapter Data attributes.

lazyFollow

true

boolean

When pagination used, it skips loading the images from pages that got skipped. It only loads the images that get displayed in viewport. If set to false, all images get loaded when pagination used. It is a sub setting of the lazy load function.

lazyEffect

"fade"

boolean / string

Default is fadeIn on 400ms speed. Use false to remove that effect.

autoHeight

false

boolean

Add height to owl-wrapper-outer so you can use different heights on slides. Use it only for one item per page setting.

jsonPath

false

string

Allows you to load directly from a jSon file. The JSON structure you use needs to match the owl JSON structure used here. To use custom JSON structure see jsonSuccess option.

jsonSuccess

false

function

Success callback for $.getJSON build in into carousel.

dragBeforeAnimFinish

true

boolean

Ignore whether a transition is done or not (only dragging).

mouseDrag

true

boolean

Turn off/on mouse events.

touchDrag

true

boolean

Turn off/on touch events.

addClassActive

false

boolean

Add "active" classes on visible items. Works with any numbers of items on screen.

transitionStyle

false

string

Add CSS3 transition style. Works only with one item on screen. Values: fade, fadeUp, backSlide and goDown

Callbacks

To customize the behaviour of your slide shows, several callback functions are available with Owl Carousel. See with the following table all events that can be bound to custom functions.

Variable Default Type Description

beforeUpdate

false

function

Before responsive update callback

afterUpdate

false

function

After responsive update callback

beforeInit

false

function

Before initialization callback

afterInit

false

function

After initialization callback

beforeMove

false

function

Before move callback

afterMove

false

function

After move callback

afterAction

false

function

After startup, move and update callback

startDragging

false

function

Call this function while dragging.

afterLazyLoad

false

function

Call this function after lazyLoad.

Methods

For existing carousel instances, several methods are available to modify the slider or add additional options to the show. To use Owl Carousel with dynamic data methods at runtime, an instance object (variable) is needed.

Go for the following sequence:

  1. Define a global instance variable

  2. Initialize the Carousel Plugin

  3. Load the instance data using jQuery $.data function

  4. Modify some data (options) as needed

JS code example for using data methods at runtime
<script type="text/javascript">
  // Define a (global) instance variable
  // outside document-ready
  var owl;
  $(document).ready(function() {
    // Initialize the Carousel Plugin
    $(".owl-carousel").owlCarousel()
  });
  // Get carousel data and store the object data
  // in an instance variable (owl)
  var owl = $(".owl-carousel").data('owlCarousel');
  // Modify some data (options)
  owl.reinit({
    navigation: true,
    items:      2
  });
</script>

Find withe following table all data methods available for J1 Owl carousel instances.

Method Option Description

reinit(newOptions)

JSON string

Reloads an existing carousel instance with new or additional parameters. Parameters are given as a JSON object: {option:value, .. ,option:value}

destroy()

none

Destroy an existing carousel

addItem(htmlString [,targetPosition])

string, [integer]

Adds an additional image to the show. Parameter htmlString contains the HTML markup, targetPosition the position, the new item should be added to.

removeItem(targetPosition)

integer

Removes an image (item) from the show at the specified targetPosition

next()

none

Go to next slide

prev()

none

Go to previous slide

goTo(n)

integer

Go to slide n and use slide animation

jumpTo(n)

integer

Go to slide n without slide animation

play([speed])

integer

Start auto playing the show. Accept speed as an optional parameter.

stop()

none

Stop auto playing the show