Back Button

The Back button on Magic Remote helps users navigate back easily in your app. When a user presses the Back button on Magic Remote, your app should either:

  • Move back to the previous page, or

  • If the current page is the entry page to your app, switch back to the Home screen.

For more about the mandatory guidance for webOS TV UX, see webOS TV UX Checklist.

 

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

Using History API

By default, the webOS TV Platform itself handles the Back button press on Magic Remote using the DOM's history object. So, if you want to customize the backward and forward navigation behaviors, use the DOM's history object.

To make your app move to another page or state, add the current state to the history stack using history.pushState().

history.pushState(stateData, title, targetURL);

As long as something resides in the history stack, your app receives the popstate event when a user presses the Back button. Your app can subscribe to the popstate event using the History API or by adding an event listener 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 a user presses the Back button at the entry page of your app, the screen control is passed on to the Home screen.

The following diagram shows how the history object works and when the Home screen should be displayed. 

Example chart of history object and back button using History API

To keep the track of your app's state, use the popstate event and pushState() method. That will allow users to navigate back within the app.

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

Handling a back button event

You can make your app handle the Back button press by receiving a back button event. This options is especially useful if your app consists of a single page, because otherwise, tracking the history of such app can be a real fuss.

Here’s how you handle the Back button press in your app.

  1. Set the disableBackHistoryAPI property to true in the appinfo.json file.

    {
    	...
    	disableBackHistoryAPI: true;
    	...
    }
    
  2. Add the back button keycode (0x1CD, 461 in decimal) in your event listener.

    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 about Magic Remote and key code of its buttons, see Magic Remote.

Implementing a navigation back to the Home screen

If your app handles the back button press manually (for example, when you set the disableBackHistoryAPI property to true), sometimes it needs a forcible navigation back to the Home screen. To implement a navigation back to the Home screen, use the webOS prototype provided through the webOSTV.js file.

The following code is an example of using the webOS.platformBack() method in the back button event listener.

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

If 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