Photo Browser

Photo Browser is an iOS like photo browser component to display collection of photos / images. Photos can be zoomed and panned (optional).

Photo Browser uses Swiper Slider component to slide between photos.

Create Photo Browser Instance

Photo Browser can be created and initialized only using JavaScript. We need to use related App's method:

myApp.photoBrowser(parameters) - initialize Photo Browser with parameters

  • parameters - object - object with Photo Browser parameters. Required.
  • Method returns initialized Photo Browser instance

For example:

var myPhotoBrowser = app.photoBrowser({
    zoom: 400,
    photos: ['path/to/image1.jpg', 'path/to/image2.jpg']
});   
myPhotoBrowser.open(); // open photo browser

Photo Browser Parameters

Let's look on list of all available parameters:

Parameter Type Default Description
photos array [] Array with URLs of photos or array of objects with "url" (or "html") and "caption" properties.
initialSlide number 0 Index number of initial photo slide.
spaceBetween number 20 Distance between photo slides in px.
speed number 300 Duration of transition between photo slides (in ms).
zoom boolean true Enable/disable ability to zoom and pan photos.
maxZoom number 3 Max zoom ratio.
minZoom number 1 Minimal zoom ratio.
exposition boolean true Enable disable exposition mode when clicking on Photo Browser.
expositionHideCaptions boolean false Set to true if you also want to hide captions in exposition mode
swipeToClose boolean true You can close Photo Browser with swipe up/down when this parameter is enabled
view View instance undefined Link to initialized View instance if you want use "page" Photo Browser type. By default, if not specified, it will be opened in Main View.
type string 'standalone' Define how Photo Browser should be opened. Could be 'standalone' (will be opened as an overlay with custom transition effect), 'popup' (will be opened as popup), 'page' (will be injected to View and loaded as a new page).
loop boolean false Set to "true" to enable continuous loop mode
theme string 'light' Photo Browser color theme, could be 'light' or 'dark'
captionsTheme string Captions color theme, could be also "dark" or "light". By default, equal to "theme" parameter
navbar boolean true Set to false to remove Photo Browser's Navbar
toolbar boolean true Set to false to remove Photo Browser's Toolbar
backLinkText string 'Close' Text on back link in Photo Browser's Navbar
ofText string 'of' Text of "of" in photos counter: "3 of 5"
Lazy Loading
lazyLoading boolean false Set to "true" to enable images lazy loading
lazyLoadingInPrevNext boolean false Set to "true" to enable lazy loading for the closest photos (for previous and next photos)
lazyLoadingOnTransitionStart boolean false By default, Photo Browser will load lazy photos after transition to this photo, so you may enable this parameter if you need it to load new photo in the beginning of transition
Templates
navbarTemplate string *Look below Navbar HTML template
toolbarTemplate string *Look below Toolbar HTML template
photoTemplate string *Look below Single photo element HTML template
lazyPhotoTemplate string *Look below Single lazy loading photo element HTML template
objectTemplate string *Look below Single object element HTML template
captionTemplate string *Look below Single caption element HTML template
Callbacks
onOpen(photobrowser) function Callback function, will be executed on photo browser open.
onClose(photobrowser) function Callback function, will be executed when user close photo browser.
onSwipeToClose(photobrowser) function Callback function, will be executed when user close photo browser with swipe up/down.
Swiper Callbacks
onSlideChangeStart(swiper) function Callback function, will be executed in the beginning of animation to other slide (next or previous). Receives Swiper instance as an argument.
onSlideChangeEnd(swiper) function Callback function, will be executed after animation to other slide (next or previous). Receives Swiper instance as an argument.
onTransitionStart(swiper) function Callback function, will be executed in the beginning of transition. Receives swiper instance as an argument.
onTransitionEnd(swiper) function Callback function, will be executed after transition. Receives slider instance as an argument.
onClick(swiper, event) function Callback function, will be executed when user click/tap on slider after 300ms delay. Receives Swiper instance and 'touchend' event as an arguments.
onTap(swiper, event) function Callback function, will be executed when user click/tap on slider. Receives Swiper instance and 'touchend' event as an arguments.
onDoubleTap(swiper, event) function Callback function, will be executed when user double tap on slider's container. Receives Swiper instance and 'touchend' event as an arguments.
onLazyImageLoad(swiper, slide, image) function Callback function, will be executed when Photo Browser begins to load lazy loading photo
onLazyImageReady(swiper, slide, image) function Callback function, will be executed after lazy loading photo will be loaded

Photo Browser Methods & Properties

After we initialize Photo Browser we have its initialized instance in variable (like myPhotoBrowser variable in example above) with helpful methods and properties:

Properties
myPhotoBrowser.swiper Contains initialized Swiper instance with all available Swiper methods and properties
myPhotoBrowser.container Dom7 element with Photo Browser container HTML element
myPhotoBrowser.exposed Contains "true" if Photo Browser in exposition mode
myPhotoBrowser.activeIndex Index number of currently active photo slide
myPhotoBrowser.params Object with passed initialization parameters
Methods
myPhotoBrowser.open(index); Open Photo Browser on photo with index number equal to "index" parameter. If "index" parameter is not specified, it will be opened on last closed photo.
myPhotoBrowser.close(); Close Photo Browser
myPhotoBrowser.toggleZoom(); Toggle zoom of currently active photo/slide
myPhotoBrowser.toggleExposition(); Toggle exposition mode
myPhotoBrowser.enableExposition(); Enable exposition mode
myPhotoBrowser.disableExposition(); Disable exposition mode

Photos Array

When we initialize Photo Browser we need to pass array with photos/videos in "photos" parameter. Let's look at different variations of this array:

// If we need photo browser with just photos we may pass array with string urls:
var photos = [
    'image1.jpg',
    'image2.jpg',
    'image3.jpg',
    'image4.jpg',
];
 
//If we need to use caption for some of photos then each photo should be presented as object:
var photos = [
    {
        url: 'image1.jpg',
        caption: 'Caption 1'
    },
    {
        url: 'image2.jpg',
        caption: 'Caption 1'
    },
    // This one will be without caption
    {
        url: 'image3.jpg',
    },
    // This one will be also without caption
    'image4.jpg'
];
 
//If we need to use videos in some slides we need to pass HTML element of video element or iframe within "html" property:
var photos = [
    {
        url: 'image1.jpg',
        caption: 'Caption 1'
    },
    // Video element with caption
    {
        html: '<video src="video1.mp4"></video>',
        caption: 'Video Caption'
    },
    // This one is embedded video without caption
    {
        html: '<iframe src="..."></iframe>',
    },
    // This one will be also video without caption
    '<video src="video2.mp4"></video>'
];        

Examples

<div class="page-content">
  <div class="content-block-title">Light Theme</div>
  <div class="content-block row">
    <div class="col-33"><a href="#" class="button pb-standalone">Standalone</a></div>
    <div class="col-33"><a href="#" class="button pb-popup">Popup</a></div>
    <div class="col-33"><a href="#" class="button pb-page">Page</a></div>
  </div>
  <div class="content-block-title">Dark Theme</div>
  <div class="content-block row">
    <div class="col-50"><a href="#" class="button pb-standalone-dark">Standalone</a></div>
    <div class="col-50"><a href="#" class="button pb-popup-dark">Popup</a></div>
  </div>
</div> 
          
var myApp = new Framework7(); 
 
var $$ = Dom7;
 
var mainView = myApp.addView('.view-main', {
  dynamicNavbar: true
});
 
/*=== Default standalone ===*/
var myPhotoBrowserStandalone = myApp.photoBrowser({
    photos : [
        'http://lorempixel.com/1024/1024/sports/1/',
        'http://lorempixel.com/1024/1024/sports/2/',
        'http://lorempixel.com/1024/1024/sports/3/',
    ]
});
//Open photo browser on click
$$('.pb-standalone').on('click', function () {
    myPhotoBrowserStandalone.open();
});
 
/*=== Popup ===*/
var myPhotoBrowserPopup = myApp.photoBrowser({
    photos : [
        'http://lorempixel.com/1024/1024/sports/1/',
        'http://lorempixel.com/1024/1024/sports/2/',
        'http://lorempixel.com/1024/1024/sports/3/',
    ],
    type: 'popup'
});
$$('.pb-popup').on('click', function () {
    myPhotoBrowserPopup.open();
});
 
/*=== As Page ===*/
var myPhotoBrowserPage = myApp.photoBrowser({
    photos : [
        'http://lorempixel.com/1024/1024/sports/1/',
        'http://lorempixel.com/1024/1024/sports/2/',
        'http://lorempixel.com/1024/1024/sports/3/',
    ],
    type: 'page',
    backLinkText: 'Back'
});
$$('.pb-page').on('click', function () {
    myPhotoBrowserPage.open();
});
 
/*=== Standalone Dark ===*/
var myPhotoBrowserDark = myApp.photoBrowser({
    photos : [
        'http://lorempixel.com/1024/1024/sports/1/',
        'http://lorempixel.com/1024/1024/sports/2/',
        'http://lorempixel.com/1024/1024/sports/3/',
    ],
    theme: 'dark'
});
$$('.pb-standalone-dark').on('click', function () {
    myPhotoBrowserDark.open();
});
 
/*=== Popup Dark ===*/
var myPhotoBrowserPopupDark = myApp.photoBrowser({
    photos : [
        'http://lorempixel.com/1024/1024/sports/1/',
        'http://lorempixel.com/1024/1024/sports/2/',
        'http://lorempixel.com/1024/1024/sports/3/',
    ],
    theme: 'dark',
    type: 'popup'
});
$$('.pb-popup-dark').on('click', function () {
    myPhotoBrowserPopupDark.open();
}); 
 
/*=== With Captions ===*/
var myPhotoBrowserPopupDark = myApp.photoBrowser({
    photos : [
        {
            url: 'http://lorempixel.com/1024/1024/sports/1/',
            caption: 'Caption 1 Text'
        },
        {
            url: 'http://lorempixel.com/1024/1024/sports/2/',
            caption: 'Second Caption Text'
        },
        // This one without caption
        {
            url: 'http://lorempixel.com/1024/1024/sports/3/',
        },
    ],
    theme: 'dark',
    type: 'standalone'
});
$$('.pb-standalone-captions').on('click', function () {
    myPhotoBrowserPopupDark.open();
});
 
/*=== With Video ===*/
var myPhotoBrowserPopupDark = myApp.photoBrowser({
    photos : [
        {
            html: '<iframe src="//www.youtube.com/embed/lmc21V-zBq0?list=PLpj0FBQgLGEr3mtZ5BTwtmSwF1dkPrPRM" frameborder="0" allowfullscreen></iframe>',
            caption: 'Woodkid - Run Boy Run (Official HD Video)'
        },
        {
            url: 'http://lorempixel.com/1024/1024/sports/2/',
            caption: 'Second Caption Text'
        },
        {
            url: 'http://lorempixel.com/1024/1024/sports/3/',
        },
    ],
    theme: 'dark',
    type: 'standalone'
});
$$('.pb-standalone-video').on('click', function () {
    myPhotoBrowserPopupDark.open();
});

Photo Browser Templates

Let's look at Photo Browser templates which you can pass on Photo Browser initialization

Navbar Template

Here is an example of Navbar template that you can pass in navbarTemplate parameter:

<div class="navbar">
    <div class="navbar-inner">
        <div class="left sliding">
            <a href="#" class="link close-popup photo-browser-close-link {{#unless backLinkText}}icon-only{{/unless}} {{js "this.type === \'page\' ? \'back\' : \'\'"}}">
                <i class="icon icon-back {{iconsColorClass}}"></i>
                {{#if backLinkText}}<span>{{backLinkText}}</span>{{/if}}
            </a>
        </div>
        <div class="center sliding">
            <span class="photo-browser-current"></span> 
            <span class="photo-browser-of">{{ofText}}</span> 
            <span class="photo-browser-total"></span>
        </div>
        <div class="right"></div>
    </div>
</div>  

Where:

  • <a class="photo-browser-close-link"> - link that will close Photo Browser on click. Not just close popup or page, but also detach all events listeners

  • <span class="photo-browser-current">. Photo Browser will insert index number currently active slide into element with photo-browser-current class

  • <span class="photo-browser-total">. Photo Browser will insert total number of slides/photos into element with photo-browser-total class

Toolbar Template

Example of Photo Browser's Toolbar template that you can pass in toolbarTemplate parameter:

<div class="toolbar tabbar">
    <div class="toolbar-inner">
        <a href="#" class="link photo-browser-prev">
            <i class="icon icon-prev {{iconsColorClass}}"></i>
        </a>
        <a href="#" class="link photo-browser-next">
            <i class="icon icon-next {{iconsColorClass}}"></i>
        </a>
    </div>
</div>

As you see it is actually tab bar, where:

  • <a class="photo-browser-next"> - link with photo-browser-next class works like next button

  • <a class="photo-browser-prev"> - link with photo-browser-prev class works like previous button

Photo Element Template

Template example of single photo slide element that you can pass in photoTemplate parameter:

<div class="photo-browser-slide swiper-slide">
    <span class="photo-browser-zoom-container">
        <img src="{{js "this.url || this"}}">
    </span>
</div>

Lazy Photo Element Template

Template example of single photo slide element that you can pass in lazyPhotoTemplate parameter:

<div class="photo-browser-slide photo-browser-slide-lazy swiper-slide">
    <div class="preloader {{@root.preloaderColorClass}}">{{#if @root.material}}{{@root.materialPreloaderSvg}}{{/if}}</div>
    <span class="photo-browser-zoom-container">
        <img data-src="{{js "this.url || this"}}" class="swiper-lazy">
    </span>
</div>

Object Element Template

Template example of single object slide element that you can pass in objectTemplate parameter:

<div class="photo-browser-slide photo-browser-object-slide swiper-slide">{{js "this.html || this"}}</div>

Single Caption Template

Template example of single caption element. You can pass in captionTemplate parameter:

<div class="photo-browser-caption" data-caption-index="{{@index}}">
    {{caption}}
</div>