Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

WebView

Methods 11  
Properties 16
Examples 5

The Webview is the core container used for rendering your application code. You can control certain behaviors of the webview by using this API class.

Enabling the API

This API is part of the coreapi extension that is included automatically.

extensions: ["coreapi"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

active_tab()

Deprecated

Use NativeTabbar.currentTab property: returns the current tab index.

Synchronous Return:

  • INTEGER

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.WebView.active_tab()
    • Ruby: Rho::WebView.active_tab()

currentLocation(INTEGER tabIndex)

Returns the relative url (location) of the current page(without server and port); the last URL loaded to WebView from Ruby controller action.

If you open your page in WebView, and after it makes a few jumps by linking (for example, to outside web adresses for example), currentLocation will still return the initial url opened in WebView. Also, if you use JQMobile, current_location has the initial URL, but does not reflect the actual window.location containing the JQMobile additional address by adding #, etc. See currentUrl.

Parameters

  • tabIndex : INTEGER Optional Default: -1

    TabBar tab index. If no tab bar present, index is ignored.Tab should be loaded once to return current url.

    Current location of active WebView.

Synchronous Return:

  • STRING

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Ruby: Rho::WebView.currentLocation(INTEGER tabIndex)

currentURL(INTEGER tabIndex)

Replaces: get_current_url

Returns the actual URL in WebView. This works the same as the JavaScript window.location.href.

Parameters

  • tabIndex : INTEGER Optional Default: -1

    TabBar tab index. If no tab bar present, index is ignored.

    Current url of active WebView.

Synchronous Return:

  • STRING

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Ruby: Rho::WebView.currentURL(INTEGER tabIndex)

executeJavascript(STRING javascriptText, INTEGER tabIndex)

Replaces: execute_js executeJavaScript

Execute JavaScript on the current page from your controller.

For most mobile platforms, WebView.execute_js has been implemented via redirection to URL with ‘javascript:’ schema. If WebView.execute_js used in an AJAX call handler method in the controller, it may lead to the situation where the success javascript handler will never be executed. This may happen because, at the moment of success handler should be executed, a URL of the page already has been changed. This means no handlers from the previous page are valid.

Parameters

  • javascriptText : STRING

    The call to the JavaScript method on the current page, such as “test();”.

  • tabIndex : INTEGER Optional Default: -1

    TabBar tab index. If no tab bar present, index is ignored.

    Execute javascript in active WebView.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Ruby: Rho::WebView.executeJavascript(STRING javascriptText, INTEGER tabIndex)

full_screen_mode(BOOLEAN enable)

Deprecated

Use WebView.fullScreen property: Switch to / from full screen mode.

Parameters

  • enable : BOOLEAN

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.WebView.full_screen_mode(BOOLEAN enable)
    • Ruby: Rho::WebView.full_screen_mode(BOOLEAN enable)

navigate(STRING url, INTEGER tabIndex)

navigateBack(INTEGER tabIndex)

refresh(INTEGER tabIndex)

Force WebView to refresh the current page.

Parameters

  • tabIndex : INTEGER Optional Default: -1

    TabBar tab index. If no tab bar present, index is ignored.

    Refresh active WebView.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.WebView.refresh(INTEGER tabIndex)
    • Ruby: Rho::WebView.refresh(INTEGER tabIndex)

save(STRING format, STRING path, INTEGER tabIndex)

Save current page to file system.

Parameters

  • format : STRING

    Format of the saved page.

    Possible Values :

    Constant: Rho::WebView.SAVE_FORMAT_JPEG (For Ruby use "::" instead of ".")
    String:jpeg

    Save as jpeg image.

  • path : STRING

    Path to the file / folder to save the page.

  • tabIndex : INTEGER Optional Default: -1

    TabBar tab index. If no tab bar present, index is ignored.

    If tabbar index omitted then active WebView will be saved.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.WebView.save(STRING format, STRING path, INTEGER tabIndex)
    • Ruby: Rho::WebView.save(STRING format, STRING path, INTEGER tabIndex)

setCookie(STRING url, STRING cookie)

When WebView loads the specified url (either by selecting link or from calling WebView.navigate), it will add this cookie to the HTTP request.Not implemented for WebKit.

Parameters

  • url : STRING

    Set a cookie to be used by WebView for this url.

  • cookie : STRING

    One or more name-value pairs of the format “NAME=VALUE”. Separate multiple name-value pairs with a semicolon, such as “NAME1=VALUE1; NAME2=VALUE2”.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Ruby: Rho::WebView.setCookie(STRING url, STRING cookie)

set_menu_items(HASH menuItems)

Deprecated

Use Application.nativeMenu property: set native menu items.

Parameters

  • menuItems : HASH

    Map of menu items: name to action.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.WebView.set_menu_items(HASH menuItems)
    • Ruby: Rho::WebView.set_menu_items(HASH menuItems)

Properties

activeTab : INTEGER Read Only

Return an active tab index. For change active tab use Use Rho.NativeTabbar.currentTab property.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.activeTab

cacheSize : INTEGER Read Only

The browser cache size, in whole MBs. Defines in config.xml: Navigation\Cache.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.cacheSize

enableCache : BOOLEAN Read Only

Enable / disable Browser cache. Use ‘WebView.enableCache’ parameter in rhoconfig.txt to configure this value.

Default: true

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.enableCache

enablePageLoadingIndication : BOOLEAN Read Only

Show page loading indication. On Windows Mobile/CE this property can be set only in config.xml: GUI\HourglassEnabled. At Android use ‘disable_loading_indication’ parameter in rhoconfig.txt to configure this value.

Default: true

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.enablePageLoadingIndication

enableWebPlugins : BOOLEAN Read Only

Enable / disable web plug-ins. Use ‘enable_web_plugins’ parameter in rhoconfig.txt to configure this value. This option only has effect on Android versions before 4.0 (ICS). It mainly affects if Flash content is displayed.

Default: true

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.enableWebPlugins

enableZoom : BOOLEAN Read Only

Enable WebView zoom. Use ‘enable_screen_zoom’ parameter in rhoconfig.txt to configure this value.

Default: true

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.enableZoom

fontFamily : STRING Read Only

Specifies the default font to use when rendering text in web pages. The specified font should be a TrueType font present on the device. On Windows the default font has been set to ‘Tahoma’ as this is present on all Symbol WM / CE devices, note that Tahoma has no italic or oblique variants. On the Enterprise Tablet the default is Droid Sans Fallback. The font specified must be stored in \Windows for Windows WM / CE devices, or /system/fonts for Enterprise Tablet. Defines in config.xml: HTMLStyles\FontFamily

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.fontFamily

framework : STRING Read Only

Same as System.webViewFramework.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.framework

fullScreen : BOOLEAN

Use full screen mode.

Default: true

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.fullScreen

navigationTimeout : INTEGER

Can be defined in config.xml: Navigation\NavTimeout. Number of milliseconds(maximum is 45000) before the browser times out and navigates to the page specified in the badlink setting. If it is determined that the destination is unreachable regardless of wait time, the badlink may be loaded before NAVTIMEOUT. This is the time taken to establish communication with the server, not the time taken to fully load the page.Note that the navigation timeout will not be invoked when navigating to the start page, best practice is to store your first page locally to avoid connectivity issues at start up, you can then redirect to an online page if desired.

Default: 45000

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.navigationTimeout

scrollTechnique : STRING Read Only

Specifies the technique used to scroll about the page.Defines in config.xml: Scrolling\ScrollTechnique.

Default: FingerScroll

Possible Values (STRING):

Constant: Rho.WebView.SCROLL_NONE (For Ruby use "::" instead of ".")
String: None

No scrollbars will be displayed and the page will not respond to finger swipes.

Constant: Rho.WebView.SCROLL_SCROLLBARS (For Ruby use "::" instead of ".")
String: Scrollbars

When the size of the page is larger than the screen scrollbars will be presented which can be used to scroll the page.

Constant: Rho.WebView.SCROLL_FINGER (For Ruby use "::" instead of ".")
String: FingerScroll

You can scroll around the page using finger swiping.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.scrollTechnique

textZoomLevel : INTEGER

Sets the font size to be displayed on the page, set to 0 for the smallest font and 4 for the largest font.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.textZoomLevel

userAgent : STRING Read Only

Defines in config.xml: Navigation\UserAgent. When visiting a web server the WebKit browser will report its self as the specified user agent. Use the following substitution variables:

  • %p – platform name (“Windows CE ” + version number)
  • %w – WebKit version number
  • %e – WebKit version number.

Use the UserAgent setting to spoof your device to the server, e.g. to view content designed for the desktop on your mobile screen. From RhoElements 2.1 onwards the default value was changed to work out of the box with a greater number of server configurations, prior to RhoElements 2.1 the default user agent was: “Mozilla/5.0 (%p) AppleWebKit/%w (KHTML, like Gecko) WebKit/%e Safari/%w”

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.userAgent

viewportEnabled : BOOLEAN Read Only

Whether to enable or disable viewport meta tag processing.Defines in config.xml: Navigation\ViewportEnabled.

Default: true

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.viewportEnabled

viewportWidth : INTEGER Read Only

Default viewport width to use for pages that do not have a viewport meta tag (uses 1:1 scaling if not specified).Defines in config.xml: Navigation\ViewportWidth.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.viewportWidth

zoomPage : FLOAT

Sets the zoom factor of the page. Factor 1.0 is no zoom, values less than 1.0 are zoomed out and values greater than 1.0 are zoomed in. In Windows, it is recommended to not to use the zoom value less than 1.0 because the page doesn’t look in readable format.

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.zoomPage

Examples

Execute javascript

You can call the WebView and make it execute JavaScript code from a Ruby controller. This can be particularly helpful in order to reuse JavaScript functionality that is already included in your pages.

#call javascript alert on the current page
Rho::WebView.executeJavascript("alert('This is Webview.executejavascript function');")

As an example, you can invoke JQuery Mobile’s changePage.

#call JQuery Mobile from a Ruby controller
Rho::WebView.executeJavascript("$.mobile.changePage('#my_page');")

You can also call your own functions.

function greet(name) {
    alert("Hello, "+name);  
}

From the Ruby controller we can execute the JavaScript function that may be in the view.

#call a custom JavaScript function from Ruby
Rho::WebView.executeJavascript("greet('John Doe');")
Use full-screen mode

The WebView can be set to use all the available screen real-estate by turning on “full-screen” mode.

# Toggle fullScreen on / off
Rho::WebView.fullScreen = !Rho::WebView.fullScreen

This property can also be assigned to in JavaScript.

// Fullscreen can also be invoked from JavaScript
Rho.WebView.fullScreen = true;

Rho.WebView.fullScreen = false;
Navigate

This is the section that will appear before the code block.

#Force WebView to navigate to a URL.
Rho::WebView.navigate(url_for(:action => :my_action))

You can also navigate outside of your application, to an external site.

#Navigate out of the local application and into an externally-served site
Rho::WebView.navigate("http://www.example.com");

This API is also available from JavaScript.

//Navigate out of the local application and into an externally-served site
Rho.WebView.navigate("http://www.example.com");
Navigate back

This is the section that will appear before the code block.

#Force WebView to navigate to the previous page using Browser back.
Rho::WebView.navigateBack

The same method is available in JavaScript.

//Force WebView to navigate to the previous page using Browser back.
Rho.WebView.navigateBack();
Refresh the page

Reload the current URL into the WebView. This is useful especially after having updated data that must be now shown to the user

# Update database or variables here
# ...     
# Refresh the current page to show new information
Rho::WebView.refresh

By default, “refresh” will update the current view. If you are using the native Tabbar and have multiple WebViews, you can specify which one to refresh.

# Reload the page on WebView number 2
Rho::WebView.refresh(2)

Also available from JavaScript.

// Reload the current page
Rho.WebView.refresh()

// Reload the page on WebView number 3
Rho.WebView.refresh(3)