Using the OpenInsight 10 Browser Control

The OpenInsight 10 Browser Control is based on the Chromium browser engine, used by most of the major desktop browsers.  The OI 10 version has been embedded in a COM object for easier control from inside the OpenInsight environment.

To use the Browser Control, you must add it to your form.  In the form designer, add an OLE control:



Set its class id (CLSID) to ChromeOI_10.CEFBrowser:

I

You may name the control anything you wish; for the purposes of this document, we will use the name OLE_WB for our examples. You may wish to set the AutosizeWidth and AutosizeHeight properties to true:


Be sure to also set the 'OLE' event in the Events tab - this should be set as a quick event to "Call Commuter Module (@Window)":





You’ll also (most likely) need to set the events for Create to call your commuter module in the same way.

In your commuter module, you must mark the events you wish to be notified about.  You may wish to catch all OLE events for the web control:

   call exec_Method( atWindow : ".OLE_WB",       |
                      "QUALIFY_EVENT",           |
                      "ALL_OLES",  |
                      TRUE$ )

In your handler for the OLE events, you can use the utility function RTI_CEF_OLE_EVENTS which can process many of the browser control's events for you (such as download requests, opening new tabs, etc.):

* param1, param2: passed from the OLE event
* atWindow: the window ID that contains the control
* statusLine : control ID of the status line, if any
* UNUSED: pass null
* titleLine: control ID of the title, if any
* ctlID: control ID of the browser control
StatusLine = atWindow:".STATUSTEXT"  ;* where to put the status messages
titleLine = atWindow
ctlID = atWindow:".OLE_WB"
RTI_CEF_OLE_EVENTS(param1, param2, atWindow, statusLine, unused, titleLine, ctlID)   
* update the toolbar buttons as appropriate
canGoBack = Get_Property(atWindow, "@GOBACK")
canGoFwd = Get_Property(atWindow, "@GOFWD")       
call Set_Property(atWindow:".BTN_BACK", "ENABLED", canGoBack+0)
call Set_Property(atWindow:".BTN_FWD", "ENABLED", canGoFwd+0)

Note that if a link inside the web page hosted by the browser control starts with "oi://" (instead of a normal http:// or https://), a special "browserOIEvent" event will be raised and passed back to OpenInsight.  Your code in the OLE handler can look for this and use the information passed back to perform any desired action.  For example:

   Case ( param1 _eqc "browserOIEvent" )
     realURL = param2[6, Len(param2)] ;* remove oi:// prefix
     oiEventID = oconv(realURL, "[URL_FORMAT,COMPONENT]")
     oiEventName   = trim(oiEventID[1,","])
     oiEventName[-1,1] = "" ;* remove trailing slash
     oiEventParam1 = oiEventID[col2()+1,","]

To initialize the control, you must first wait until it is ready and you can then send it HTML or a URL:

   Loop
     isReady = Get_Property(atWindow:".OLE_WB", "isReady")
   While isReady = "0"
     call yield()
   repeat
   call exec_Method( atWindow : ".OLE_WB", "Navigate2", url )

or

     Loop
          rs = Get_Property(atWindow: WEB_CONTROL$, "isReady")
     While rs = "0"
          call yield()
     repeat
     call exec_method( atWindow : WEB_CONTROL$, "setHTML", startHTML, "file://":drive():"/")


An example of a very simple commuter module would be:

Function BROWSER_TEST_FORM( CtrlEntId, Method, Param1, Param2, Param3, Param4, Param5, Param6, Param7)


Declare Function exec_method, Set_Property, Get_Property
Declare Subroutine rti_cef_ole_events, set_property

$Insert Logical

If Assigned( CtrlEntID ) Else CtrlEntID = Null$
If Assigned( Method    ) Else Method    = Null$
If Assigned( Param1    ) Else Param1    = Null$
If Assigned( Param2    ) Else Param2    = Null$
If Assigned( Param3    ) Else Param3    = Null$
If Assigned( Param4    ) Else Param4    = Null$
If Assigned( Param5    ) Else Param5    = Null$
If Assigned( Param6    ) Else Param6    = Null$
if assigned( Param7    ) else param7    = Null$

RetVal = False$

WinID      = CtrlEntID[1,'.']
BrowserCtl   = WinID:".OLE_WB"
statusLine  = WinID:".StatusLine"

Begin Case
Case method _eqc "CREATE"      ; Gosub WinCreate
Case method _eqc "OLE"         ; Gosub handleOLE
End Case

Return RetVal

// --------------------------------------------------------------------------------------------
WinCreate:
// This Sub Handles Window Creation.
title = "Browser Test Control"

// Qualify OLE Events
eventOp = ''
eventOp<1> = True$
eventOp<4> = False$  ; * synch
eventOp<7> = False$ ; * single param
OleEvent = 'ALL_OLES'
x = exec_method( BrowserCtl, 'QUALIFY_EVENT', OleEvent, eventOp )

Set_Property( BrowserCtl, "isSecure", "0")

If title <> "" then
    x = Set_Property( WinID, "TEXT", title)
End

Loop
     rs = Get_Property(BrowserCtl, "isReady")
While rs = "0"
     call yield()
Repeat

baseFileURL =   "file://":drive():"/"
html = "<html><head></head><body>Hello, world, I am the Chromium Browser Control!</body></html>"
call exec_method( BrowserCtl, "setHTML", html, baseFileURL)

Return

// --------------------------------------------------------------------------------------------
handleOLE:
* handle OLE events
RTI_CEF_OLE_EVENTS(param1, param2, winID, statusLine)

Return

For more information, see the descriptions for the properties and methods below.

Properties of the Web Control

isReady (read only)
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "isReady")
returns 0 if the browser control is not yet fully initialized, 1 otherwise

History (read only)
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "History")
returns @FM delimited list of pages visited by the control

DefaultURL
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "DefaultURL")
Example: rs = Set_Property(atWindow: WEB_CONTROL$, "DefaultURL", “https://www.revelation.com”)
gets or sets the default URL used by the browser control (default is about:blank)

HTML
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "HTML")
Example: rs = Set_Property(atWindow: WEB_CONTROL$, "HTML", “<html><head></head><body>Hello world</body></html>”)
gets or sets the HTML of the browser control

documentValue(whichElement)
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "documentValue", “overallResult”)
Example: rs = Set_Property(atWindow: WEB_CONTROL$, "documentValue", “overallResult”, “’quit’”)
retrieves or sets the value of the DOM element specified

ShowContextMenu
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "ShowContextMenu")
Example: rs = Set_Property(atWindow: WEB_CONTROL$, "ShowContextMenu", “0”)
enables (1) or disables (0) the built-in context menu

Debug
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "Debug")
Example: rs = Set_Property(atWindow: WEB_CONTROL$, "Debug", “c:\temp\wboutput.txt”)
gets or sets the status of debugging.  Call with the filename where you wish debugging output to be placed.

isSecure
Example: rs = Get_Property(atWindow: WEB_CONTROL$, "isSecure")
Example: rs = Set_Property(atWindow: WEB_CONTROL$, "isSecure”, “1”)
gets or sets a flag whether the contents of the page should be considered "secure".  When set to 1, the option to display the source of the page will be disabled, for example

Methods of the Web Control

Navigation methods:

Navigate2(URL)
Example:  call exec_Method( atWindow : ".OLE_WB", "Navigate2", “https://www.revelation.com” )
Sets the browser content to the specified URL

CanGoBack() as string
Example:  rs = exec_Method( atWindow : ".OLE_WB", "CanGoBack")
returns "1" if the browser control history is non-empty

Back()
Example:  call exec_Method( atWindow : ".OLE_WB", "Back")
Navigate backwards in the browser control history

CanGoForward() as string
Example:  rs = exec_Method( atWindow : ".OLE_WB", "CanGoForward")
returns "1" if the current page is not the final page in the browser control history

Forward()
Example:  call exec_Method( atWindow : ".OLE_WB", "Forward")
Navigate forwards in the browser control history

Reload()
Example:  call exec_Method( atWindow : ".OLE_WB", "Reload")
Reloads the current URL

Stopping/shutting down:

StopLoad()
Example:  call exec_Method( atWindow : ".OLE_WB", "StopLoad")
Tries to stop loading the current page

IsStopping() as boolean
Example:  rs = exec_Method( atWindow : ".OLE_WB", "IsStopping")
Returns boolean true if stopping has been set

SetStopping()
Example:  call exec_Method( atWindow : ".OLE_WB", "SetStopping")
Sets the stopping flag to true

ClearStopping()
Example:  call exec_Method( atWindow : ".OLE_WB", "ClearStopping")
Clears the stopping flag (sets it to false)

ResetStopping()
Example:  call exec_Method( atWindow : ".OLE_WB", "ResetStopping")
Clears the stopping flag (sets it to false) and resets downloading information

IsShutdown() as boolean
Example:  rs = exec_Method( atWindow : ".OLE_WB", "IsShutdown")
Returns boolean true if browser control has been shutdown

ShutdownOK() as string
Example:  rs = exec_Method( atWindow : ".OLE_WB", "ShutdownOK")
Tries to shut down the browser control, and returns "1" if OK to shutdown, or "0" if a download is in process (and sets the stopping flag)

Shutdown()
Example:  call exec_Method( atWindow : ".OLE_WB", "Shutdown")
Tries to shut down the browser control

Editing:

Copy()
Example:  call exec_Method( atWindow : ".OLE_WB", "Copy")
Copies the selected contents of the browser control to the clipboard

Cut()
Example:  call exec_Method( atWindow : ".OLE_WB", "Cut")
Cuts the selected contents of the browser control to the clipboard

Paste()
Example:  call exec_Method( atWindow : ".OLE_WB", "Paste")
Pastes the contents of the clipboard into the browser control

Interacting with the DOM:

setHTML(html, baseURL)
Example:  call exec_Method( atWindow : ".OLE_WB", "setHTML", ourHTML, “file://c:/revsoft/”)
Sets the contents of the browser control to the specified html, using the base url as the "base" for loading other required resources.  For example, if using html that references local resources, the base URL should be the directory where the resources may exist; if using html that references a different web server, the base URL should be the root of the desired internet url

callJSFunction(fnName, param1, param2)
Example:  call exec_Method( atWindow : ".OLE_WB", "call JSFunction", “exampleFunction”, “some value here”,”another value”)
Calls the javascript function specified by fnName, passing in 2 parameters (param1 and param2), in the context of the current page in the browser control

getJSMessage()
Example:  rs = exec_Method( atWindow : ".OLE_WB", "getJSMessage")
Retrieves the result of a javascript function call to "messageReceiver.setMsg". For example:
$(document).on("click","#test-element",function() {messageReceiver.setMsg("clicked on element");});

callJSFunctionWithResult(script)
Adds the specified script to the context of the current page in the browser control and executes it, returning the result of the function call.  For example:
        script = "(function () {var x=document.overallResult; document.overallResult=''; return x;})();"
        rs = exec_method(atWindow:”.OLE_WB”, "callJSFunctionWithResult", script)

Miscellaneous:

Save(filename)
Example:  call exec_Method( atWindow : ".OLE_WB", "Save", “c:\temp\wbcontent.txt”)
Save the contents of the current browser control page into the specified filename

Zoom(amount)
Example:  call exec_Method( atWindow : ".OLE_WB", "Zoom", “+.1”)
Zoom in (positive numbers) or out (negative numbers)

setSpecialHeaders(headerName, headerValue)
Example:  call exec_Method( atWindow : ".OLE_WB", "setSpecialHeaders", “my_special_header”, “1”)
Add the specified header names and values (associated, @VM delimited) to the page as it is being generated

Debugging the Web Control

Debugging is enabled through a text file named CefDebuggerPort.txt.  Create, or edit, this file in the folder where the Browser Control's assembly resides (normally c:\program files\revelation software\Revelation Software .NET 4.0 Components v10.0 (64bit)):


Place a port number that's not currently used - for example, 9999 - in the text file:


Restart your OI and launch your form – you should see a message indicating that browser debugging is enabled:


You can then open a desktop Chrome browser and connect to localhost:<port number> - for example, localhost:9999 - and you can use the debugging tools built into the Chrome browser on your OI 10 Browser Control instance.



Select the proper browser control to debug:



Be sure to either delete the CefDebuggerPort.txt file, or set the port number to 0, when you are finished debugging.