Now you can see our HTML layout with linked required CSS and JavaScript files. Now we should initialize our app (for example in my-app.js
):
var myApp = new Framework7();
In the example above we use myApp
variable where we store Framework7 initialized instance for easy access in future. It is not necessary to name it "myApp", it could be any name you like.
It was pretty simple. But Framework7 also provides more customization on initialization by passing object with parameters:
var myApp = new Framework7({
pushState: true,
swipePanel: 'left',
// ... other parameters
});
Let's look at the list of all available parameters:
Parameter | Type | Default | Description |
---|---|---|---|
root | string | 'body' | App root element. Useful when using F7 with libraries like Vue or React that doesn't allow to mount the app to the body. |
Material Theme (Material theme only) | |||
material | boolean | false | Set to true to activate Material-specific App JS behavior |
materialPageLoadDelay | number | 0 | Delay (in ms) before animation of loaded page. Can be increased a bit to improve performance |
materialRipple | boolean | true | Enable/disable Material-specific touch ripple effect |
materialRippleElements | string | '.ripple, a.link, a.item-link, .button, .modal-button, .tab-link, .label-radio, .label-checkbox, .actions-modal-button, a.searchbar-clear, .floating-button' | CSS selector of elements to apply touch ripple effect on click |
materialPreloaderHtml | string | '<span class="preloader-inner"><span class="preloader-inner-gap"></span><span class="preloader-inner-left"><span class="preloader-inner-half-circle"></span></span><span class="preloader-inner-right"><span class="preloader-inner-half-circle"></span></span></span>' | HTML of Material's theme preloader |
Caching | |||
cache | boolean | true | As Framework7 uses Ajax to load HTML content for pages it is good to use caching, especially if your content in those pages updates not very often. |
cacheDuration | number | 1000*60*10 | Duration in ms (milliseconds) while app will use cache instead of loading page with another Ajax request. By default it takes 10 minutes. |
cacheIgnore | array | [] | Array of URLs (string) that should not be cached by Framework7 |
cacheIgnoreGetParameters | boolean | false | If "true" then URLs like "about.html?id=2" and "about.html?id=3" will be treated and cached like single "about.html" page |
Fast clicks library | |||
fastClicks | boolean | true | Fast clicks is a built-in library that removes 300ms delay from links and form elements in mobile browser while you click them. You can disable this built-in library if you want to use other third party fast clicks script. |
fastClicksExclude | string | '' | This parameter allows to specify elements not handled by fast clicks by passing CSS selector of such elements |
fastClicksDelayBetweenClicks | number | 50 | Minimal allowed delay (in ms) between multiple clicks |
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 |
activeState | boolean | true | When enabled, app will add "active-state" class to currently touched (:active) element. |
activeStateElemets | string | 'a, button, label, span' | CSS selector of elements where activeState will add appropriate active class |
tapHold | boolean | false | Set to true to enable tap hold events |
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 |
Navigation / Router | |||
router | boolean | true | With this option you may disable default navigation router if you want to implement your own |
ajaxLinks | string | undefined | By default (when this parameter is not specified) Framework7 will load all links (<a>) using Ajax. You can change this behavior by passing here CSS selector string for links that should be loaded with Ajax, like "a.ajax" - only all links with "ajax" class |
dynamicPageUrl | string | 'content-{{index}}' | URL rule for dynamically loaded pages. Available replaceable expressions: '{{index}}' (page index number in navigation history) and '{{name}}' (value of page "data-page" attribute) |
uniqueHistory | boolean | false | Set to true and App will keep View's navigation history unique, and remove duplicated pages |
uniqueHistoryIgnoreGetParameters | boolean | false | Use this parameter in addition to uniqueHistory . Set to true and App will ignore URL GET parameters when cheking its uniqueness. So the URLs like "page.html" and "page.html?id=3" will be treated as the same. |
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") |
allowDuplicateUrls | boolean | false | You may enable this parameter to allow loading of new pages that have same url as currently "active" page in View. |
animateNavBackIcon | boolean | false | This option (when enabled) gives more native look for dynamic navbar left back-link icon animation. Useful only when you use dynamic navbar with default back-link icon on left side set as "sliding". iOS theme only |
animatePages | boolean | true | Set to false if you want to disable animated transitions between pages |
preloadPreviousPage | boolean | true | Enable/disable preloading of previous page when you go deep in navigation. Should be enabled for correct work of "swipe back page" feature. |
preroute | function(view, options) | - |
This callback allows to prevent default router load/back actions and to load another page or do another required actions Look for example below |
preprocess | function(content, url, next) | - |
This callback function allows you to modify loaded router (mostly Ajax) content right before it will be injected to DOM. Callback receives "content" and "url" of the loaded page and the "next" callback function. After you modify content within this function you should return it with: Look for example below |
routerRemoveWithTimeout | boolean | false |
When enabled, then framework will remove element after 0 timeout instead of immediately. Useful to enable if you use another library like Vue or React to manage (remove) pages |
Push State | |||
pushState | boolean | false | If you develop web app (not PhoneGap or Home Screen web app) it is useful to enable hash navigation (browser url will look like "http://my-webapp.com/#/about.html"). User as well will be able to navigate through app's history by using browser's default back and forward buttons. |
pushStateSeparator | string | '#!/' | Push state URL separator, can be changed for something like '#page/' and then your push state urls will look like "http://myapp.com/#page/about.html" |
pushStateRoot | string | undefined | Push state root URL separator, for example "http://my-app.com/". It is useful only in case when you use empty ("") pushStateSeparator |
pushStateNoAnimation | boolean | false | If false then it will inherit View's animatePages parameter. If true, then push state navigation will happen without animation (page transitions) |
pushStateOnLoad | boolean | true | Disable to ignore parsing push state URL and loading page on app load |
Swipe back (iOS theme only) | |||
swipeBackPage | boolean | true | Enable/disable ability to swipe back from left edge of screen to get to the previous page. |
swipeBackPageThreshold | number | 0 | Value in px. Swipe back action will start if "touch distance" will be more than this value. |
swipeBackPageActiveArea | number | 30 | Value in px. Width of invisible left edge of the screen that triggers swipe back action |
swipeBackPageAnimateShadow | boolean | true | Enable/disable box-shadow animation during swipe back action. You can disable it to improve performance |
swipeBackPageAnimateOpacity | boolean | true | Enable/disable opacity animation during swipe back action. You can disable it to improve performance |
Sortable Lists | |||
sortable | boolean | true | If you don't use sortable lists you can disable it for potentially better performance. |
Swipeout | |||
swipeout | boolean | true | If you don't use swipeouts you can disable this feature for potentially better performance. |
swipeoutNoFollow | boolean | false | Fallback option for potentially better performance on old/slow devices. If you enable it, then swipeout item will not follow your finger during touch, it will be automatically opened/closed on swipe left/right. |
swipeoutRemoveWithTimeout | boolean | false | When enabled, then framework will remove element after 0 timeout instead of immediately. Useful to enable if you use another library like Vue or React to manage (remove) swipeout items |
Side Panels | |||
panelLeftBreakpoint | number | Minimal app width when left panel becomes always visible | |
panelRightBreakpoint | number | Minimal app width when right panel becomes always visible | |
swipePanel | string | false | Disabled by default. If you want to enable ability to open side panels with swipe you can pass here "left" (for left panel) or "right" (for right panel) or "both" (for both panels). |
swipePanelCloseOpposite | boolean | true | This parameter gives ability to close opposite panel by swipe. For example, if your swipePanel is "left", then you could close "right" panel also with swipe. |
swipePanelOnlyClose | boolean | false | This parameter allows to close (but not open) panels with swipes |
swipePanelActiveArea | number | false | Value in px. Width of invisible edge from the screen that triggers swipe panel |
swipePanelNoFollow | boolean | false | Fallback option for potentially better performance on old/slow devices. If you enable it, then side panel will not follow your finger during touch, it will be automatically opened/closed on swipe left/right. |
swipePanelThreshold | number | 0 | Value in px. Panel will not move with swipe if "touch distance" will be less than this value. |
panelsCloseByOutside | boolean | true | Enable/disable ability to close panel by clicking outside of panel (on panel's overlay) |
Modals | |||
modalsMoveToRoot | boolean | true | When enabled it will move opened modal to the app root element (or body) if it is not there on the moment of opening and move back after modal closed. It allows to use/load modals on demand inside of loaded pages |
modalTitle | string | 'Framework7' | Default title for modals (Alert, Confirm, Prompt) |
modalButtonOk | string | 'OK' | Default text for modal's "OK" button |
modalButtonCancel | string | 'Cancel' | Default text for modal's "Cancel" button |
modalPreloaderTitle | string | 'Loading... ' | Default text for preloader modal |
modalCloseByOutside | boolean | false | Enable/disable ability to close modal (Alert, Confirm, Prompt) by clicking outside of modal (on modal's overlay) |
actionsCloseByOutside | boolean | true | The same as previous but for Action Sheet modal |
popupCloseByOutside | boolean | true | The same as previous but for Popup modal |
popoverCloseByOutside | boolean | true | The same as previous but for Popover modal |
modalTemplate | string | undefined | Full HTML Template7 formatted HTML template for modals (like alert, confirm and prompt). Look at the example of Modal Template |
modalActionsTemplate | string | undefined | Template7 formatted HTML template for Action Sheet. Could be useful if you want to add some custom elements to Action Sheet layout. Look at the example of Action Sheet Template |
modalActionsToPopoverTemplate | string | Template7 formatted HTML template for Action Sheet that will be converted to Popover. Could be useful if you want to add some custom elements to Popover layout. Look at the example of Action Sheet To Popover Template | |
modalUsernamePlaceholder | string | 'Username' | Place holder text for username input in Login Modal |
modalPasswordPlaceholder | string | 'Password' | Place holder text for password input in Login and Password Modals |
modalStack | boolean | true | This feature doesn't allow to open multiple modals at the same time, and will automatically open next modal when you close the current one. Such behavior is similar to browser native alerts |
Smart Select | |||
smartSelectOpenIn | string | 'page' | Specify default way of how Smart Select should be opened. Can be 'page', 'popup' or 'picker' |
smartSelectBackTemplate | string | '<div class="left sliding"><a href="#" class="back link"><i class="icon icon-back"></i><span>{{backText}}</span></a></div>' | Smart Select page navbar back link HTML template |
smartSelectPopupCloseTemplate | string | '<div class="left"><a href="#" class="link close-popup"><i class="icon icon-back"></i><span>{{closeText}}</span></a></div>' | Smart Select popup close link HTML template |
smartSelectBackText | string | 'Back' | Default back link text for Smart Select's page navbar |
smartSelectPopupCloseText | string | 'Close' | Default close link text for Smart Select's popup navbar |
smartSelectPickerCloseText | string | 'Done' | Default close link text for Smart Select's picker toolbar |
smartSelectSearchbar | boolean | false | Set to true if you want to enable Search Bar for all Smart Selects |
smartSelectBackOnSelect | boolean | false | If enabled then smart select page will be automatically closed after user picks any option |
smartSelectFormTheme | string | undefined | One of 10 default color themes for form elements on smart select page/popup |
smartSelectNavbarTheme | string | undefined | One of 10 default color themes for navbar on smart select page/popup |
Navbars / Toolbars | |||
hideNavbarOnPageScroll | boolean | false | Set to true and Navbar will be hidden automatically on page scroll down, and become visible on scroll up |
hideToolbarOnPageScroll | boolean | false | Set to true and Toolbar will be hidden automatically on page scroll down, and become visible on scroll up |
hideTabbarOnPageScroll | boolean | false | Set to true and Tab bar will be hidden automatically on page scroll down, and become visible on scroll up. Note that this is only for Tab Bar app layout, otherwise use hideToolbarOnPageScroll |
showBarsOnPageScrollEnd | boolean | true | Set to true to show hidden Navbar and Toolbar when scrolling reaches end of the page |
showBarsOnPageScrollTop | boolean | true | Set to false and bars will not become visible when you scroll page to top everytime. They will become visible only on the most top scroll position, in the beginning of the page |
scrollTopOnNavbarClick | boolean | false | Set to true and each click on Navbar's "center" element will scroll currently active page to top |
Images Lazy Load | |||
imagesLazyLoadThreshold | number | 0 | By default images are loaded when they appear on the screen. Use this parameter if you want to load images earlier. Setting it to 50 will load image when it 50 pixels before it appears on viewport |
imagesLazyLoadSequential | boolean | true | If enabled, then lazy images will be loaded one by one when they appear in viewport |
imagesLazyLoadPlaceholder | string | Lazy load image placeholder source to show while image is not yet loaded. By default it is 1x1 px image | |
onLazyLoad | function (el) | Callback function that will be executed when "lazy" image begins to load | |
onLazyLoaded | function (el) | Callback function that will be executed when "lazy" image loaded | |
onLazyError | function (el) | Callback function that will be executed when "lazy" image fails to load | |
Notifications | |||
notificationTitle | string | undefined | Default title for all notifications iOS theme only |
notificationSubtitle | string | undefined | Default subtitle for all notifications iOS theme only |
notificationMedia | string | undefined | Default media (icon or image) for all notifications iOS theme only |
notificationHold | number | undefined | Default hold duration (in ms) for all notifications |
notificationCloseOnClick | boolean | false | Set to true if you want to close notification on click by default |
notificationCloseIcon | boolean | true | Set to true if you want to display close icon (button) for notifications by default iOS theme only |
notificationCloseButtonText | string | 'Close' | Default text for Snackbars' close button Material theme only |
Status Bar (iOS theme only) | |||
statusbarOverlay | boolean | undefined | With this option you can overwrite automatic status bar detection |
scrollTopOnStatusbarClick | boolean | false | Set to true and each click on Status bar ("status-bar-overlay") will scroll currently active page to top |
Template7 | |||
template7Pages | boolean | false | Set to true to enable Template7 rendering for Ajax and Dynamic pages. Learn more about it in Template7 Pages section |
template7Data | object | {} | Parameter to store templates/pages data for Template7 rendering. Learn more about it in Template7 Pages section |
precompileTemplates | boolean | false | With this option you may framework will compile all Template7 templates automatically. Learn more about Templates Auto Compilation section |
templates | object | {} | Object with compiled Template7 templates. Learn more about it in Templates Auto Compilation section |
Page Callbacks | |||
onPageBeforeInit | function(app, page) | - | Callback function that will be executed when Framework7 just inserts new page to DOM. Does the same as "page:beforeinit" page event |
onPageInit | function(app, page) | - | Callback function that will be executed when Framework7 initialize required page's components and navbar. Does the same as "page:init" page event |
onPageBeforeAnimation | function(app, page) | - | Callback function that will be executed when everything initialized and page (and navbar) is ready to be animated. Does the same as "page:beforeanimation" page event |
onPageAfterAnimation | function(app, page) | - | Callback function that will be executed after page (and navbar) animation. Does the same as "page:afteranimation" page event |
onPageBeforeRemove | function(app, page) | - | Callback function that will be executed right before page will be removed from DOM. Does the same as "page:beforeremove" page event |
onPageBack | function(app, page) | - | Callback function that will be executed right before "back" transition. Difference with "onPageBeforeAnimation" is that this callback will be executed for the "old" page - page that slides from center to right. Does the same as "page:back" page event |
onPageAfterBack | function(app, page) | - | Callback function that will be executed right after "back" transition. Difference with "onPageAfterAnimation" is that this callback will be executed for the "old" page - page that slides from center to right. Does the same as "page:afterback" page event |
Ajax Callbacks | |||
onAjaxStart | function(xhr) | - | Callback function that will be executed in the beginning of Ajax request. This function accepts xhr data as an argument. |
onAjaxComplete | function(xhr) | - | Callback function that will be executed after Ajax request. This function accepts xhr data as an argument. |
Namespace
Attention! If you change following class names you will also need to change them in CSS! |
|||
viewClass | string | 'view' | Class name for your View element |
viewMainClass | string | 'view-main' | Class name for your Main View element |
viewsClass | string | 'views' | Class name for your Views element |
Init | |||
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 myApp.init() when you need it. |
So your final initialization code in my-app.js
could look like:
var myApp = new Framework7({
// Default title for modals
modalTitle: 'My App',
// If it is webapp, we can enable hash navigation:
pushState: true,
// Hide and show indicator during ajax requests
onAjaxStart: function (xhr) {
myApp.showIndicator();
},
onAjaxComplete: function (xhr) {
myApp.hideIndicator();
}
});
Framework7 allows you to use your favorite client-side template engine or do any modifications with loaded content.
Let's look on how to init app with usage of Template7 as our client-side template engine
Init app in my-app.js
:
var myApp = new Framework7({
preprocess: function (content, url, next) {
if (url === 'people.html') {
var template = Template7.compile(content);
var resultContent = template({
title: 'People',
people: ['John', 'Ivan', 'Mary']
})
return resultContent;
}
}
});
And the people.html
page:
<div class="navbar">
<div class="navbar-inner">
<div class="center">{{title}}</div>
</div>
</div>
<div class="pages">
<div data-page="people" class="page">
<div class="page-content">
<ul>
{{#each people}}
<li>{{this}}</li>
{{/each}}
</ul>
</div>
</div>
</div>
But sometimes you may have asynchronous thread inside of your preprocess functon, for example if you need to do one more Ajax request and only after that to continue page loading. For this case we have "next" callback function where we need to pass our genereated/modified content:
var myApp = new Framework7({
preprocess: function (content, url, next) {
if (url === 'people.html') {
// For example, we will retreive template JSON data using Ajax and only after that we will continue page loading process
$$.get('sometemplate.html', function(data) {
// Template
var template = Template7.compile(content);
// Compile content template with received JSON data
var resultContent = template(data);
// Now we call "next" callback function with result content
next(resultContent);
});
// Now we shouldn't return anything
}
}
});
This callback allows to prevent default router load/back actions and to load another page, redirects or do another required actions.
For example we can check if the user is not logged in when he requesting some page and then to redirect him to the login page
var myApp = new Framework7({
preroute: function (view, options) {
if (!userLoggedIn) {
view.router.loadPage('auth.html'); //load another page with auth form
return false; //required to prevent default router action
}
}
});
Ok, right after we initialize our App we need to add and initialize Views