BEE Script:   call [location=URL] [operation=string] [connector=string] [callback=string] [domain=string] [auth=bool]
[name=value ...];

BEE Tag:     <beecall [location=URL] [operation=string] [connector=string]
[callback=string] [domain=string] [auth=bool]
[name=value ...]>

The "call" command initiate a "remote call" to a function (the "server function") in another page (the "server page") indicated by the URL parameter.  This command is useful in performing an operation at or retrieving data from the server without refreshing the current page.

The server function is indicated by the "operation" parameter and needs to be accessible from the server page indicated by the "location" parameter.  The server function is operating under the Scope of the server page, not the client page.

The result (the result%function array) of the server function will be passed back to a client script (e.g. JavaScript) on the client page, so that the script and handle the result without refreshing the client page.

Two Connectors, one for the client page and one for the server page, are required to facilitate the communication.  Please see the "connector" command for more details.

Calling a function on another site

If the server page happens to be on a different web site (defined as a collection of URL prefix of the same "owner" as mentioned in the "CROFT" section), it will use the Scope (authentication and data access) of the "server site", not the "client site".  This mechanism not only provides security for the server function but also bridges the data access gap of the two sites.

For example, let's suppose Site A needs to access a piece of information on Site B.  The client page on Site A, a.mydomain.com/caller.htm, calls the server page on Site B, b.mydomain.com/callee.htm.  The connector at callee.htm will invoke a server function (which is just an ordinary function on Site B) and pass the result back to caller.htm on Site A via JavaScript.

Access control

To the server page, the request comes from the visitor's browser, not from the client page.  However, the sys%client:referrer variable still show the client page address, and therefore can be used by the server function to restrict access from only the client page it allows.

Since the server function works under the scope of the server function, it can restrict access based on visitor's login and access level.  That means the visitor needs to have logged into the server site already before gaining access by means of the client site.  This way, the server site security will not be compromised by granting access via the client site.

If SSL is available on the callee site, the caller can include "https://" in the callee URL to indicate a secure submission.

Calling another web host

At the moment, due to a security restrictions on Internet Explorer, BEE needs to restrict the calling to between two pages of the same host (e.g. www.mydomain.com/client.htm and www.mydomain.com/server.htm), and between two pages of two different hosts in the same domain (e.g. client.mydomain.com/a.htm and server.mydomain.com/b.htm, both in the domain of mydomain.com).  In the later case, the "domain" parameter is required on both the client "call" command and the server "connector" command.

BEE Remote Authentication

The Remote Calling machenism of BEE can be used to obtain (or transfer) authentication information from the server site.  For example, if Site A and Site B are two closely related web sites (e.g. two departments of the same company), how can we allow users who have logged into Site B to automatically have access to Site A?  The answer is to set the "auth" parameter in the "call" command to invoke a server function via a "server" connector with "auth" set as well.

To begin, Site A initiates a authentication call to Site B.  Since there is no session information in the call, the authentication server connector on Site B refreshes the caller page on Site A with the session information (which come from the scope of Site B in which the server function is running in).  Site A after being refreshed initiates a second authentication call to Site B, this time with the session information.  The server function will return the sys%auth array via result%function.  The "username" and "accesslevel" are compulsory, while "realm" is optional.  All these three attributes need to be prefixed by "@" in the index.  For example:

connector myauth mode="server" auth=1;

function myauth

{

      var result%function = "(var)sys%auth";

      var result%function:@username = "{sys%auth:username}";

      var result%function:@accesslevel = "{sys%auth:accesslevel}";

      var result%function:@realm = "{sys%auth:realm}";

}

Programmers do not need to concern the above details.  The BEE Remote Authentication machenism is encapsulated in the "auth" parameter of the "call" command and the server "connector" command on the server page.  Once these parameters are specified, everything else will happen automatically.

Parameters

location specifies the URL of the server page.  If the location URL is not specified, the Client Connector will still prepare the parameters but stop just before calling.  For example, <beecall operation=myfunc connector=myconn a=1 b=xyz> (with a style="" in the connector to make it visible) will show the calling sequence in a small window at where the connector is without actually calling the server function.  This is useful to debug the parameters without they being overwritten by the server results.

operation specifies the name of the server function (at the server page).  The default is the name of the connector.

connector specifies the name of the connector used in the remote call.

callback specifies the name of the callback function.  The default value is the name of the connector (in which case, you need to name your callback function the same as your client connector.)

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 "call" command.  On the server side, the "connector" 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 indicates a BEE Remote Authentication call.

name is not really a fixed parameter.  The name name can be anything (except for the parameter names above) and can be more than one.  They are used to pass parameters to the remote function (as indicated by the Attribute Name-Value Pairs in the syntax description).  If a value is preceded by an "@" sign, the rest of the content indicates a JavaScript expression (instead of a BEE expression.)