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.
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>
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");
The displayView function of the JavaScript Engine has the purpose of
integrating a single view within an HTML page. The idea was that you would
use this build things like a contact form or a signup form and integrate
that into a website that is not managed by the framework. This website
is build using the DataFlex Content Manager but integrates a signup form
build using the WebApp Framework.
When using displayView you should not use code that navigates to a different
view (Send Show or Send NavigatePath / NavigateForward / ..). The framework
does not anticipate for that (and the displayView feature actually predates
the navigation logic). URL parameters can be read.
When using the displayView function, it loads and initializes the WebApp
object and its children, but it does not render any of it. It only renders
the view specified from JavaScript with the displayView call. The developer
is responsible for making sure that the view is accessible by the current
session, it will not redirect automatically to the login screen.
You can actually use displayView multiple times within the same page to display different views. The idea is really that the navigation is handled by the surrounding page. If you want navigation, you should use displayApp and hide the surrounding menu's and panels.
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