Developing Applications for the Chromecast using EWD.js

I described how Google’s Chromecast device works in my previous article.  In this article, I’ll explain how to use the new Chromecast extensions for EWD.js to build your own Chromecast applications.

Preparation

The first thing you’ll need to do is install EWD.js or, if you’re already using EWD.js, update it to Build 54.10 or later.  See the EWD.js Reference Guide Appendices for details on installing EWD.js, or Page 54 for information on updating EWD.js.  You can also find all the source code at the EWD.js Github Repository.

Building a Sender Application

The first step is to build a Sender Application.  This is a standard browser-based application that will be used to start and stop the Chromecast application and control its User Interface (UI).  You have to run Sender Applications in a Chrome browser (running on Windows, OS X, Linux or Chromebook), and you’ll have to install the Chromecast Extension.

I’ve already created an example for you that I’ll explain here.  The Sender Application is named chromecast.  If you were to run it on your server, you should copy the directory /node_modules/ewdgateway2/ewdLite/www/ewd/chromecast to the directory /www/ewd/chromecast on your EWD.js system.

I’ve built it using the Bootstrap framework, but you can use any JavaScript framework you like.

Main Container Page

Let’s start with the index.html page.  You’ll find that it’s a pretty standard EWD.js “container” page.  However there are several things to notice:

  • As it can only be run in a desktop Chrome browser, we can dispense with the markup and JavaScript script tags that relate to using Internet Explorer or tablets and phones.
  • At line 83, you’ll see the script tag that loads the Google Cast Sender APIs (<script type=”text/javascript” src=”https://www.gstatic.com/cv/js/sender/v1/cast_sender.js”></script&gt;)
  • At line 93, you’ll see a script tag that loads the EWD.js Chromecast Sender APIs (<script type=”text/javascript” src=”/ewdLite/ewdChromecast.js”></script>)

EWD.js Chromecast Sender Script File

You’ll not need to make any changes to the EWD.js Chromecast Sender API script file, but it’s worth taking a look inside it for one specific thing.  If you look at line 7 you’ll see the following:

    var applicationID = 'CCBCB93C'  // Generic EWD.js Receiver Application Id

I’ve hardwired it to the generic EWD.js Chromecast Receiver application that will act as a container for all of your Chromecast applications.  In other words, you don’t need to create your own Chromecast Receiver application, which, in turn, means that you don’t have to register as a Chromecast developer or register your Chromecast devices for use in development: I’ve done all that work for you already!

HTML Fragment Files

The Sender Application example includes several HTML fragment files that are brought into play at various times when you run the application.  The important one to examine is main.html which contains the markup that defines the UI that will control your Chromecast application.  You’ll see that it defines a set of Bootstrap buttons, each of which will be displayed or hidden at various stage’s of the Sender Application’s life-cycle.  The JavaScript that controls the visibility and behaviour of these buttons, along with the rest of the application’s dynamic behaviour is held in the app.js file.

Your Application’s JavaScript File: app.js

Take a look at the source code for the app.js file.  If you’re already familiar with EWD.js / Bootstrap applications, then you’ll hopefully recognise the usual EWD.application object definition (starting at line 107).  The one difference within this block of code is at line 133 within the onStartup() function:

    EWD.chromecast.initialiseCastApi();

This initialises the Google Cast Sender APIs ready for communication with eny Chromecast devices on your wireless network.

Now look towards the top of the app.js file.  You’ll see a number of properties and methods that are defined for the special EWD.chromecast object:

  • EWD.chromecast.launchUrl: this defines the URL of your EWD.js Chromecast application that will be loaded into the iframe of the generic EWD.js Receiver Application.  In the case of the example application, that URL is https://www.mgateway.com:38080/ewd/cctest/index.html, which, of course, is a typical EWD.js application URL.
  • EWD.chromecast.onStart(): this function will be triggered when your Chromecast application is loaded into the Chromecast.  This function is used to modify the UI of your Sender Application.
  • EWD.chromecast.onStop(): this function will be triggered when your Chromecast application is unloaded from the Chromecast.  This function is used to modify the UI of your Sender Application.
  • EWD.chromecast.onMessage: within this object you optionally define handlers for messages (if any) sent by your Chromecast application to your Sender Application.

Ignore, for now, the JavaScript logic that is included for a LeapMotion Controller.  Otherwise you’ll see that the main activity in the onStart() and onStop() functions is to turn various of the buttons (defined in main.html) on and off as appropriate.

Now it’s time to look at the handlers for those buttons.  They are defined from line 171 onwards in the onFragment() handler for the main.html fragment (ie they are instantiated after the main.html Fragment File is loaded into the container page).  The first one to look at is the startBtn button at line 171:

      $('#startBtn').on('click', function() {
        EWD.chromecast.launchApp();
      });

This Start button is the only one that is on display after you log in to the Sender Application (username rob, password secret).  When you click it, it invokes the pre-built EWD.js function: EWD.chromecast.launchApp().  This is the function you use to instruct the browser’s Chromecast Extension to pop up its window that shows all the Chromecast devices that are available on the wireless network:

 

Screen Shot 2014-04-05 at 11.16.18

 

 

 

 

 

 

 

Clicking on a Chromecast device will cause the generic EWD.js Receiver Application to be loaded into the Chromecast (using the hardwired registered Receiver Application Id CCBCB93C).  As soon as the EWD.js Receiver Application is loaded and it establishes its WebSocket connection to your Sender Application, your Sender Application automatically sends a message to the Receiver application, telling it to load the URL defined in EWD.chromecast.launchUrl into its iframe.

Once your Chromecast application has loaded, your Sender Application’s EWD.chromecast.onStart() method fires.  You’ll see that the visible effect is for the Start button to be hidden and most of the others to become visible, so that you can use them to control your Chromecast application’s UI.  Your Chromecast application is now up and running and ready for use.

If you look at the click() handler functions for these buttons, you’ll see that what they all do is to invoke the EWD.chromecast.sendMessage() function which sends a JSON-structured WebSocket message to the Chromecast Receiver application (which, in turn, automatically forwards them to your Chromecast application that is running inside its iframe).  For example, see at line 198 the handler for the Pointer Down button:

      $('#downBtn').on('click', function() {
        EWD.chromecast.sendMessage({
          type: 'down'
        });
      });

Although the messages I’ve used for the button click handlers only define a type property (all messages must at the very least have a type property), the JSON payload can be as complex as you like, eg at line 76 you’ll see one that specifies the x and y coordinates to which the pointer should be moved in the Chromecast:

        EWD.chromecast.sendMessage({
          type: 'pointerPosition',
          x: x,
          y: y
        });

When we look later at how a Chromecast application is defined, you’ll see that you define a corresponding handler for each of these messages, just as you do for EWD.js WebSocket messages.

So, controlling your Chromecast Application’s UI is simply a matter of sending messages from the Sender Application using the EWD.chromecast.sendMessage() function.

Stopping your Chromecast Application

You’ll see how your Chromecast application is instructed to stop and be unloaded from the Chromecast if you look at line 41 in app.js.  You simply invoke the function:

   EWD.chromecast.stopApp();

Once your Chromecast application has stopped, the Sender Application’s EWD.chromecast.onStop() method fires, allowing you to modify the appearance of your Sender Application’s UI.  In our example application all the buttons are turned off and the green Start button is made visible, completing the Sender Application’s life-cycle which is restarted if you click the green Start button again.

 

Building a Chromecast Application

Now let’s turn our attention to the application that will run within the Chromecast itself.  A fully-worked example is included in EWD.js.  The example Chromecast Application is named cctest.  If you were to run it on your server, you should copy the directory /node_modules/ewdgateway2/ewdLite/www/ewd/cctest to the directory /www/ewd/cctest on your EWD.js system.

Actually, building the Chromecast application is the really simple part.  Once again, it’s really nothing more than a standard EWD.js application, and once again I’ve used Bootstrap, but you could use any other JavaScript framework.

 The Main Container Page: index.html

First, take a look at index.html.  Just like the Sender Application, this can only run in the Chrome browser within a Chromecast device, so I’ve been able to strip out all Script and other tags that relate to the use of Internet Explorer, tablets and phones.  Otherwise there’s nothing in this file that you’d not see in a standard EWD.js index.html file.  The same is true of the application’s Fragment files.

Now look at app.js which contains the application’s dynamic logic.  There is only one change in the definition of the EWD.application object: see line 6, where the chromecast property is set to true:

EWD.application = {
  name: 'cctest',
  timeout: 3600,
  chromecast: true,
  ...etc

Otherwise the EWD.application object contains the usual things you’d expect in any EWD.js application.  The major difference is that after the EWD.application object definition, there’s another object – EWD.chromecast – that is defined (see line 43 onwards).  In fact, all that this defines is a set of handlers for the WebSocket messages received from the Sender Application.   So, for every button click handler function in the Sender Application that sent a message to the Chromecast Receiver Application we have defined a corresponding message handler function.  For example, when the Down button was clicked in the Sender Application, it sent a message with a type value of “down” (see above).  If you look at line 57 in app.js, you’ll see the corresponding handler in the Chromecast application:

    down: function(obj) {
      $('#pointer').animate({
        top: "+=50"
      }, 100, function() {
        // Animation complete.
      });
    },

This causes the pointer to move down in an animated fashion by 50 pixels.

Usually, communication between your Sender Application and Chromecast Application will be one-way on a “fire and forget” basis.  However, you can, if you wish, send a message from the Chromecast Application to the Sender Application.  You’ll see an example of this in the “about” message handler in the Chromecast Application’s app.js file: see line 49:

      EWD.chromecast.sendMessage({
        type: 'aboutReceived',
        message: 'Yes I received the request to switch to the about panel'
      });

So, you just use the same function as you used in the Sender Application to send a message from the Chromecast Application to the Sender Application. Meanwhile, on the Sender Application, you have a corresponding message handler, once again using the same syntax that you saw in the Chromecast application. See line 100 in its app.js file:

EWD.chromecast.onMessage = {
  aboutReceived: function(messageObj) {
    console.log(messageObj.message);
  }
};

So, EWD.js creates a symmetrical environment for message communication between your Sender and Chromecast Applications.

You’ve probably realised that, quite deliberately, the example application is a very simple demonstration of a Sender and Chromecast application, but you should be able to see that anything that you can do in a standard EWD.js application is possible within a Chromecast application.  The only difference is that you control its UI from the Sender Application using simple JSON messages.  In addition, the Sender Application is also a standard EWD.js application, and doesn’t need to be limited to providing a proxy UI for the Chromecast application.

EWD.js makes it incredibly quick and easy to build powerful and flexible Chromecast Applications – now it’s over to you to dream up some cool ideas that harness the full power of EWD.js and the opportunities afforded by the Chromecast!

What’s Next?

In the next article, we’ll take a look at the use of the LeapJS JavaScript library to create a gesture-based UI for your Chromecast Application using a LeapMotion Controller.

 

About these ads

One comment

  1. […] app? With JavaScript, you can create your own Leap Motion-controlled TV. Rob Tweed posted a getting started guide for developers on his […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 58 other followers

%d bloggers like this: