Overview

The attached package includes eight samples that illustrate the use of the Camera and Worklight Enable builders that are new in Web Experience Factory 8.5. The samples are:

Prerequisites

WEF applications must be run from a Worklight hybrid application installed on a mobile device in order to access native device features, such as the camera. Refer to “Getting Started with WEF 8.5 Worklight Support” for information on developing Worklight hybrid applications.

Note on client applications

Two models are provided for each of the Camera samples. One is a traditional WEF server-side model and the other is a WEF client-side model. WEF server-side applications render a new page on the server for each action or form submission. The page includes HTML markup, scripting logic, and application data. WEF client-side applications render template pages on the server when the application is started (or optionally as each page is needed.) The template pages include HTML markup and scripting logic. The necessary application data is returned from each action or form submission, and is added to the template page using client-side scripting logic.

A client-side application typically results in fewer requests and smaller responses than a similar server-side application. Refer to the article "IBM Web Experience Factory - Anatomy of a Client-Side Application" for more details on client-side applications.

CameraTest and ClientCameraTest

These models are in the samples/worklight/camera_test folder. They are very simple models intended to be used to verify the configuration requirements for using the Camera builder. Each model has two pages. The first page includes a Camera builder for taking a picture. Submitting the first page displays the second page, which contains the uploaded picture.

Mobile device screen shots

CitizenReports and ClientCitizensReport

These applications might be part of a city government web site, where users can report issues they encounter, such as graffiti or sign damage. When running from an installed hybrid application, they can take a picture of the issue and submit it with the other information, which is stored in a database table.

These models are updated versions of the sample that accompanies this article on developerWorks: http://www.ibm.com/developerworks/mobile/library/mo-aim1301-worklight-portal-4/index.html

The new models have been updated to use the Camera builder, which takes the place of the hand-edited JavaScript and other builders that were previously needed to implement the camera functionality. the new models were also updated to use new layouts and styling.

Note

To create and populate the database table, open the CitizenReportsProvider model, open the SQL Table Create builder call and click the "Fetch DataSource Names" button. From the "SQL DataSource" drop-down menu, select "jdbc/CloudscapeForWEF". If this data source doesn't exist, it will offer to create it for you. Scroll down in the builder and click the "Create Table" button. This should create and populate the database table.

Mobile device screen shots

CheckDeposit and ClientCheckDeposit

These applications let a banking customer deposit a check by taking pictures of the front and back of the check and entering the amount. This application is intended just as an example of camera use -- it doesn't store any of the captured data.

Mobile device screen shots

WLDeviceNotification

This application demonstrates the use of the Cordova Notification API. The Worklight Enable builder call loads the Cordova JavaScript files if the application is running stand alone. Each Button builder call contains some JavaScript code that calls the appropriate Cordova API.

Mobile device screen shot

WLClientAudio

This application demonstrates the use of the Cordova Media API. The Worklight Enable builder call loads the Cordova JavaScript files if the application is running stand alone. Each Button builder call links to a Client Method that calls the appropriate Cordova API.

Mobile device screen shot

Running the samples

To use the Camera builder with these samples, you will need to have your development environment configured for using Worklight with Web Experience Factory, as described in “Getting Started with WEF 8.5 Worklight Support”, as mentioned in the Prerequisites section.

To use these samples, you will need to download the attached zip file. Right-click a WEF project, choose the Import > Web Experience Factory Archive menu item, and select the downloaded zip file. Doing this will add the samples to your WEF application. You will also need to create a Worklight hybrid application that accesses the WEF application to run the samples on a mobile device.

Note on Smart Refresh

The WEF Camera builder functionality is dependent on the Cordova JavaScript files supplied by Worklight. These JavaScript files do not get loaded correctly if the page containing the Camera builder uses Smart Refresh. Because of this, the Theme used by the sample models for a tablet device sets the Use "Smart Refresh" input to "No". (The Theme used by the sample models for a smartphone device already has Smart Refresh disabled by default.)

Note on file upload and security

The default location in the WAR (under the WEB-INF folder) to which files are uploaded should be considered a temporary location. Uploaded pictures should not be permanently stored in this location for several reasons, including but not limited to:

– Access. Uploaded images cannot be displayed from a location within the WEB-INF folder.

– Persistence. The WAR on disk may be deleted and replaced when the application is redeployed.

– Topology. A multi-node cluster may have multiple copies of the WAR, but the file is only uploaded to one of these.

For security reasons, you should always configure the default file upload location to be within the WEB-INF folder of the deployed application. This prevents potentially malicious content from being uploaded into a location which is accessible from a browser. After verifying that the uploaded files are appropriate to the application (right file extension(s), appropriate content, etc.), the uploaded files can then be moved to a more suitable location.

The Camera builder facilitates this security behavior. It will produce a Designer warning if the upload location is outside the WEB-INF folder. Once an image is uploaded, the Camera builder validates that it has the expected file extension and that the image content is the expected type. If the validation succeeds, the image is moved to the specified folder location relative to the application root. If the validation fails, the image is deleted.

This Camera builder functionality addresses basic security and access issues for uploaded images, but it does not address the persistence or topology issues. Additional application functionality would be required to address these issues.