BEE Script:   connector name [mode=string] [style=string] [domain=string]
[auth=string];

BEE Tag:     <beeconnector name [mode=string] [style=string] [domain=string]
[auth=string]>

The "connector" command encapsulates the remote function call mechanism.  Remote function call enables a client web page to call a function on the server without refreshing the page.

Two processes are involved: the client calls the server, and the server "calls back" the client.  On the client side, the calling process is indicated below:

The "call" command -> Client Connector -> Server Connector -> Remote function

On the server side, the callback process is indicated below:

Remote function "returns" -> Server Connector -> Client Connector -> Callback function

The "call" command and is invoked in a client script, e.g. JavaScript (and should be in the BEE Tag syntax because nested <script> tag is not a good idea.)  The tag specifies the URL to the Server Connector page, and the Client Connector used to deliver the call.

The Client Connector then packs the call parameters and sends them to the Server Connector (specified by the URL).  The Server Connector will unpack the parameters and call the Remote function (specified in the Server Connector itself.)

When the function returns the result, status and message, the Server Connector will pack them and call the Callback function on the client page via the Client Connector.

The Callback function is in a client script (e.g. JavaScript) which will use the results for its operation (e.g. display in the proper field or pop up a message box etc.)  The Callback function accepts three parameters: "result" (which is an array that the server function set up in rsult%function), status and message.  They're also available globally via JavaScript variable connector_name.result, connector_name.status and connector_name.message.

For example:

Client-side

<script language="JavaScript">

function searchOnClick(fld)

{

      // In JavaScript, we need to use BEE Tag instead of BEE Statement.

      <beecall "http://myserver.com/ws/search.htm" connector="srch"

            key="@fld.value">

      // Arbitrary parameters (like "key") for the remote function allowed

      // "@" indicates that "fld.value" is a JavaScript expression.

}

// The callback function (named after the connector)

function srch(result, status, message)

{

      // The arguments (result, status and message) are returned

      // from the server function.

      // They are also available globally via connector_srch.result,

      // connector_srch.status and connector_srch.message.

      if (status > 0) alert(message);

      else myForm.myField.value = result['Name'];

}

...

</script>

...

<beeconnector "srch">

Server-side

<script langauge="bee">

connector "findname" mode="server";

function findname

{

      ...

      var result%function = ...;

      return status=... message=...;

}

</script>

Parameters

connector specifies the name of the connector.  The connector's name is not only a handle to the connector but also the default name of the remote function (mode="server") or the callback function (mode="client").

The Client Connector is an HTML construct and therefore its name is in the name space of the client document object hierarchy.  It can be accessed by the "connector_name" name in JavaScript.  (e.g. if connector="abc", the object name is connector_abc.)

In particular, three JavaScript variables are made available after the remote call: connector_name.result (an array containing the result%function of the remote function), connector_name.status and connector_name.message (which are status%function and message%function respectively.)

Unlike in the Client Connector, the Server Connector name is not used for any other purpose (not even in the call command, which calls the URL containing the Server Connector, not the Server Connector's name).

mode indicates what the connector does.  A Client Connector is located in the client page for call tags to pass parameters to the remote function.  The Client Connector is an HTML construct.  It is hidden unless style="..." is specified that makes it displayable.  Displaying the Client Connector (e.g. by style="") is useful for debugging as you can see what parameters are being passed and what results are passed back.

Since a Client Connector is a displayable construct (even when it is hidden), it must be put in the <body> section and not contained in a JavaScript section.  (A Client Connector can exist within a BEE Script section as long as the section is in the <body> section.)

A Server Connector is used in the remote function page to be called. It is translated to an execution procedure of the remote function and therefore should be the only executable construct in the function page, but you can add other debugging messages which is to be showing up on the Client Constructor (if it's not hidden).

The remote function can be on the Server Connector page or another page included in by the "include" command.  Basically, the remote function can be on any page as long as it is accessible by the Server Connector.

style specifies the style="..." attribute for the Client Connector HTML construct.  Normally, the Client Connector is a hidden HTML construct, but you can use style="..." to show it.  The simplest way is to use a null style (e.g. style=""), which will show the connector as a display box of default size at where the connector is located on the client page.  Other style attributes can be used to, say, relocate the connector box or show different background or font etc.

domain is a security feature for connecting across web hosts.  e.g. if you call a remote function on server.mydomain.com from a web page on client.mydomain.com, you need to specify domain="mydomain.com" in the Server Connector (at server.mydomain.com).  On the client side, the "call" command needs to have the same domain="mydomain.com" parameter as well.  The "domain" parameter is optional if both the server and the client is on the same web host.

auth if set to true indicate that the server connector is for BEE Remote Authentication.  This parameter contains a secret string that the caller needs to provide in order to authenticate remotely.  The "auth" parameter is effective only for a server connector (mode=server).  Please refer to the "call" command for details.

Note: In the current implementation of BEE, the client connector is in fact an <IFRAME ...> tag.  Parameters other than the above will be used as additional attributes of the IFRAME.  A typical use is to include a src="/blank.htm" attribute to avoid browser complaining about an SSL page containing non-secure parts (the unspecified IFRAME content).