====== Using the OpenInsight 10 Browser Control (Web) ======

======   ======

==== Created at 28 MAY 2019 01:28PM ====




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:




{{kb1084_1.png}}




{{kb1084_2.png}}




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




I{{kb1084_3.png}}




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:




{{kb1084_4.png}}




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)":




{{kb1084_5.png}}




{{kb1084_6.png}}




{{kb1084_7.png}}




{{kb1084_8.png}}




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.):



<code>
* 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)
</code>



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:



<code>
   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,","]
</code>



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



<code>
   Loop

     isReady = Get_Property(atWindow:".OLE_WB", "isReady")

   While isReady = "0"

     call yield()

   repeat

   call exec_Method( atWindow : ".OLE_WB", "Navigate2", url )
</code>



or



<code>
     Loop

          rs = Get_Property(atWindow: WEB_CONTROL$, "isReady")

     While rs = "0"

          call yield()

     repeat

     call exec_method( atWindow : WEB_CONTROL$, "setHTML", startHTML, "file:%%//%%":drive():"/")
</code>






An example of a very simple commuter module would be:



<code>
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
</code>



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)):




{{kb1084_9.png}}




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




{{kb1084_10.png}}




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




{{kb1084_11.png}}




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.




{{kb1084_12.png}}




{{kb1084_13.png}}




Select the proper browser control to debug:




{{kb1084_14.png}}




{{kb1084_15.png}}




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




{{kb1084_16.png}}