Script extension - control your app' out of webpages - trigger behaviour out of html

Applies to:
Working with BrowserBob

Trigger application behaviour out of your html-pages - send commands to the BrowserBob application, change interfaces, read info from the application in order to process it further via a script, use all BrowserBob functionality triggered from the code of your webpage with BrowserBob's HTML - Script extension.
 

Introduction to the BrowserBob Script extension:

BrowserBob's Script Extension allows you to send commands to your web application, trigger standard browser behaviour (like "Back/Forward") and control the interface using a Script language which is able to communicate with the DOM (Document Object Model) like JavaScript, VisualBasic Script and others.

Most of BrowserBob's functionalities are available through this DOM-interface, exceptions are the ones which are in need of direct user input with the mouse, like resizing the interface by dragging a button or moving the interface by grabbing it (left click) and dragging it over your screen). However, such functionality can be accessed using the standard JS or VBS controls, repositioning the interface on the screen.

Syntax:

All commands to the weblication or information to be retrieved from the weblication are to be communicated via the following simple syntax, following the DOM. The object in question, which is hosted by each html document, is called "window.external" (in JavaScript syntax) or "Window.External"(in VBScript syntax).

This object has been extended with 2 commands for the communication with BrowserBob weblications:
 

  • A procedure BB2Command to invoke the weblication to process a BrowserBob action, with parameters.
  • A function BB2GetValue which returns specified values of weblication variables for further processing in the script.

Usage of these procedures follows the following syntax:

  • BB2Command(Commandstring)

    Commandstring
    is a string of type: "Target,Action,Param0,Param1,..."


    Target:
    represents the target object name in BrowserBob, examples are: Main Web, Web1, Main Dialog, Panel1, Edit1, Label1, or whatever name the addressed target object has been assigned in BrowserBob.

    TIP:
    Please double-check your spelling, each target needs to be spelled exactly like in BrowserBob - "Main Web" including the space in the middle for example.

    Action:
    represents the action name in BrowserBob, examples are: Back, Forward, Navigate to Target, Add to Favorites, and so on. Again, please double-check your spelling!

    Param0,Param1,...:
    represents any parameters necessary for the action or optionally available separated by commas. Examples are: a URL, a local path, a state identifier (name), a variable.
  • Examples:
    BB2Command("Panel1,Show") - which makes a panel, named Panel1 appear.

    BB2Command("Main Web,Navigate to Target,www.browserbob.com") - which opens the URL www.browserbob.com in Main Web.

    BB2Command("Change State,State1,800,600") - which changes the state to State1 and resizes the interface to 800x600 pixels.

    TIP:
    please don't forget the " " signs around the full Commandstring.

    Note:
    for reference about which commands are available for use with the BrowserBob script extension as explained above, please refer to Chapter B - Button Object properties and available actions, where the exact use as well as availability of each action via the Script Extension, ActionLists and Scanning is stated (to the left in the table).
  • BB2GetValue(VarName)

    VarName
    is a string of type:


    <_currentdir_>
    - which returns the working directory of the browser/weblication, usually the installation directory of the browser.

    <_state_>
    - returns a string with the current state of the browser.

    <_NameOfEditObject.Text_>
    - returns a string with the text content of the specified edit object e.g.: <_Edit1.Text_>.

    <_NameOfLabelObject.Text_>
    - returns a string with the text content of the specified label object e.g.: <_Label1.Text_>.

    <_Main Web.URL_>
    - returns a string with the current URL displayed in Main Web.


    <_NameOfWebObject.URL_>
    returns a string with the current URL of the specified web object e.g.: <_Web1.URL_>.
  • Example usage: BB2GetValue("<_currentdir_>")
    TIP:
    please don't forget the " " signs around the full VarName.

Embedding the usage of the commands into different Script languages:
Depending on the used Script language, these commands BB2Command(Commandstring) and BB2GetValue(VarName) need to address the window.external object of the DOM in the following way:

JavaScript:
window.external.BB2Command(Commandstring)
window.external.BB2GetValue(VarName)


Visual Basic Script:
Window.External.BB2Command(Commandstring)
Window.External.BB2GetValue(VarName)

Usage Examples within the Script environment:
JavaScript:

Popping up a message dialog showing the current state of the browser:

<script type="text/javascript">
alert('the current state is '+window.external.BB2GetValue("<_state_>"));
</script>

Changing the browsers state to State1:
<script type="text/javascript">
window.external.BB2Command("Main Dialog,Change State,State1");
</script>

Changing the browsers state to State1, interface resize to 600x400:

<script type="text/javascript">
window.external.BB2Command("Main Dialog,Change State,State1,600,400");
</script>

Triggering ActionList1, which has been added to Main Dialog:
<script type="text/javascript">
window.external.BB2Command("Main Dialog ,ActionList1");
</script>

Popping up a message dialog showing the content of edit object "UserName" (an object of type Edit, with name UserName):

<script type="text/javascript">
alert('Welcome '+window.external.BB2GetValue("<_UserName.Text_>"));
</script>

Reading out the URL of Main Web and assigning it to a variable (Var1):

<script type="text/javascript">
VAR Var1=window.external.BB2GetValue("<_Main Web.URL_>"));
</script>

Opening a link in a webobject (Web1):

<script type="text/javascript">
window.external.BB2Command("Web1,Navigate to Target,www.browserbob.com");
</script>

Complete example (simplistic) demonstrating the functionatity:

The following small demonstration shows how these new methods work. Download Demobrowser

Clicking the left button on the html page will maximize and restore the browser, a click on the second button will display a text on the html-page, which has been entered into the edit field called "myedit" on the browser interface.

The BrowserBob export file (.BEX) of this demo can be downloaded here: Download DemoBEXfile

The source html-code of the html page included in this demo is the following (using VBScript):

<HTML>
<HEAD>
<TITLE>Script Extensions Demo VBScript</TITLE>

<SCRIPT language=vbscript>
sub BBMax()
Window.External.BB2Command("Main Dialog,Maximize")
end sub
sub BBGetEdit()
AppString.InnerText = Window.External.BB2GetValue("<_MyEdit.Text_>")
end sub
</SCRIPT>
</HEAD>
<BODY>
<SPAN ID="AppString"></SPAN><BUTTON onclick="BBMax()">Maximize/Restore</BUTTON><BUTTON onclick="BBGetEdit()">Display Edit Text</BUTTON><BR>
</BODY>
</HTML>

The same in JavaScript:


<HTML>
<HEAD>
<TITLE>Script Extensions Demo JavaScript</TITLE>
<script type="text/javascript">
function BBMax() {
window.external.BB2Command("Main Dialog,Maximize");
}
function BBGetEdit() {
AppString.innerText = window.external.BB2GetValue("<_MyEdit.Text_>");
}
</script>
</HEAD>
<BODY>
<SPAN ID="AppString"></SPAN><BUTTON onclick="BBMax()">Maximize/Restore</BUTTON><BUTTON onclick="BBGetEdit()">Display Edit Text</BUTTON><BR>
</BODY>
</HTML>

Explanation of the above script example:
Two subroutines have been defined in the SCRIPT-section of the code:
BBMax
and BBGetEdit (you would give them your own speaking names for clarity of your code):

BBMax uses BB2Command to call the browsers maximize action ("Main Dialog,Maximize").

BBGetEdit calls BB2GetValue to retrieve the text from the edit-object named MyEdit located on the interface of the demo-browser. This text string, the return value of the function, is assigned to AppString, which is defined in the SPAN-section. Every information you specify in parameters of a BrowserBob action can be drawn by the web-page in the same way.

Further examples will follow: the intention of this tutorial can't be to teach usage of JavaScript - the only intention of this reference is to explain the links between the BrowserBob Script Extension and Script languages. Any further reference should be retrieved from the respective original Script resources.

Tip:
do also visit The ScriptExtension page on browserbob.com , which contains the same information in principle, but might have been updated with more examples and further reference!