WebSVN – scratch – Blame – Rev 115 – /bower_components/blueimp-gallery/README.md

        data-sources='[{"href": "https://example.org/videos/fruits.mp4", "type": "video/mp4"}, {"href": "https://example.org/videos/fruits.ogg", "type": "video/ogg"}]'

687

>Fruits</a>

688

</div>

```

#### YouTube

The Gallery can display [YouTube](https://www.youtube.com/) videos for Gallery

693

items with a **type** of **text/html** and a **youtube** property

694

(configurable via [YouTube options](#youtube-options)) with the YouTube

video-ID:

```js

blueimp.Gallery([

{

title: 'A YouYube video',

701

href: 'https://www.youtube.com/watch?v=VIDEO_ID',

702

type: 'text/html',

703

youtube: 'VIDEO_ID',

704

poster: 'https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg'

},

{

title: 'Banana',

href: 'https://example.org/images/banana.jpg',

709

type: 'image/jpeg',

710

thumbnail: 'https://example.org/thumbnails/banana.jpg'

}

]);

```

If the `href` and `poster` properties are undefined, they are set automatically

716

based on the video ID.

717

718

Please note that the Gallery YouTube integration requires a browser with

719

[postMessage](https://developer.mozilla.org/en-US/docs/Web/API/window.postMessage)

720

support, which excludes IE7.

721

722

#### Vimeo

723

The Gallery can display [Vimeo](https://vimeo.com/) videos for Gallery items

724

with a **type** of **text/html** and a **vimeo** property

725

(configurable via [Vimeo options](#vimeo-options)) with the Vimeo video-ID:

```js

blueimp.Gallery([

{

title: 'A Vimeo video',

731

href: 'https://vimeo.com/VIDEO_ID',

732

type: 'text/html',

733

vimeo: 'VIDEO_ID',

734

poster: 'https://secure-b.vimeocdn.com/ts/POSTER_ID.jpg'

},

{

title: 'Banana',

href: 'https://example.org/images/banana.jpg',

739

type: 'image/jpeg',

740

thumbnail: 'https://example.org/thumbnails/banana.jpg'

}

]);

```

If the `href` property is undefined, it is set automatically based on the

746

video ID.

747

748

Please note that the Gallery Vimeo integration requires a browser with

749

[postMessage](https://developer.mozilla.org/en-US/docs/Web/API/window.postMessage)

750

support, which excludes IE7.

751

752

### Additional Gallery elements

753

It is possible to add additional elements to the Gallery widget, e.g. a

754

description label.

755

756

First, add the desired HTML element to the Gallery widget:

757

758

```html

759

<div id="blueimp-gallery" class="blueimp-gallery">

760

<div class="slides"></div>

761

<h3 class="title"></h3>

762

763

<p class="description"></p>

764

<a class="prev">‹</a>

765

<a class="next">›</a>

766

<a class="close">×</a>

767

<a class="play-pause"></a>

768

<ol class="indicator"></ol>

</div>

```

Next, add the desired element styles to your CSS file:

773

774

```css

775

.blueimp-gallery > .description {

776

position: absolute;

top: 30px;

left: 15px;

color: #fff;

display: none;

}

.blueimp-gallery-controls > .description {

display: block;

}

```

Then, add the additional element information to each of your links:

```html

<div id="links">

<a href="images/banana.jpg" title="Banana" data-description="This is a banana.">Banana</a>

792

<a href="images/apple.jpg" title="Apple" data-description="This is an apple.">Apple</a>

</div>

```

Finally, initialize the Gallery with an onslide callback option, to set the

797

element content based on the information from the current link:

```js

blueimp.Gallery(

document.getElementById('links'),

802

{

803

onslide: function (index, slide) {

804

var text = this.list[index].getAttribute('data-description'),

805

node = this.container.find('.description');

806

node.empty();

807

if (text) {

808

node[0].appendChild(document.createTextNode(text));

}

}

}

);

```

### Additional content types

816

By extending the Gallery prototype with new factory methods, additional content

817

types can be displayed. By default, blueimp Gallery provides the

818

**imageFactory** and **videoFactory** methods for **image** and **video**

819

content types respectively.

820

821

The Gallery uses the **type** property of each content object to determine which

822

factory method to use. The **type** defines the

823

[Internet media type](https://en.wikipedia.org/wiki/Internet_media_type) of the

824

content object and is composed of two or more parts: A type, a subtype, and zero

825

or more optional parameters, e.g. **text/html; charset=UTF-8** for an HTML

826

document with UTF-8 encoding.

827

The main type (the string in front of the slash, **text** in the example above)

828

is concatenated with the string **Factory** to create the factory method name,

829

e.g. **textFactory**.

830

831

#### Example HTML text factory implementation

832

Please note that the textFactory script has to be included after the core

833

Gallery script, but before including the [YouTube](#youtube) and [Vimeo](#vimeo)

834

integration plugins, which extend the textFactory implementation to handle

835

YouTube and Vimeo video links.

836

837

Please also note that although blueimp Gallery doesn't require

838

[jQuery](https://jquery.com/), the following example uses it for convenience.

839

840

Extend the Gallery prototype with the **textFactory** method:

841

842

```js

843

blueimp.Gallery.prototype.textFactory = function (obj, callback) {

844

var $element = $('<div>')

845

.addClass('text-content')

846

.attr('title', obj.title);

847

$.get(obj.href)

848

.done(function (result) {

849

$element.html(result);

850

callback({

851

type: 'load',

852

target: $element[0]

853

});

854

})

855

.fail(function () {

856

callback({

857

type: 'error',

858

target: $element[0]

859

});

860

});

861

return $element[0];

};

```

Next, add the **text-content** class to the Gallery CSS:

866

867

```css

868

.blueimp-gallery > .slides > .slide > .text-content {

overflow: auto;

margin: 60px auto;

padding: 0 60px;

max-width: 920px;

text-align: left;

}

```

With the previous changes in place, the Gallery can now handle HTML content

types:

```js

blueimp.Gallery([

{

title: 'Noodle soup',

884

href: 'https://example.org/text/noodle-soup.html',

type: 'text/html'

},

{

title: 'Tomato salad',

889

href: 'https://example.org/text/tomato-salad.html',

type: 'text/html'

}

]);

```

### jQuery plugin

#### jQuery plugin setup

898

The blueimp Gallery jQuery plugin registers a global click handler to open links

899

with **data-gallery** attribute in the Gallery lightbox.

900

901

To use it, follow the [lightbox setup](#lightbox-setup) guide, but replace the

902

minified Gallery script with the jQuery plugin version and include it after

903

including [jQuery](https://jquery.com/):

904

905

```html

906

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>

907

<script src="js/jquery.blueimp-gallery.min.js"></script>

908

```

909

910

Next, add the attribute **data-gallery** to your Gallery links:

```html

<div id="links">

<a href="images/banana.jpg" title="Banana" data-gallery>

915

<img src="images/thumbnails/banana.jpg" alt="Banana">

916

</a>

917

<a href="images/apple.jpg" title="Apple" data-gallery>

918

<img src="images/thumbnails/apple.jpg" alt="Apple">

919

</a>

920

<a href="images/orange.jpg" title="Orange" data-gallery>

921

<img src="images/thumbnails/orange.jpg" alt="Orange">

</a>

</div>

```

The onclick handler from the [lightbox setup](#lightbox-setup) guide is not

927

required and can be removed.

928

929

#### HTML5 data-attributes

930

Options for the Gallery lightbox opened via the jQuery plugin can be defined as

931

[HTML5 data-attributes](https://api.jquery.com/data/#data-html5) on the Gallery

932

widget container.

933

934

The jQuery plugin also introduces the additional **filter** option, which is

935

applied to the Gallery links via

936

[jQuery's filter method](https://api.jquery.com/filter/) and allows to remove

937

duplicates from the list:

938

939

```html

940

<div id="blueimp-gallery" class="blueimp-gallery" data-start-slideshow="true" data-filter=":even">

941

<div class="slides"></div>

942

<h3 class="title"></h3>

943

<a class="prev">‹</a>

944

<a class="next">›</a>

945

<a class="close">×</a>

946

<a class="play-pause"></a>

947

<ol class="indicator"></ol>

</div>

```

This will initialize the Gallery with the option **startSlideshow** set to

952

**true**.

953

It will also filter the Gallery links so that only links with an even index

954

number will be included.

955

956

#### Container ids and link grouping

957

If the **data-gallery** attribute value is a valid id string

958

(e.g. "#blueimp-gallery"), it is used as container option.

959

Setting **data-gallery** to a non-empty string also allows to group links into

960

different sets of Gallery images:

```html

<div id="fruits">

<a href="images/banana.jpg" title="Banana" data-gallery="#blueimp-gallery-fruits">

965

<img src="images/thumbnails/banana.jpg" alt="Banana">

966

</a>

967

<a href="images/apple.jpg" title="Apple" data-gallery="#blueimp-gallery-fruits">

968

<img src="images/thumbnails/apple.jpg" alt="Apple">

969

</a>

970

</div>

971

<div id="vegetables">

972

<a href="images/tomato.jpg" title="Tomato" data-gallery="#blueimp-gallery-vegetables">

973

<img src="images/thumbnails/tomato.jpg" alt="Tomato">

974

</a>

975

<a href="images/onion.jpg" title="Onion" data-gallery="#blueimp-gallery-vegetables">

976

<img src="images/thumbnails/onion.jpg" alt="Onion">

</a>

</div>

```

This will open the links with the **data-gallery** attribute

982

**#blueimp-gallery-fruits** in the Gallery widget with the id

983

**blueimp-gallery-fruits**, and the links with the **data-gallery** attribute

984

**#blueimp-gallery-vegetables** in the Gallery widget with the id

985

**blueimp-gallery-vegetables**.

986

987

#### Gallery object

988

The gallery object is stored via

989

[jQuery data storage](https://api.jquery.com/category/miscellaneous/data-storage/)

990

on the Gallery widget when the Gallery is opened and can be retrieved the

following way:

```js

var gallery = $('#blueimp-gallery').data('gallery');

995

```

996

997

This gallery object provides all methods outlined in the API methods section.

998

999

#### jQuery events

1000

The jQuery plugin triggers Gallery events on the widget container, with event

1001

names equivalent to the gallery [event callbacks](#event-callbacks):

1002

1003

```js

1004

$('#blueimp-gallery')

1005

.on('open', function (event) {

1006

// Gallery open event handler

1007

})

1008

.on('opened', function (event) {

1009

// Gallery opened event handler

1010

})

1011

.on('slide', function (event, index, slide) {

1012

// Gallery slide event handler

1013

})

1014

.on('slideend', function (event, index, slide) {

1015

// Gallery slideend event handler

1016

})

1017

.on('slidecomplete', function (event, index, slide) {

1018

// Gallery slidecomplete event handler

1019

})

1020

.on('close', function (event) {

1021

// Gallery close event handler

1022

})

1023

.on('closed', function (event) {

1024

// Gallery closed event handler

});

```

## Requirements

blueimp Gallery doesn't require any other libraries and can be used standalone

1030

without any dependencies.

1031

1032

You can also use the individual source files instead of the standalone minified

version:

```html

<link rel="stylesheet" href="css/blueimp-gallery.css">

1037

<link rel="stylesheet" href="css/blueimp-gallery-indicator.css">

1038

<link rel="stylesheet" href="css/blueimp-gallery-video.css">

1039

1040

<script src="js/blueimp-helper.js"></script>

1041

<script src="js/blueimp-gallery.js"></script>

1042

<script src="js/blueimp-gallery-fullscreen.js"></script>

1043

<script src="js/blueimp-gallery-indicator.js"></script>

1044

<script src="js/blueimp-gallery-video.js"></script>

1045

<script src="js/blueimp-gallery-youtube.js"></script>

1046

<script src="js/blueimp-gallery-vimeo.js"></script>

1047

```

1048

1049

The helper script can be replaced by [jQuery](https://jquery.com/) v. 1.7+.

1050

The fullscreen, indicator, video, youtube and vimeo source files are optional if

1051

their functionality is not required.

1052

1053

The [jQuery plugin](#jquery-plugin) requires

1054

[jQuery](https://jquery.com/) v. 1.7+ and the basic Gallery script, while the

1055

fullscreen, indicator, video, youtube and vimeo source files are also optional:

1056

1057

```html

1058

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

1059

<script src="js/blueimp-gallery.js"></script>

1060

<script src="js/blueimp-gallery-fullscreen.js"></script>

1061

<script src="js/blueimp-gallery-indicator.js"></script>

1062

<script src="js/blueimp-gallery-video.js"></script>

1063

<script src="js/blueimp-gallery-youtube.js"></script>

1064

<script src="js/blueimp-gallery-vimeo.js"></script>

1065

<script src="js/jquery.blueimp-gallery.js"></script>

1066

```

1067

1068

Please note that the jQuery plugin is an optional extension and not required for

1069

the Gallery functionality.

1070

1071

## Browsers

1072

blueimp Gallery has been tested with and supports the following browsers:

1073

1074

### Desktop browsers

1075

1076

* Google Chrome 14.0+

1077

* Apple Safari 4.0+

1078

* Mozilla Firefox 4.0+

1079

* Opera 10.0+

1080

* Microsoft Internet Explorer 7.0+

1081

1082

### Mobile browsers

1083

1084

* Apple Safari on iOS 6.0+

1085

* Google Chrome on iOS 6.0+

1086

* Google Chrome on Android 4.0+

1087

* Default Browser on Android 2.3+

1088

* Opera Mobile 12.0+

1089

1090

## License

1091

Released under the [MIT license](https://opensource.org/licenses/MIT).

1092

1093

## Credits

1094

The swipe implementation is based on code from the

1095

[Swipe](http://swipejs.com/) library.

scratch – Blame information for rev 115