The JavaScript Engine

Enhanced Security in Web Framework Applications

JavaScript and DataFlex Classes

 

The JavaScript engine is a set of JavaScript files that implement all the user interface controls on the client. It is responsible for rendering the application, handling events and maintaining the current state. This set of files is located in the 'AppHtml\DfEngine' within the workspace. The Studio will help in placing these files and keeping them up-to-date between revisions of DataFlex.

Including

When creating a new web project within the studio a file called 'index.html' is placed within the AppHtml folder of the workspace. This is the default page for running the entire application within a single page. It basically is an empty HTML structure that includes the engine at the top. It is possible to include the engine in other HTML or ASP pages to render the entire or parts of the application within that page.

A central JavaScript file needs to be included to bring in the entire JavaScript engine. This file ('DfEngine\df-include.js' will generate the include statements needed for the entire engine and the CSS files.

Adding the following line to the <head>…</head> section of an HTML document is all that is necessary:

<!-- DataFlex Engine -->

<script src="DfEngine/df-include.js"></script>

 

Initializing

Now that the engine is included we need to initialize the application and tell it what and where to render. Before we can do this we need to create the application context within JavaScript. We do this by creating a new instance of the df.WebApp class which has the logic to load the objects from the server and communicate with the web-service API. It needs to know the URL of the web-service. The following line of code needs to be added within script tags below the include statement.

var oWebApp = new df.WebApp("WebServiceDispatcher.wso");

The entire application will run within this object. The instances of the objects defined on the client will be accessible as properties of the oWebApp object. It  becomes an tree of objects that has the same structure as the objects on the server. So "oWebApp.oCommandbar.oFindToolBar.oPromptMenuItem" will become the instance of the prompt button defined in the DataFlex code. Note that these objects will be created at runtime when they are loaded which is an asynchronous process.

Rendering the application is done using the displayApp method. It needs to know where to render the application so we pass it a DOM element or a string selector of the DOM element. By using a string selector we can let it render to DOM elements that are not yet available. It will wait until the DOM is initialized before trying to get a reference. To render the application to a DIV with the id 'viewport' the following line of code can be used.

oWebApp.displayApp("#viewport");

This DIV needs to be defined within the <body>…</body>  section of our HTML document like in the example below. Note that we explicitly define the size of this section. The engine will take the space that it gets within the element.

<div id="viewport" style="width: 100%; height: 100%;"></div>

It is also possible to render a single view within a page using the displayView method. It needs the name of the view to render and a DOM element or string selector. The view will be loaded by the engine and rendered as soon as it is ready.

oWebApp.displayView("oOrderView", "#viewport");

 

Debugging

By default the engine is included in minified format. This means that all the JavaScript is pushed into a single file without whitespace and comments. This is a common technique within web development to optimize the amount of data and network round trips needed to load the data. Of course this is very hard to debug since the code is pretty much unreadable.

The 'df-include.js' file supports two standard methods to switch to the full version of the JavaScript. This can be done by adding a GET request parameter to the loaded URL. So instead of loading 'http://localhost/AjaxWeb/index.html' we load 'http://localhost/AjaxWeb/index.html?vdfdebug=true'.

During development it might be convenient to load the full version by default. A configuration variable can be created before including the JavaScript engine. The JavaScript variable bVdfDebug needs to be created and set to true. This overrides the GET parameter and if it is explicitly set to false then the GET parameter is ignored as well.

<script>

var bDfDebug = true;

</script>

<!-- DataFlex Engine -->

<script src="DfEngine/df-include.js"></script>

 

Previous Topic: Enhanced Security in Web Framework Applications

Next Topic: JavaScript and DataFlex Classes

 

See Also

Developing Web Applications