Photo Browser

Photo Browser App Methods
Photo Browser Parameters

Photos Array

Photo Browser Methods & Properties
Photo Browser Events

DOM Events
App and Photo Browser Instance Events

CSS Variables
Examples

Photo Browser is a 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.

Photo Browser App Methods

Let's look at related App methods to work with Photo Browser:

app.photoBrowser.create(parameters)- create Photo Browser instance

parameters - object. Object with photo browser parameters

Method returns created Photo Browser's instance

app.photoBrowser.destroy(el)- destroy Photo Browser instance

el - HTMLElement or string (with CSS Selector) or object. Photo Browser element or Photo Browser instance to destroy.

app.photoBrowser.get(el)- get Photo Browser instance by HTML element

el - HTMLElement or string (with CSS Selector). Photo Browser element.

Method returns Photo Browser's instance

For example:

var photoBrowser = app.photoBrowser.create({
  photos: [
    'path/to/photo-1.jpg',
    'path/to/photo-2.jpg'
  ],
});

Photo Browser Parameters

Let's look on list of all available Photo Browser parameters:

Parameter	Type	Default	Description
photos	array	[]	Array with URLs of photos or array of objects with "url" (or "html") and "caption" properties.
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
routableModals	boolean	true	Will add opened photo browser to router history which gives ability to close photo browser by going back in router history and set current route to the photo browser modal
url	string	photos/	Photo browser modal URL that will be set as a current route
view	object		Link to initialized View instance if you want use "page" Photo Browser type or where to set routing when `routableModals` enabled. 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).
theme	string	light	Photo Browser color theme, could be `light` or `dark`
captionsTheme	string		Captions color theme, could be also `light` or `dark`. 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
navbarOfText	string	'of'	Text of "of" in photos counter: "3 of 5"
iconsColor	string		One of the default colors
swiper	object		Swiper parameters. By default equals to: `swiper: { initialSlide: 0, spaceBetween: 20, speed: 300, loop: false, preloadImages: true, navigation: { nextEl: '.photo-browser-next', prevEl: '.photo-browser-prev', }, zoom: { enabled: true, maxRatio: 3, minRatio: 1, }, lazy: { enabled: true, }, },`
Render functions
renderNavbar	function		Function to render navbar, must return navbar HTML string
renderToolbar	function		Function to render toolbar, must return toolbar HTML string
renderCaption	function(caption, index)		Function to render single caption, must return caption HTML string
renderObject	function(photo, index)		Function to render photo object, must return photo object HTML string
renderLazyPhoto	function(photo, index)		Function to render lazy loaded photo slide, must return slide HTML string
renderPhoto	function(photo, index)		Function to render photo as a swiper slide, must return slide HTML string
renderPage	function		Function to render photobrowser page, must return full page HTML layout string
renderPopup	function		Function to render photobrowser popup, must return full popup HTML layout string
renderStandalone	function		Function to render photobrowser standalone modal, must return full modal HTML layout string
Events
on	object		Object with events handlers. For example: `var photoBrowser = app.photoBrowser.create({ ... on: { opened: function () { console.log('photo browser opened') } } })`

Note that all following parameters can be used in global app parameters under photoBrowser property to set defaults for all photo browsers. For example:

var app = new Framework7({
  photoBrowser: {
    type: 'popup',
  }
});

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>'
];

Photo Browser Methods & Properties

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

Properties
photoBrowser.app	Link to global app instance
photoBrowser.el	Photo Browser HTML element
photoBrowser.$el	Dom7 instance with Photo Browser HTML element
photoBrowser.activeIndex	Index number of currently active photo slide
photoBrowser.exposed	`true` if Photo Browser in exposition mode
photoBrowser.opened	`true` if Photo Browser is currently opened
photoBrowser.url	Photo Browser URL (that was passed in `url` parameter)
photoBrowser.view	Photo Browser View (that was passed in `view` parameter) or found parent view
photoBrowser.swiper	Contains initialized Swiper instance with all available Swiper methods and properties
photoBrowser.params	Object with initialization parameters
Methods
photoBrowser.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.
photoBrowser.close()	Close Photo Browser
photoBrowser.expositionToggle()	Toggle exposition mode
photoBrowser.expositionEnable()	Enable exposition mode
photoBrowser.expositionDisable()	Disable exposition mode
photoBrowser.destroy()	Destroy photo browser instance
photoBrowser.on(event, handler)	Add event handler
photoBrowser.once(event, handler)	Add event handler that will be removed after it was fired
photoBrowser.off(event, handler)	Remove event handler
photoBrowser.off(event)	Remove all handlers for specified event
photoBrowser.emit(event, ...args)	Fire event on instance

Photo Browser Events

Photo Browser will fire the following DOM events on photo browser element and events on app and photo browser instance:

DOM Events

Event	Target	Description
photobrowser:open	Photo Browser Element	Event will be triggered when Photo Browser starts its opening animation
photobrowser:opened	Photo Browser Element	Event will be triggered after Photo Browser completes its opening animation
photobrowser:close	Photo Browser Element	Event will be triggered when Photo Browser starts its closing animation
photobrowser:closed	Photo Browser Element	Event will be triggered after Photo Browser completes its closing animation

App and Photo Browser Instance Events

Photo Browser instance emits events on both self instance and app instance. App instance events has same names prefixed with photoBrowser.

Event	Target	Description
swipeToClose	photoBrowser	Event will be fired when user close photo browser with swipe up/down.
tap	photoBrowser	Swiper event. Event will be fired when user click/tap on Swiper. Receives 'touchend' event as an arguments.
click	photoBrowser	Swiper event. Event will be fired when user click/tap on Swiper after 300ms delay. Receives 'touchend' event as an arguments.
doubleTap	photoBrowser	Swiper event. Event will be fired when user double tap on Swiper's container. Receives 'touchend' event as an arguments
slideChange	photoBrowser	Swiper event. Event will be fired when currently active slide is changed
transitionStart	photoBrowser	Swiper event. Event will be fired in the beginning of transition.
transitionEnd	photoBrowser	Swiper event. Event will be fired after transition.
slideChangeTransitionStart	photoBrowser	Swiper event. Event will be fired in the beginning of animation to other slide (next or previous).
slideChangeTransitionEnd	photoBrowser	Swiper event. Event will be fired after animation to other slide (next or previous).
lazyImageLoad	photoBrowser	Swiper event. Event will be fired in the beginning of lazy loading of image
lazyImageReady	photoBrowser	Swiper event. Event will be fired when lazy loading image will be loaded
touchStart	photoBrowser	Swiper event. Event will be fired when user touch Swiper. Receives 'touchstart' event as an arguments.
touchMoveOpposite	photoBrowser	Swiper event. Event will be fired when user touch and move finger over Swiper in direction opposite to direction parameter. Receives 'touchmove' event as an arguments.
touchEnd	photoBrowser	Swiper event. Event will be fired when user release Swiper. Receives 'touchend' event as an arguments.
open	photoBrowser	Event will be triggered when Photo Browser starts its opening animation. As an argument event handler receives photoBrowser instance
photoBrowserOpen	app
opened	photoBrowser	Event will be triggered after Photo Browser completes its opening animation. As an argument event handler receives photoBrowser instance
photoBrowserOpened	app
close	photoBrowser	Event will be triggered when Photo Browser starts its closing animation. As an argument event handler receives photoBrowser instance
photoBrowserClose	app
closed	photoBrowser	Event will be triggered after Photo Browser completes its closing animation. As an argument event handler receives photoBrowser instance
photoBrowserClosed	app
beforeDestroy	photoBrowser	Event will be triggered right before Photo Browser instance will be destroyed. As an argument event handler receives photoBrowser instance
photoBrowserBeforeDestroy	app

CSS Variables

Below is the list of related CSS variables (CSS custom properties).

Note that commented variables are not specified by default and their values is what they fallback to in this case.

:root {
  --f7-photobrowser-bg-color: #fff;
  --f7-photobrowser-bars-bg-image: none;
  /*
  --f7-photobrowser-bars-bg-color: rgba(var(--f7-bars-bg-color-rgb), 0.95);
  --f7-photobrowser-bars-text-color: var(--f7-bars-text-color);
  --f7-photobrowser-bars-link-color: var(--f7-bars-link-color);
  */
  --f7-photobrowser-caption-font-size: 14px;
  --f7-photobrowser-caption-light-text-color: #000;
  --f7-photobrowser-caption-light-bg-color: rgba(255, 255, 255, 0.8);
  --f7-photobrowser-caption-dark-text-color: #fff;
  --f7-photobrowser-caption-dark-bg-color: rgba(0, 0, 0, 0.8);
  --f7-photobrowser-exposed-bg-color: #000;
  --f7-photobrowser-dark-bg-color: #000;
  --f7-photobrowser-dark-bars-bg-color: rgba(27, 27, 27, 0.8);
  --f7-photobrowser-dark-bars-text-color: #fff;
  --f7-photobrowser-dark-bars-link-color: #fff;
}

Examples

<div class="page-content">
  <div class="block-title">Light Theme</div>
  <div class="block row">
    <div class="col-33"><a href="#" class="button button-fill pb-standalone">Standalone</a></div>
    <div class="col-33"><a href="#" class="button button-fill pb-popup">Popup</a></div>
    <div class="col-33"><a href="#" class="button button-fill pb-page">Page</a></div>
  </div>
  <div class="block-title">Dark Theme</div>
  <div class="block row">
    <div class="col-50"><a href="#" class="button button-fill pb-standalone-dark">Standalone</a></div>
    <div class="col-50"><a href="#" class="button button-fill pb-popup-dark">Popup</a></div>
  </div>
</div>

var app = new Framework7();

var $$ = Dom7;


/*=== Default standalone ===*/
var myPhotoBrowserStandalone = app.photoBrowser.create({
    photos : [
        'https://cdn.framework7.io/placeholder/sports-1024x1024-1.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-2.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-3.jpg',
    ]
});
//Open photo browser on click
$$('.pb-standalone').on('click', function () {
    myPhotoBrowserStandalone.open();
});

/*=== Popup ===*/
var myPhotoBrowserPopup = app.photoBrowser.create({
    photos : [
        'https://cdn.framework7.io/placeholder/sports-1024x1024-1.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-2.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-3.jpg',
    ],
    type: 'popup'
});
$$('.pb-popup').on('click', function () {
    myPhotoBrowserPopup.open();
});

/*=== As Page ===*/
var myPhotoBrowserPage = app.photoBrowser.create({
    photos : [
        'https://cdn.framework7.io/placeholder/sports-1024x1024-1.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-2.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-3.jpg',
    ],
    type: 'page',
    backLinkText: 'Back'
});
$$('.pb-page').on('click', function () {
    myPhotoBrowserPage.open();
});

/*=== Standalone Dark ===*/
var myPhotoBrowserDark = app.photoBrowser.create({
    photos : [
        'https://cdn.framework7.io/placeholder/sports-1024x1024-1.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-2.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-3.jpg',
    ],
    theme: 'dark'
});
$$('.pb-standalone-dark').on('click', function () {
    myPhotoBrowserDark.open();
});

/*=== Popup Dark ===*/
var myPhotoBrowserPopupDark = app.photoBrowser.create({
    photos : [
        'https://cdn.framework7.io/placeholder/sports-1024x1024-1.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-2.jpg',
        'https://cdn.framework7.io/placeholder/sports-1024x1024-3.jpg',
    ],
    theme: 'dark',
    type: 'popup'
});
$$('.pb-popup-dark').on('click', function () {
    myPhotoBrowserPopupDark.open();
});

/*=== With Captions ===*/
var myPhotoBrowserPopupDark = app.photoBrowser.create({
    photos : [
        {
            url: 'https://cdn.framework7.io/placeholder/sports-1024x1024-1.jpg',
            caption: 'Caption 1 Text'
        },
        {
            url: 'https://cdn.framework7.io/placeholder/sports-1024x1024-2.jpg',
            caption: 'Second Caption Text'
        },
        // This one without caption
        {
            url: 'https://cdn.framework7.io/placeholder/sports-1024x1024-3.jpg',
        },
    ],
    theme: 'dark',
    type: 'standalone'
});
$$('.pb-standalone-captions').on('click', function () {
    myPhotoBrowserPopupDark.open();
});

/*=== With Video ===*/
var myPhotoBrowserPopupDark = app.photoBrowser.create({
    photos : [
        {
            html: '<iframe src="//www.youtube.com/embed/lmc21V-zBq0" frameborder="0" allowfullscreen></iframe>',
            caption: 'Woodkid - Run Boy Run (Official HD Video)'
        },
        {
            url: 'https://cdn.framework7.io/placeholder/sports-1024x1024-2.jpg',
            caption: 'Second Caption Text'
        },
        {
            url: 'https://cdn.framework7.io/placeholder/sports-1024x1024-3.jpg',
        },
    ],
    theme: 'dark',
    type: 'standalone'
});
$$('.pb-standalone-video').on('click', function () {
    myPhotoBrowserPopupDark.open();
});