Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

WebView

Methods14
Methods - Class
active_tabcurrentLocationcurrentURLexecuteJavascriptfull_screen_modegetCookiesnavigatenavigateBackrefreshremoveAllCookiesremoveCookiesavesetCookieset_menu_items
Properties19
Class Properties
activeTabcacheSizeenableCacheenableDragAndDropenableMediaPlaybackWithoutGestureenablePageLoadingIndicationenableWebPluginsenableZoomfontFamilyframeworkfullScreenkeyboardDisplayRequiresUserActionnavigationTimeoutscrollTechniquetextZoomLeveluserAgentviewportEnabledviewportWidthzoomPage
Examples5
Execute javascriptUse full-screen modeNavigateNavigate backRefresh the page

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.
    • JavaScript: Rho.WebView.executeJavascript(STRING javascriptText, INTEGER tabIndex)
    • 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)
getCookies
(STRING url, CallBackHandler callback)

Returns cookies map for specified URL. Crosswalk is not supported.

Parameters

  • url : STRING

    An URL to retrieve cookies for.

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    Synchronous Return:

    • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.WebView.getCookies(STRING url, CallBackHandler callback)
      • Ruby: Rho::WebView.getCookies(STRING url, CallBackHandler callback)
    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)
    removeAllCookies
    (CallBackHandler callback)

    Removes all cookies for application’s webview. Crosswalk is not supported.

    Parameters

    • callback : CallBackHandler Mandatory

    Async Callback Returning Parameters: HASH

      Synchronous Return:

      • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

      Method Access:

      • Class Method: This method can only be accessed via the API class object.
        • JavaScript: Rho.WebView.removeAllCookies(CallBackHandler callback)
        • Ruby: Rho::WebView.removeAllCookies(CallBackHandler callback)
      removeCookie
      (STRING url, STRING name, CallBackHandler callback)

      Removes cookie by its name for specified URL. Crosswalk is not supported.

      Parameters

      • url : STRING

        An URL to remove cookie from.

      • name : STRING

        A cookie name to be removed.

      • callback : CallBackHandler Mandatory

      Async Callback Returning Parameters: HASH

        • removed_cookie : STRING

          A name of removed cookie if it was removed successfully

      Synchronous Return:

      • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

      Method Access:

      • Class Method: This method can only be accessed via the API class object.
        • JavaScript: Rho.WebView.removeCookie(STRING url, STRING name, CallBackHandler callback)
        • Ruby: Rho::WebView.removeCookie(STRING url, STRING name, CallBackHandler callback)
      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 "::" for all "." when referencing constants)
        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

        Cookie value in RFC format, for instance ‘session=123;expires=Fri, 31 Dec 2010 23:59:59 GMT; path=/;

      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
      enableDragAndDrop
      : BOOLEAN

      enable drag and drop operations for iOS >= 11.0

      Default: true

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.enableDragAndDrop
      enableMediaPlaybackWithoutGesture
      : BOOLEAN Read Only

      Enable Media playback without gesture. If set to true, the application can play some medias (video, sound) without requiring a user gesture.

      Default: false

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.enableMediaPlaybackWithoutGesture
      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: false

      Property Access:

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

      Attention: not worked with WKWebView! Can be defined in rhoconfig.txt as “WebView.keyboardDisplayRequiresUserAction” to 1 or 0. When this property is set to true, the user must explicitly tap the elements in the web view to display the keyboard (or other relevant input view) for that element. When set to false, a focus event on an element causes the input view to be displayed and associated with that element automatically.

      Default: true

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.keyboardDisplayRequiresUserAction
      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 "::" for all "." when referencing constants)
      String: None

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

      Constant: Rho.WebView.SCROLL_SCROLLBARS (For Ruby use "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      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.It is recommended to not to use the zoom value less than 1.0 because the page doesn’t look in readable format.In Android new Zoom value takes effect on current page, Previous page has to be revisited for the new zoom values to take effect

      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)