Echo Client Side Engine

Added by Karora Administration, last edited by Karora Administration on Sep 05, 2007  (view change)

Introduction

As there is absolutely no documentation anywhere about what goes on in the Echo/Cooee Javascript "Client Engine", below is my attempt at documenting it. Please note this is a work in progress, however I'll be updating this rapidly over the next few days.

Of course, I'm welcome for any help along the way

Echo Event Processor

When you have a particular element for which you require notification of some javascript event, you make a call to the Echo Event Processor to register this particular event.

Lets take a simple example: The Window Pane.
A standard Use Case for the Window Pane is that when you click, and hold the mouse down over the titlebar, you can drag the window to wherever you want.

To achieve this, the client engine needs to know what exactly your user will be clicking on, what the action you're interested in is, and the method that should be called.

If we look at the folloowing from the WindowPane.js class

if (this.movable) {
        EchoEventProcessor.addHandler(titleBarDivElement, "mousedown",
                "EchoWindowPane.processTitleBarMouseDown");
    }

We see firstly the script checking whether or not the window pane has the movable property set (we'll look at the Echo2 - Javascript property stuff later), then adding the appropraite handler.

Let's have a quick look at what happens when this event is fired:

EchoWindowPane.prototype.processTitleBarMouseDown = function(echoEvent) {
    if (!this.enabled || !EchoClientEngine.verifyInput(this.elementId)) {
        return;
    }
    EchoDomUtil.preventEventDefault(echoEvent);
    this.raise();
    EchoWindowPane.activeInstance = this;
    this.dragInitPositionX = this.positionX;
    this.dragInitPositionY = this.positionY;
    this.dragOriginX = echoEvent.clientX;
    this.dragOriginY = echoEvent.clientY;

    // Remove all listeners to avoid possible retention issues in IE.
    this.removeListeners();

    EchoDomUtil.addEventListener(document, "mousemove", EchoWindowPane.processTitleBarMouseMove, false);
    EchoDomUtil.addEventListener(document, "mouseup", EchoWindowPane.processTitleBarMouseUp, false);
    if (EchoClientProperties.get("browserInternetExplorer")) {
        EchoDomUtil.addEventListener(document, "selectstart", EchoWindowPane.selectStart, false);
    }
};

Echo Message Processor

So say we want to send a "property" value back to Echo. On the client side, echo provides us with the following:

EchoClientMessage.setPropertyValue = function(componentId, propertyName, newValue)

So if we wanted to send a property value for our javascript back to the server to sync with the server, we'd do it such that:

EchoClientMessage.setPropertyValue(this.element.id, "dragStart", "start");

Where in this example, we're sending back the property name "dragStart" with the message "start".

If we wanted this to happen immediately, we'd then call:

EchoServerTransaction.connect();

However, if this doesn't get called, the property will be sent back the next time connect() is called. This may be on an actionevent for example.

On the server side, receiving this message is a little strange - as the Property Update Processor API is not well designed. Property Update Processor is an interface that will require you to implement an extra method in your Peer. This is:

public void processPropertyUpdate(ContainerInstance ci, Component component, Element propertyElement);

So when Echo calls your peer to provide you with a property from the server side, it will give you the current instance of the container, the component for which the property is relevant, and the "property element".

You will need to do the following (and Cooee needs to change this) to get the contents of your property:

String propertyName = propertyElement.getAttribute(PROPERTY_NAME);
   String propertyValue = propertyElement.getAttribute(PROPERTY_VALUE);

Generally you'd apply these values directly back into your component.

Echo Server Transaction

Echo Server Transaction is the grit of Echo. Its here that the Java Script will send back all the information to the servlet.

The key function here is:

EchoServerTransaction.connect = function()

Lifecycle of the EchoServerTransaction.connect() function

  • Checks to see if there is a currently active transaction
  • Delay Message is activated
  • Async monitor (update polling) is stopped
  • A new http connection is made to the server
  • The response handler and invalid response handler are setup
  • The transaction is marked as active
  • The framework begins the update, sending the message object back to the server
  • The client message is reset
    Only one trasaction at a time!
    Be aware - It seems the EchoServerTransaction method only allows for one transaction at a time. As such, if one is in progress, attempting to start another will most likely result in the second transaction being ignored.

Echo CSS Utilities

Echo Client Properties

Echo Focus Manager

Echo Script Library Manager

Object type : Static

The script library manager is what handles the loading of different Echo/Cooee Javascript libraries. So for a given component, say, Button, there may be a piece of Javascript that needs to go along with this. The Script Library Manager handles the loading and inclusion of this script into the client engine.

Methods Provided

getState(<serviceID>) - Returns the state of the Javascript Library/Service
installLibrary(<serviceID>) - Installs/Loads a new library into the browser via eval()
loadLibrary(<serviceID>) - Requests a library via the Library Service ID from the Server
responseHandler() - Handler for responses received via an EchoHttpConnection

Library Manager - Install Library

When installing a library into the client engine, you provide the method "installLibrary" with the Javascript Service ID. The method then looks up whether or not this library has previously been installed. If it has, it won't install the library again.

Install Library then checks locates where the actual javascript is that you want to be installed. Once located, the Client Engine does something that has raised some contention in the past. The Client Engine will execute the following:

eval (source);

Its important to note at this point that Echo/Cooee DOESN'T create a script tag for integrating new libraries.

Once the script has been installed, it's removed from the "library", as its no longer needed. The script is then marked as installed to ensure no further installs of the script against this ID occur for the given session.

Echo Virtual Position

Server Message Object

Review Required

I'm not convinced the below is 100% correct - as such a review of it is required.

This object is desgined to send your messages back to the server. Generally you will ask the RenderContext for the server message from your peer as part of an update process.

When adding to the server message object through a call such as:

ServerMessage serverMessage = rc.getServerMessage();
Element partElement = serverMessage.addPart(ServerMessage.GROUP_ID_POSTUPDATE, "ExtrasDragSource.MessageProcessor");
Element initElement = serverMessage.getDocument().createElement("init");

Here we grab a reference to the server message from the render context. We then add a "part" to it. One of the key points to look at here is the GROUP_ID_POSTUPDATE. Server messages will be executed in different orders. This is as follows:

INIT then PREREMOVE then REMOVE then UPDATE then POSTUPDATE

The second parameter for calling "addPart" is the MessageProcessor. This is effectively the piece of javascript that will be processing your server message. So when the Client Engine receives your server message, it will delegate to the appropriate message processor to process the message and do whatever needs to be done.

Echo Debug Manager

The Echo Debug Manager provides routines that populate information in the Cooee/Echo debug manager. If you haven't seen it before, this is accessed via /<echoServletName>?debug

Its important to note that if the Debug Window is closed, no actions from the Debug Manager will have any effect.

Sending log messages to the debug console

Any Echo javascript can send logs to the debug window console. This is can be done by calling the following:

EchoDebugManager.consoleWrite( message );

When called, the message will appear in the console section of the Cooee Debug Window. As mentioned above - if the debug window is not open, this method will have no effect. This means you won't receive any logging prior to the window being open.

Update Client Message

When a client message is about to be sent back to the server, the method "updateClientMessage" is called on the Debug Manager. This instructs the debug pane update the "Client Message" section of the window.

Update Server Message

Much like the update client message method of the Debug Manager, "updateServerMessage" updates the debug window with the most recent server message received from the client.

Labels

 
(None)