📺 "One project. One language. Three apps." Learn more in our upcoming code sharing webinar!

NativeScript Core

Frame

The Frame class represents the logical unit that is responsible for navigation between different pages. An application can have single or multiple Frame instances depending on the business logic and requirements.

Frame Creation

The frame should have the defaultPage property set (mandatory). The page passed as value for defaultPage will load on frame initialization. The id property can be used to get a reference to the frame instance.

<Frame id="root-frame" defaultPage="main-page"/>

More complex application structure can be created by using multiple frame instances.For example, you can create a TabView while using different frames for each tab item.

<TabView>
    <TabViewItem title="First">
        <Frame id="firstFrame" defaultPage="home/home-page" />
    </TabViewItem>
    <TabViewItem title="Second">
        <Frame id="secondFrame" defaultPage="second/second-page" />
    </TabViewItem>
</TabView>

Improve this document

Demo Source


Frame Reference

The navigation in NativeScript is based on the Frame API and using navigate method of the wanted frame. To get a reference to the Frame instance you need use the following methods or properties:

  • the topmost method from the tns-core-modules/ui/frame module. The method returns the last navigated Frame instance or in case you are in a TabView, the currently selected tab item's Frame instance. For more complex cases or more control, you should use methods like getFrameById or the frame property of Page class.
const topmost = require("tns-core-modules/ui/frame").topmost;

const topmostFrame = topmost();
import { Frame, topmost } from "tns-core-modules/ui/frame";

const topmostFrame: Frame = topmost();
  • the getFrameById method from the tns-core-modules/ui/frame module. This method allows you to get a reference to a Frame by a id that you specified on the element. Note that this searches for already navigated frames and won't find frames that are not yet displayed like in a modal view for example.
<Frame id="root-frame" defaultPage="main-page"/>
const getFrameById = require("tns-core-modules/ui/frame").getFrameById;

const currentFrame = getFrameById("root-frame");
import { getFrameById } from "tns-core-modules/ui/frame";

const currentFrame: Frame = getFrameById("root-frame");
  • the frame property of Page instance. Each Page instance carries information about the frame object which navigated to it in the frame property. This lets you navigate with the frame property as well.
function onTap(args) {
    const button = args.object;
    const page = button.page;
    const myFrame = page.frame;
    myFrame.navigate("secondary-page");
}
exports.onTap = onTap;
import { Button } from "tns-core-modules/ui/button";
import { Page } from "tns-core-modules/ui/page";

export function onTap(args) {
    const button: Button = args.object;
    const page: Page = button.page;
    const myFrame: Frame = page.frame;
    myFrame.navigate("secondary-page");
}

Note We can get a reference to a Frame only for a frame that has been already loaded in the visual tree. Frames that are not still loaded (for example a Frame within a modal page that is not yet opened) can not be retrieved.

Improve this document

Demo Source


Basic Navigation

Default page

To load a default (initial) page in your application use the defaultPage property of the Frame element. With the example below the applicaiton will load a page located in <project-folder>/app/home/first-page.xml

<Frame id="my-frame-id" defaultPage="home/first-page"/>

To navigate between pages, you can use the navigate method of the desired Frame instance.

const getFrameById = require("tns-core-modules/ui/frame").getFrameById;
    // Example using `getFrameById(frameId)` to get a `Frame` reference
    // As an alternative, we could use `topmost()` method or `page.frame` property
    const frame = getFrameById("my-frame-id");
    frame.navigate("home/second-page");

import { getFrameById } from "tns-core-modules/ui/frame";
    // Example using `getFrameById(frameId)` to get a `Frame` reference
    // As an alternative, we could use `topmost()` method or `page.frame` property
    const frame = getFrameById("my-frame-id");
    frame.navigate("home/second-page");

The navigate method accepst NavigationEntry object

const frame = getFrameById("my-frame-id");

const navigationEntry = {
    moduleName: "home/second-page",
    context: { info: "something you want to pass to your page" },
    animated: false
};
frame.navigate(navigationEntry);
const frame = getFrameById("my-frame-id");

// import { NavigationEntry } from "tns-core-modules/ui/frame";
const navigationEntry: NavigationEntry = {
    moduleName: "home/second-page",
    context: { info: "something you want to pass to your page" },
    animated: false
};
frame.navigate(navigationEntry);

Improve this document

Demo Source


Dynamic Navigation

A more dynamic way of navigating can be done by providing a function that returns the instance of the page to which you want to navigate.

const frame = getFrameById("my-frame-id");
frame.navigate({
    create: () => {
        const stack = new StackLayout();
        const label = new Label();
        label.text = "Hello, world!";
        stack.addChild(label);

        const page = new Page();
        page.content = stack;

        return page;
    }
});
const frame = getFrameById("my-frame-id");

frame.navigate({
    create: () => {
        const stack = new StackLayout();
        const label = new Label();
        label.text = "Hello, world!";
        stack.addChild(label);

        const page = new Page();
        page.content = stack;

        return page;
    }
});

Improve this document

Demo Source


Passing context during navigation

When you navigate to another page, you can pass context to the page with a NavigationEntry object. The navigaiton entry provides two different (optional) propertes to work with:

  • The context property
exports.onNavigate = function(args) {
    const button = args.object;
    const page = button.page;
    const frame = page.frame;

    const navEntryWithContext = {
        moduleName: "home/second-page",
        context: {
            name: "John",
            age: 25,
            isProgramer: true
        }
    };

    frame.navigate(navEntryWithContext);
};
import { EventData } from "tns-core-modules/data/observable";
import { Button } from "tns-core-modules/ui/button";
import { Page } from "tns-core-modules/ui/page";
import { Frame, NavigationEntry } from "tns-core-modules/ui/frame";

export function onNavigate(args: EventData) {
    let button = <Button>args.object;
    let page = <Page>button.page;
    let frame = <Frame>page.frame;

    let navEntryWithContext: NavigationEntry = {
        moduleName: "home/second-ts-page",
        context: {
            name: "John",
            age: 25,
            isProgramer: true
        }
    };

    frame.navigate(navEntryWithContext);
}
  • The bindingContext property.
const navEntryWithBindingContext = {
    moduleName: "home/second-ts-page",
    // when using bindingContext the landing page will automatically
    // receive and set this object as page.bindingContext with navigatedTo event
    bindingContext: {
        name: "John",
        age: 25,
        isProgramer: true
    }
};
const navEntryWithBindingContext: NavigationEntry = {
    moduleName: "home/second-ts-page",
    // when using bindingContext the landing page will automatically
    // receive and set this object as page.bindingContext with navigatedTo event
    bindingContext: {
        name: "John",
        age: 25,
        isProgramer: true
    }
};

Both properties are used to pass context while navigating, but the bindingContext property will automatically assign the binding context for the landing page.

Retreiving context during navigation

Any context send with bindingContext is automatically assigned as binding context for the navigated (landing) page. Retreiving a context send through the context property, can be achieved with two different approaches.

  • Accessing the navigationContext property of your landing Page instance.
  • Using the navigatedTo event and its arguments of type NavigatedData.
function onNavigatedTo(args) {
    const page = args.object;
    const navigationContext = page.navigationContext;

    // The navigation event arguments are of type NavigatedData and provide another way to grab the passed context
    const context = args.context;

    page.bindingContext = navigationContext;
}
exports.onNavigatedTo = onNavigatedTo;
import { Page, NavigatedData } from "tns-core-modules/ui/page";

// Event handler for Page "navigatedTo" event attached in details-page.xml e.g.
export function onNavigatedTo(args: NavigatedData): void {
    const page: Page = <Page>args.object;
    const navigationContext = page.navigationContext;

    // The navigation event arguments are of type NavigatedData and provide another way to grab the passed context
    const context = args.context;

    page.bindingContext = navigationContext;
}

Improve this document

Demo Source


See Also Page See Also ActionBar