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:
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.
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.
Repeat these steps for adding a Label, Button and another Edit component onto the Designer.
Now you should see four components on the Designer. Use the mouse pointer to rearrange the components like this:
You can view and change a component’s properties using the Object Inspector and selecting the component on the Designer.
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.
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.
Execute your Application
The implementation of this application is finished, so you can run it. You can click the Run button 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:
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.
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.
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).
- 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.
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.
Now, wherever you want to call a DataSnap method in your code:
- Include the global variable for the module: global $ClientModuleDataModule1;
- Call the method from its
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.
// 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).
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