REBOL/Plugin Developer Guide

Version: Beta-6 1.3.2
Author: Josh Mitts
Date: 10-May-2006

Contents:

1. Overview

This document describes how to implement the REBOL/Plugin control in an HTML page to host REBOL/View within the web browser.

REBOL/Plugin is a plugin that allows you to host REBOL/View scripts within the web browser. Using REBOL/Plugin, you can create REBOL scripts that display View windows within the browser. With the Visual Interface Dialect (VID), you can create high-quality user interfaces that utilize the full power of REBOL.

This document describes how to implement the REBOL/Plugin control in an HTML page. If you have any questions, please contact JoshM on the rebol3 safeworld.

Note: REBOL/Plugin is a non-enhanced version (no-Pro features) of the latest REBOL/View 1.3 release.

Note: We have recently released an alpha-1 version of REBOL/Plugin for Mozilla-based browsers. This document does not contain instructions for the Mozilla release. We will be releasing a users guide at a later date for Mozilla-based browsers. For installation instructions for both Internet Explorer and Mozilla, see the following URL: http://www.rebol.com/web-plugin-install.html

Security Warning

The purpose of this release is to provide a prototype for testing and user comments. This is not a secure prototype. Please do not make assumptions regarding security when executing unknown REBOL scripts over the Internet.

Use this prototype at your own risk.

2. System requirements

In order to use REBOL/Plugin, end-users viewing your web site must have:

• Windows 95 or higher. Linux, and Macintosh are currently not supported.
• Internet Explorer 4.0 or higher. Netscape and other browsers are currently not supported.

3. Installation

No installation is required for your web server or development machine. Simply add the <object> tag to your HTML, ASP, ASPX, JSP, etc. page, and REBOL/Plugin and REBOL/View automatically downloads and installs on the end-user’s machine with one click ("Yes" in the security prompt window).

Remove Previous Versions

If you have installed previous versions of REBOL/Plugin, including the beta-5 release, you MUST uninstall those previous versions before installing the beta-6 release. Released versions will run side-by-side, however during the development process, you must be sure to uninstall all previous versions.

To uninstall an earlier release, go to the "Downloaded Program Files" directory in Windows. Right-click on "REBOL/Plugin Object" and click "Remove".

4. How to use REBOL/Plugin

Below is an example of REBOL/Plugin in an HTML page. To try it yourself, click here: http://www.rebol.net/plugin/tests/test.html

<OBJECT ID="REBOL" CLASSID="CLSID:9DDFB297-9ED8-421d-B2AC-372A0F36E6C5" 
    CODEBASE="http://www.rebol.com/plugin/rebolb6.cab#Version=0,6,0,0"
    WIDTH="640" HEIGHT="480">
    <PARAM NAME="LaunchURL" VALUE="http://myserver.com/rebol-script.r">
    <PARAM NAME="BgColor" VALUE="#FFFFFF">
    <PARAM NAME="Version" VALUE="#FFFFFF">
    <PARAM NAME="BgColor" VALUE="#FFFFFF">
</OBJECT>

These components are described below.

• <OBJECT> – Indicates to the browser that this is an embedded object within the page.
• ID="REBOL" – Sets the script identifier of the REBOL object.
• CLASSID="…" – The class ID of the REBOL browser control. Cannot be changed.
• CODEBASE="…#Version=…" – The location of the .cab file containing the REBOL/Plugin and REBOL/View components. The version attribute indicates the version of the components you are requesting.

Version Updating

New versions of REBOL/Plugin will require a new CODEBASE URL as well as a new #Version number. Internet Explorer will only update the plugin on end-users computers if the version number increases. To ensure small .cab files and simplicity in REBOL/Plugin updates, each version of REBOL/Plugin will have its own .cab file.

• WIDTH="..." – The width of the plugin.
• HEIGHT="..." – The height of the plugin.
• <PARAM NAME="LaunchURL" VALUE="…"> – URL of the REBOL script file you want to load.
• <PARAM NAME="BgColor" VALUE="…"> – Background color of the plugin.
• <PARAM NAME="Version" VALUE="…"> – Minimum required script version.
• <PARAM NAME="Args" VALUE="…"> – Command-line arguments passed to the script (available in system/options/args).

4.1 Object Tag

Note: No parameters or tag names are case-sensitive.

4.1.1 Class ID

The class ID of REBOL/Plugin is 9DDFB297-9ED8-421d-B2AC-372A0F36E6C5. This cannot be changed.

4.1.2 Codebase URL

The URL where REBOL/Plugin can be downloaded. Currently, this is "http://www.rebol.com/plugin/rebolb6.cab#Version=0,6,0,0".

4.1.3 Width & Height

The width and height of REBOL/Plugin must be specified in the <OBJECT> tag. This width and height is available to your scripts via the browser document object model (DOM), in the offsetWidth and offsetHeight properties of the plugin HTML element.

4.1.4 Parameter: LaunchURL

This parameter contains the URL of the REBOL script file you want to load. The path may be absolute (http://www.myserver.com/file.r), root relative (/myfile.r), or document relative (myfile.r). If a root relative or document relative path is supplied, REBOL/Plugin will generate the full URL based on the location of the hosting HTML page. This .r file must contain a proper REBOL script header.

4.1.5 Parameter: BgColor

This parameter contains the background color of the plugin. The plugin fills itself with this color upon initialization (before the script is loaded), during its first painting (before the window is redrawn), and upon termination of the script. This value should be a hex string, for example "#000000" specifies the color black.

4.1.6 Parameter: Version

Specifies the version of the script (set in the REBOL header of the script). If the version specified is greater than that of the locally cached script file, a new script will be downloaded. If it is less or equal the script will be evalutated from the local cache, and no URL download will be done.

4.1.7 Parameter: Args

Text string available in system/options/args.

5. Browser DOM & Script Interaction

REBOL/Plugin includes a function callable from REBOL scripts, do-browser, that allows you to execute and retrieve the result of browser script code. This script code may manipulate the browser's document object model (DOM), giving you the ability to interact with other elements in the HTML page.

5.1 Usage:

do-browser code

5.2 Arguments:

code - Script code to be executed.

The return value of the do-browser function is the result of the script code. To retrieve a value, declare it in script syntax (see below for example).

Important: In order to interact with the browser, you must add the following Javascript code to your HTML document (preferably in the HEAD section):

function evaluate(code) { return eval(code); }

This function exposes script evaluation to the plugin; without it, do-browser will not function. Note: this function must be named "evaluate". A full example of interacting with the browser script & DOM follows.

5.3 Example

5.3.1 HTML Page

...
<HEAD>
<SCRIPT LANGUAGE="Javascript">
    function evaluate(code) { return eval(code); }
</SCRIPT>
</HEAD>

5.3.2 REBOL Script

; Retrieve the # of HTML elements and size of plugin object.
; 'REBOL' is the ID of the <OBJECT> tag of the plugin object.
all-length: do-browser "document.getElementById.length"
plugin-width: do-browser "document.getElementById('REBOL').offsetWidth"
plugin-height: do-browser "document.getElementById('REBOL').offsetHeight"
; Set the document's title
do-browser reform 
    ["document.title = 'REBOL Page Title! # of elements:" 
    all-length ", Plugin-Width:" plugin-width 
    "Plugin-Height:" plugin-height "'"]

6. Questions & Answers

Nothing shows up except a small white box with an "X" in it. What do I do?

A small white box with an "X" in it indicates that the ActiveX control was not properly loaded. There are several possible causes for this:

• Internet Explorer security settings are set to "High". The user may also receive a message "Your current security settings prohibit running ActiveX controls on this page. As a result, the page may not display correctly." The solution is to go to Internet Options and change the default (Internet) security settings to "Medium" or lower.
• "No" was clicked in the security confirmation dialog. You must click "Yes" to accept the download and installation of the REBOL/Plugin control.
• An operating system and/or browser other than Windows 95+ and Internet Explorer 4.0+.

Can I place more than one plugin on the same page?

Only one instance of REBOL/Plugin is allowed per page and browser instance. Attempts to use a second plugin on the page, or view a second page with the plugin in the same browser instance (for example, by opening a new window), will result in the 2nd+ instances not functioning.

In order to use two instances of the plugin simultaneously, launch a separate instance of the browser (via Start->Run or clicking on the "Internet Explorer" icon).

What happens when the user refreshes or navigates to a different page, and returns to my page hosting the plugin?

Upon refresh or navigation to another page, the script running in the plugin is exited. When returning to the page hosting the plugin, the plugin and its script are restarted. Data and code is not persisted across the page views.

Will REBOL/Plugin work properly behind a proxy/firewall?

Absolutely! REBOL/Plugin detects and imports your Windows & Internet Explorer proxy settings automatically.

How do I obtain the width and height of the plugin in my script?

The width and height of the plugin is available programmatically via the browser document object model (DOM). You can obtain the width and height of the plugin through the offsetWidth and offsetHeight properties of the plugin's HTML element. An easy way to obtain the plugin's HTML element is to give the plugin a unique ID in its <OBJECT> tag, and use the getElementById method of the document object to retrieve the plugin's HTML element by its ID via the do-browser function. Example:

// The ID of the plugin <OBJECT> tag is "REBOL".
plugin-width: do-browser "document.getElementById('REBOL').offsetWidth"
plugin-height: do-browser "document.getElementById('REBOL').offsetHeight"

Where are created and downloaded files stored?

Scripts running within the plugin have full read/write access to the secure sandbox. The location of the secure sandbox is %TEMP%\REBOL\Plugin\IE\0. On Windows XP, %TEMP% is typically C:\Documents and Settings\\Local Settings\Temp. The current directory for the startup script (the one used in the LaunchURL) is the script's sub-directory within the secure sandbox.

How are users protected from malicious scripts "spoofing" password and authentication requests?

Popup windows created by scripts using view/new within the plugin have a special prefix on their window title, "REBOL/Plugin". This communicates to the user that the window is not a trusted operating system window, but rather running from within REBOL/Plugin.

How are users protected from malicious scripts opening hunderds of popup windows?

The free version of REBOL/Plugin limits the total number of windows to five (5), including the main and popup windows.

Why can't I open two HTML files from Windows Explorer containing the plugin simultaneously?

Opening files from the Desktop, Windows Explorer, or My Computer all utilize the same instance of Internet Explorer (REBOL/Plugin can only run once per instance of the browser). To launch two simultaneous instances of the plugin from Windows Explorer, create individual shortcuts to the Internet Explorer program file (iexplore.exe), adding the HTML file path as an argument. This will launch seperate instances of IE when the shortcut is opened.

7. Uninstall

The plug-in extracts to the "Downloaded Program Files" directory in Windows. This is usually at C:\WINDOWS\Downloaded Program Files. To uninstall the plug-in, go to that directory, right-click on "REBOL/Plugin Object" and click "Remove".