Panel / Side Panels
- Panel Layout
- Panel App Methods
- Panel Parameters
- Panel Methods & Properties
- Panel Events
- Panel Auto Initialization
- Control Panel With Links
- Routable Panels
- CSS Variables
- Examples
Panel Layout
Let's look how to add Side Panels to our App. We may include up to 2 panels to our App, one on left side and another one on right side. We should add panels' HTML right in the beginning of the app root element (or <body>
in case there is no root element in use):
<body>
<!-- App root element -->
<div id="app">
<!-- Left panel -->
<div class="panel panel-left">
... panel content goes here ...
</div>
<!-- Right panel -->
<div class="panel panel-right">
... panel content goes here ...
</div>
...
</div>
</body>
After we added panels we need to choose opening effect for each panel. There could be one of two effects: "Reveal" (when panel moves out whole app's content) or "Cover" (when panel overlays app's content). If you want to use "Reveal" effect you should add additional panel-reveal
class to Panel, or panel-cover
for cover effect:
<body>
<!-- App root element -->
<div id="app">
<!-- Left panel, let it be with reveal effect -->
<div class="panel panel-left panel-reveal">
... panel content goes here ...
</div>
<!-- Right panel, with cover effect -->
<div class="panel panel-right panel-cover">
... panel content goes here ...
</div>
...
</div>
</body>
Each Panel can be resizable. To make Panel resizable we just need to add panel-resizable
class to Panel element:
<body>
<!-- App root element -->
<div id="app">
<!-- Make left panel resizable -->
<div class="panel panel-left panel-resizable">
... panel content goes here ...
</div>
<!-- Make right panel resizable -->
<div class="panel panel-right panel-resizable">
... panel content goes here ...
</div>
...
</div>
</body>
Panel App Methods
Let's look at related App methods to work with Panel:
app.panel.create(parameters)- create Panel instance
- parameters - object. Object with panel parameters
Method returns created Panel's instance
app.panel.destroy(el)- destroy Panel instance
- el - HTMLElement or string (with CSS Selector) or object. Panel element or Panel instance to destroy.
app.panel.get(el)- get Panel instance by HTML element
- el - HTMLElement or string (with CSS Selector). Panel element.
Method returns Panel's instance
app.panel.open(panel, animate)- open panel
- panel - HTMLElement or string (with CSS Selector) of panel element to open
- animate - boolean. Should it be opened with animation or not. Optional, by default is
true
app.panel.close(panel, animate)- close panel
- panel - HTMLElement or string (with CSS Selector) of panel element to close
- animate - boolean. Should it be closed with animation or not. Optional, by default is
true
app.panel.toggle(panel, animate)- toggle panel
- panel - HTMLElement or string (with CSS Selector) of panel element to toggle
- animate - boolean. Should it be opened/closed with animation or not. Optional, by default is
true
Panel Parameters
If we create Panel manually using app.panel.create
method we need to pass object with panel parameters:
Parameter | Type | Default | Description |
---|---|---|---|
el | HTMLElement | Panel element | |
resizable | boolean | Enables resizable panel. If not passed then will be determined based on panel-resizable class. | |
visibleBreakpoint | number | Minimal app width (in px) when left panel becomes always visible | |
collapsedBreakpoint | number | Minimal app width (in px) when left panel becomes partially visible (collapsed) | |
swipe | boolean | false | Enable if you want to enable ability to open/close panel with swipe |
swipeNoFollow | boolean | false | Fallback option for potentially better performance on old/slow devices. If you enable it, then swipe panel will not follow your finger during touch move, it will be automatically opened/closed on swipe left/right. |
swipeActiveArea | number | 0 | Width (in px) of invisible edge from the screen that triggers panel swipe |
swipeOnlyClose | boolean | false | This parameter allows to close (but not open) panel with swipes. (swipe should be also enabled) |
swipeThreshold | number | 0 | Panel will not move with swipe if "touch distance" will be less than this value (in px). |
backdrop | boolean | true | Enables Panel backdrop (dark semi transparent layer behind) |
backdropEl | HTMLElement string | HTML element or string CSS selector of custom backdrop element | |
closeByBackdropClick | boolean | true | Enable/disable ability to close panel by clicking outside of panel |
containerEl | HTMLElement string | Allows to mount the panel to custom element rather than app root element | |
on | object | Object with events handlers. For example:
|
For example:
var panel = app.panel.create({
el: '.panel-left',
resizable: true,
visibleBreakpoint: 1024,
collapsedBreakpoint: 768,
})
Note that all following parameters can be used in global app parameters under panel
property to set defaults for all panels. For example:
var app = new Framework7({
panel: {
swipe: true,
visibleBreakpoint: 1024,
}
});
Panel Methods & Properties
After we created Panel instance (by calling app.panel.create
) or after we got Panel instance (by calling app.panel.get
) we may use its useful methods and properties:
Properties | |
---|---|
panel.app | Link to global app instance |
panel.side | String with panel side: left or right |
panel.effect | String with panel effect: cover or reveal |
panel.opened | Boolean property indicating whether it is opened or not |
panel.el | Panel HTML element |
panel.$el | Dom7 instance with panel HTML element |
panel.backdropEl | Backdrop HTML element |
panel.$backdropEl | Dom7 instance with backdrop HTML element |
panel.params | Panel parameters |
panel.containerEl | Element to mount panel to. (default app.root ) |
panel.$containerEl | Dom7 instance with element to mount panel to. (default app.root ) |
Methods | |
panel.open(animate) | Open panel. Where
|
panel.close(animate) | Close panel. Where
|
panel.toggle(animate) | Toggle panel. Where
|
panel.enableVisibleBreakpoint() | Enable visible breakpoint |
panel.disableVisibleBreakpoint() | Disable visible breakpoint |
panel.toggleVisibleBreakpoint() | Toggle visible breakpoint |
panel.enableCollapsedBreakpoint() | Enable collapsed breakpoint |
panel.disableCollapsedBreakpoint() | Disable collapsed breakpoint |
panel.toggleCollapsedBreakpoint() | Toggle collapsed breakpoint |
panel.enableResizable() | Enable resizable panel |
panel.disableResizable() | Disable resizable panel |
panel.enableSwipe() | Enable swipeable panel |
panel.disableSwipe() | Disable swipeable panel |
panel.destroy() | Destroy panel instance |
panel.on(event, handler) | Add event handler |
panel.once(event, handler) | Add event handler that will be removed after it was fired |
panel.off(event, handler) | Remove event handler |
panel.off(event) | Remove all handlers for specified event |
panel.emit(event, ...args) | Fire event on instance |
Panel Events
Panel will fire the following DOM events on panel element and events on app and panel instance:
DOM Events
Event | Target | Description |
---|---|---|
panel:open | Panel Element<div class="panel"> | Event will be triggered when Panel starts its opening animation |
panel:opened | Panel Element<div class="panel"> | Event will be triggered after Panel completes its opening animation |
panel:close | Panel Element<div class="panel"> | Event will be triggered when Panel starts its closing animation |
panel:closed | Panel Element<div class="panel"> | Event will be triggered after Panel completes its closing animation |
panel:backdrop-click | Panel Overlay Element<div class="panel-backdrop"> | Event will be triggered when the panel overlay is clicked |
panel:swipeopen | Panel Element<div class="panel"> | Event will be triggered in the very beginning of opening it with swipe |
panel:swipe | Panel Element<div class="panel"> | Event will be triggered for swipe panel during touch swipe action |
panel:collapsedbreakpoint | Panel Element<div class="panel"> | Event will be triggered when it becomes visible/hidden when app width matches its collapsedBreakpoint |
panel:breakpoint | Panel Element<div class="panel"> | Event will be triggered when it becomes visible/hidden when app width matches its visibleBreakpoint |
panel:resize | Panel Element<div class="panel"> | Event will be triggered on resizable panel resize |
panel:beforedestroy | Panel Element<div class="panel"> | Event will be triggered right before Panel instance will be destroyed |
App and Panel Instance Events
Panel instance emits events on both self instance and app instance. App instance events has same names prefixed with panel
.
Event | Target | Arguments | Description |
---|---|---|---|
open | panel | (panel) | Event will be triggered when Panel starts its opening animation. As an argument event handler receives panel instance |
panelOpen | app | (panel) | |
opened | panel | (panel) | Event will be triggered when Panel completes its opening animation. As an argument event handler receives panel instance |
panelOpened | app | (panel) | |
close | panel | (panel) | Event will be triggered when Panel starts its closing animation. As an argument event handler receives panel instance |
panelClose | app | (panel) | |
closed | panel | (panel) | Event will be triggered when Panel completes its closing animation. As an argument event handler receives panel instance |
panelClosed | app | (panel) | |
backdropClick | panel | (panel) | Event will be triggered when the panel backdrop is clicked. As an argument event handler receives panel instance |
panelBackdropClick | app | (panel) | |
swipeOpen | panel | (panel) | Event will be triggered in the very beginning of opening it with swipe. As an argument event handler receives panel instance |
panelSwipeOpen | app | (panel) | |
swipe | panel | (panel, progress) | Event will be triggered for swipe panel during touch swipe action. As an argument event handler receives panel instance and opened progress (from 0 to 1) |
panelSwipe | app | (panel, progress) | |
collapsedBreakpoint | panel | (panel) | Event will be triggered when it becomes visible/hidden when app width matches its collapsedBreakpoint . As an argument event handler receives panel instance |
panelCollapsedBreakpoint | app | (panel) | |
breakpoint | panel | (panel) | Event will be triggered when it becomes visible/hidden when app width matches its visibleBreakpoint . As an argument event handler receives panel instance |
panelBreakpoint | app | (panel) | |
resize | panel | (panel, newPanelWidth) | Event will be triggered on resizable panel resize |
panelResize | app | (panel) | |
beforeDestroy | panel | (panel) | Event will be triggered right before Panel instance will be destroyed |
panelBeforeDestroy | app | (panel) |
Panel Auto Initialization
If you don't need to use Panel API and your Panel is inside of the app on init or inside of the page and presented in DOM on moment of page initialization then it can be auto initialized with just adding additional panel-init
class:
<!-- Add panel-init class -->
<div class="panel panel-left panel-cover panel-init">
...
</div>
In this case if you need to access created Panel instance you can use the app.panel.get
app method:
var panel = app.panel.get('.panel-left');
if (panel.opened) {
// do something
}
When using auto init you may need to pass additional parameters. It can be done with data-
attributes on panel element.
<!-- parameters set via data- attributes -->
<div
class="panel panel-left panel-reveal panel-init"
data-collapsed-breakpoint="768"
data-visible-breakpoint="1024"
data-swipe="true"
>
...
</div>
Parameters used in camelCase, for example visibleBreakpoint, in data- attributes should be used in kebab-case as data-visible-breakpoint
Control Panel With Links
It is possible to open and close required panel (if you have them in DOM) using special classes and data attributes on links:
To open panel we need to add
panel-open
class to any HTML element (prefered to link)To close panel we need to add
panel-close
class to any HTML element (prefered to link)To toggle panel we need to add
panel-toggle
class to any HTML element (prefered to link)If you want to specify which panel should opened/closed, then it could be done via additional
data-panel=".panel-left"
attribute on this HTML element. This attribute can also receive justleft
orright
value if there is only one panel of such side in DOM.
According to above note:
<body>
<div id="app">
<!-- Left Panel with Reveal effect -->
<div class="panel panel-left panel-reveal panel-init">
<div class="block">
...
<!-- Clicking on link with "panel-close" class will close panel -->
<p><a href="#" class="panel-close">Close me</a></p>
<!-- Click on link with "panel-open" and data-panel=".panel-right" attribute will open Right panel -->
<p><a href="#" data-panel=".panel-right" class="panel-open">Open Right Panel</a></p>
</div>
</div>
<!-- Right Panel with Cover effect -->
<div class="panel panel-right panel-cover panel-init">
<div class="block">
...
<!-- Click on link with "panel-close" class will close panel -->
<p><a href="#" class="panel-close">Close me</a></p>
<!-- Click on link with "panel-open" and data-panel=".panel-left" attribute will open Left panel -->
<p><a href="#" data-panel=".panel-left" class="panel-open">Open Left Panel</a></p>
</div>
</div>
...
<div class="page-content">
<div class="block">
<!-- Click on link with "panel-open" and data-panel=".panel-left" attribute will open Left panel -->
<p><a href="#" data-panel=".panel-left" class="panel-open">Open Left Panel</a></p>
<!-- Click on link with "panel-open" and data-panel=".panel-right" attribute will open Right panel -->
<p><a href="#" data-panel=".panel-right" class="panel-open">Open Right Panel</a></p>
</div>
</div>
</div>
...
</body>
Routable Panels
Panels can also be routable with same features as for routable modals and pages:
- it provides opportunity to open Panel by usual links instead of so called special links or API,
- with enabled Push State, the same Panel will be opened when you refresh browser, navigate back and forward in history,
- with routable Panels you can load Panel itself and its content in the same ways as for pages and modals, i.e. using
url
,content
,template
,templateUrl
,component
orcomponentUrl
routes = [
...
// Creates Panel from passed HTML string
{
path: '/left-panel/',
panel: {
content: `
<div class="panel panel-left panel-cover">
<div class="view">
<div class="page">
...
</div>
</div>
</div>
`
}
},
// Load Panel from file via Ajax
{
path: '/right-panel-ajax/',
panel: {
url: './right-panel.html',
/* right-panel.html contains:
<div class="panel panel-right panel-reveal">
<div class="view">
<div class="page">
...
</div>
</div>
</div>
*/
},
},
// Load Panel from component file
{
path: '/panel-component/',
panel: {
componentUrl: './panel-component.html',
/* panel-component.html contains:
<template>
<div class="panel panel-left panel-cover">
<div class="view">
<div class="page">
...
</div>
</div>
</div>
</template>
<style>...</style>
<script>...</script>
*/
},
},
]
According to example above:
- when you click on link with
/left-panel/
href attribute it will open Panel from specified string content, - when you click on link with
/right-panel-ajax/
href attribute it will perform Ajax request toright-panel.html
file and open it as a Right Panel, - when you click on link with
/panel-component/
href attribute it will perform Ajax request topanel-component.html
file, parse it as a Router Component and open it as a Panel,
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-panel-width: 260px;
/*
--f7-panel-left-width: var(--f7-panel-width);
--f7-panel-right-width: var(--f7-panel-width);
--f7-panel-left-collapsed-width: var(--f7-panel-collapsed-width);
--f7-panel-right-collapsed-width: var(--f7-panel-collapsed-width);
*/
--f7-panel-bg-color: #fff;
}
.ios {
--f7-panel-collapsed-width: 58px;
--f7-panel-backdrop-bg-color: rgba(0, 0, 0, 0);
--f7-panel-transition-duration: 400ms;
--f7-panel-shadow: transparent;
}
.md {
--f7-panel-collapsed-width: 60px;
--f7-panel-backdrop-bg-color: rgba(0, 0, 0, 0.3);
--f7-panel-transition-duration: 300ms;
--f7-panel-shadow: rgba(0, 0, 0, 0.2) 0%,
rgba(0, 0, 0, 0.07) 30%,
rgba(0, 0, 0, 0.03) 40%,
rgba(0, 0, 0, 0) 60%,
rgba(0, 0, 0, 0) 100%;
}
.aurora {
--f7-panel-collapsed-width: 44px;
--f7-panel-backdrop-bg-color: rgba(0, 0, 0, 0.2);
--f7-panel-transition-duration: 400ms;
--f7-panel-shadow: transparent;
}
Examples
<body>
<div id="app">
<div class="panel panel-left panel-reveal panel-resizable panel-init">
<div class="block">
<p>Left Panel content here</p>
<p><a class="panel-close" href="#">Close me</a></p>
<p><a class="panel-open" href="#" data-panel=".panel-right-1">Open Right Panel</a></p>
</div>
</div>
<div class="panel panel-right panel-right-1 panel-cover panel-resizable panel-init">
<div class="block">
<p>Right Panel content here</p>
<p><a class="panel-close" href="#">Close me</a></p>
<p><a class="panel-open" href="#" data-panel=".panel-left">Open Left Panel</a></p>
</div>
</div>
<div class="panel panel-right panel-right-2 panel-cover panel-init theme-dark">
<div class="page">
<div class="block">
<p>Here comes another 3rd panel.</p>
<p><a class="panel-close" href="#">Close me</a></p>
</div>
</div>
</div>
<div class="view view-main view-init">
<div class="page">
<div class="navbar">
<div class="navbar-bg"></div>
<div class="navbar-inner">
<div class="left"></div>
<div class="title">Panels</div>
<div class="right"></div>
</div>
</div>
<div class="page-content">
<div class="block block-strong">
<p><a class="button panel-open" href="#" data-panel=".panel-left">Open Left Panel</a></p>
<p><a class="button panel-open" href="#" data-panel=".panel-right-1">Open Right Panel</a></p>
<p><a class="button panel-open" href="#" data-panel=".panel-right-2">Open Another Panel</a></p>
</div>
</div>
</div>
</div>
</div>
</body>
/* Limit resizable panel width */
.panel {
min-width: 100px;
max-width: 90vw;
}
var app = new Framework7();
var $$ = Dom7;
// Dom Events
$$('.panel-left').on('panel:open', function () {
console.log('Panel left: open');
});
$$('.panel-left').on('panel:opened', function () {
console.log('Panel left: opened');
});
// Instance Events
var panelRight = app.panel.get('.panel-right-1');
panelRight.on('open', function () {
console.log('Panel right: open');
});
panelRight.on('opened', function () {
console.log('Panel right: opened');
});
// App Events
app.on('panelClose', function (panel) {
console.log('Panel ' + panel.side + ': close');
});
app.on('panelClosed', function (panel) {
console.log('Panel ' + panel.side + ': closed');
});
app.on('panelResize', function (panel, newPanelWidth) {
console.log('Panel resized to ' + newPanelWidth + 'px');
});