DIAMOND GALLERYDocumentation v1.0

Installation Basic usage Initialization Images Captions Options Public methods Public properties Events Easing functions
Diamond Gallery jQuery

DIAMOND GALLERY

Version 1.0 Documentation

INSTALLATION

Download the plugin, then upload diamond-gallery.min.css and diamond-gallery.min.js files from the diamond folder to your server.

Include diamond-gallery.min.css in your page (usually in the head section)

<!-- Main Diamond Gallery CSS file --> <link rel="stylesheet" href="path-to-file/diamond-gallery.min.css" type="text/css">

Include diamond-gallery.min.js file in your page right below jQuery. Note that this plugin requires jQuery 3.0+

<!-- Plugin requires jQuery 3.0+ --> <!-- If you already have jQuery on your page, you shouldn't include it again --> <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script> <!-- Main Diamond Gallery JS file --> <script src="path-to-file/diamond-gallery.min.js"></script>

BASIC USAGE

Create a new <div> tag with unique id and add it to the <body> section of your page.

<!-- This is your gallery --> <div id="my-diamond-gallery"></div>

INITIALIZATION

To init the plugin, include this script below in your page (usually at the bottom of the <body> tag, under jQuery and source script included previously).

<script> $(document).ready(function(){ $("#my-diamond-gallery").diamondGallery(); }); </script>

IMAGES

To add an image, just add HTML markup to your gallery. Create a <div> element and specify the path to your image using the data-img-dg attribute.

<!-- This is your gallery --> <div id="my-diamond-gallery"> <!-- Put your images here --> <div data-img-dg="path-to-image/1.jpg"></div> <div data-img-dg="path-to-image/2.jpg"></div> <div data-img-dg="path-to-image/3.jpg"></div> </div>

CAPTIONS

You can add a caption to each image in your gallery and it will appear in the lightbox. Just put your caption HTML layout inside the <div> object.

<!-- This is your gallery --> <div id="my-diamond-gallery"> <!-- Your image --> <div data-img-dg="path-to-image/1.jpg"> <!-- Your caption data goes here --> <p>This is my awesome image</p> </div> </div>

OPTIONS

Use options to configure the plugin. Options should be passed to the initialization code and separated by comma. As an example, set some options as shown in the code below.

<script> $(document).ready(function(){ $("#my-diamond-gallery").diamondGallery({ // options go here crslStyle: 'diamond', crslColumns: 5, itemSize: 96, // and so on... }); }); </script>

In the tables below you can find a complete list of existing options, their default settings and descriptions. The list is separated into the logical blocks to become more informative.

PLUGIN GLOBAL

Option Default Value Description
initWhenInVieweport true Allows to initialize the plugin only when it appears in the user`s viewport. Useful for increasing page load speed.
Set it to false for immediate initialization
fontFamily null

Allows to set a specific font to the gallery. By default, the plugin applies the font settings from the parent tag <div> to which it is attached.

To apply custom font it must be installed on the page. Option must be passed as string: 'My-font-name'

transitionSpeed 300 Global transitions speed. Value is in ms
transitionTimingFunction 'linear'

The type of the easing function for transition events.

The easing functions specify the rate of change of a parameter over time. More information can be found in the easing functions section of the current documentation

allowHover true Allows hover events. Set it to false to disable hover
hoverSpeed 200 Global hover speed. Value is in ms
hoverTimingFunction 'linear'

The type of the easing function for hover events.

The easing functions specify the rate of change of a parameter over time. More information can be found in the easing functions section of the current documentation

touchThreshold 40 Minimum distance that user has to swipe to trigger a gallery slide event. Value is in px
keyboardControl true Enables gallery navigation using the keyboard. Set to false to disable keyboard control
Option Default Value Description
crslPosition 'inline'

There are two possible values: 'inline' and 'outline'.

By default, the carousel will fit all the available width of the element to which the plugin is attached. In other words, you can adjust the width of the carousel by setting the CSS "width" property for the gallery tag ( in the examples above - <div id="my-diamond-gallery"> tag )

But in case you need a carousel to fit the width of the viewport, and your layout doesn't allow it, set the value to 'outline' and the carousel will fit all the available viewport width no matter what

crslStyle 'diamond' Carousel grid style. There are four available values:
'diamond'
'tile'
'ellipse'
'hexagon'
crslColumns 5

The number of columns in the carousel.
Recommended range of values - from 2 to 12.

Note that the carousel is responsive, so this value could be changed dynamically using breakpoints option

crslAutoSlide 0

Time interval in ms for automatic carousel sliding.

If set to 0, auto sliding is disabled. Set to 1000 and the carousel will slide automatically every second, up to 5000 - every 5 seconds respectively.

Auto sliding will be stopped after user interaction: tap, click or swipe

crslBgColor null Carousel background color.
Only HEX format is allowed ( for example: '#000000' )
Option Default Value Description
navTextColor '#e2e2e2'

Carousel navigation buttons text color. This color will also be applied to the navigation arrows.

Only HEX format is allowed

navDisableTextColor '#080808'

Disabled navigation button text color. This color will also be applied to the navigation arrows.

Only HEX format is allowed

navArrowHeight 2

This value sets the line height for navigation button arrows, in px.
Range of values - from 0 to 10.

If set to 0, the navigation arrows will be completely removed and the navigation texts will be centered

navArrowGradientPoint 30 This value sets the transparency point for navigation button arrows gradient in %. Range of values - from 0 to 100
navBgColor '#2f353a' Background color of the carousel navigation buttons.
Only HEX format is allowed
navGradientColor '#000000' Carousel navigation buttons gradient color.
Only HEX format is allowed
navGradientOpacity 95 The level of opacity of the carousel navigation buttons gradient layer. Value is in %. Range of values - from 0 to 100
Option Default Value Description
itemSize 96

Slide size, in % of the maximum available size.
Range of values - from 0 to 100.

This option allows to control margins between slides. The less the value, the larger margin will be.

This value will also be applied to the carousel navigation buttons and could be dynamically changed using breakpoints option

itemAspectRatio 1

Slide aspect ratio.

Value set to 1 means that the width and height of the slide will be equal. Value less than 1 means that the slide will be stretched vertically, more than 1 - horizontally. Minimum value is 0.1.

1
0.5
1.5

This value will also be applied to the carousel navigation buttons

itemBorderRadius 4

Slide border radius, in px.

This value will also be applied to the carousel navigation buttons and could be dynamically changed using breakpoints option

itemGradientColor '#000000' Slide gradient color. Only HEX format is allowed
itemGradientPoint 50

The point where the gradient should stop. Will be calculated as a percentage of the slide height.
Range of values - from 0 to 100.

If set to 50, the gradient layer will start at the bottom of the slide and stop in the middle. Set it to 100 and the gradient layer will cover all the slide height and will stop at the top of the slide

itemGradientOpacity 50 Opacity level of the slide gradient layer, in %.
Range of values - from 0 to 100
itemGrayscaleLevel 0

Grayscale level of the slide image, in %.
Range of values - from 0 to 100

A value of 0 leaves the image full color saturated. Set it to 100 and the image will be black and white

itemPreloaderColor '#2f353a' Color of the preloader that appears before the slide is loaded. Only HEX format is allowed
itemHoverTextColor '#e2e2e2' Color of the slide hover text. Only HEX format is allowed
itemHoverTextOpacity 80 Opacity level of the slide hover text, in %.
Range of values - from 0 to 100
itemHoverFontSize 40

Font size of the slide hover text, in px

This value also could be dynamically changed using breakpoints option

itemHoverTextScale 10

Initial scale level of the hover text, in %.
Range of values - from -100 to 100.

If the value is less than 0, the text size will decrease, more than 0 - will increase.

If set to -100, then the text will be enlarged from half the original size to full size on hover. Set it to 100 and the text will be reduced from double the size to the original on hover

itemHoverImageScale 10

Initial scale level of the slide image, in %.
Range of values - from -100 to 100.

If the value is less than 0, the initial image size will be enlarged and reduced to the original size while hovering. If set to more than 0, image size will remain original and will be enlarged on hover

itemHoverGrayscaleLevel 100

Grayscale level for slide image while hovering, in %.
Range of values - from 0 to 100.

A value of 0 leaves the image full color saturated. Set it to 100 and the image will be black and white

itemHoverOverlayColor '#000000' The color of the slide hover overlay layer.
Only HEX format is allowed
itemHoverOverlayOpacity 50 Opacity level of the slide hover overlay layer, in %.
Range of values - from 0 to 100
itemShadowColor '#000000' Color of the slide shadow layer.
Only HEX format is allowed
itemShadowOpacity 60 Opacity level of the slide shadow layer, in %.
Range of values - from 0 to 100
itemShadowSize 20

Size of the slide shadow, in px

This value also could be dynamically changed using breakpoints option

itemShadowOffsetX 0

Horizontal offset of the shadow, in %.
Range of values - from -100 to 100.

Positive value puts the shadow on the right side of the slide, negative value puts the shadow on the left side of the slide

itemShadowOffsetY 20

Vertical offset of the shadow, in %.
Range of values - from -100 to 100.

Positive value puts the shadow below the slide, negative value puts the shadow above the slide

Option Default Value Description
lightboxClass null This option will add an additional class to the lightbox.
Must be passed as string: 'my-diamond-lightbox'
lightboxZindex 9000 CSS z-index for the lightbox
lightboxBgColor '#000000' Color of the lightbox background layer.
Only HEX format is allowed
lightboxBgOpacity 90 The level of opacity of the lightbox background layer, in %. Range of values - from 0 to 100
lightboxContentScale 5

Lightbox content block scale level, in %.
Range of values - from -100 to 100.

If the value is less than 0, the size of the lightbox content block will be increased from the set value to the original size during the opening animation and vice versa if the value is greater than 0

lightboxContentMaxWidth 80

The maximum allowed lightbox content block width is a percentage of the viewport width.
Range of values - from 65 to 90.

If value is set to 80, any lightbox image including caption won`t be wider than 80% of viewport.

Note, that lightbox navigation and close buttons also depend on this value. For example: if maximum allowed content width set to 80, that means content can cover up to 80% of viewport width and 20% is left for navigation buttons ( 10% for 'previous' and 10% for 'next' button ). Otherway, if maximum allowed content width set to 100, content can cover up to 100% of viewport width and there will be no space left to display the navigation buttons

lightboxContentMaxHeight 90

The maximum allowed lightbox content block height is a percentage of the viewport height.
Range of values - from 0 to 100.

If value is set to 90, any lightbox image won`t be higher than 90% of viewport

lightboxControlSize 35

The size of the navigation and close buttons of the lightbox. Range of values - from 0 to 100

As noted above, this parameter depends on 'lightboxContentMaxWidth' option so calculation is based on available space. This value sets buttons size in % of maximum available space for them.

This value also could be dynamically changed using breakpoints option

lightboxControlColor '#e2e2e2' Color of the navigation and close buttons of the lightbox. Only HEX format is allowed
lightboxControlLineWidth 2 This value sets the line thickness for navigation and close buttons of the lightbox in px. Range of values - from 1 to 20
lightboxControlGradientPoint 90 This value sets the transparency point for gradient of navigation and close buttons of the lightbox, in %.
Range of values - 0 to 100
lightboxControlNavAngle 70 This value sets the angle of the lightbox window navigation buttons in degrees. Range of values - 20 to 80
lightboxMobileViewPoint 768

The size of the viewport in px when the lightbox should be switched to the mobile layout.

For the adaptation ability there are two layouts of a lightbox: 'desktop' and 'mobile'. For example, if the value is set to 800, screens are larger than 800px will display a 'desktop' layout of the lightbox and smaller than 800px - 'mobile' layout

lightboxCaptionBgColor '#ffffff' Background color of the lightbox caption.
Only HEX format is allowed
lightboxCaptionTextColor null

Text color of the lightbox caption. By default, text color settings of the <body> tag will be applied.

Only HEX format is allowed

lightboxCaptionWidth 360

Width of the lightbox caption, in px.

In the 'mobile' layout of the lightbox the width of the caption is automatically adjusted according to the image width

lightboxCaptionMinHeight 360 Minimum height of the lightbox caption, in px.
Will be applied to 'desktop' lightbox layout
lightboxCaptionMinWidth 360 Minimum width of the lightbox caption, in px.
Will be applied to 'mobile' lightbox layout
lightboxShadowColor '#000000' Color of the lightbox content block shadow.
Only HEX format is allowed
lightboxShadowOpacity 60 Opacity level of the lightbox content block shadow, in %. Range of values - from 0 to 100
lightboxShadowSize 20

Size of the lightbox content block shadow, in px

This value also could be dynamically changed using breakpoints option

lightboxShadowOffsetX 0

Horizontal offset of the shadow, in %.
Range of values - from -100 to 100.

Positive value puts the shadow on the right side of the lightbox content block, negative value puts the shadow on the left side of the lightbox content block.

lightboxShadowOffsetY 20

Vertical offset of the shadow, in %.
Range of values - from -100 to 100

Positive value puts the shadow below the lightbox content block, negative value puts the shadow above the lightbox content block

BREAKPOINTS

Option Default Value Description
breakPoints breakPoints: { // when window width is <= 1024px 1024: { crslColumns: 4, navFontSize: 18, itemHoverFontSize: 30, itemShadowSize: 18 }, // when window width is <= 768px 768: { crslColumns: 3, navFontSize: 16, itemHoverFontSize: 20, itemShadowSize: 14, lightboxControlSize: 45 }, // when window width is <= 480px 480: { crslColumns: 2, navFontSize: 14, itemHoverFontSize: 16, itemShadowSize: 10, lightboxControlSize: 60, lightboxShadowSize: 10 } } This option allows to set different parameters for different responsive breakpoints (screen sizes). Following options can be changed: Feel free to change values or to add your own breakpoint. Let's say you need 5 columns in your gallery when window width will be less or equal to 800px. Add this code to the options: breakPoints: { 800: { crslColumns: 5 } }

DICTIONARY

Option Default Value Description
navPrevText 'Prev' The text of the carousel "Previous" navigation button
navNextText 'Next' The text of the carousel "Next" navigation button
itemHoverText 'View' Carousel slide hover text

PUBLIC METHODS

<script> $(document).ready(function(){ <!-- This is your gallery initialization code --> $("#my-diamond-gallery").diamondGallery(); <!-- Call method to start carousel autoplay --> $("#my-diamond-gallery").diamondGallery('start_autoplay'); <!-- Call method to open lightbox and show the image by index '1' --> $("#my-diamond-gallery").diamondGallery('lightbox_show_slide', 1); }); </script>
Method Argument Description
add_slide data

Appends slides to the gallery. Accepts HTML String or jQuery Object

For example: '<div data-img-dg="Image.jpg">Caption</div>'

remove_slide index

Removes slides. Provide slide index to remove a specific slide, or 'last' to remove the last one.

If no argument is provided, the method will remove all gallery slides

slide_prev - Navigates to the previous carousel index
slide_next - Navigates to the next carousel index
slide_to index Navigates the carousel to a provided index
start_autoplay - Starts carousel autoplay. Make sure that crslAutoSlide value is correct
stop_autoplay - Stops carousel autoplay
lightbox_show_slide index Opens a slide by index in the lightbox
lightbox_hide - Hides the lightbox
destroy - Removes all events and clears all gallery data

PUBLIC PROPERTIES

<script> $(document).ready(function(){ <!-- This is your gallery initialization code --> $("#my-diamond-gallery").diamondGallery(); <!-- Get the width of the carousel --> $("#my-diamond-gallery").diamondGallery('get_carousel_width'); <!-- Get the value of the 'fontFamily' option --> $("#my-diamond-gallery").diamondGallery('get_option', 'fontFamily'); }); </script>
Property Argument Description
get_carousel_index - Returns the current carousel index
get_carousel_width - Returns the width of the carousel
get_carousel_height - Returns the height of the carousel
get_slides_number - Returns the total number of slides in the gallery
get_slides - Returns an array that contains all the data for each slide
get_option option Returns an individual option value. If no argument is provided, returns a list of plugin options

EVENTS

<script> $(document).ready(function(){ <!-- This is your gallery initialization code --> $("#my-diamond-gallery").diamondGallery(); <!-- Set event listener to the slide click event --> $("#my-diamond-gallery").on('carousel_slide_click', function(event, index){ console.log(event.type, index); }); }); </script>
Event Argument Description
carousel_before_slide event
direction
currentIndex
nextIndex
Fires before the carousel starts the sliding animation
carousel_after_slide event
direction
Fires when the carousel sliding animation ends
carousel_start_reached event Fires when the carousel reached 0 index
carousel_end_reached event Fires when the carousel reached maximum index
carousel_slide_click event
index
Fires after clicking on the carousel slide
lightbox_open event
currentIndex
Fires when the lightbox opening animation ends
lightbox_close event Fires when the lightbox closing animation ends
lightbox_before_slide event
direction
currentIndex
nextIndex
Fires before the lightbox starts the sliding animation
lightbox_after_slide event
currentIndex
Fires when the lightbox sliding animation ends
reinit event Fires after every re-initialization
destroy event Fires when the plugin is destroyed

EASING FUNCTIONS

The easing functions denotes a mathematical function that describes how fast one-dimensional values change during animations. This lets you vary the animation's speed over the course of its duration. They can be used to smooth down the start and end of the animation.

For a better understanding, let's look at three different functions: linear, easeInSine and easeInOutSine to compare and describe them. In the graphs, the X axis represents the time and the Y axis - the output value:

linear

In the 'linear' function, the animation moves from the beginning to the end at a constant rate which means that the value will increase by an equal amount. In other words, if you need to move an object 10 pixels in 10 seconds and you use a linear function, that object will move 1 pixel every second.

easeInSine

In the 'easeInSine' function, the animation starts slowly, and then progressively speeds up until the end.

easeInOutSine

In the 'easeInOutSine' function, the animation starts slowly, accelerates sharply, and then slows gradually towards the end.

Here is a complete list of easing functions (except basic one - linear) that you can use in the Diamond Gallery.

easeInSine
easeOutSine
easeInOutSine
easeInQuad
easeOutQuad
easeInOutQuad
easeInCubic
easeOutCubic
easeInOutCubic
easeInQuart
easeOutQuart
easeInOutQuart
easeInQuint
easeOutQuint
easeInOutQuint
easeInExpo
easeOutExpo
easeInOutExpo
easeInCirc
easeOutCirc
easeInOutCirc
easeInBack
easeOutBack
easeInOutBack
easeInElastic
easeOutElastic
easeInOutElastic
easeInBounce
easeOutBounce
easeInOutBounce