Back Button

Back Button Behavior

The back button in magic remote and your app should let users to navigate in your app as below.

How should your app behave when the back button of the magic remote control is pressed? Your app should behave as follows:

  • Move back to the previous screen.
  • If the current page is the entry page to your app, move back to the TV's Home screen.
For more about the mandatory guidance for webOS TV UX , see webOS TV UX Checklist.

Handling Back Button in App

In your app, you can combine the following options to handle the back button:

Using History API

By default, the platform itself handles back button press on a magic remote control, using the DOM's history object. If you want to customize back and forward navigation behavior, use the DOM's history object. When user moves another page or state, add the current state to the history stack with using history.pushState().

history.pushState(stateData, title, targetURL);

 

As long as something resides on the history stack, webOS TV apps will receive the popstate event when the back button is pressed. You can subscribe to the popstate event using the History API or by adding a listener to the event as shown below.

window.addEventListener("popstate", function(inEvent) {
	// received back, check inEvent.state if you want the data from the history push
});

 

In webOS TV, when the back button is pressed at the start point of your app, the screen control will be passed on to the Home screen. The following diagram shows the how the History object works and indicates when the Home screen should be displayed. If you set disableBackHistoryAPI property to true and use the History API, you should customize a popstate event handler to open the Home screen manually.

 

Use the popstate events and pushState() to keep track of app state, and allow users to navigate back within your app.

To see the sample code on handling back button press, see Back Button Control.

Handling Back Key Event

You can choose to make your app handle back button press, by receiving back key event. To handle the back button press as desired, indicate your intention on the appinfo.json file, by setting the disableBackHistoryAPI property to trueThis can be useful especially if your app consists of a single page; because taking track of history on a single-page app can be a real fuss.

 

To handle the back button press:

  1. Set the disableBackHistoryAPI property to true in appinfo.json file.
    {
    	...
    	disableBackHistoryAPI: true;
    	...
    }
    

     

  2. Add the back button keycode (0x1CD, 461 in decimal) in your event handler.
    window.addEventListener("keydown", function(inEvent){   
        if(window.event) {
            keycode = inEvent.keyCode;
        } else if(e.which) {
            keycode = inEvent.which;
        }
    	switch (keycode) {
    		case 461: doBack(); break;
    		case 38: doUp(); break;
    		case 40: doDown(); break;
    		...
    	}
    });
    

 

For more information on the magic remote control and key code of its buttons, see Remote Control.

 

Going Back to the HOME Screen

In case of managing your app state manually (such as when you set the disableBackHistoryAPI property to true), sometimes your app needs to display the Home screen forcibly. To make a navigate back to the TV's Home screen, use the webOS prototype provided through the webOS.js file.

The following code shows a one of cases which is using the webOS.platformBack() method in back button event handlers:

...
<script type="text/javascript" src="webOSjs-0.1.0/webOS.js"></script>
...
<script>
...
function doBack() {
	// Do something for Back button();
	
	// If you need to open Home UI
	if (someCondition == true)
		webOS.platformBack();
}
...
</script>

 

Also when you set disableBackHistoryAPI property to true and used the History API, you can use webOS.platformBack() as below:

window.addEventListener('popstate', function (event) {
	var data = event.state;
	if (data) {
		// do page move or anything else
		doSomething();
	} else {
		webOS.platformBack();
	}
		
}, false);
Navigation