JavaScript Engine
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-min.js) will generate the include statements needed for the entire engine and the CSS files.
Adding the following line to the <head> section of an HTML document is all that is necessary:
<script src="DfEngine/df-min.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 a tree of objects that has the same structure as the objects on the server. For example, 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> 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.
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 to 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 built using the DataFlex Content Manager but integrates a signup form built using the WebApp Framework.
When using displayView, you should not use code that navigates to a different view (e.g., Send Show or Send NavigatePath / NavigateForward). The framework does not anticipate 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 menus and panels.
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.
During development, it might be convenient to load the full version by default. To do so, replace the following code:
<script src="DfEngine/df-min.js"></script>
with:
<script type="module">
import './DfEngine/df-lib.js';
var oWebApp = new df.WebApp("WebServiceDispatcher.wso");
oWebApp.displayApp("#viewport");
</script>
This allows you to insert the full version of the JavaScript engine.
Previous Topic: Enhanced Security in Web Framework Applications
Next Topic: JavaScript and DataFlex Classes