# Titanium.UI.WebView
The web view allows you to open an HTML5 based view which can load either local or remote content.
# Overview
Use the Titanium.UI.createWebView method or <WebView>
Alloy element to create a web view.
Web views are more expensive to create than other native views because of the requirement to load the HTML browser into memory.
The web view content can be any valid web content such as HTML, PDF, SVG or other WebKit supported content types.
# JavaScript Context in WebViews--Local vs. Remote Content
JavaScript in the web view executes in its own context. The web view can interact with this content, but most of this functionality is limited to local content.
Local Scripts
When running local web content (that is, content that is included in the application's resources), scripts have access to the Titanium namespace. In particular, when running local web content:
You can use Titanium.App.addEventListener and Titanium.App.fireEvent to receive and send application-level events.
Events can be logged using the Titanium.API logging methods.
Remote Scripts
Scripts downloaded from remote web servers cannot access the Titanium namespace.
To interact with remote content, wait until the content is loaded, then use the Titanium.UI.WebView.evalJS method to execute a JavaScript expression inside the web view and retrieve the value of an expression.
You can inject the local Ti.App.fireEvent
bindings yourself by adding a script element using
evalJS.
webview.evalJS(
'javascript=(function addBinding(){' +
'var s=document.createElement("script");' +
's.setAttribute("type","text/javascript");' +
's.innerHTML="' + /* insert content of binding.min.js */ + '";'
+
'document.getElementsByTagName("body")[0].appendChild(s);' +
'})()'
);
The binding.min.js
is available in the repository (opens new window).
For iOS check the example in Titanium.UI.WebView.addScriptMessageHandler.
# Local JavaScript Files
During the build process for creating a package, all JavaScript files, that is, any file with a '.js' extension, are removed and their content is encrypted and obfuscated into one resource, causing these files to not load properly in a WebView if they are loaded externally.
For JavaScript files referenced in static local HTML files, these JavaScript files are omitted from processing and left intact, which means they can be correctly loaded in the WebView.
For local JavaScript files not referenced in static local HTML files, for example, a dynamically-generated HTML file referencing a local JavaScript file, rename the file extension of the local JavaScript files to '.jslocal' instead of '.js'.
The build process for testing your application on the simulator, emulator or device does not affect the loading of local JavaScript files.
# iOS Platform Implementation Notes
On the iOS platform, the native web view handles scrolling and other related touch
events internally. If you add event listeners on the web view or its parent views
for any of the standard touch events (touchstart
, click
, and so on), these events
do not reach the native web view, and the user will not be able to scroll, zoom, click
on links, and so on. To prevent this default behavior, set
Titanium.UI.WebView.willHandleTouches to false
.
In other words, you can have either Titanium-style events against the web view instance, or internal JavaScript events in the DOM, but not both.
# Android Platform Implementation Notes
Android 4.4 and Later Support
Starting with Android 4.4 (API Level 19), the WebView component is based off of Chromium, introducing a number of changes to its rendering engine. Web content may look or behave differently depending on the Android version. The WebView does not have full feature parity with Chrome for Android.
By default, the Chromium WebView uses hardware acceleration, which may cause content to fail to render. If the WebView fails to render the content, the web view will clear itself, displaying only the default background color. The following log messages will be displayed in the console:
[WARN] : AwContents: nativeOnDraw failed; clearing to background color.
[INFO] : chromium: [INFO:async_pixel_transfer_manager_android.cc(56)]
To workaround this issue, you can enable software rendering by setting the WebView's Titanium.UI.WebView.borderRadius property to a value greater than zero.
If you are developing local HTML content and size your elements using percentages, the WebView may not calculate the sizes correctly when hardware acceleration is enabled, resulting in the same behavior previously mentioned.
To workaround this issue, you can use the previously mentioned workaround to enable software
rendering, use absolute size values or use the
onresize (opens new window) event to set the
heights of the components. For example, if you have a div element with an id set to component
that needs to use the entire web view, the following callback resizes the content to use the
full height of the web view:
window.onresize= function(){
document.getElementById("component").style.height = window.innerHeight + 'px';
};
For more information, see the following topics:
- Android Developers: Migrating to WebView in Android 4.4 (opens new window)
- Google Chrome: WebView for Android (opens new window)
Plugin Support
The Android web view supports native plugins.
To use plugin content, you must set the Titanium.UI.WebView.pluginState property to either Titanium.UI.Android.WEBVIEW_PLUGINS_ON or Titanium.UI.Android.WEBVIEW_PLUGINS_ON_DEMAND.
You must also call Titanium.UI.WebView.pause when the current activity is paused, to prevent plugin content from continuing to run in the background. Call Titanium.UI.WebView.resume when the current activity is resumed. You can do this by adding listeners for the Activity.pause and Activity.resume events.
Accessing Cookies
On Android, the web view uses the system cookie store which does not share cookies with the Titanium.Network.HTTPClient cookie store. Developers can manage their cookies for both cookie stores using the methods Titanium.Network.addHTTPCookie, Titanium.Network.addSystemCookie, Titanium.Network.getHTTPCookies, Titanium.Network.getHTTPCookiesForDomain, Titanium.Network.getSystemCookies, Titanium.Network.removeHTTPCookie, Titanium.Network.removeHTTPCookiesForDomain, Titanium.Network.removeAllHTTPCookies, Titanium.Network.removeSystemCookie, Titanium.Network.removeAllSystemCookies.
WKWebView
With Titanium SDK 8.0.0, we now use WKWebView to implement Ti.UI.WebView (as Apple has deprecated UIWebView). WKWebView has few restriction specially with local file accessing. For supporting custom-fonts with WKWebView a little modification is required in the HTML files:
<style>
@font-face
{
font-family: 'Lato-Regular';
src: url('fonts/Lato-Regular.ttf');
}
</style>
To have a WKWebView scale the page the same way as UIWebView, add the following meta tag to the HTML header:
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
</html>
# Ti.UI.SIZE and WebViews
With Titanium 8.0.0+, Titanium.UI.SIZE does not work for WebViews. We recommend to give a fixed height to Titanium.UI.WebView (as noted in TIDOC-3355 (opens new window)).
As a workaround you can try to get the document.body.scrollHeight
inside Titanium.UI.WebView.load event
of webview and set the height to webview. See following example.
var win = Ti.UI.createWindow();
var verticalView = Ti.UI.createView({layout: 'vertical', width: "100%", height: "100%"});
verticalView.add(Ti.UI.createLabel({text: 'Label 1', top: 30, width: Ti.UI.SIZE, height: Ti.UI.SIZE}));
var htmla = "<div style='font-family: Helvetica Neue; font-size:16px'><ul><li>Item 1</li><li>Item 2</li></ul></div>";
var html = "<!DOCTYPE html>";
html += "<html><head><meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0'><style type='text/css'>html {-webkit-text-size-adjust: none;}</style><script type='text/javascript'>document.ontouchmove = function(event){event.preventDefault();}</script></head><body style='overflow: hidden'>";
html += htmla;
html += "</body></html>";
var webview = Ti.UI.createWebView({left: '14dp', right: '14dp', top: '7dp', height: Ti.UI.SIZE, html: html, backgroundColor: "yellow"});
verticalView.add(webview);
verticalView.add(Ti.UI.createLabel({text: 'Label 2', top: 30, width: Ti.UI.SIZE, height: Ti.UI.SIZE}));
win.add(verticalView);
win.open();
webview.addEventListener('load', function(e) {
var result = webview.evalJSSync('document.body.scrollHeight');
Ti.API.info('webview height: ' + result);
webview.height = result;
});
# For More Information
See Integrating Web Content (opens new window) in the Titanium Mobile Guides for more information on using web views, including use cases, more code examples, and best practices for web view content.
# Examples
# Basic Web View to External URL
Create a web view to a remote URL and open the window as modal.
var webview = Titanium.UI.createWebView({url:'http://www.titaniumsdk.com'});
var window = Titanium.UI.createWindow();
window.add(webview);
window.open({modal:true});
# Alloy XML Markup
Previous example as an Alloy view.
<Alloy>
<Window id="win" modal="true">
<WebView id="webview" url="http://www.titaniumsdk.com" />
</Window>
</Alloy>
# Listening to Web View properties in iOS
Create a web view and listen 'title' property of web view.
var webview = Ti.UI.createWebView({
url:'http://www.titaniumsdk.com'
});
webview.startListeningToProperties([ 'title' ]);
webview.addEventListener('title', function(e) {
alert('Title is : -' +e.value);
});
var window = Ti.UI.createWindow();
window.add(webview);
window.open();
# Usage of allowedURLSchemes and handleurl in iOS
Create a web view and listen 'handleurl' event to open url from Titanium platform.
var webview = Ti.UI.createWebView({
url: 'https://www.google.com',
allowedURLSchemes: [ 'https', 'http' ]
});
webview.addEventListener('handleurl', function(e) {
var handler = e.handler;
Ti.Platform.openURL(e.url);
handler.invoke(Ti.UI.iOS.ACTION_POLICY_CANCEL);
});
var window = Ti.UI.createWindow();
window.add(webview);
window.open();
# Properties
# accessibilityDisableLongPress CREATION ONLY
Boolean value to remove the long press notification for the device's accessibility service.
Will disable the "double tap and hold for long press" message when selecting an item.
Default: true
Whether the view should be "hidden" from (i.e., ignored by) the accessibility service.
On iOS this is a direct analog of the accessibilityElementsHidden
property defined in the
UIAccessibility
Protocol.
On Android, setting accessibilityHidden
calls the native
View.setImportantForAccessibility
method. The native method is only available in Android 4.1 (API level 16/Jelly Bean) and
later; if this property is specified on earlier versions of Android, it is ignored.
Default: false
# accessibilityHint
Briefly describes what performing an action (such as a click) on the view will do.
On iOS this is a direct analog of the accessibilityHint
property defined in the
UIAccessibility Protocol.
On Android, it is concatenated together with
accessibilityLabel and accessibilityValue in the order: accessibilityLabel
,
accessibilityValue
, accessibilityHint
. The concatenated value is then passed as the
argument to the native View.setContentDescription method.
Default: null
# accessibilityLabel
A succint label identifying the view for the device's accessibility service.
On iOS this is a direct analog of the accessibilityLabel
property defined in the
UIAccessibility Protocol.
On Android, it is concatenated together with
accessibilityValue and accessibilityHint in the order: accessibilityLabel
,
accessibilityValue
, accessibilityHint
. The concatenated value is then passed as the
argument to the native View.setContentDescription method.
Defaults to Title or label of the control.
# accessibilityValue
A string describing the value (if any) of the view for the device's accessibility service.
On iOS this is a direct analog of the accessibilityValue
property defined in the
UIAccessibility Protocol.
On Android, it is concatenated together with
accessibilityLabel and accessibilityHint in the order: accessibilityLabel
,
accessibilityValue
, accessibilityHint
. The concatenated value is then passed as the
argument to the native View.setContentDescription method.
Defaults to State or value of the control.
# allowedURLSchemes
List of allowed URL schemes for the web view.
See the example section "Usage of allowedURLSchemes and handleurl in iOS".
# allowFileAccess
A Boolean value indicating file access within WebView.
Set to true
to enable access to local files for examples images stored in applicationDataDirectory. If false resources are still accessible using file:///android_asset
and file:///android_res
. Do not enable this if your app accepts arbitrary URLs from external sources.
Default: false
A Boolean value indicating whether horizontal swipe gestures will trigger back-forward list navigations.
Default: false
# allowsLinkPreview
A Boolean value that determines whether pressing on a link displays a preview of the destination for the link.
This property is available on devices that support 3D Touch. Default value is false
.
If you set this value to true
for a web view, users (with devices that support 3D Touch)
can preview link destinations, and can preview detected data such as addresses, by pressing on links.
Such previews are known to users as peeks. If a user presses deeper, the preview navigates (or pops,
in user terminology) to the destination. Because pop navigation switches the user from your app to
Safari, it is opt-in, by way of this property, rather default behavior for this class.
Default: false
# anchorPoint
Coordinate of the view about which to pivot an animation.
Used on iOS only. For Android, use anchorPoint.
Anchor point is specified as a fraction of the view's size. For example, {0, 0}
is at
the view's top-left corner, {0.5, 0.5}
at its center and {1, 1}
at its bottom-right
corner.
See the "Using an anchorPoint" example in Titanium.UI.Animation for a demonstration. The default is center of this view.
# apiName READONLY
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button
returns Ti.UI.Button
.
# assetsDirectory
Path of file or directory to allow read access by the WebView.
Use this property to change the resources the web view has access to when loading the content of a local file. By default the web view only has access to files inside the same directory as the loaded file. To reference resources from other directories (e.g. a parent directory) change this property accordingly.
If assetsDirectory references a single file, only that file may be loaded. If assetsDirectory references a directory, files inside that directory may be loaded.
This property needs to be set before url is assigned to a local file.
# backgroundColor
Background color of the view, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI. Defaults to Transparent
.
# backgroundDisabledColor
Disabled background color of the view, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI. Defaults to the normal background color of this view.
# backgroundDisabledImage
Disabled background image for the view, specified as a local file path or URL.
If backgroundDisabledImage
is undefined, and the normal background imagebackgroundImage
is set, the normal image is used when this view is disabled.
# backgroundFocusedColor
Focused background color of the view, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI.
For normal views, the focused color is only used if focusable
is true
.
Defaults to the normal background color of this view.
# backgroundFocusedImage
Focused background image for the view, specified as a local file path or URL.
For normal views, the focused background is only used if focusable
is true
.
If backgroundFocusedImage
is undefined, and the normal background image backgroundImage
is set, the normal image is used when this view is focused.
# backgroundGradient
A background gradient for the view.
A gradient can be defined as either linear or radial. A linear gradient varies continuously
along a line between the startPoint
and endPoint
.
A radial gradient is interpolated between two circles, defined by startPoint
and
startRadius
and endPoint
and endRadius
respectively.
The start points, end points and radius values can be defined in device units, in the view's coordinates, or as percentages of the view's size. Thus, if a view is 60 x 60, the center point of the view can be specified as:
{ x: 30, y: 30 }
Or:
{ x: '50%', y: '50%' }
When specifying multiple colors, you can specify an offset value for each color, defining how far into the gradient it takes effect. For example, the following color array specifies a gradient that goes from red to blue back to red:
colors: [ { color: 'red', offset: 0.0}, { color: 'blue', offset: 0.25 }, { color: 'red', offset: 1.0 } ]
Android's linear gradients ignores backfillStart
and backfillEnd
, treating them as if
they are true. Android's radial gradients ignore the endPoint
property.
Defaults to no gradient.
# backgroundImage
Background image for the view, specified as a local file path or URL.
Default behavior when backgroundImage
is unspecified depends on the type of view and the platform.
For generic views, no image is used. For most controls (buttons, textfields, and so on), platform-specific default images are used.
# backgroundLeftCap
Size of the left end cap.
See the section on backgroundLeftCap and backgroundTopCap behavior on iOS in Titanium.UI.View.
Default: 0
# backgroundRepeat
Determines whether to tile a background across a view.
Setting this to true
makes the set backgroundImage
repeat across the view as a series
of tiles. The tiling begins in the upper-left corner, where the upper-left corner of the
background image is rendered. The image is then tiled to fill the available space of the
view.
Note that setting this to true
may incur performance penalties for large views or
background images, as the tiling must be redone whenever a view is resized.
On iOS, the following views do not currently support tiled backgrounds:
Default: false
# backgroundSelectedColor
Selected background color of the view, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI.
focusable
must be true for normal views.
Defaults to background color of this view.
# backgroundSelectedImage
Selected background image url for the view, specified as a local file path or URL.
For normal views, the selected background is only used if focusable
is true
.
If backgroundSelectedImage
is undefined, and the normal background image backgroundImage
is set
the normal image is used when this view is selected.
# backgroundTopCap
Size of the top end cap.
See the section on backgroundLeftCap and backgroundTopCap behavior on iOS in Titanium.UI.View.
Default: 0
# blacklistedURLs CREATION ONLYDEPRECATED
DEPRECATED SINCE 9.2.0
Use the blockedURLs property instead.
An array of url strings to blacklist.
An array of url strings to blacklist. This will stop the webview from going to urls listed in the blacklist. Note, this only applies in the links clicked inside the webview. The first website that is loaded will not be stopped even if it matches the blacklist.
# blockedURLs CREATION ONLY
An array of url strings to be blocked.
An array of url strings to be blocked from loading. This will stop the webview from going to urls listed in this array. Note that this only applies to the links tapped on by the end-user. The first website that is loaded will not be stopped, even if it is listed in the blocklist.
# borderColor
Border color of the view, as a color name or hex triplet.
For information about color values, see the "Colors" section of Titanium.UI.
Defaults to the normal background color of this view (Android), black (iOS).
# borderRadius
Radius for the rounded corners of the view's border.
Each corner is rounded using an arc of a circle.
Values for each corner can be specified. For example, '20px 20px' will set both left and right corners to 20px
.
Specifying '20px 20px 20px 20px' will set top-left, top-right, bottom-right and bottom-left corners in that order.
If you have issues with dark artifacts on Android you can try to disable Hardware acceleration by setting a
backgroundColor
with a small amount of transparency: backgroundColor:"rgba(255,255,255,254)"
.
Default: 0
# borderWidth
Border width of the view.
If borderColor is set without borderWidth, this value will be changed to 1 of the unit declared as 'ti.ui.defaultunit' in tiapp.xml descriptor.
Default: 0
# bottom
View's bottom position, in platform-specific units.
This position is relative to the view's parent. Exact interpretation depends on the parent view's layout property. Can be either a float value or a dimension string (for example, '50%' or '10px').
This is an input property for specifying where the view should be positioned, and does not represent the view's calculated position.
Defaults to undefined
.
# bubbleParent
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.
Default: true
# cacheMode
Determines how a cache is used in this web view.
Default: Titanium.UI.Android.WEBVIEW_LOAD_DEFAULT
# cachePolicy
The cache policy for the request.
# center
View's center position, in the parent view's coordinates.
This is an input property for specifying where the view should be positioned, and does not represent the view's calculated position.
Defaults to undefined
.
# clipMode
View's clipping behavior.
Setting this to CLIP_MODE_ENABLED enforces all child views to be clipped to this views bounds. Setting this to CLIP_MODE_DISABLED allows child views to be drawn outside the bounds of this view. When set to CLIP_MODE_DEFAULT or when this property is not set, clipping behavior is inferred. See section on iOS Clipping Behavior in Titanium.UI.View.
Defaults to undefined
. Behaves as if set to CLIP_MODE_DEFAULT.
# configuration
The configuration for the new web view.
This property can only be set when creating the webview and will be ignored when set afterwards.
# disableBounce
Determines whether the view will bounce when scrolling to the edge of the scrollable region.
Set to true
to disable the bounce effect.
Default: false
Determines whether or not the webview should not be able to display the context menu.
Set to true
to disable the context menu. Note that disabling the context menu will
also disable the text selection on iOS.
Default: false
# elevation
Base elevation of the view relative to its parent in pixels.
The elevation of a view determines the appearance of its shadow. Higher elevations produce larger and softer shadows.
Note: The elevation
property only works on Titanium.UI.View
objects.
Many Android components have a default elevation that cannot be modified.
For more information, see
Google design guidelines: Elevation and shadows.
# enableJavascriptInterface CREATION ONLY
Enable adding javascript interfaces internally to webview prior to JELLY_BEAN_MR1 (Android 4.2)
This property is introduced to prevent a security issue with older devices (< JELLY_BEAN_MR1)
Default: true
# filterTouchesWhenObscured
Discards touch related events if another app's system overlay covers the view.
This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.
Setting this property to true
causes touch related events (including "click") to not be fired
if a system overlay overlaps the view.
Default: false
# focusable
Whether view should be focusable while navigating with the trackball.
Default: false
# handlePlatformUrl DEPRECATED
DEPRECATED SINCE 8.0.0
This property in no more supported in Titanium SDK 8.0.0+. Use property allowedURLSchemes in conjuction with handleurl. See the example section "Usage of allowedURLSchemes and handleurl in iOS".
Lets the webview handle platform supported urls
By default any urls that are not handled by the Titanium platform but can be handled by the
shared application are automatically sent to the shared application and the webview does not
open these. When this property is set to true
the webview will attempt to handle these
urls and they will not be sent to the shared application. An example is links to telephone
numbers.
Default: undefined. Behaves as if false
# height
View height, in platform-specific units.
Defaults to: If undefined, defaults to either FILL or SIZE depending on the view. See "View Types and Default Layout Behavior" in Transitioning to the New UI Layout System.
Can be either a float value or a dimension string (for example, '50%' or '40dp'). Can also be one of the following special values:
- SIZE. The view should size itself to fit its contents.
- FILL. The view should size itself to fill its parent.
- 'auto'. Represents the default sizing behavior for a given type of
view. The use of 'auto' is deprecated, and should be replaced with the
SIZE
orFILL
constants if it is necessary to set the view's behavior explicitly.
This is an input property for specifying the view's height dimension. To determine the view's size once rendered, use the rect or size properties.
Sets the behavior when hiding an object to release or keep the free space
If setting hiddenBehavior
to HIDDEN_BEHAVIOR_GONE it will automatically release the space the view occupied.
For example: in a vertical layout the views below the object will move up when you hide
an object with hiddenBehavior:Titanium.UI.HIDDEN_BEHAVIOR_GONE
.
- HIDDEN_BEHAVIOR_INVISIBLE. Keeps the space and just hides the object (default).
- HIDDEN_BEHAVIOR_GONE. Releases the space and hides the object.
Defaults to Titanium.UI.HIDDEN_BEHAVIOR_INVISIBLE.
# hideLoadIndicator
Hides activity indicator when loading remote URL.
Default: false
# horizontalMotionEffect
Adds a horizontal parallax effect to the view
Note that the parallax effect only happens by tilting the device so results can not be seen on Simulator. To clear all motion effects, use the <Titanium.UI.clearMotionEffects> method.
# horizontalWrap
Determines whether the layout has wrapping behavior.
For more information, see the discussion of horizontal layout mode in the description of the layout property.
Default: true
# html
HTML content of this web view.
See setHtml for additional parameters that can be specified when setting HTML content.
The web view's content can also be set using the data or url properties.
If you want to get the HTML content of a remote URL you can grab it with this evalJS
call:
webview.addEventListener('load', function() {
webview.evalJS('document.documentElement.outerHTML.toString()', function(data) {
console.log(data);
});
});
# id
View's identifier.
The id
property of the Ti.UI.View represents the view's identifier. The identifier string does
not have to be unique. You can use this property with getViewById method.
# ignoreSslError
Controls whether to ignore invalid SSL certificates or not.
If set to true
, the web page loads despite having an invalid SSL certificate.
If set to false
, a web page with an invalid SSL certificate does not load.
iOS Note: As soon as you set this property to true
, iOS will cache the response
for the lifetime of the current web view.
Default: undefined but behaves as false
# keepScreenOn
Determines whether to keep the device screen on.
When true
the screen will not power down. Note: enabling this feature will use more
power, thereby adversely affecting run time when on battery.
For iOS look at idleTimerDisabled.
Default: false
# keyboardDisplayRequiresUserAction
A Boolean value indicating whether web content can programmatically display the keyboard.
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: undefined but behaves as true
# layout
Specifies how the view positions its children. One of: 'composite', 'vertical', or 'horizontal'.
There are three layout options:
-
composite
(orabsolute
). Default layout. A child view is positioned based on its positioning properties or "pins" (top
,bottom
,left
,right
andcenter
). If no positioning properties are specified, the child is centered.The child is always sized based on its
width
andheight
properties, if these are specified. If the child's height or width is not specified explicitly, it may be calculated implicitly from the positioning properties. For example, if bothleft
andcenter.x
are specified, they can be used to calculate the width of the child control.Because the size and position properties can conflict, there is a specific precedence order for the layout properties. For vertical positioning, the precedence order is:
height
,top
,center.y
,bottom
.The following table summarizes the various combinations of properties that can be used for vertical positioning, in order from highest precedence to lowest. (For example, if
height
,center.y
andbottom
are all specified, theheight
andcenter.y
values take precedence.)Scenario Behavior height
&top
specifiedChild positioned top
unit from parent's top, using specifiedheight
; anycenter.y
andbottom
values are ignored.height
¢er.y
specifiedChild positioned with center at center.y
, using specifiedheight
; anybottom
value is ignored.height
&bottom
specifiedChild positioned bottom
units from parent's bottom, using specifiedheight
.top
¢er.y
specifiedChild positioned with top edge top
units from parent's top and center atcenter.y
. Height is determined implicitly; anybottom
value is ignored.top
&bottom
specifiedChild positioned with top edge top
units from parent's top and bottom edgebottom
units from parent's bottom. Height is determined implicitly.Only top
specifiedChild positioned top
units from parent's top, and uses the default height calculation for the view type.center.y
andbottom
specifiedChild positioned with center at center.y
and bottom edgebottom
units from parent's bottom. Height is determined implicitly.Only center.y
specifiedChild positioned with center at center.y
, and uses the default height calculation for the view type.Only bottom
specifiedChild positioned with bottom edge bottom
units from parent's bottom, and uses the default height calculation for the view type.height
,top
,center.y
, andbottom
unspecifiedChild entered vertically in the parent and uses the default height calculation for the child view type. Horizontal positioning works like vertical positioning, except that the precedence is
width
,left
,center.x
,right
.For complete details on composite layout rules, see Transitioning to the New UI Layout System in the Titanium Mobile Guides.
-
vertical
. Children are laid out vertically from top to bottom. The first child is laid outtop
units from its parent's bounding box. Each subsequent child is laid out below the previous child. The space between children is equal to the upper child'sbottom
value plus the lower child'stop
value.Each child is positioned horizontally as in the composite layout mode.
-
horizontal
. Horizontal layouts have different behavior depending on whether wrapping is enabled. Wrapping is enabled by default (thehorizontalWrap
property istrue
).With wrapping behavior, the children are laid out horizontally from left to right, in rows. If a child requires more horizontal space than exists in the current row, it is wrapped to a new row. The height of each row is equal to the maximum height of the children in that row.
Wrapping behavior is available on iOS and Android. When the
horizontalWrap
property is set to true, the first row is placed at the top of the parent view, and successive rows are placed below the first row. Each child is positioned vertically within its row somewhat like composite layout mode. In particular:- If neither
top
orbottom
is specified, the child is centered in the row. - If either
top
orbottom
is specified, the child is aligned to either the top or bottom of the row, with the specified amount of padding. - If both
top
andbottom
is specified for a given child, the properties are both treated as padding.
If the
horizontalWrap
property is false, the behavior is more equivalent to a vertical layout. Children are laid or horizontally from left to right in a single row. Theleft
andright
properties are used as padding between the children, and thetop
andbottom
properties are used to position the children vertically.Defaults to Composite layout.
- If neither
# left
View's left position, in platform-specific units.
This position is relative to the view's parent. Exact interpretation depends on the parent view's layout property. Can be either a float value or a dimension string (for example, '50%' or '10px').
This is an input property for specifying where the view should be positioned, and does not represent the view's calculated position.
Defaults to undefined
.
# lifecycleContainer
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
# lightTouchEnabled
Enables using light touches to make a selection and activate mouseovers.
Setting this property solves the problem of web links with specific length not triggering a link click in Android.
This is only an Android specific property and has no effect starting from API level 18.
This flag is true
by default to retain backwards compatibility with previous
behavior.
Default: true
# mixedContentMode CREATION ONLY
If true
, allows the loading of insecure resources from a secure origin.
On iOS this functionality can be set in the <plist>
section of the tiapp.xml
using the NSAllowsArbitraryLoads
key as part of the App Transport Security.
The plist key is enabled by default, allowing arbitrary loads to be processed.
Default: false
# onCreateWindow
Callback function called when there is a request for the application to create a new window to host new content.
For example, the request is triggered if a web page wants to open a URL in a new window. By default, Titanium will open a new full-size window to host the new content. Use the callback to override the default behavior.
The callback needs to create a new WebView object to host the content in and add the WebView to the
application UI. The callback must return either a WebView object to host the content in or null
if
it does not wish to handle the request.
The callback is passed a dictionary with two boolean properties:
isDialog
: set to true if the content should be opened in a dialog window rather than a full-size window.isUserGesture
: set to true if the user initiated the request with a gesture, such as tapping a link.
The following example opens new web content in a new tab rather than a new window:
var tabGroup = Ti.UI.createTabGroup(),
win = Ti.UI.createWindow(),
tab = Ti.UI.createTab({window: win, title: 'Start Page'}),
webview = Ti.UI.createWebView({ url:'index.html'});
webview.onCreateWindow = function(e) {
var newWin = Ti.UI.createWindow(),
newWebView = Ti.UI.createWebView(),
newTab = Ti.UI.createTab({window: newWin, title: 'New Page'});
newWin.add(newWebView);
tabGroup.addTab(newTab);
return newWebView;
};
win.add(webview);
tabGroup.addTab(tab);
tabGroup.open();
# onlink
Fired before navigating to a link.
The callback will be called before navigating to the link. The Boolean return value of the callback will determine if the link will be navigated or discarded.
# opacity
Opacity of this view, from 0.0 (transparent) to 1.0 (opaque). Defaults to 1.0 (opaque).
# overrideCurrentAnimation CREATION ONLY
When on, animate call overrides current animation if applicable.
If this property is set to false, the animate call is ignored if the view is currently being animated.
Defaults to undefined
but behaves as false
# overScrollMode
Determines the behavior when the user overscrolls the view.
Default: Titanium.UI.Android.OVER_SCROLL_ALWAYS
# pluginState
Determines how to treat content that requires plugins in this web view.
This setting affects the loading of content that requires web plugins.
To enable hardware acceleration, add the tool-api-level
and
manifest
elements shown below inside the android
element in your tiapp.xml
file.
<android xmlns:android="http://schemas.android.com/apk/res/android">
<tool-api-level>11</tool-api-level>
<manifest>
<application android:hardwareAccelerated="true"/>
</manifest>
</android>
See Android documentation for WebSettings.PluginState.
This property only works on Android devices at API Level 8 or greater.
Default: Titanium.UI.Android.WEBVIEW_PLUGINS_OFF
# previewContext
The preview context used in the 3D-Touch feature "Peek and Pop".
Preview context to present the "Peek and Pop" of a view. Use an configured instance of Titanium.UI.iOS.PreviewContext here.
Note: This property can only be used on devices running iOS9 or later and supporting 3D-Touch. It is ignored on older devices and can manually be checked using forceTouchSupported.
# progress READONLY
An estimate of what fraction of the current navigation has been loaded.
This value ranges from 0.0 to 1.0 based on the total number of bytes expected to be received, including the main document and all of its potential subresources. After loading completes, the progress remains at 1.0 until a new download starts, at which point progress is reset to 0.0.
# pullBackgroundColor
Background color of the wrapper view when this view is used as either pullView or headerPullView.
Defaults to undefined
. Results in a light grey background color on the wrapper view.