Photo Browser
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. |
thumbs | array | [] | Array with URLs of thumbs images. Will not render thumbs if not specified, or empty array |
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 |
popupPush | boolean | false | Enables Photo Browser popup to push view/s behind on open |
routableModals | boolean | false | 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 |
pageBackLinkText | string | Back | Text on back link in Photo Browser's navbar |
popupCloseLinkText | string | Close | Text on close link in Photo Browser's navbar when opened in Popup or as Standalone |
navbarShowCount | boolean | undefined | Defines should it display "3 of 5" text in navbar title or not. If not specified (undefined) then it will show this text if there is more than 1 item |
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:
| |
virtualSlides | boolean | true | When enabled then Swiper will use Virtual Slides |
closeByBackdropClick | boolean | true | When enabled, Photo Browser popup will be closed on backdrop click |
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:
|
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: 'Second Caption'
},
// 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 |
photobrowser:beforedestroy | Photo Browser Element | Event will be triggered right before Photo Browser instance will be destroyed |
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. 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 |
doubleClick | 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).
:root {
--f7-photobrowser-bg-color: #fff;
--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: 13px;
--f7-photobrowser-caption-font-weight: 500;
--f7-photobrowser-caption-light-text-color: #000;
--f7-photobrowser-caption-dark-text-color: #fff;
--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
<template>
<div class="page">
<div class="navbar">
<div class="navbar-bg"></div>
<div class="navbar-inner sliding">
<div class="title">Photo Browser</div>
</div>
</div>
<div class="page-content">
<div class="block block-strong-ios block-outline-ios">
<p>Photo Browser is a standalone and highly configurable component that allows to open window with photo viewer
and navigation elements with the following features:</p>
<ul>
<li>Swiper between photos</li>
<li>Multi-gestures support for zooming</li>
<li>Toggle zoom by double tap on photo</li>
<li>Single click on photo to toggle Exposition mode</li>
</ul>
</div>
<div class="block block-strong-ios block-outline-ios">
<p>Photo Browser could be opened in a three ways - as a Standalone component (Popup modification), in Popup, and
as separate Page:</p>
<div class="grid grid-cols-3 grid-gap">
<a class="button button-fill" @click=${openStandalone}>Standalone</a>
<a class="button button-fill" @click=${openPopup}>Popup</a>
<a class="button button-fill" @click=${openPage}>Page</a>
</div>
</div>
<div class="block block-strong-ios block-outline-ios">
<p>Photo Browser supports 2 default themes - default Light (like in previous examples) and Dark theme. Here is a
Dark theme examples:</p>
<div class="grid grid-cols-3 grid-gap">
<a class="button button-fill" @click=${openStandaloneDark}>Standalone</a>
<a class="button button-fill" @click=${openPopupDark}>Popup</a>
<a class="button button-fill" @click=${openPageDark}>Page</a>
</div>
</div>
</div>
</div>
</template>
<script>
export default (props, { $f7, $on }) => {
const photos = [
{
url: 'img/beach.jpg',
caption: 'Amazing beach in Goa, India'
},
'http://placekitten.com/1024/1024',
'img/lock.jpg',
{
url: 'img/monkey.jpg',
caption: 'I met this monkey in Chinese mountains'
},
{
url: 'img/mountains.jpg',
caption: 'Beautiful mountains in Zhangjiajie, China'
}
];
const thumbs = [
'img/beach.jpg',
'http://placekitten.com/1024/1024',
'img/lock.jpg',
'img/monkey.jpg',
'img/mountains.jpg'
]
let standalone;
let popup;
let page;
let standaloneDark;
let popupDark;
let pageDark;
const openStandalone = () => {
standalone.open();
}
const openPopup = () => {
popup.open();
}
const openPage = () => {
page.open();
}
const openStandaloneDark = () => {
standaloneDark.open();
}
const openPopupDark = () => {
popupDark.open();
}
const openPageDark = () => {
pageDark.open();
}
$on('pageInit', () => {
// Create PBs when page init
standalone = $f7.photoBrowser.create({
photos: photos,
thumbs: thumbs,
});
popup = $f7.photoBrowser.create({
photos: photos,
thumbs: thumbs,
type: 'popup',
});
page = $f7.photoBrowser.create({
photos: photos,
thumbs: thumbs,
type: 'page',
backLinkText: 'Back',
});
standaloneDark = $f7.photoBrowser.create({
photos: photos,
thumbs: thumbs,
theme: 'dark',
});
popupDark = $f7.photoBrowser.create({
photos: photos,
thumbs: thumbs,
type: 'popup',
theme: 'dark',
});
pageDark = $f7.photoBrowser.create({
photos: photos,
thumbs: thumbs,
type: 'page',
backLinkText: 'Back',
theme: 'dark',
});
});
$on('pageBeforeRemove', () => {
// Destroy PBs on page remove
standalone.destroy();
popup.destroy();
page.destroy();
standaloneDark.destroy();
popupDark.destroy();
pageDark.destroy();
});
return $render;
};
</script>