Building Custom Controls

Overview

The building blocks for web applications in DataFlex are the controls. A standard set of controls are provided by the framework. If these controls are not sufficient there is the possibility to extend these or to add custom controls. This is considered advanced technology and requires knowledge of web technologies and especially JavaScript and DOM manipulation.

There will be a difference between incorporating existing controls (from different frameworks) and building the control yourself. This document is meant as a startup for both types but will focus on building your own control. Depending on the technology behind the existing control this control should provide an idea of how and where you could connect to it.

Framework Ecosystem

The Web Application Framework has its own ecosystem of JavaScript objects and DataFlex objects that communicate with each other over a fixed web-service. Building a custom control that lives within this ecosystem means that you have to rely on and work with this provided technology a lot.

The system is based on the idea that each DataFlex object on the server is represented on the client by a JavaScript object. These two objects know each other and can talk to each other. To make this work each control consists of JavaScript class and a corresponding DataFlex class. So there is not only a one on a relationship between the objects but also between the classes.

In this system the JavaScript class is responsible for rendering the user interface based on information (web properties and client actions) it gets from the server. It is also responsible for triggering the server when a user interface events happens that makes this necessary. The server-side DataFlex class provides the API that the application developer uses and contains logic for loading and storing data.

A complete logic is available for communication between the JavaScript class and the DataFlex class. Web properties are the most important piece of this the system as they allow the server to configure and update the user interface rendered on the client. On initialization the initial values are sent to the client and configure the JavaScript objects. When a web property is changed on the server at runtime the framework will send the new value to the client and update it on the object executing setter functions if they are defined. This allows the user interface to respond to a change on the server. Once a web property is changed on the client or the server it becomes synchronized meaning that it will be sent to the server as part of the application state.

Communication is always initiated by the client (usually on a user interface event). The client can call published functions / procedures on the server. These requests are called server actions. If needed the server can add function calls to the response that the client will then execute. These are called client actions.

Components

Each control consists of a DataFlex class that provides the server-side API and a matching JavaScript class that implements the control. Most classes will also rely on a CSS file to define the looks of the control. The DataFlex class is located in the AppSrc folder of the workspace (or a library) and is included like any other DataFlex class. The JavaScript file needs to be in the AppHtml folder of the workspace and needs to be included from the html file (usually index.html).

The sample above shows how to include the JavaScript & CSS files from the index.html. Note that this should be done after the df-include.js file is included and before the oWebApp = new df.WebApp(".."); line.

How It All Works