v6.3.17
Support Framework7
logo_github stars forks
Improve this Doc

Migration from Framework7 v5

In this article we will walk through most of the breaking changes to check what needs to be done to migrate your app from Framework7 v5 to Framework7 v6.

Package

Core version has new package structure, and you may need to tweak your imports for lite and bundle versions:

  • framework7/framework7.esm.js is now framework7
  • framework7/framework7.esm.bundle.js is now framework7/bundle
  • framework7/framework7-lite.esm.js is now framework7/lite
  • framework7/framework7-lite.esm.bundle.js is now framework7/lite-bundle

So if you have something like this in v5:

import Framework7 from 'framework7/framework7-lite.esm.bundle.js'

it should be changed to:

import Framework7 from 'framework7/lite-bundle'

Dom7

Framework7 v6 uses new Dom7 v3. It has breaking changes for all "iteration" methods like .each() and .map(). Specifically, order of arguments has been swapped to match native JavaScript array iterators:

// in v5 (Dom7 v2)
$('p').each((index, el) => {
  // ...
})

// in v6 (Dom7 v3) - arguments are swapped, element is now always the first argument
$('p').each((el, index) => {
  // ...
})

Template7

Template7 template library has been completely removed from Framework7. If your app still needs it, just install it manually:

npm i template7
import Template7 from 'template7';

Template7.compile('...');

Request

Request library's import has been renamed from Request to request. Also now it uses Promises for all methods. Check updated Request documentation.

// import renamed
import { request } from 'framework7/lite';

// not it always uses Promises
request.get('some-url').then((res) => {
  console.log(res.data);
});

Device & Support

Device & Support imports are also changed. Now only getters functions are available for imports.

In v5 we had:

import { Device, Support } from 'framework7';

if (Device.android) {
  console.log('it is Android');
}

if (Support.touch) {
  console.log('touch is supported');
}

In v6 we should use different approach:

import { getDevice, getSupport } from 'framework7';

const device = getDevice();
const support = getSupport();

if (device.android) {
  console.log('it is Android');
}

if (support.touch) {
  console.log('touch is supported');
}

Utils

Utils import has been renamed from Utils to utils:

// in v5
import { Utils } from 'framework7';

// in v6
import { utils } from 'framework7';

View/Router

Route Callback Context

Route's beforeEnter, beforeLeave, redirect and async methods now receive a single object with following props:

  • to
  • from
  • resolve
  • reject
  • direction (new in v6 - can be forward or backward)
  • router (new in v6 - current router instance)
  • app (new in v6 - f7 app instance)

Check updated Routes documentation for more details and examples.

pushState -> browserHistory

pushState parameters renamed to browserHistory:

// in v5
app.views.create('.view-main', {
  pushState: true,
  pushStateSeparator: '',
});

// in v6
app.views.create('.view-main', {
  browserHistory: true,
  browserHistorySeparator: '',
});

Route context

Route's options.context property has been removed in favor of using options.props. Check updated Routes documentation for more details and examples.

Route template and templateUrl

With removal of Template7, routes loaded by template and templateUrl are not supported anymore. Such routes should be migrated to Router Component

App data & methods

App data and methods parameters for storing "global" app state are completely removed.

Now Framework7 comes with new Store library for managing app state. Check new Store documentation and how to use in Framework7 Vue.

App root

App root parameter (to pass app root element) renamed to el:

// in v5
const app = new Framework7({
  root: '#app'
})

// in v6
const app = new Framework7({
  el: '#app'
})

app.root property with Dom7 instance of root element, renamed to app.$el

Virtual List

With removal of Template7, itemTemplate feature, to render virtual list items by Template7 template, is not supported anymore. It should be migrated to renderItem callback

Preloader

Preloader layout for MD theme has been changed to new SVG layout. Check updated Preloader documentation for more details and examples.

Skeleton Elements

Skeleton Elements now also integrated as a standalone library. For the full API documentation and more examples check out the official Skeleton Elements for HTML & CSS documentation.

New Router Component

Framework7 v6 has completely new syntax and functionality for Router Component. So v5 version which used Template7 is not supported anymore, and you should migrate all components to new Router Component syntax.

For example in v5:

<template>
  <div class="page">
    <p>Value is: {{foo}}</p>
    <p>
      <a href="#" @click="changeValue">Change value</a>
    </p>
    <ul>
      {{each items}}
      <li>{{title}}</li>
      {{/each}}
    </ul>
  </div>
</template>
<script>
  export default {
    data() {
      return {
        foo: 'bar',
        items: [
          {
            title: 'Item 1'
          },
          {
            title: 'Item 2'
          },
        ]
      }
    },
    methods: {
      changeValue() {
        this.foo = 'bar 2';
        this.$update();
      },
    },
    on: {
      pageInit() {
        this.$app.dialog.alert('page init')
      }
    }
  }
</script>

Should be changed to this in v6:

<template>
  <div class="page">
    <p>Value is: ${foo}</p>
    <p>
      <a href="#" @click=${changeValue}>Change value</a>
    </p>
    <ul>
      ${items.map((item) => $h`
      <li>${item.title}</li>
      `)}
    </ul>
  </div>
</template>
<script>
  export default (props, { $f7, $on, $update }) => {
    let foo = 'bar';
    const items = [
      {
        title: 'Item 1'
      },
      {
        title: 'Item 2'
      },
    ];

    const changeValue = () => {
      foo = 'bar 2';
      $update();
    }

    $on('pageInit', () => {
      $f7.dialog.alert('page init')
    })

    return $render;
  }
</script>