Badboy Plugins

Badboy supports a simple plugin framework that allows you to make your own extensions to Badboy. Badboy Plugins are very simple and easy to write using only basic knowledge of Javascript and HTML. Plugins can do the following things:

• Create and display HTML based views that display in the main Badboy window
• Interact with the open browser windows including examining and modifying the DOM and HTML
• Control Badboy, the Script and Variables through Badboy's OLE Automation API
• Create and use any ActiveX controls on the local computer (without the normal security restrictions placed on browsers). This allows almost any interaction with the the desktop and native programs on the computer.
• Bind hotkeys to perform javascript actions that control Badboy or the browser windows that are open
• Add tools to the Toolbox that are implemented by Javascript with all the plugin capabilities listed above.
• Retrieve and Set Badboy Preferences

Installing a Plugin

Plugins are installed in Badboy's installation directory in the "plugins" folder. Each plugin is contained in a directory inside this folder. Installing a plugin is done simply by unzipping the plugin (if necessary) and placing it's folder in the Badboy Plugin directory.

Structure of Plugins

The only file that a plugin must have is a Javascript file called "init.js" which should be at the top level inside the plugin's folder. When Badboy starts it scans all the plugin folders found inside its plugins directory and executes init.js for each one. The init.js file is executed as regular javascript inside the main Badboy window. Plugins that wish to continue running after Badboy has started should add views and keyboard and menu commands inside their init.js script.

Plugins may also include other files in their folder which can be referenced by the plugin later on. A typical example would be to include HTML files to be displayed by the plugin when it opens a Plugin View.

Plugin Tools

As well as adding views and options to Badboy's toolbars and menus, Plugins can create tools in the Toolbox, to be used in scripts. This is done by calling the "addTool()" function on Badboy's plugin object (see below).

A Badboy tool is implemented as a single Javascript file. The file need only contain a single function called "execute()" which must return either 'true' or 'false'. The 'true' value indicates that the item is finished playing and the script should continue playing the next item. The 'false' value indicates that the item is not finished and is waiting for some activity to occur. Therefore the script will pause and wait for the item itself to resume play.

Other optional functions and attributes can be defined in the tool's Javascript file and are listed in the table below:

Operation	Description
tick()	If this function is defined then it will be called asynchronously by Badboy while the item is in scope
scriptTreeLabel	If defined this will be used as the label for the item in the script tree.

The Badboy Plugin Object

Badboy gives Plugins access to a special "plugin" object that can do more powerful things than the regular Javascript access to the "badboy" object can. The plugin object can be accessed in one of two ways:

• as a property of the "badboy" object itself. For example, Javascript could refer to it as "badboy.plugin"
• Only for the case of Javascript executing inside a plugin's window the plugin is available as a property of the window. Hence it can be accessed as "window.plugin" or even just "plugin"

The Plugin object exposes the following functions for plugin scripts to call:

Operation	Description
int addView ( String strTitle, String strPlugin, String strHTML )	Adds a view with the given name and loaded with html from the given plugin.
void bindKey ( int key, int dwModifiers, String strPlugin, String strCommand )	Binds the given key, specified as an ASCII character code, to the specified plugin and Javascript command. If the plugin has a window then the Javascript will be executed in the context of that window. The dwModifiers parameter must be one or more of the following values summed, indicating which additional keys apply to the binding: 4 - Shift key must be pressed 8 - Control key must be pressed 16 - Alt key must be pressed Example: to bind Ctrl-U to 'alert("hello world")': plugin.bindKey(85,8,"testplugin",'alert("hello world")');
BSTR BrowseFile ( String type, String filter, String initialLocation )	Shows an open/save file dialog to browse for the location of a file. type - "open" or "save" (affects title, prompting for overwriting) filter - filter string, leave empty for any file, otherwise supply standard format filter string (see MSDN documentation) initialLocation - initial directory, leave blank to use default.
Window browser ( String windowName )	Return dispatch pointer to requested window. Window may be specified by name or by index in form ":n" where n is index.
Object createObject ( String progId )	Creates an instance of the named ActiveX Control.
int addTool(String plugin, String name, String scriptSrc, String iconSrc )	Adds a tool to the toolbox that is executed using the script defined in the given source file. The source file is searched for within the plugin's directory and should define a function named 'execute()' that badboy will call run the action when it is played in the script. The execute() function must return true or false as follows: true - continue playing the script immediately false - continue playing after a page has loaded The script may also define a global variable called 'scriptTreeLabel'. If it does so, this variable will be displayed as the label of the item in the script tree.
Object addChild(LONG id, LPCTSTR strType, UINT nIndex)	Creates an instance of the requested item type as a child of the given item with given id in the script and returns it. If nIndex is greater than zero then the child is created at the specified index, otherwise it is created as the last child of the item. Example: to add a new Step to your script as a child of item 234: plugin.addChild(234,"Step",-1);
void addToolBarButton(String strPlugin, String strCommand, String strIconSrc, String strDescription, String strOptions)	Adds a button to the toolbar that executes the given javascript, using the given image for the button and the given description as a tooltip. The icon should be a 16x15 size non-indexed PNG file. Example: to add a toolbar button that shows an alert box using an icon called 'test.png': badboy.plugin.addToolBarButton("testplugin","alert(1);", "test.png","My Button", "");
String getPreference(String strName)	Attempts to retrieve and return named preference. Example: to find the number of undo levels - badboy.plugin.getPreference("Undo Levels");
Int setPreference(String strName, String strValue)	Attempts to set the named preference with the given value. Example: to set the number of undo levels to 25 - badboy.plugin.setPreference("Undo Levels",25);
String showPopup(String strPluginName, String fileName)	Displays a popup window loaded from the given filename in the given plugin's directory.
String execScript(Object window, String strScript, String strOptions)	Executes the given script in the context (domain, etc.) of the given window. It is also allowable to pass a Javascript function object to be executed. strOptions is reserved for future use.

Example 1: A simple Plugin

To make a simple example plugin, perform the following steps:

• Find your Badboy Installation directory and the "plugins" folder inside it. Inside the "plugins" folder, make a new directory called "testplugin".
• Inside the "testplugin" directory, make a new file called "init.js" with a text editor (such as Notepad).
• In the init.js file, place the following Javascript command:
  
  
  badboy.plugin.addView("testplugin","testplugin","test.html");
• In the same directory, add a file called "test.html", and place in it the follwoing HTML:
  
  

    <html>
      <head>
        <style type="text/css">
          * { font-family: arial; }
          body { overflow: auto; }
        </style>
        <script type="text/javascript">
          function init() {
            window.setInterval(update,2000);
          }
          function update() {
            var played = window.external.summary(1,"played");
            document.getElementById('played').innerHTML = "Played: " + played;
            document.getElementById('linkcount').innerHTML = "Links: " + window.plugin.browser("").document.links.length;
          }
        </script>
      </head>
      <body onload="init();">
        <h2>Example Plugin</h2>
        <p id="played">&nbsp;</p>
        <p id="linkcount">&nbsp;</p>
      </body>
    </html>

• Restart Badboy

When you restart Badboy you should find that the plugin adds a new view to your Badboy window which contains information that updates as you play your script and tells you how many items have played and also the number of links on the current page in the main browser window.

You will also see that a new entry has been added to the "View" menu to show the plugin in case the user closes the plugin's view.

Example 2: Adding a tool to the Toolbox

We can extend the previous example to add a tool to the toolbox. The tool will simply set a Badboy variable named "hello" with the value "world":

• Add a file called "mytool.js" to the testplugin directory created in the previous example with the following contents:
  function execute() { badboy.setVariable("hello","world"); return true; }
• Edit the init.js file created in the previous example and add a new line at the end as follows:
  badboy.plugin.addTool("testplugin","my tool", "mytool.js","test.png");
• Add an image file called 'test.png' to be the icon for the tool in the toolbox. You can copy an example image from the following location: http://www.badboy.com.au/Images/test.png. If you use another image then you should make sure that it is exactly the same size and type as this image. Place the image file along side the other files in your plugin folder. Note that the image file name is specified in the addTool() call in the previous step.
• Restart Badboy

After performing these steps you should have a new item in your toolbox called 'my tool'. By dragging it to your script you can make it play as part of your script.

Appendix: List of Badboy Preferences Accessible via setPreference and getPreference functions

Preference Name
Show Statistics In Tree
Suppress Bbrand
Play Delay
Suppress Popups
Suppress JScript Errors
Force Resynchronization
Register Popups
Disable Response Recording
Enable Direct Downloads
Results Listener Port
Enable Logging
Logfile Location
Log Threshold
Record JavaScript Requests
Record Passive Navigations
Record Passive Navigation Timeout
Document Root
Server Log File Location
Enable Server Log Capture
Label Manual Screen Shots
Legacy Report XML
Start Page
Load Previous
Summary Style Sheet
Show Summary Descriptions
Enable Custom User Agent
Custom User Agent
Undo Levels
XMLHttpRequest Interception
Root Item Type
Enable Recording on Startup
Editor Path
Diff Program
Diff Capture Output
SMTP Server
SMTP From Address
SMTP Display Name