Watch the Walkthrough

We are going to develop a mobile application with CA Plex and CM First's WebClient mobile templates. The application will allow us to access a network of real-time traffic cameras around the State of Maryland, view their live video feeds, their location on a map, and access the Maryland Traffic live Twitter feed. In this session we will package the Web Application with Cordova to allow it to run on an Android device, though it can also be packaged to run on iOS, Blackberry, or other mobile platforms.

Getting Started

Make sure you have followed the directions in WebClient Workshop Installation to copy the Workspace to your C: drive.

Eclipse

The installation includes a pre-configured version of the Eclipse development environment, open Eclipse by clicking on the Eclipse shortcut in C:\WebClient Workshop.  Eclipse should automatically open the Traffic Application workspace, which is a collection of Project folders.  You should see something like this when Eclipse is opened.

Important Note: The included version of WebClient is using the Plex 6.1 obrun.jar.  If you are using a later version of Plex for this workshop, please paste the updated obrun.jar into the WebClient project in the workspace.

Derby Database

We provide a compact, pre-configured database server named Derby with the Workshop, this allows the application to access data without the need to install and configure database software such as SQL Server on each PC.  The database server must be started before the application is run, otherwise you will get run-time errors. 

The Derby Database server can be started by right-clicking on the 'TrafficJava' project, and selecting 'Apache Derby → Start Derby Network Server'.

You should see the following messages appear in the console tab in the bottom half of the screen.

Sat Oct 26 13:06:14 CDT 2013 : Security manager installed using the Basic server security policy. 
Sat Oct 26 13:06:15 CDT 2013 : Apache Derby Network Server - 10.8.2.2 - (1181258) started and ready to accept connections on port 1527

Note: The Derby Server is ended when you exit Eclipse, so you will need to start the server again using the method above each time you open the workspace in Eclipse.

If you are developing your own WebClient applications, you would probably want to use a standalone database, such as SQL Server, Oracle, or DB2 – so normally you would not need to perform this step.

Exercise 1 – Test the Application

The first exercise is to test that the installation is working, and that you can run the web application in a browser, and on a virtual Android device.

1. Start the Web Server

Make sure your Derby Database server has been started as described in the Getting Started section. 

Locate and click on the 'Server' tab in the bottom third of your workspace.  Right-click on the 'Tomcat v7.0 localhost:8080' server and select 'Start'.  The status of the server should change to '[Started, Synchronized]'

Note: It's possible that you may have another server on your PC that uses the same 8080 port.  If you get a message that the port is already in use, let a member of the CM First support staff know, and they will help you reconfigure it.

2. Access the web application in a browser

Open your Chrome browser, and enter the following URL:

http://localhost:8080/trafficmobile/wc

You should see the application menu in the browser.

If you have the Ripple browser extension installed, you will see a mockup of how the application would look on a mobile device.  In the next step we will actually run it on a virtual Android device.

3. Launch the application on a virtual Android device.

The version of Eclipse we are using has already been configured to use the Android Development Tools (ADT) plug-in.  This allows us to test Android applications on different virtual devices and Android versions.  The workspace also includes a Cordova project which can package our web application as a native Android application (Cordova can be used to package this application for many other mobile platforms, but we'll concentrate on Android for this workshop).

a) Determine the local IP address

When you run the application on the Android device, it needs to know the location of the server (your PC) where the web application is running.  We will find the local IP address of your PC, and enter it into the Android project so it can find the web application.

From your start menu, select 'Run...', then enter 'cmd' to bring up a command prompt.

Enter 'ipconfig', which will display your network settings, and look for the IPv4 address that will probably start with 192.168.

Wireless LAN adapter Wireless Network Connection: 
   Connection-specific DNS Suffix  . : 
   Link-local IPv6 Address . . . . . : fe80::94cb:4b7b:2441:873a%12 
   IPv4 Address. . . . . . . . . . . : 192.168.0.104 
   Subnet Mask . . . . . . . . . . . : 255.255.255.0

In this case, the address is 192.168.0.104, though yours may be different.

b) Enter the URL in index.html

The Cordova Android project is set up to first load a HTML page called 'index.html' which is set up to display a loading screen, perform some device initialization, then redirect to your web application.  We will edit this file to provide the URL to your web application.

In Eclipse, open the TrafficAndroid project, then expand 'assets/www'.  Double-click on index.html to open it in the Eclipse editor.

In the Editor, locate the script tag that sets window.location, and replace the IP address with the local IP address you found in the previous step.  If you are using a different port than 8080, change that here too.

<script type="text/javascript"> 
   function startWebClientApp() { 
         setTimeout(function() { 
                  window.location = 'http://192.168.0.104:8080/trafficmobile/wc'; 
                  }, 1500); 
   }; 
script>

Save the file by clicking on the save icon, or pressing Ctrl+S.

c) Run the application.

Right-click on the TrafficAndroid project, and select 'Run As → Android Application'.

The first time you try to run the application you will be prompted to select a virtual device, you will probably need to create one.

Select 'Launch a new Android Virtual Device', then press the 'Manager...' button.

The Virtual Device Manager will display, click on 'New...' to create a new device.

Enter a name (no spaces allowed), and select a Device from the list.  Choose the following settings:

Click 'Okay' to create the device.  You should now see it in the Virtual Device Manager, close this panel and return to the Android Device Chooser panel.  Click 'Refresh', your device should now be listed.

Select your device, and press 'Start...'.  You will be presented with the Launch dialog, just press 'Launch'.

Your Android emulator will start, bear in mind that your PC is emulating a device, and it will run a lot slower than an actual device.  It may take a few minutes to boot up and run the first time.

Eventually, you will see your application running on the virtual device.

Note: If you own an actual Android device, you can follow the steps at the end of this document to deploy to your own device.

Exercise 2 – Add Buttons

In this exercise, we will add two buttons to the Camera page to allow us to navigate to the Video and Map pages.

1. Open the ViewCameras panel

Open up the CA Plex model C:\WebClient Workshop\Models\Traffic.mdl.

All the objects related to the workshop have been scoped under the 'Workshop' entity.  Open 'Workshop.MobileFunctions.ViewCameras.Panel' in the Panel Editor.

2. Add the two Buttons

In the Panel Palette, right-click on the 'GridButtonP' region and click 'Create PushButton'.  Repeat this step to create the second button.

Note that the WebClient Mobile Templates do not use the position or size of the controls on the panel, instead the controls are attached to pre-defined areas of the screen using control name directives.

Arrange the buttons on the panel designer so they are not overlapping, making it easier to work with.

a) Prepare the Map button

Select the first Push Button, and set the following properties:

Add a logical event 'View Map' to the button's 'Pressed' physical event.

b) Prepare the Video button

Select the second Push Button, and set the following properties:

Add a logical event 'View Video' to the button's 'Pressed' physical event.

3. Call the appropriate functions

We will add the action diagram code to process the events for the selected grid row.

Open the function 'Workshop.MobileFunctions.ViewCameras' in the action diagram editor, and locate collection point 'Pre Point Events'.  Add the following code:

Event Event: View Map 
     For Each Selected GridP 
          Get GridP 
               Call Workshop.MobileFunctions.ViewCameraMap      [Map Input variable to GridP variable] 
Event Event: View Video 
     For Each Selected GridP 
          Get GridP 
               Call Workshop.MobileFunctions.ViewCameraVideo    [Map Input variable to GridP variable]

Close the Panel and Action Diagram, and save your local model.

4. Generate the functions

Drag the following functions to the Generate and Build window:

• Workshop.MobileFunctions.ViewCameras
  
• Workshop.MobileFunctions.ViewCameraMap
  
• Workshop.MobileFunctions.ViewCameraVideo
  

You only need to Generate these functions, they will be built within Eclipse.

5. Build the functions

In Eclipse, the TrafficJava project has already been configured to access your CA Plex Gen folder.  You need to refresh this project to let it know that its contents have changed.

Select the 'TrafficJava' project, and press 'F5' (refresh).  Eclipse will automatically build any changed files, and the WebClient generator will generate the updated panel templates.  The console tab should show something similar to this:

>>> Starting WebClient Build for TrafficJava

        > Using WebClient i+ v1.8.2-pre7133
        > Licensed to WebClient User
        > Valid until Wed Dec 31 00:00:00 CST 2014

        Generating Web templates.
        .

        >>> WebClient Build complete.
                3 panels processed. 0 panels not processed.

6. Start the Web Server

Now that your changes have been built, you are almost ready to view the changes. Click on the 'Servers' tab near the bottom of the screen.  The server may have the status [Started, Republish] which indicates that changes have been made that have not been published to the Web Server yet.  Right-click on the Server and select 'Start'. This will publish and start the server.  When the status changes to [Started, Synchronized] the application is ready to be accessed in the browser.

In your Chrome browser, access the site at http://localhost:8080/trafficmobile/wc

7. Test your changes

On the main menu, select the 'Cameras' button. 

You will see the list of Cameras available, on the bar at the top is a Back button to return to the previous page, a Home button to return to the main menu, and a combo-box to filter the region you want to see.

At the bottom of the screen are the button you have just added.

To test your buttons, select a camera from the grid, then first press the 'Map' button. It should take you to the View Map function (which only displays the location coordinates at the moment).

Press the Back button (if you are testing on an Android device, you can press the device back button) to return to the Camera grid.  Select another Camera, then press the Video button.  This should take you to the View Video function (again, it only displays a URL at the moment).

There are a few improvements that can be made to the application.  First, we are going to apply some templates to display the Map and Video.  We are then going to add a Twitter feed, then tidy up the Camera grid to remove the column headings.

Exercise 3 – Add Map and Video

With WebClient, we can display a control on a panel any way we wish by specifying a control template.  This gives us the ability to provide more controls than CA Plex normally provides.  Templates can be specified as part of the control's control name with the 'template=' directive.  The target is a .ctrl file within the workspace.

We will use a couple of templates that are included with the WebClient mobile templates;

WebMap.ctrl, and WebVideo.ctrl.

These templates can be found in the Eclipse workspace under WebClientMobile\SysTemplates.

1. Apply the Map template

Open up the panel 'Workshop.MobileFunctions.ViewCameraMap.Panel' in the Panel Editor.

Select the control 'DetailP.LatitudeLongitudCoordinates.Edit'.  Note, we are working with the Edit control itself, not the field.

The existing control name should be:

LatLng:MainArea:label=Location

Change this to:

LatLng:FullscreenArea:template=WebMap

The control name directs WebClient how to generate the template, and the directives are separated by the ':' character.  The first part 'LatLng' is a unique identifier for the control, the second part 'FullscreenArea' is the attach point, which controls where the control will be rendered within the page.  The third part is telling WebClient which template to use – in this case, WebMap.ctrl.  For other controls, there may be more parameters specific to the control.

The WebMap.ctrl template expects the value of the Plex field to be a comma-separated latitude/longitude pair, and will display a map centered at that location.

2. Apply the Video Template

Open up the panel 'Workshop.MobileFunctions.ViewCameraVideo.Panel' in the Panel Editor.

Select the control 'DetailP.VideoURL.Edit', again we are working on the Edit control, not the field itself.

The existing control name should be:

VidURL:MainArea:label=Video URL

Change this to:

VidURL:FullscreenArea:template=WebVideo

The WebVideo.ctrl, expects the value of the Plex field to be a URL.  It then uses that to display the video from that location within the page.

Close and save your panels.

3. Generate your functions

Drag the functions 'Workshop.MobileFunctions.ViewCameraMap' and 'Workshop.MobileFunctions.ViewCameraVideo' to the Gen & Build window and generate them both.

4. Build your functions

Select the 'TrafficJava' and press F5 to refresh.  The WebClient template builder should generate two templates.

5. Test your changes

Open the 'Servers' tab, and restart the server.  When the status changes to [Started, Synchronized], open your application at http://localhost:8080/trafficmobile/wc.

Perform the same steps as the previous exercise to get to the 'View Camera Map' and 'View Camera Video', the pages should look a lot different now.

The View Camera Map function lets you zoom in, and view as a Satellite image.

The View Camera Video function may not display correctly on your desktop browser, or in some versions of Android as the video format is not universally handled.  In addition, some cameras may not be currently active, so try a few.

On an Android device, you may have to touch the main area to activate the video, then press the Play button when visible.

Exercise 4 – Add a Twitter Feed

In addition to the standard templates that are provided with WebClientMobile, it's possible to write your own templates, or adapt an existing HTML/JavaScript control or widget to work with WebClient.  In this exercise, we will use a control to view a Twitter feed from a specified source, in this case; the Maryland Road Traffic service (@mdrtraffic), which provides real-time information such as accidents, road conditions, and general delays.

The custom template 'MobileTwitterFeed.ctrl' can be found in the TrafficCustom project in the workspace, and uses the JavaScript file 'trafficmobile/WebContent/js/custom/twitterWidget.js'.

The Twitter API requires a preset access token from which it can derive the required feed, and which application is accessing the feed.  The access token for Maryland Traffic is already defined in your Plex model as a value of the TwitterAccessToken field.  Passing this value to the template is very simple; first we define a control on the panel to associate with the template, then we set the value for it to use.

1. Add the Twitter Access Token field to the panel

Open 'Workshop.MobileFunctions.TrafficTwitter.Panel' in the Panel Editor.  In the Object Browser, locate field 'TwitterAccessToken', and drag it to the Panel.  When prompted for a region, enter 'DetailP'.

Select the 'Edit' control for this field – DetailP.TwitterAccessToken.Edit, and in the Property Palette set the 'Control Name' property to:

TwtrFeed:FullscreenArea:template=MobileTwitterFeed

This defines the unique control name to 'TwtrFeed', and instructs WebClient to override the default WebEdit.ctrl template with our MobileTwitterFeed.ctrl template, and to place the control in a predefined area of the page called 'FullscreenArea' which is reserved for the area between the rows of buttons at the top and bottom of the page.

2. Set the value from the Action Diagram

Open the action diagram for function 'Workshop.MobileFunctions.TrafficTwitter', and locate collection point 'Post Point End initialize'.  Add the following code:

Set  DetailP = 
Put  DetailP

 3. Generate in Plex, Build in Eclipse

In Plex, generate the function 'Workshop.MobileFunctions.TrafficTwitter' in the Generate and Build window.  In Eclipse, refresh the TrafficJava project and WebClient will automatically generate the panel templates.

4. Test your changes

Restart the server, and refresh your page http://localhost:8080/trafficmobile/wc and select the 'Twitter' menu option.  The page should look like this:

Exercise 5 – Edit Grid Presentation

Grids are a useful component of most Plex applications, but on a small mobile screen it is not practical to display a grid that requires both horizontal and vertical scrolling to view the rows and columns.  The common solution for mobile applications is to present grids as lists that can be navigated vertically by swiping up and down on the screen.  With this approach, each row in the list can display data from any of the columns in the grid, however one consideration with this is that grids can vary widely with respect to the number of columns, column widths and data types, so you would not want to display all grids the same way.  Fortunately there is a technique we can use to customize how any of our grids appear.

WebClient uses the Sencha Touch JavaScript library to provide the look and feel of a mobile application.  The Sencha Touch List control that we use for displaying our grids provides an option to specify an HTML template for each grid row.  By default, the WebClient mobile grids use a template that defines an HTML

element to display the name and value for each column.  The template contains placeholders for the grid column data in curly brackets, for example:

Camera grid Template...

At run-time, it generates as...

And displays as...

In this exercise, we will override the default template to demonstrate how we can control the appearance.

1. Customize the grid control

Open the panel 'Workshop.MobileFunctions.ViewCameras.Panel' in the Panel Editor.  Select the grid and add the directive 'tplGenerator=cmfirst.custom.camGridTpl' to the control name.  The full control name should now be:

Grid1P:FullscreenArea:grouped=true:tplGenerator=cmfirst.custom.camGridTpl

The 'tplGenerator' property specifies a JavaScript function which will put together the HTML template.  The function 'cmfirst.custom.camGridTpl' function can be found in the workspace at trafficmobile/WebContent/Custom/js/custom.js.

Take a look at the function, you'll see that it builds a collection of

2. Generate in Plex, build in Eclipse

In Plex, generate the function 'Workshop.MobileFunctions.ViewCameras' in the Generate and Build window.  In Eclipse, refresh the TrafficJava project and WebClient will automatically generate the panel templates.

3. Test the application

Restart the server and access the application in a browser, or on your virtual Android device.  You'll see that the presentation of the grid is now very different.

The ability to customize the appearance of grids this way is very powerful, and provides the developer with a lot of control over the appearance of the application.  You may be surprised to know that the main menu you see on the first screen is actually a Plex grid loaded from the database with a BlockFetch function.  It was created with exactly the same technique practiced in this exercise. 

Have a look at function 'Workshop.MobileFunctions.AppMenu' and see if you can work out how it was done.

Exercise 6 – Add a Page Template

WebClient provides the ability to include custom HTML and JavaScript code in your generated  page with the use of Page Templates.  Page templates, can provide common functionality or common page elements to your pages.  A page template is a file with a filename that ends with '-page.wcli'.  WebClient determines if a function uses any page template by analyzing its inheritance path, and getting the implementation name of each function.  If a file is found with the name 'ImplName-page.wcli', then that template is included.

For example, 'Workshop.MobileFunctions.AppMenu' inherits from function 'Workshop.Abstract.CustomShell', which has implementation name 'CustomStdPage'.  This equates to the page template in the Workspace 'TrafficCustom/src/CustomStdPage-page.wcli'.  If you look at this file you see it includes the HTML