Home > Element Reference : Browser

Contents

### Browser

A frame which is expected to contain a view of a Web document. It is similar to an iframe except that it holds a page history and contains additional methods to manipulate the currently displayed page.

Most of the properties and methods of the browser would rarely be used and can only be called from chrome URLs. Other URLs will need to use the document and history objects to change the displayed document.

The browser element implements the following interfaces:

nsIAccessibleProvider

Attributes:

autocompleteenabled | autocompletepopup | autoscroll | disablehistory | disablesecurity
homepage | src | type

Properties and Methods:

accessible | addProgressListener | canGoBack | canGoForward | contentDocument
contentTitle | contentViewerEdit | contentViewerFile | contentWindow | currentURI
docShell | documentCharsetInfo | goBack | goForward | goHome
gotoIndex | homePage | loadURI | loadURIWithFlags | markupDocumentViewer
preferences | reload | reloadWithFlags | removeProgressListener | securityUI
sessionHistory | stop | webBrowserFind | webNavigation | webProgress

#### Attributes:

Inherited from XUL Element:

align
allowevents
allownegativeassertions
class
coalesceduplicatearcs
collapsed
container
containment
context
contextmenu
datasources
dir
empty
equalsize
flags
flex
height
hidden
id
insertafter
insertbefore
left
maxheight
maxwidth
menu
minheight
minwidth
mousethrough
observes
ordinal
orient
pack
persist
popup
position
preference-editable
ref
removeelement
sortDirection
sortResource
sortResource2
statustext
style
template
tooltip
tooltiptext
top
uri
wait-cursor
width

##### autocompleteenabled Firefox only

Type: boolean

Set to true to enable autocomplete of fields.

##### autocompletepopup

Type: id of popup element

The id of a popup element used to hold autocomplete results for the browser.

##### autoscroll Firefox only

Type: boolean

Set to false to disable autoscroll for this browser. If this attribute is set to true or omitted, autoscroll will be enabled or depending on the user preference 'general.autoScroll'.

##### disablehistory

Type: boolean

If false, an arrow button will appear on the end of the textbox which, when pressed, will open a dropdown menu of all available results. The default value is true, which will hide the dropdown button.

##### disablesecurity

Type: boolean

Set this attribute to true to disable the security UI for this browser. Leave the attribute off to enable it.

##### homepage

Type: string home page URL

This attribute allows you to set a homepage for the browser element. It does not have any correlation with the user's browser homepage; instead it is a convenient property to hold a home page. You can switch to this home page using the goHome method.

##### src

Type: URL

The URL of the page to appear in the browser.

##### type

Type: string

The type of browser, which can be used to set the access of the document loaded inside the browser. If this is not set, the loaded document has the same access as the window containing the <browser>.

- content: A browser for content. The content that is loaded inside the browser is not allowed to access the chrome above it.
- content-primary: The primary browser for content. The content that is loaded inside the browser is not allowed to access the chrome above it. For instance, in a web browser, this would be the element that displays the web page. The window for the primary content can be retrieved more conveniently using 'window.content'.

#### Properties and Methods:

Inherited from XUL Element:

align
allowEvents
blur
boxObject
boxObject.element
boxObject.getLookAndFeelMetric
boxObject.height
boxObject.screenX
boxObject.screenY
boxObject.width
boxObject.x
boxObject.y
builder
className
click
collapsed
contextMenu
controllers
database
datasources
dir
doCommand
flex
focus
getElementsByAttribute
height
hidden
id
left
maxHeight
maxWidth
menu
minHeight
minWidth
observes
ordinal
orient
pack
persist
ref
resource
statusText
style
tooltip
tooltipText
top
width

Inherited from Element:

addEventListener
appendChild
attributes
childNodes
cloneNode
dispatchEvent
firstChild
getAttribute
getAttributeNS
getAttributeNode
getAttributeNodeNS
getElementsByTagName
getElementsByTagNameNS
hasAttribute
hasAttributeNS
hasAttributes
hasChildNodes
insertBefore
isSupported
lastChild
localName
namespaceURI
nextSibling
nodeName
nodeType
nodeValue
normalize
ownerDocument
parentNode
prefix
previousSibling
removeAttribute
removeAttributeNS
removeAttributeNode
removeChild
removeEventListener
replaceChild
setAttribute
setAttributeNS
setAttributeNode
setAttributeNodeNS
tagName

##### accessible

Type: nsIAccessible

Returns the accessibility object for the browser.

##### addProgressListener ( listener )

Return Type: no return value

Add a progress listener to the browser which will monitor loaded documents. The progress listener should implement the nsIWebProgressListener interface.

##### canGoBack

Type: boolean

This read-only property is true if there is a page to go back to in the session history and the Back button should be enabled.

##### canGoForward

Type: boolean

This read-only property is true if there is a page to go forward to in the session history and the Forward button should be enabled.

##### contentDocument

Type: document

This read-only property contains the document object in the browser.

##### contentTitle

Type: string

This read-only property contains the title of the document object in the browser.

##### contentViewerEdit

Type: nsIContentViewerEdit

This read-only property contains the nsIContentViewerEdit which handles clipboard operations on the document.

##### contentViewerFile

Type: nsIContentViewerFile

Reference to the nsIContentViewerFile interface for the document.

##### contentWindow

Type: window

This read-only property contains the window object in the browser.

##### currentURI

Type: string current URI

This read-only property contains the currently loaded URL. To change the URL, use the loadURI method.

##### docShell

Type: nsIDocShell

This read-only property contains the nsIDocShell object for the document.

##### documentCharsetInfo

Type: nsIDocumentCharsetInfo

This read-only property contains the nsIDocumentCharsetInfo object for the document which is used to handle which character set should be used to display the document.

##### goBack ( )

Return Type: no return value

Go back one page in the history.

##### goForward ( )

Return Type: no return value

Go forward one page in the history.

##### goHome ( )

Return Type: no return value

Load the user's home page into the browser.

##### gotoIndex ( index )

Return Type: no return value

Navigate to the page in the history with the given index. Use a positive number to go forward and a negative number to go back.

##### homePage

Type: string home page URL

This property holds the value of the user's home page setting.

##### loadURI ( uri , referrer , charset )

Return Type: no return value

Load a URL into the document, with the given referrer and character set.

##### loadURIWithFlags ( uri , flags , referrer , charset )

Return Type: no return value

Load a URL into the document, with the specified load flags and the given referrer and character set. In addition to the flags allowed for the reloadWithFlags methods, the following flags are also valid:

- LOAD_FLAGS_IS_REFRESH: This flag is used when the URL is loaded because of a meta tag refresh or redirect.
- LOAD_FLAGS_IS_LINK: This flag is used when the URL is loaded because a user clicked on a link. The HTTP Referer header is set accordingly.
- LOAD_FLAGS_BYPASS_HISTORY: Do not add the URL to the session history.
- LOAD_FLAGS_REPLACE_HISTORY: Replace the current URL in the session history with a new one. This flag might be used for a redirect.

##### markupDocumentViewer

Type: nsIMarkupDocumentViewer

This read-only property contains the nsIMarkupDocumentViewer which is responsible for drawing the document.

##### preferences

Type: nsIPrefService

This read-only property contains an nsIPref object for getting and setting user preferences.

##### reload ( )

Reloads the document in the browser.

##### reloadWithFlags ( flags )

Return Type: no return value

Reloads the document in the browser with the given load flags. The flags listed below may be used, which are all constants of the webNavigation property (or the nsIWebNavigation interface). You may combine flags using a or symbol ( | )

- LOAD_FLAGS_NONE: No special flags. The document is loaded normally.
- LOAD_FLAGS_BYPASS_CACHE: Reload the page, ignoring if it is already in the cache. This is the flag used when the reload button is pressed while the Shift key is held down.
- LOAD_FLAGS_BYPASS_PROXY: Reload the page, ignoring the proxy server.
- LOAD_FLAGS_CHARSET_CHANGE: This flag is used if the document needs to be reloaded because the character set changed.

##### removeProgressListener ( listener )

Return Type: no return value

Remove a progress listener from the browser.

##### securityUI

Type: nsISecureBrowserUI

The readonly property holds an object which may be used to determine the security level of the loaded document.

##### sessionHistory

Type: nsISHistory

This read-only property contains the nsISHistory object which holds the session history.

##### stop ( )

Return Type: no return value

Equivalent to pressing the Stop button, this method stops the currently loading document.

##### webBrowserFind

Type: nsIWebBrowserFind

This read-only property contains an nsIWebBrowserFind object which can be used to search for text in the document.

##### webNavigation

Type: nsIWebNavigation

This read-only property contains the nsIWebNavigation object for the document. Most of its methods are callable directly on the browser itself, such as goBack and goForward. It also contains the load constants used by reloadWithFlags and loadURIWithFlags.

##### webProgress

Type: nsIWebProgress

This read-only property contains an nsIWebProgress object which is used to monitor the progress of a document loading.

Copyright (C) 1999 - 2004 XulPlanet.com