2 year anniversary

Components Guide

This document cover aspects of vcl.js under node.js there is a diffrent document covering .Net   : "Getting started with Vcl.js for .Net"


Getting Started with Vcl.js for Node.js


Vcl.js is a typescript web framework focused on an enterprise application development.Vcl.js contain all the necessary components to support business application software.
Vcl.js takes the Delphi/VB approach into the HTML5 world,its designed to help developers build large web applications that are competitive with native apps,so if you a VisualBasic or delphi developer you will learn vcl.js in no time.

In this tutorial we'll cover most aspects of vcl.js development . This project is a simple ordering system with basic CRUD functionality running on top of node.js and MySQL database located on azure server.

You can watch the sample running on azure cloud by clicking here.



Before you can use vcl.js you must first download the following packages to your development computer. 

Visual Studio 2013 SP3
Node tools for visual studio
VCL.JS Visual studio plugin
Sample project source code



1. Make sure prerequisites are met.
2. Download the visual studio project source code : Sample project source code.
3. Open the project.
4. Refresh npm packages by right clicking the npm folder and select "update npm packages" (wait until all packages are loaded).
5. Run the project.
6. Let us know if you encounter any problems on our support forum.



Vcl.js project consist of 3 folders:

public : The client side folder,place here all browser files including code & html,images and CSS.
‚Äčserver : The node.js server side folder,place here all business logic code.
Config : Location of the following configuration files:
     database.json : Store here the connection string for your application.
     queries.json :  json file that contain list of SQL queries that can be use by the frontend without writing plugins.
     users.json : Defines here the username,password and role names used to log on.

And the following files:

public/main.ts : This is the starting point of vcl.js,in fact every time you refresh the screen this file is loaded and execute the application.You can initialize here application wide properties.
By default, when a new project is loaded, vcl.js constructs an TApplication class and assigns it to the V.Application variable.
Application has many properties and methods that can be used to get and set information about an application while it runs.
The value of MainPage is the page that is the application's main page. The main form is the first page created in the main body of the application by a calling to V.Application.navigateToPage method;

import V = require("VCL/VCL");
export function start() {

    V.Application.CurrencyDecimals = 2;
    V.Application.ApplicationBrandName = "Contoso LTD";
    V.Application.ApplicationTitle = "VCL.JS App";
    V.Application.MainPage = "PageHome";

    V.Application.AuthenticationRequired = true;

    //application navigation bar 
    var navItem = V.Application.addNavbarItem("Customer Center", "icon-home icon-white", () => {





Database transaction and queries are very common to most business application. Vcl.js provide all the necessary tools need to run queries in no time. 

There is more than one way to run a database query:

The first (and easy) way to run a query is by adding the SQL statement to Config/queries.json file and later calling it from the client side.

in the following example the query id is "getCust" followed by:
sql : The sql statement.To use a parameter in a SQL statement, use a question mark.
db: The id of the connection string locate in in Config/database.json file.
role : The role of the users who allowed running this query.Users definition is located in Config/users.json file.

  "getCust": {
    "sql": "select ID,FirstName,LastName,AddressLine1,EmailAddress from Customers where id=?",
    "db": "DB",
    "role": "guest,admin"    


Calling the query from the client achieved by creating a TQueryRemote object,passing the query id and calling the open method which will call the backend asynchronously.
TQueryRemote is TClientdataset descendants so you can bind it to most data aware components.

var qurCust : V.TQueryRemote= new V.TQueryRemote(this);
this.qurCust.QueryID = "getCust"; // this is the id of the query in config/queries.json
this.qurCust.createParam(customerID); //add paramter to the query

var grd: V.TDBGrid = new V.TDBGrid(pnlCust, "grdCust");
grd.PageSize = 8;
grd.Dataset = this.qurCust; //bind the grid component to the dataset


A different approach is to write the query programmatically as a server side plugin. Plugin is a class that accept json as a parameter and return json (usually array) as a results. 
In the following example the plugin is getting the customerid as a parameter and return the query results to the front-end.
You can add new plugin by right clicking Add->New tem->VCL-ServerMothod-Node under the server/Plugins folder.

import express = require('express');
import iVCLPlugin = require('iVCLPlugin');
import SU = require('server/serverUtil');

export class getCustomerData implements iVCLPlugin.iVCLPlugin {
   execute(req: express.Request, res: express.Response, session: any, jParam: any) {
      if (SU.getUserRole(req) == "") return SU.raiseError(res, "User not loggedin");
      var customerID = jParam.CUSTOMER;

      SU.DBexecute("DB", "CustomerID,SalesOrderNumber from Customers where id=?", [customerID], (error, data) => {
          if (error) return SU.raiseError(res, error);
          else res.send(data);


Calling the plugin from the client achieved by creating a TQueryRemote object,passing the customer id and calling the openRemoteMethod method which will call the backend asynchronously.

var qurCust : V.TQueryRemote= new V.TQueryRemote(this);
this.qurCust.openRemoteMethod("customers.getCustomerData", { CUSTOMER: 1000 });

var grd: V.TDBGrid = new V.TDBGrid(pnlCust, "grdCust");
grd.PageSize = 8;
grd.Dataset = this.qurCust; //bind the grid component to the dataset




Vcl.js includes over 50 components for everything from creating user interfaces to database connectivity, making it fast and easy to build connected applications.
The vcl.js is very similar to Delphi's VCL. Most Vcl.js classes and properties have the same name and functionality as their equivalents in Delphi

A key aim of the vcl.js combined with the typescript language is to change the requirements of building a user interface.The combination of the typescript language and the vcl.js framework written in that language addressed these by:

   1. Controls that wrapped pure html & JQuery controls, in framework that managed resources

   2. Language features that allowed instances of a class to be customized without subclassing, in two ways: first, through the use of properties, allowing instances
      of an object to  have its own fields (such as a caption) easily changed through code; second, by allowing events to be handled by another object; this creates
      "custom behaviours through  delegation instead of inheritance.

   3. Facilitates a clear separation of the development of the graphical user interface (page html markup language or GUI code) .

Creating a page

When you create page (By right clicking Add->New Item->VCLJS-Page) at design time, they are implemented as descendants of V.TContainer. Page can represent the application's main page, or modal page, or sub-page in a parent page. A page can contain other components, such as TButton, TInput, and TCombobox components.

Page (or any other TContainer descendants) module consist from two files.The class file and the html file.

import V = require("VCL/VCL");
export class PageEditCustomer extends V.TPage {
    private custID: number;

    private qurCust: V.TQueryRemote;

    private edFrst: V.TDBInput;
    private edLast: V.TDBInput;
    private edAddress: V.TDBTextArea;
    private edBirth: V.TDBInputDate;

    constructor() {

        this.qurCust = new V.TQueryRemote(this);
        this.qurCust.QueryID = "getCust";

        this.edFrst = new V.TDBInput(this, "edFrst");
        this.edFrst.DataField = "FirstName";
        this.edFrst.Dataset = this.qurCust;
        this.edFrst.LabelText = "First Name";
        this.edFrst.Required = true;

        this.edLast = new V.TDBInput(this, "edLast");
        this.edLast.DataField = "LastName";
        this.edLast.Dataset = this.qurCust;
        this.edLast.LabelText = "Last Name";
        this.edLast.Required = true;

        this.edBirth = new V.TDBInputDate(this, "edBirth");
        this.edBirth.DataField = "BirthDate";
        this.edBirth.Dataset = this.qurCust;
        this.edBirth.LabelText = "Birth Date";

        this.edAddress = new V.TDBTextArea(this, "edAddress");
        this.edAddress.DataField = "AddressLine1";
        this.edAddress.Dataset = this.qurCust;
        this.edAddress.LabelText = "Address";

        var btnSave: V.TButton = new V.TButton(this, "btnSave", "Save");
        btnSave.ButtonStyle = V.ButtonStyle.Primary;
        btnSave.onClicked = () => {
            if (this.ValidateInputs()) {

<div class="row-fluid">
  <div class="span4" id="edFrst"/>
  <div class="span5" id="edLast" />
  <div class="span3" id="edBirth" />

<div class="row-fluid">
  <div class="span12" id="edAddress" />
<div class="row-fluid">
  <div id="btnSave" />

Navigation to page is done by calling V.Application.navigateToPage(<name of the module>,[

In general all components start with the letter "T", all of them have properties, methods, and events that describe aspects of their appearance, such as the text or hint of the control,methods to paint or animate the control, and events that respond to user actions.
Constructing a component is usually done by passing two parameters,the owner of the component and the reference to to element in the html.

export class PageHome extends V.TPage {
  constructor() {
    var edSearch: V.TInput= new V.TInput(this, 'edSearch');
    edSearch.LabelText = "Search";
    edSearch.Text = "Search customer";
    edSearch.onChanged = () => {
       //do somthing

<div class="row-fluid">
    <div id="edSearch" style="width:100px"></div>


Associating a Data Aware Component with a Dataset

When working with database datasets, it is often convenient to have controls that are data aware. That is, the application can establish a link between the control and some part of the data. Vcl.js includes data-aware labels, edit boxes, list boxes, combo boxes, and grids. 

To associate a data component with a dataset
1. Create a dataset , and set its properties as appropriate.(qurCust in our example)
2. Create a data component,All the component that starts with "TDB" prefix are data aware.
3. Set the Dataset property the component to the dataset component you created step 2.
4. Set the DataField property of the control to the name of a field to display. This step does not apply to TDBGrid because they access all available fields in the dataset.
5. Open the query. 

//set up a query
var qurCust : V.TQueryRemote= new V.TQueryRemote(this);
qurCust.QueryID = "getCust";

//create the data aware component
this.edLast = new V.TDBInput(this, "edLast");
this.edLast.Dataset = qurCust;
this.edLast.DataField = "LastName";
this.edLast.LabelText = "Last Name";
this.edLast.Required = true;




Vcl.js is a professional integration plug-in for Visual Studio.Key benefits of vcl.js for visual studio are:
1. IntelliSense : make typescript language references easy to access.
2. New pages : Create new pages and modal page by right clicking (under public folder) New->New Item->VCL-JS Page/VCL-Modal-Node.
3. Server-side plugin : right clicking (under server folder) New->New Item->VCL-JS Page/VCL-ServerMothod-Node.
4. Node.js :  Profiling, npm, TypeScript, Debugging locally and remotely.
5. Azure built in integration.



Azure Websites are for quick and easy web application and service deployments. You can start for free and scale as you go. Vcl.js can be be deployed easily into azure node.js website. In Visual Studio, make sure you’re configuration is set to Release and then right click on your project and select Publish from the menu(If you’re configuration isn’t set to Release then the Publish Wizard will give you a warning.) new you will need to specify where to deploy the application. Finally, a summary page is displayed. Click Finish and your app will be deployed to Azure Websites in about 2 to 3 minutes.



To install new software from package repositories, right click "Update npm Packages" on the npm folder.
Vcl.js is update on a monthly basis providing feature updates and bug fixes.