Views

View (<div class="view">) - is a separate visual part of app with its own settings, navigation and history. Each view also may have different navbar and toolbar layouts, different styles. So it is some kind of app in app. Such kind of functionality allows you easily manipulate each part of your app.

Views (<div class="views">) - is the wrapper container for all visual views that stays visible most of time (not in modals, panels). Let's say that views is a main wrapper for body of your app. Only one "Views" element is allowed

Let's look at views' HTML structure:

<body>
  ...
  <div class="panel panel-left panel-cover">
    <div class="view panel-view"> ... </div>
  </div>
  <!-- Views -->
  <div class="views">
    <!-- Your main view -->
    <div class="view view-main">
      <!-- Navbar-->
      <!-- Pages -->
      <!-- Toolbar-->
    </div>
    <!-- Another view -->
    <div class="view another-view">
      <!-- Navbar-->
      <!-- Pages -->
      <!-- Toolbar-->
    </div>          
  </div>
  <div class="popup">
    <div class="view popup-view"> ... </div>
  </div>
  ...
</body>

As you see View may be almost in any part of your app, except one important rule - all visible views should within Views (<div class="views">). This required for some animations when we need to move whole app (like when you open panel).

Main View

Your main view should have additional view-main class. Why we need main view? By default all links (which is not in any initialized view) will load pages in main view. Also if you use pushState hash navigation then it works only for main view's navigation.

Initialize View

We already have required views in HTML and our app is already initialized, now we need to initialize our views in JavaScript.

Note that not all views should be initialized, intialize only those where you need navigation. Other views (like in popup) may stay not initialized, we use them just for correct layout of navbars, pages and toolbars.

As you remember from previous article we have app's initialized instance in myApp variable:

var myApp = new Framework7({
  // ...
});   

This instance has a lot of methods to work with different parts of our app. And there is one method to initialize view:

myApp.addView(selector, parameters) - initialize View.

  • container - string or HTMLElement. If string - CSS selector of View element
  • parameters - object. Object with View parameters
  • This method returns object with just created View instance.

View initialization parameters

Parameter Type Default Description
name string Set to true to enable Dynamic Navbar in this View iOS theme only
dynamicNavbar boolean false Set to true to enable Dynamic Navbar in this View iOS theme only
url string undefined Default (initial) View's url. If not specified, then it is equal to document url
domCache boolean false If enabled then all previous pages in navigation chain will not be removed from DOM when you navigate deeper and deeper. It could be useful, for example, if you have some Form from 5 steps (5 pages) and when you are on last 5th page you need access to form that was on 1st page.
linksView string / View instance undefined CSS Selector of another view or initialized View instance. By defaul all links in initialized (only) view will load pages in this view. You can change this logic on the fly by changing this paremeter. This tell links to load pages in other view.
Navigation
uniqueHistory boolean Set to true and App will keep View's navigation history unique, it will also remove duplicated pages. By default, equal to the same App's parameter. Allows to override global App parameter for current View
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. By default, equal to the same App's parameter. Allows to override global App parameter for current View
allowDuplicateUrls boolean You may enable this parameter to allow loading of new pages that have same url as currently "active" page in View. By default, equal to the same App's parameter. Allows to override global App parameter for current View
animatePages boolean Set to false if you want to disable animated transitions between pages. By default, equal to the same App's parameter. Allows to override global App parameter for current View
preloadPreviousPage boolean Enable/disable preloading of previous page when you go deep in navigation. Should be enabled for correct work of "swipe back page" feature. By default, equal to the same App's parameter. Allows to override global App parameter for current View
reloadPages boolean false When enabled, View will always reload currently active page without loading new one
preroute function(view, options) -

This callback allows to prevent default router load/back actions and to load another page or do another required actions.

Allows to override the same App callback but for the current View

Example

preprocess function(content, url, next) -

This callback function allows you to modify loaded by 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.

Allows to override the same App callback but for the current View

Example

Swipe back (iOS theme only)
swipeBackPage boolean By default, equal to the same App's parameter. Allows to override the same App parameter but for the current View
swipeBackPageThreshold number By default, equal to the same App's parameter. Allows to override the same App parameter but for the current View
swipeBackPageActiveArea number By default, equal to the same App's parameter. Allows to override the same App parameter but for the current View
swipeBackPageAnimateShadow boolean By default, equal to the same App's parameter. Allows to override the same App parameter but for the current View
swipeBackPageAnimateOpacity boolean By default, equal to the same App's parameter. Allows to override the same App parameter but for the current View
Callbacks (iOS theme only)
onSwipeBackMove(callbackData) function Callback function that will be executed during swipe back move. callbackData contains object with the following properties:
  • percentage - number, swipe back percentage
  • activePage - HTMLElement with currently active page
  • previousPage - HTMLElement with previous (left) page
  • activeNavbar - HTMLElement with currently active navbar (only for Dynamic Navbar)
  • previousNavbar - HTMLElement with previous (left) navbar (only for Dynamic Navbar)
onSwipeBackBeforeChange(callbackData) function Callback function that will be executed right before swipe back animation to previous page when you release it.
onSwipeBackAfterChange(callbackData) function Callback function that will be executed after swipe back animation to previous page when you release it.
onSwipeBackBeforeReset(callbackData) function Callback function that will be executed right before swipe back animation to current page when you release it.
onSwipeBackAfterReset(callbackData) function Callback function that will be executed after swipe back animation to current page when you release it.

Now when we know all required parameters we can initialize our views according to HTML example above:

var myApp = new Framework7({
  // ...
});   
 
/* Initialize views */
var mainView = myApp.addView('.view-main', {
  dynamicNavbar: true
})
var anotherView = myApp.addView('.another-view');

That is all, it was pretty simple. In this example we don't init views that inside of panel and popup, because we don't use them for navigation, only for visual styling and correct layout. But if you need navigaion in those views you should also initialize them.

View Methods & Properties

As you may see in example above we initialize our views and store their instances in mainView and anotherView variables. View instance is an Object with useful methods and parameters that allows to manipulate views. Let's lool at list of these methods and parameters on example of mainView:

Properties
mainView.params Returns object with intialized parameters. You can access and rewrite some parameters like mainView.params.linksView = '.another-view'
mainView.history Returns array with View's history. Each array element contains URL of loaded page
mainView.contentCache Returns object with cached pages. It is available only if you use dynamically generated content
mainView.pagesCache Returns object with initial cached pages (For the case with enabled domCache)
mainView.contextCache Returns object with context relevant for specific pages. It is available only if you use Template7 generated pages
mainView.pageElementsCache Returns object with page elements. It is available only if you load pages using pageElement parameter
mainView.url Returns string with url of currently active (loaded) page
mainView.pagesContainer Returns HTMLElement link to pages element
mainView.activePage Contains object with Page Data of currently active page
mainView.main Returns true if this view is main view
mainView.router Object with router methods
Methods
mainView.router.load(options) Read more about it in Router API
mainView.router.back(options) Read more about it in Router API
mainView.hideNavbar(isAnimated) Hide navbar in this View
isAnimated - Boolean - Default: true
mainView.showNavbar(isAnimated) Show navbar in this View
isAnimated - Boolean - Default: true
mainView.hideToolbar(isAnimated) Hide toolbar in this View
isAnimated - Boolean - Default: true
mainView.showToolbar(isAnimated) Show toolbar in this View
isAnimated - Boolean - Default: true
mainView.destroy() Destroy initialized View, detach swipe events, and disable navigation

View Events

These events are available only in iOS theme

Event Target Description
swipeback:move View Element<div class="view"> Event will be triggered during swipe back move
swipeback:beforechange View Element<div class="view"> Event will be triggered right before swipe back animation to previous page when you release it
swipeback:afterchange View Element<div class="view"> Event will be triggered after swipe back animation to previous page when you release it
swipeback:beforereset View Element<div class="view"> Event will be triggered right before swipe back animation to current page when you release it
swipeback:afterreset View Element<div class="view"> Event will be triggered after swipe back animation to current page when you release it

Default View URL

If you think that for some reason Framework7 detects wrong default View URL (which is used for navigation history), or if you want to have different default View URL, you can specify it using data-url attribute on View element or using url parameter when you initialze View:

<div class="view" data-url="index2.html">

Get Current View

There could be situation when we need to get currently active View, because instead of main app view we may also have view in opened popup, popover, opened panel, tabs, etc. This method allows to get the View instance of currently active/visible/"most-top" view.

For example, if you have initilized View in panel, and panel is currently opened, then this method will return panel's view. Or, if you use app with tab bar layout, where each tab is view, then this method will return currently active/visible tab-view

myApp.getCurrentView(index) - get currently active/visible View instance

  • index - number - If there are few currently active views (as in Split View layout), then you need to specify index number of View. Optional
  • Method returns initialized View instance or array with View instances if there are few currently active views

Access to View's instance

In case you init(added) views without assignment (anonymous) you can always access them by named property of global app instance (myApp), e.g. myApp.views.[name] or myApp.[name]View:

myApp = new Framework7();
// Main view
myApp.addView('.view-main', {
    main: true,
    //...
});
// Another view
myApp.addView('.view-left', {
    name: 'left',
    //...
});
// One more view
myApp.addView('.view-right', {
    name: 'right',
    //...
});
// Access left view
myApp.views.left /* or */ myApp.leftView

// Access right view
myApp.views.right /* or */ myApp.rightView

// Access main view
myApp.views.main /* or */ myApp.mainView

Note that name parameter for main view will be ignored, it will be always accessible via myApp.views.main or myApp.mainView.

Access to View's instance from DOM

Sometimes it could be useful to know or to get View's instance from HTML element. It is easy, right after we iniitalize view, Framework7 adds special property-link to our <div class="view"> element so we can access it any time in our JavaScript:

var viewsElement = $$('.view-main')[0];
var viewInstance = viewsElement.f7View;

Also, all view instances are stored in special App property - views (array of View instances). If we need to find main view we can do like that:

for (var i = 0; i < myApp.views.length; i ++) {
  var view = myApp.views[i];
  if (view.main) myApp.alert('I found main View!')
}

What's next

Let's look now on Pages