HTML5 Builder - DataSnap REST Client Module Tutorial

By: Al Mannarino

Abstract: This tutorial shows how to create and use a HTML5 Builder DataSnap REST Client Module to access a DataSnap server and call database access functions exposed by the DataSnap server.

By Al Mannarino, Embarcadero Technologies, Inc.

Purpose: This tutorial shows how to create and use a HTML5 Builder DataSnap REST Client Module to access a DataSnap server and call database access functions exposed by the DataSnap server.

Introduction: DataSnap is a technology that enables RAD creation of multi-tier web applications. You can use HTML5 Builder to create client-side web applications that interact with DataSnap. A DataSnap REST client module is a data module that lets you access a DataSnap server. You can then include that data module in another data module or a webpage to be able to call the functions exposed by the DataSnap server.

First we’ll create a Server Web Application, like this:

Hide image

A server web application is a web application that runs in a web server, allowing you to use both server-side and client-side web technologies, and built-in support for database interaction and AJAX is provided. Advanced interface localization features are also available. Once deployed to the server, it can be accessed through a web browser from any device.

Do: Home > New > HTML5 Builder Projects > Server Web Application.

Your new Web Server Project will then be created with an empty server page (unit1.php), which will be opened on the Design view.

Hide image

A Server Web Application consist mainly of server pages, often along with server data modules and server units, although they might have any type of file. To add new files to your project, use the Project Manager.

    Add Some Controls

The first step in creating a server web application with HTML5 Builder is designing the user interface. There are many components available by default for creating user interfaces. Move your cursor over to the Tool Palette (the widget in the top-right corner) and expand the Standard category by clicking the plus (+) icon. Then select the Edit component and drop it onto the Designer. An instance of the component will be displayed on the Designer.

ToolPaletteStandardHighlightedToolPaletteEditHighlighted

Repeat these steps for adding a Label, Button and another Edit component onto the Designer.

ToolPaletteLabelHighlightedToolPaletteButtonHighlighted

Now you should see four components on the Designer. Use the mouse pointer to rearrange the components like this:

Hide image

You can view and change a component’s properties using the Object Inspector and selecting the component on the Designer.

Hide image
Hide image
Hide image

Change the Caption = ‘Execute’ for the Button component.

Change the Caption = “HTML5 Builder DataSnap Web Client” for the Label component.

Change Name = eInput for the top Edit component.

Change Name = eOutput for the botton Edit component.

Note: To change a property of a component, select the component on the Designer (or the drop-down list in the top of the Object Inspector), change the value of the target property and press Enter to apply the change.

    Write a Response for a Button Click

For web applications, any response to users’ actions such as button clicks and text field entries can be implemented as a response to an event. In HTML5 Builder, such responses are referred to as event handlers.

For the Button component, the most typical event is a button click. When you double-click the button on the Designer, HTML5 Builder creates skeleton code to implement an event handler for the button click event.

WebHelloWorld3

Now you can implement responses between the braces. Let’s implement a response to pass the value from the top Edit box (input) to the bottom Edit box (output).

function Button1Click($sender, $params)

{

// take in input from top Edit box and pass it to the bottom Edit box.

$this->eOutput->Text = $this->eInput->Text;

}

}

Note: In HTML5 Builder, while you are typing code, some hints indicating the kind of parameter you need to specify will appear. Also, hints will indicate the kinds of members that are supported in a given object, that is, the properties and methods of your components.

WebHelloWorld4

    Execute your Application

The implementation of this application is finished, so you can run it. You can click the Run button Hide image
in the main toolbar or press F9.

You will be asked to SAVE the application. Create a new folder, and save the application and project:

Hide image
Hide image

Once you have executed the application, the webpage will be loaded on your default web browser. Enter text in the top Edit and click the Execute button.

Hide image
Hide image

Now that we have a Web Server Application, we’ll add our DataSnap REST Client module.

A DataSnap REST client module is a data module that lets you access a DataSnap server. You can then include that data module in another data module or a webpage to be able to call the functions exposed by the DataSnap server.

Note: If you don’t already have a DataSnap Server, please use either Delphi or C++ Builder and create a new DataSnap REST Application (stand-alone VCL app, http, localhost, port 81, sample server methods, TComponent).

You MUST have your DataSnap Server started before creating the DataSnap REST Client Module.

Hide image

Do: Home >> Other Projects >> Other Files >> DataSnap REST Client

On the New DataSnap REST Client Module dialog, you can fill these properties as needed.

  • Set the Protocol to either http (faster) or https (more secure).
  • Choose a Programming Language for the module. It can be either PHP or JavaScript. If you choose PHP, the connection will be setup with RPCL components; if you can it to be generated with pure PHP code, just check the Generate pure PHP code option.
  • Set the Host and the Port to those used by your DataSnap server.
  • You might need to also fill URL Path, Context, User name and Password fields.

For this example, our DataSnap Server (Delphi or C++ Builder created) uses http, localhost, and port 81. We will also use PHP for the language.

Hide image

Click OK.

Hide image

Two files will be added to your Web Server Project, by default: ClientClassUnit1.php and ClientModuleUnit1.php.

The module (ClientModuleUnit1) contains a DSRestConnection component, which will be responsible for the connection with the DataSnap server. It also includes a read method, readServerMethods1Client(), which returns an instance of a class, TServerMethods1. This class is defined in the ClientClassUnit1 file and contains the methods on the DataSnap server you will be able to call from your web client.

    Call DataSnap Methods from Web Client

In the Code view, open the unit1.php of the WebServerApp project to call the DataSnap server methods.

Add: require_once("ClientModuleUnit1.php");

Hide image

Now, wherever you want to call a DataSnap method in your code:

  1. Include the global variable for the module: global $ClientModuleDataModule1;
  2. Call the method from its ServerMethods1Client property:

$ClientModuleDataModule1->ServerMethods1Client->methodName()

In our Web Client (unit1.php), we will replace the function Button1Click code with this to display the result of the DataSnap call for the function ReverseString to our web client.

function Button1Click($sender, $params)

{

// Prepare to use $ClientModuleDataModule1 global variable.

global $ClientModuleDataModule1;

// Run DataSnap ReverseString() method, passing it input field content.

$ds = $ClientModuleDataModule1->ServerMethods1Client->ReverseString($this->eInput->Text);

// Print result in output field.

$this->eOutput->Text = $ds->result;

}

}

We are calling the ReverseString function from the DataSnap Server. The value in our top Edit box is our input. Result gets displayed on the bottom Edit box.

Run the application (F9).

Hide image

    Concluding Remarks

Embarcadero’s HTML5 Builder is the definitive software for Rapid Application Development with Web Technologies. HTML5 Builder and its library, the RAD PHP Component Library (RPCL), includes a lot of new features and improvements to make your life easier, and take the RAD methodology even further into the web development. HTML5 Builder features a brand-new interface that adapts itself to your workflow as you take care of the different aspects of your application: writing the logic, designing the Interface, managing databases, and so much more. For HTML5, the RPCL now supports HTML5, the new version of the web standard that is revolutionizing the way you write webpages! To learn more about HTML5 Builder, or to download a trial, visit http://www.embarcadero.com/products/HTML5-Builder

Server Response from: ETNASC04