# Objects

*BROWSER | Chromium Browser Object

## Format

Initializes Browser Object: | DEF OBJECT obj_id,@(col,ln,wth,ht ){, |=}"*BROWSER"

Where: |
*BROWSER | Keyword used in defining PxPlus Chromium Browser Object.
@(col,ln,wth,ht) | Numeric expressions. Column and line coordinates for top left corner, width in number of columns and height in number of lines.
obj_id | Numeric variable that will be used to save the object reference.

## Description

This object allows you to embed a Chromium Browser into PxPlus windows. Use this object to display a Web page, execute JavaScript, and subscribe to browser events. See Important Note below.

If loading a Web page that has a certificate error (i.e. self-signed, expired, etc.), a warning will display. It will describe the certificate error and give the option to either go back to safety or proceed to the URL that has the error. The warning may be avoided if the server is added to the exceptions list. See CertErrExceptions$ property.

(The Chromium Browser object was added in PxPlus 2017.)
(Support for ignoring certificate errors was added in PxPlus 2022.)

The 'BI' system parameter controls whether or not the embedded Chromium browser runs in incognito mode. If running in incognito mode, the browser does not store or cache anything. This system parameter defaults to On, indicating that all Chromium browsers created will be in incognito mode.

(The 'BI' parameter was added in PxPlus 2017 Update 0001.)

The language of the embedded browser will be based on the Windows user language. This can be overridden by specifying the language code of the desired language in the BrowserLang INI setting or 'OPTION' mnemonic. See the Language Codes table for a list of supported languages and codes.

(Embedded browser support of other languages was added in PxPlus 2019.)

If *BROWSER Debug mode is On, the browser developer console will display in a popup window for *BROWSER controls that are created. The browser developer console makes it possible to examine the code and properties of the Web page loaded by the *BROWSER control and debug any errors. Debug mode can be set in the BrowserDebug INI setting or 'OPTION' mnemonic.

(The *BROWSER Debug mode was added in PxPlus 2021.)

A Find( ) method is provided that opens a Find dialog for searching text in a *BROWSER displayed Web page. By default, no hot key is assigned to the Find dialog. A FindHotKey property gives you the option to enable the standard hot key Ctrl+F, define a custom hot key (e.g. Ctrl+S) or have no hot key. The Find( ) method makes it possible for developers to add their own menus and buttons for opening the Find dialog.

(The Find( ) method and FindHotKey property were added in PxPlus 2021 Update 2.)

The first *BROWSER created by a process will initialize the language and incognito settings for all embedded chromium browsers created by the process. These settings cannot be changed on the fly; i.e. changing the setting after the first *BROWSER has been created will have no effect.

For information on adding a Chromium Browser control to a NOMADS panel, see External Controls - *Browser, ActiveX (COM), PVX Plus, .NET.

#### Important Note:
As of April 2019, Google prevents embedded browsers from being able to sign into Google accounts for security purposes (Source: https://support.google.com/accounts/answer/7675428?co=GENIE.Platform%3DDesktop&hl=en). Google does this to combat a form of phishing known as "man in the middle" (MITM), which can be done through embedded browsers to steal users' information.
This Google decision affects both the PxPlus *BROWSER embedded Chromium Browser object/control and the Shell.Explorer embedded browser COM control (see External Controls - *Browser, ActiveX (COM), PVX Plus, .NET). If you use an embedded Browser control in your application, the embedded Browser will not be able to be used to sign in to any Google account. This affects all versions of PxPlus because the change is on the Google sign-in process side, not in the application or the embedded Browser control.
If you need your application to bring the user to a Google service, you can still have your PxPlus application launch the default system Web browser and direct it to the Google service.
SYSTEM_HELP url$
Google still allows standard system Web browsers, such as Chrome, Firefox, Safari and Edge, to log into Google accounts. It is only restricting embedded browsers from doing so.
Using the system Web browser means that the user will be taken away from your application. This is a less integrated solution, but it is more secure. If you need a more integrated solution that meets Google security standards, your application will need to transition to oAuth2 to login to Google accounts and the Google APIs to interact with the Google services. PxPlus provides an *obj/oauth2 object (see *OBJ/OAUTH2) that can be used to help with the oAuth2 login process.

## Properties, Methods and Events

#### Note:
Some *BROWSER properties and methods (see tables below) have an "alias" that has been provided to match the Shell.Explorer external object properties and methods. The purpose for this is to make it easier to use *BROWSER as a drop-in replacement for Shell.Explorer.

The interface supports the following properties:

Property | Description
CertErrExceptions$ | Gets/Sets a comma-separated list of servers where certificate errors are ignored. You must only specify the server portion of the URL. Example: For the URL https://home.pvxplus.com/pgsrvr.pvp?pg=products, the server portion is only home.pvxplus.com: "localhost,127.0.0.1,192.168.1.100,home.pvxplus.com" This property can also be set to "All" to ignore certificate errors on any server. For security reasons, this is not recommended unless the *BROWSER control is only loading pages locally and not from the Internet. (The CertErrExceptions$ property was added in PxPlus 2022.)
Col | Gets/Sets the position of the left side of the embedded browser (in columns) from the left side of the panel.
Cols | Gets/Sets the width of the embedded browser (in columns).
Document | Access the document object (HTML DOM) of the active URL. For details on the HTML DOM, visit http://www.w3schools.com/jsref/default.asp. #### Note: Not accessible when using iNomads due to browser security.
DragDrop | Gets/Sets whether the browser allows drag and drop into the browser control or popup windows. (Support to allow drag and drop was added in PxPlus 2021.)
FindHotKey | Used to set the hot key for opening the Find dialog (if applicable). See Find( ) method. Set this property to 1 to enable the standard Ctrl+F Find hot key or leave it set to 0 (default) if no hot key will be used. Alternatively, a custom Find hot key can be defined using this format: DEC("char") Where: char is a single alpha character ("A" to "Z"), enclosed in quotes. Example: To set Ctrl+S as the Find hot key: dec("S") (The FindHotKey property was added in PxPlus 2021 Update 2.)
Height PvxHeight | Gets/Sets the height of the embedded browser (in pixels).
History Location Navigator Screen Window | Access the various browser BOM objects. For details on the browser BOM objects, visit http://www.w3schools.com/jsref/default.asp. #### Note: Not accessible when using iNomads due to browser security.
Left PvxLeft | Gets/Sets the position of the left side of the embedded browser (in pixels) from the left side of the panel.
Line | Gets/Sets the position of the top of the embedded browser (in lines) from the top of the panel.
Lines | Gets/Sets the height of the embedded browser (in lines).
PvxEvents[$] | Returns the PxPlus class object that is handling events or returns a list of events names (depending on $ suffix) for the object. #### Note: Not accessible when using iNomads due to browser security.
PvxExtData[$] | Returns zero or an empty string. (Included for Shell.Explorer Compatibility) (Support for the numeric PvxExtData[$] property was added in PxPlus 2020 Update 1.)
Title$ LocationName$ | Gets the title of the resource that is currently loaded in the embedded browser. #### Note: Due to browser security when using iNomads, the title can only be accessed if the browser has loaded a resource from the same domain as the iNomads server. If the resource is from a different domain, the message "Cross domain cannot access title" is returned.
Top PvxTop | Gets/Sets the position of the top of the embedded browser (in pixels) from the top of the panel.
URL$ LocationURL$ | Gets/Sets the URL or path of the resource that is currently loaded in the embedded browser.
Width PvxWidth | Gets/Sets the width of the embedded browser (in pixels).

The interface supports the following methods:

Method | Description
ExecJS[$](JavaScript$) | Executes JavaScript$ in the currently loaded resource of the embedded browser and returns the result, if any. #### Note: Not accessible when using iNomads due to browser security.
Find( ) | Opens the Find dialog, which allows users to search for specified text within the contents of a *BROWSER displayed Web page. The FindHotKey property is used to set or not set a Find hot key for opening this dialog. This dialog consists of the following:
Find What | Enter the search text. If text is selected in the Web page when the Find dialog is invoked, the selected text will be used as the default search text.
Match case | Select this option if the search is to be case sensitive. By default, this option is unchecked.
Direction | Searches up or down within the displayed Web page. By default, Down is selected.
Find Next | Finds the next occurrence of the specified search text.
Cancel | Cancels the search and closes the Find dialog.
(The Find( ) method was added in PxPlus 2021 Update 2.)
GoBack( ) | Navigates the embedded browser backward to the previously loaded URL.
GoForward( ) | Navigates the embedded browser forward to the URL loaded before a GoBack( ).
Navigate(url$) Navigate2(url$) | Navigates the embedded browser to a resource identified by url$, which could be a URL or a full path.
PrintToPDF(PdfPath$) | Saves the current contents of the browser as a PDF file. Where: PdfPath$ is the path that the PDF will be saved as. (The PrintToPDF method was added in PxPlus 2023.)
Refresh( ) Refresh2( ) | Reloads the resource that is currently loaded in the embedded browser.
Stop( ) | Cancels a pending navigation or download and stops dynamic page elements such as background sounds and animations.

The interface supports the following events:

#### Note:
Not accessible when using iNomads due to browser security.

Event | Description
BeforeNavigate(pDisp, url, flags, targetFrameName, postData, headers, cancel) BeforeNavigate2(pDisp, url, flags, targetFrameName, postData, headers, cancel) | This event is fired just before the embedded browser navigates to a new resource URL.
pDisp | Always zero. (Included for Shell.Explorer Compatibility)
url | A reference to a variant object containing the URL to be navigated to as a string.
flags | A reference to a variant object containing the number zero. (Included for Shell.Explorer Compatibility)
targetFrameName | A reference to a variant object containing the name of the frame to be navigated as a string.
postData | A reference to a variant object containing the navigation request post data as a string.
headers | A reference to a variant object containing the navigation request headers as a string.
cancel | A number that can be set to non-zero in the event handler to cancel the navigation.
To use a reference to a variant object, you must first perform a DEF OBJECT on it to convert it to a PxPlus *VARIANT object. Once you have a *VARIANT object, you can use the VAL property to access what the variant stores. #### Warning! Any PxPlus event handler for this event must not use any of the following; otherwise, the system will hang if used: - ExecJS method - Document or Document-related properties - History or History-related properties - Location or Location-related properties - Navigator or Navigator-related properties - Screen or Screen-related properties - Window or Window-related properties
DownloadBegin( ) | This event is fired just before the embedded browser begins a download.
DownloadComplete( ) | This event is fired just after the embedded browser completes a download.
TitleChange(newTitle$) | This event is fired just after the embedded browser has its title changed to newTitle$.

## Example Code

The following code gives you an example of embedding a Chromium Browser in your panel and loading a Web page:

> def object mySite,@(20,5,40,20),"*BROWSER"
> mySite'Url$="www.mysite.com"

## Language Codes

This table lists supported languages and codes:

Language Name | Language Code
Amharic | am
Arabic | ar
Bengali | bn
Bulgarian | bg
Catalan | ca
Chinese (Mainland China) | zh-CN
Chinese (Taiwan) | zh-TW
Croatian | hr
Czech | cs
Danish | da
Dutch | nl
English (United Kingdom) | en-GB
English (United States) | en-US
Estonian | et
Filipino | fil
Finnish | fi
French | fr
German | de
Greek (Modern) | el
Gujarati | gu
Hebrew (Modern) | he
Hindi | hi
Hungarian | hu
Indonesian | id
Italian | it
Japanese | ja
Kannada | kn
Korean | ko
Latvian | lv
Lithuanian | lt
Malay | ms
Malayalam | ml
Marathi | mr
Norwegian (Bokmål) | nb
Persian | fa
Polish | pl
Portuguese (Brazil) | pt-BR
Portuguese (Portugal) | pt-PT
Romanian | ro
Russian | ru
Serbian | sr
Slovak | sk
Slovenian | sl
Spanish | es
Spanish (Central and South America) | es-419
Swahili | sw
Swedish | sv
Tamil | ta
Telugu | te
Thai | th
Turkish | tr
Ukrainian | uk
Vietnamese | vi

(Embedded browser support of other languages was added in PxPlus 2019.)

## See Also

DEF OBJECT Define Windows Object
DELETE OBJECT Remove Object
ON EVENT Event Processing
Apostrophe Operator
*VARIANT Extended Object
External Controls - *Browser, ActiveX (COM), PVX Plus, .NET
'BI' Browser Incognito Mode