EWD 3: A Simple ewd-xpress application

119 views
Skip to first unread message

rtweed

unread,
May 10, 2016, 1:16:43 PM5/10/16
to Enterprise Web Developer Community
So now you have EWD 3 / ewd-xpress working with your favourite database, we're now ready to take a look at how you build applications.

It should be fairly familiar to anyone who's previously used EWD.js, but there are differences...I think you'll find that putting up with those differences is worthwhile.

You can simply run the following installer script:



Let's take a look at what this did:

- It first installed the Node.js module named ewd-client, and then moved its core JavaScript file (ewd-client.js) to the ~/ewd3/www directory.  It's now available for loading into you application's index.html file via a <script> tag

- It then moved a simple demo application from the /examples directory in the ewd-xpress module directory:

  - index.html was moved to ~/ewd3/www/test-app
  - test-app.js, the back-end module, was moved into ~/ewd3/node_modules

Make sure you still have the EWD 3 ewd-xpress process running.  If not, restart it.  Then load the following URL in your browser (change the IP address accordingly):


You should see a button appear with the text "Click Me" inside it.

Before you do what it says, first open the browser's JavaScript Console.  You should see:

   test-app registered
   *** got the ewd-register event!!

We'll see what that was all about later.

Now click the button and you should see the following in the console:

   sent: {"type":"test","params":{"text":"Hey! You clicked the button!"}}
   raw received: {"type":"test","finished":true,"message":{"text":"You sent: Hey! You clicked the button!"}}
   received: {"type":"test","finished":true,"message":{"text":"You sent: Hey! You clicked the button!"}}
   button response: {"type":"test","finished":true,"message":{"text":"You sent: Hey! You clicked the button!"}}

OK so it's all working nicely.  Now let's take a look at the index.html file to see how and why it worked:

Navigate to ~/ewd3/www/test-app and view the index.html file:

At the top of its <body> section you'll see:

    <script src="//ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script>
    <script src="/socket.io/socket.io.js"></script>
    <script src="/ewd-client.js"></script>

So it's loading jQuery - like EWD.js, this isn't mandatory, but should be used by default unless you're using some other JS framework that provides a means of:

- detecting that all resources are loaded into the browser
- an Ajax API

It then loads socket.io, which is used for WebSocket-based messaging by the app

Finally it loads the client-side EWD 3 ewd-xpress logic


Look further down the index.html file and you'll see that it detects that the document is ready with everything loaded:

      $(document).ready(function() {
        // etc...
      });



Inside this, it starts up the EWD 3 ewd--xpress client environment:

        EWD.start('test-app', null, io);

The arguments for this are:

1) Application name.  Messages sent to the back-end will expect to find a module of this name in ~/ewd3/node_modules

2) jQuery object ($).  Use this if you want to just use Ajax for messaging instead of WebSockets.  If you want to use WebSockets, use null as the value

3) Socket.io object (io).  Use this if you want to use WebSockets for messaging.  Leave out if you just want to use Ajax messaging.

When the client side of EWD 3 is ready, it sends a message to the back-end which registers an instance of the application and starts a Session.  A token is returned and saved inside a closure within the EWD 3 client.  It then emits an 'ewd-registered' event which you should handle, because your application's logic can now safely start.  So an EWD 3 ewd-xpress application should always contain the following logic to start it up safely:


      $(document).ready(function() {
        EWD.on('ewd-registered', function() {
          // Your application's logic can now be started here
        });
        EWD.start('test-app', null, io);
        // or
        //EWD.start('test-app', $);
      });


So our simple demo application contains a button:

   <button onClick='sendMessage()'>Click me</button>

and the sendMessage() function that it triggers sends an EWD 3 ewd-xpress message to the back-end.  The structure of the message is the same as for EWD.js:



      function sendMessage() {
        var message = {
          type: 'test',
          params: {
            text: 'Hey! You clicked the button!'
          }
        };


but the way you send it is by using the EWD.send() function:


   EWD.send(message);

There are two ways of handling the response, but we'll come back to that.  Let's first look at what happens at the back-end when the message is received by socket.io.  


ewd-xpress uses the ewd-qoper8-express module's Express middleware router which, in turn, adds the message to the ewd-qoper8 queue.  It is immediately dispatched to the first available worker process (one is started up if necessary and the poolSize isn't exceeded).  It then loads your application's back-end module and invokes your handler method for the incoming message type.  This is almost identical to EWD.js.


So let's take a look at our test application's back-end module (see ~/ewd3/node_modules/test-app.js):



   module.exports = {
     handlers: {
       test: function(messageObj, session, send, finished) {
         var incomingText = messageObj.params.text;
         finished({text: 'You sent: ' + incomingText});
       }
     }
   };


Again this should be familiar to those who have used EWD.js, but there are differences.  The handlers are within the exported "handlers" object, and each handler function has a different set of arguments:


1) The incoming message object - this is the same as you sent from the browser


2) The back-end Session object for the user who sent this object.  The Session is a DocumentNode object (see http://gradvs1.mgateway.com/download/ewd-document-store.pdf for the available APIs)


3) send - Function for returning any intermediate messages back to the browser - the send function prevents the worker process from being returned to the available pool.  It should not be used for Ajax messaging!


4) finished = Function for returning the final message to the browser.  The worker process is then returned to the available pool


In our case we're just echoing back the received message object as a new message object:  {text: 'You sent: ' + incomingText}


Of course you also have access to your Cache or GT.M back-end.  In EWD 3, it's made available via 'this.documentStore', eg:


      var glo = new this.documentStore.DocumentNode('robTest', ['a']);
      glo.value = 'Hello world';



So that's the back-end.  The response message is returned to the browser where you can handle it in one of two ways:


- using the EWD.send() function's callback function

- using Pub/Sub via the EWD.on('test') handler


The example application shows the use of the EWD.send() function's callback:


        EWD.send(message, function(responseObj) {
          console.log('button response: ' + JSON.stringify(responseObj));
        });


The returned message object contains the original type (responseObj.type) and the message payload (responseObj.message).


Alternatively you can add a Pub/Sub handler for this specific message type:


   EWD.on('test', function(responseObj) {

    // process the response object

  });


The structure of the response object is identical to that consumed by the EWD.send() function's callback.


What you do with the response object in the browser is up to you.


And that's basically it for simple applications.  You should have enough information to begin developing your own applications.


Just one convention - if you want to signal an error from your back-end handler functions, do this:


   fihished({error: 'My error text'});


The response object structure is as before, eg:


    {"type":"test","finished":true,"message":{"error":"You sent: Hey! You clicked the button!"}}

but you'll find that some of the higher-level ewd-xpress modules look for this error message format and will automatically handle them



One other trick - for verbose logging in the JavaScript console, set:


   EWD.log = true;


and finally, whenever you modify a back-end ewd-xpress module, either restart ewd-xpress, or, better still, use the ewd-xpress-monitor application and close any running worker processes.  New ones will be automatically spun up as needed by ewd-qoper8.



Enjoy developing with EWD 3!


Rob


















Reply all
Reply to author
Forward
0 new messages