App / Core
When we init the app we can use the new Framework7
constructor and pass an object with main app parameters:
var app = new Framework7({
// App id
id: 'com.myapp.test',
// Enable swipe panel
panel: {
swipe: 'left',
},
// ... other parameters
});
This constructor returns main app Framework7 instance.
App Parameters
Lets look at the list of available parameters:
Parameter | Type | Default | Description |
---|---|---|---|
root | string | body | App root element. If you main app layout is not a direct child of the <body> then it is required to specify root element here |
id | string | io.framework7.testapp | App bundle id. |
name | string | Framework7 | App name. Can be used by other components, e.g. as the default title for Dialog component. |
version | string | 1.0.0 | App version. Can be used by other components. |
theme | string | auto | App theme. Can be ios , md , aurora or auto . In case of auto it will use iOS theme for iOS devices, Aurora theme for desktop device running in Electron environment, and MD theme for all other devices. |
language | string | App language. Can be used by other components. By default equal to the current browser/webview language (i.e. navigator.language ). | |
routes | array | [] | Array with default routes to all views. |
data | function | App root data. Must be a function that returns an object with root data. For example:
Note, that | |
methods | object | {} | App root methods. Object with methods, e.g.
Note, that |
lazyModulesPath | string | Path to Framework7’s lazy components. Required to use Lazy Modules with browser modules. | |
autoDarkTheme | boolean | false | Automatically enables dark theme based on user system color scheme preference. This feature support is based on (prefers-color-scheme) media query support. |
init | boolean | true | By default Framework7 will be initialized automatically when you call new Framework7() . If you want to prevent this behavior you can disable it with this option and then initialize it manually with app.init() when you need it. |
initOnDeviceReady | boolean | true | If automatic initialization is enabled with init: true parameter and app is running under cordova environment then it will be initialized on deviceready event. |
on | object | {} | Object with events handlers. For example:
|
Clicks Module Parameters | |||
clicks | object | Object with clicks-module related parameters:
| |
{ | |||
externalLinks | string | ‘.external’ | CSS selector for links that should be treated as external and shouldn’t be handled by Framework7. For example such ‘.external’ value will match to links like <a href=”somepage.html” class=”external”> (with class “external”) |
} | |||
Touch Module Parameters | |||
touch | object | Object with touch-module related parameters:
| |
{ | |||
fastClicks | boolean | false | Fast clicks is a built-in library that removes 300ms delay from links and form elements in mobile browser while you click them. Modern browsers are smart enough to eliminate that click delay. You can enable this built-in library if you target old devices or experience click delays. |
fastClicksDistanceThreshold | number | 10 | Distance threshold (in px) to prevent short taps. So if tap/move distance is larger than this value then “click” will not be triggered |
fastClicksDelayBetweenClicks | number | 50 | Minimal allowed delay (in ms) between multiple clicks |
fastClicksExclude | string | This parameter allows to specify elements not handled by fast clicks by passing CSS selector of such elements | |
touchClicksDistanceThreshold | number | 5 | Distance threshold (in px) to prevent short swipes. So if tap/move distance is larger than this value then “click” will not be triggered. (Used only for touch events when fastClicks disabled). |
disableContextMenu | boolean | false | Set to true to disable context menu (with right click or tap and hold) |
tapHold | boolean | false | Enables tap hold |
tapHoldDelay | number | 750 | Determines how long (in ms) the user must hold their tap before the taphold event is fired on the target element |
tapHoldPreventClicks | boolean | true | When enabled (by default), then click event will not be fired after tap hold event |
activeState | boolean | true | When enabled, app will add “active-state” class to currently touched (:active) element. |
activeStateElements | string | a, button, label, span, .actions-button, .stepper-button, .stepper-button-plus, .stepper-button-minus, .card-expandable, .menu-item, .link, .item-link | CSS selector of elements where enabled activeState will add appropriate active class |
iosTouchRipple | boolean | false | Enables touch ripple effect for iOS theme |
mdTouchRipple | boolean | true | Enables touch ripple effect for MD theme |
auroraTouchRipple | boolean | false | Enables touch ripple effect for Aurora theme |
touchRippleElements | string | .ripple, .link, .item-link, .list-button, .links-list a, .button, button, .input-clear-button, .dialog-button, .tab-link, .item-radio, .item-checkbox, .actions-button, .searchbar-disable-button, .fab a, .checkbox, .radio, .data-table .sortable-cell:not(.input-cell), .notification-close-button, .stepper-button, .stepper-button-minus, .stepper-button-plus, .menu-item-content | CSS selector of elements to apply touch ripple effect on click |
} | |||
serviceWorker | object | Object with service worker module parameters:
| |
{ | |||
path | string | Path to service worker file | |
scope | string | Path to service worker scope | |
} |
These are default app parameters for app core module.
Most of components that has JavaScript API may extend this list of parameters with the property named as component. For example Panel component extends app parameters with panel
property that accepts Panel specific parameters.
Example:
var app = new Framework7({
id: 'com.myapp.test',
// Extended by Panel component:
panel: {
swipe: 'left',
leftBreakpoint: 768,
rightBreakpoint: 1024,
},
// Extended by Dialog component:
dialog: {
title: 'My App',
},
// Extended by Statusbar component:
statusbar: {
iosOverlaysWebview: true,
},
});
App Methods & Properties
Returned Framework7 instance app
contains a lot of useful properties and methods:
Properties | |
---|---|
app.id | App ID passed in parameters |
app.name | App name passed in parameters |
app.version | App version |
app.routes | App routes |
app.language | App language |
app.root | Dom7 instance with app root element |
app.rtl | Boolean property indicating app is in RTL layout or not |
app.theme | String with current app theme. Can be md , ios or aurora |
app.data | Object with app root data passed on intialization |
app.methods | Object with app root methods |
app.width | App width in px |
app.height | App height in px |
app.left | App left offset in px |
app.top | App top offset in px |
app.initialized | Boolean property indicating app is initialized or not |
app.$ | Dom7 alias |
app.t7 | Template7 alias |
app.params | App parameters |
app.support | Object with properties about supported features. Check the Support utilities section |
app.device | Object with properties about device. Check the Device utilities section |
app.utils | Object with some useful utilities. Check the Utils section |
app.request | Contains methods to work with XHR requests. Check the Request utilities section |
app.serviceWorker.registration | Array with registered service workers |
Methods | |
app.enableAutoDarkTheme() | Enables auto dark theme detection |
app.disableAutoDarkTheme() | Disables auto dark theme detection |
app.on(event, handler) | Add event handler |
app.once(event, handler) | Add event handler that will be removed after it was fired |
app.off(event, handler) | Remove event handler |
app.off(event) | Remove all handlers for specified event |
app.emit(event, …args) | Fire event on instance |
app.init() | Initialize app. In case you disabled auto initialization with init: false parameter |
app.serviceWorker.register(path, scope) | Register service worker. It returns promise that will be resolved with ServiceWorkerRegistration |
app.serviceWorker.unregister(registration) | Unregister service worker. It returns promise that will be resolved when service worker unregistered. |
Same as with app parameters most of components that has JavaScript API may extend this list of properties with the property named as component. For example Panel component extends app instance properties with panel
property that accepts Panel specific properties and methods.
Example:
// Open panel
app.panel.open('left');
// Hide statusbar
app.statusbar.hide();
App Events
App instance emits the following core events:
Event | Arguments | Description |
---|---|---|
init | Event will be fired on app initialization. Automatically after new Framework7() or after app.init() if you disabled auto init. | |
resize | Event will be fired on app resize (window resize). | |
orientationchange | Event will be fired on app orientation change (window orientantion change). | |
click | (event) | Event will be fired on app click |
touchstart:active | (event) | Event will be fired on touch start (mousedown) event added as active listener (possible to prevent default) |
touchmove:active | (event) | Event will be fired on touch move (mousemove) event added as active listener (possible to prevent default) |
touchend:active | (event) | Event will be fired on touch end (mouseup) event added as active listener (possible to prevent default) |
touchstart:passive | (event) | Event will be fired on touch start (mousedown) event added as passive listener (impossible to prevent default) |
touchmove:passive | (event) | Event will be fired on touch move (mousemove) event added as passive listener (impossible to prevent default) |
touchend:passive | (event) | Event will be fired on touch end (mouseup) event added as passive listener (impossible to prevent default) |
serviceWorkerRegisterSuccess | (registration) | Event will be triggered when service worker successfully registered |
serviceWorkerRegisterError | (error) | Event will be triggered when service worker registration failed |
serviceWorkerUnregisterSuccess | (registration) | Event will be triggered when service worker successfully unregistered |
serviceWorkerUnregisterError | (registration, error) | Event will be triggered when service worker unregister failed |
And again, most of components that has JavaScript API may extend this list of events like Panel component will also trigger additional events on app instance.
Example:
app.on('panelOpen', function (panel) {
console.log('Panel ' + panel.side + ' opened');
});
CSS Variables
:root {
--f7-theme-color: #007aff;
--f7-theme-color-rgb: 0, 122, 255;
--f7-theme-color-shade: #0066d6;
--f7-theme-color-tint: #298fff;
--f7-safe-area-left: 0px;
--f7-safe-area-right: 0px;
--f7-safe-area-top: 0px;
--f7-safe-area-bottom: 0px;
--f7-safe-area-outer-left: 0px;
--f7-safe-area-outer-right: 0px;
--f7-device-pixel-ratio: 1;
}
@supports (left: env(safe-area-inset-left)) {
:root {
--f7-safe-area-top: env(safe-area-inset-top);
--f7-safe-area-bottom: env(safe-area-inset-bottom);
}
:root .ios-left-edge,
:root .ios-edges,
:root .safe-area-left,
:root .safe-areas,
:root .popup,
:root .sheet-modal,
:root .panel-left {
--f7-safe-area-left: env(safe-area-inset-left);
--f7-safe-area-outer-left: env(safe-area-inset-left);
}
:root .ios-right-edge,
:root .ios-edges,
:root .safe-area-right,
:root .safe-areas,
:root .popup,
:root .sheet-modal,
:root .panel-right {
--f7-safe-area-right: env(safe-area-inset-right);
--f7-safe-area-outer-right: env(safe-area-inset-right);
}
:root .no-safe-areas,
:root .no-safe-area-left,
:root .no-ios-edges,
:root .no-ios-left-edge {
--f7-safe-area-left: 0px;
--f7-safe-area-outer-left: 0px;
}
:root .no-safe-areas,
:root .no-safe-area-right,
:root .no-ios-edges,
:root .no-ios-right-edge {
--f7-safe-area-right: 0px;
--f7-safe-area-outer-right: 0px;
}
}
@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 2dppx) {
:root {
--f7-device-pixel-ratio: 2;
}
}
@media (-webkit-min-device-pixel-ratio: 3), (min-resolution: 3dppx) {
:root {
--f7-device-pixel-ratio: 3;
}
}
/*====================
Fonts
==================== */
:root {
--f7-font-size: 14px;
}
.ios {
--f7-font-family: -apple-system, SF Pro Text, SF UI Text, system-ui, Helvetica Neue, Helvetica, Arial, sans-serif;
--f7-text-color: #000;
--f7-line-height: 1.4;
}
.ios .theme-dark,
.ios.theme-dark {
--f7-text-color: #fff;
}
.md {
--f7-font-family: Roboto, system-ui, Noto, Helvetica, Arial, sans-serif;
--f7-text-color: #212121;
--f7-line-height: 1.5;
}
.md .theme-dark,
.md.theme-dark {
--f7-text-color: rgba(255, 255, 255, 0.87);
}
.aurora {
--f7-font-family: -apple-system, system-ui, Helvetica, Arial, sans-serif;
--f7-text-color: #000;
--f7-line-height: 1.5;
}
.aurora .theme-dark,
.aurora.theme-dark {
--f7-text-color: #fff;
}
/*====================
Bars
==================== */
:root {
/*
--f7-bars-link-color: var(--f7-theme-color);
*/
--f7-bars-bg-image: none;
--f7-bars-bg-color: #f7f7f8;
--f7-bars-bg-color-rgb: 247, 247, 248;
--f7-bars-text-color: #000;
--f7-bars-shadow-bottom-image: linear-gradient(to bottom, rgba(0, 0, 0, 0.25) 0%, rgba(0, 0, 0, 0.08) 40%, rgba(0, 0, 0, 0.04) 50%, rgba(0, 0, 0, 0) 90%, rgba(0, 0, 0, 0) 100%);
--f7-bars-shadow-top-image: linear-gradient(to top, rgba(0, 0, 0, 0.25) 0%, rgba(0, 0, 0, 0.08) 40%, rgba(0, 0, 0, 0.04) 50%, rgba(0, 0, 0, 0) 90%, rgba(0, 0, 0, 0) 100%);
}
.theme-dark {
--f7-bars-bg-color: #1b1b1b;
--f7-bars-text-color: #fff;
}
.ios {
--f7-bars-border-color: #c4c4c4;
}
.ios .theme-dark,
.ios.theme-dark {
--f7-bars-border-color: #282829;
}
.md {
--f7-bars-border-color: transparent;
}
.aurora {
--f7-bars-border-color: rgba(0, 0, 0, 0.2);
}
.aurora .theme-dark,
.aurora.theme-dark {
--f7-bars-border-color: #282829;
}