OAuth with modal views

Modal views are a feature of Forge.

Modal views allow a second webpage to be loaded "on top" of the main web view in a Forge app. This allows a second page to be displayed without reloading the original, and also provides a dedicated button on the users screen to close the second view when their interaction has ended.

Modal views have two main purposes. The first is to provide quick access to part of your app without breaking the current workflow, and the second is to access an external site to perform a task such as authentication without the chance of the user being "trapped" on the external site if their device has no back button.

Internal pages

A simple use case for modal views is to display an options page at any point when users are interacting with a Forge app. This means an options page can be displayed, interacted with and closed, without the current page losing its state. To achieve this simply create a separate options page and when you want to display it use forge.tabs.open('options.html')

External authentication

A more advanced use of modal views is to send the user to an external site (potentially your own website), to allow them to authenticate in some way. After authentication is complete, you can watch for a URL match pattern and close the modal view when it is found.

Match pattern

To watch for a match pattern use code similar to:

forge.tabs.openWithOptions({
  url: 'http://my.server.com/login/',
  pattern: 'http://my.server.com/loggedin/*'
}, function (data) {
  forge.logging.log(data.url);
});

See the openWithOptions API documentation.

See http://developer.chrome.com/extensions/match_patterns.html for documentation on the Match Pattern format and semantics.

In this example the final url in the modal view will be logged, data could also be extracted from it and used to authenticate the user, such as the query string (used for OAuth 1) or the hash fragment (in OAuth 2).