native.showWebPopup()

Type Function
Library native.*
Return value none
Revision Current Public Release (2014.2393)
Keywords web view, web popup, web overlay
See also native.newWebView()

Overview

Creates a web popup that loads a local or remote web page.

Gotchas

General

  • Web popups are only available on the Mac OS X Simulator and device builds.

  • Only one Web popup object can be displayed at a time. For multiple web overlays, see native.newWebView().

  • Web popup objects cannot be moved or resized. They must be canceled and recreated if they need to be moved or resized.

  • Web popup objects, like other native objects, don't work in groups and are always displayed on top of regular display objects (images, text, etc.).

iOS

On iOS, when checking for event.errorMessage in a web popup listener, you may occasionally receive an error message such as NSURLerrorDomain error -999. This is returned when an asynchronous load is cancelled. A Web Kit framework delegate will receive this error when it performs a cancel operation on a loading resource, however a NSURLConnection or NSURLDownload delegate will not receive this error if the download is cancelled. This event/error may occur if a link within the web popup is clicked while the web popup is still in the process of loading the first page. Generally speaking, this error can be ignored.

Android

If the web popup is displaying web pages from the Internet, then you must add an Internet permission to your build.settings file. This permission is unnecessary if the web popup will only be displaying local HTML files that do not access the Internet.

settings =
{
    android =
    {
        usesPermissions =
        {
            "android.permission.INTERNET",
        },
    },
}

Syntax

native.showWebPopup( url [, options] )  
native.showWebPopup( x, y, width, height, url [, options] )
url (required)

String. URL of the local or remote web page. By default, the URL is assumed to be an absolute URL to a remote server. If x, y, width, height are not specified, the popup occupies the entire screen.

x, y, width, height (optional)

Numbers. If specified, these parameters control the position and dimensions of the popup.

options (optional)

Table. Table containing additional parameters for the popup — see the next section for details.

Options Reference

This is an optional table you can pass containing additional options for the web popup.

local options =
{
    baseUrl = system.ResourceDirectory, -- default: nil
    hasBackground = false,  -- default: true
    autoCancel = false,  -- default: true (Android)
    urlRequest = listener_function  -- default: nil
}
baseUrl (optional)

String or Constant. Determines whether the URL parameter to native.showWebPopup() is interpreted as a relative or absolute URL.

  • By default, nil means the URL is absolute.
  • To refer to a local file instead, set the base URL to one of the base directory constants, for example system.ResourceDirectory. Then the URL parameter is relative to that base directory.
  • For remote files, you can also specify a remote base, and the URL parameter will be relative to the remote base.
hasBackground (optional)

Boolean. Controls whether the popup has a an opaque background or not. If not specified, the background will be opaque (true).

autoCancel (optional)

Boolean. Sets up the popup to be automatically closed when the Android back key has been pressed and there is no more web history to navigate to. This is true by default.

urlRequest (optional)

Function. Designates a listener function that will intercept all urlRequest events from the popup. This also provides a standard method for passing information back from a web page using pseudo-URLs. For example:

<form action="corona:close" />
    <input type="submit" />
</form>

In this example, when the user clicks Submit in the web popup, the designated listener function is sent a urlRequest event object with its URL property set to "corona:close", thus allowing the application to react appropriately. Note that the listener function must return true or the web popup will close. Without a return statement, false is assumed.

Example

local function listener( event )
    local shouldLoad = true

    local url = event.url
    if 1 == string.find( url, "corona:close" ) then
        -- Close the web popup
        shouldLoad = false
    end

    if event.errorCode then
        -- Error loading page
        print( "Error: " .. tostring( event.errorMessage ) )
        shouldLoad = false
    end

    return shouldLoad
end

local options =
{
    hasBackground = false,
    baseUrl = system.DocumentsDirectory,
    urlRequest = listener
}
native.showWebPopup( "localpage1.html", options )