Class: cWebApp

Properties  Events  Methods    Index of Classes

Outermost container for Web Framework Desktop and Mobile/Touch applications



Library: Web Application Class Library

Package: cWebApp.pkg

Mixins: cWebAppBase_Mixin cWebEndPoint_mixin cWebNavPathHelper_mixin cWebOnCallEndHandler_mixin cWebObjectOwner_mixin


cWebApp is the class for the outermost container object of all other web objects in your web application.

Please see Developing Web Applications for more in-depth information about developing Web Applications.

Create your application's cWebApp object inside the WebApp.src file. There will be one and only one cWebApp object per web application. When you run the "Desktop Web Project" or "Mobile Web Project" wizard in the Studio, it will create a WebApp.src file containing a cWebApp object.

The cWebApp object wraps your application's Web Views (cWebView), Web Dialogs (cWebModalDialog) and the main menu and toolbar system (cWebCommandBar).

The cWebApp object also wraps all web server components - Web services (cWebService), low level HTTP services (cWebHttpHandler), ASP page services (cWebASPClassicObject) and helper web components (cWebComponent) - your application may provide. If your application only uses web server components (i.e., it does not use the web framework's UI components) it is a basic web application and you may use the cWebAppBasic class to wrap these components.

See web application types (need link) for a description of the different web application types.

The global variable ghoWebApp stores the cWebApp object handle. Use this to send messages and get and set properties of the cWebApp object from any other object in your application.

Login Credentials for Managed Connections in Web Applications

Windows Applications, by default, include a connection dialog (included via "Use DatabaseLoginDialog.dg"). Since Web Applications cannot display Windows dialogs and the DataFlex Web Application Service typically uses a different Windows user id than your Studio developer Windows user id, especially when deploying an application, we have added a Windows application template in the Studio under File > Create New > Project named "Managed Connection Login Project". This creates a small Windows application that allows you to set the credentials for Managed Applications. Once it has been run, you can then run a Web Application in the same workspace to use those credentials.

Application Style

The DataFlex Web Framework supports three styles of web applications: Desktop and Mobile/Touch and Basic (link to overview). The cWebApp object is used to support Desktop and Mobile/Touch applications. cWebAppBasic is used to support Basic applications.

Desktop style web applications use our user-driven interface. This interface provides most of the user interface features of a native Windows application. It is best suited for web applications with a larger/more complex user interface that would be accessed via browser on a desktop/laptop system.

The mobile/touch style works well on a range of browser devices from mobile phones, to tablets on up to desktop browsers. It utilizes a drilldown interface; this style assumes that an application is used by navigating forward until you find what you are looking for. You "drill down" by navigating forward from one view to another view.

Set peApplicationStyle to determine whether the web application will use the desktop (user-driven), or the mobile/touch (drilldown) application style.
Desktop and Mobile/touch web applications use a different structure of objects to represent their navigational elements such as menus, breadcrumbs, etc.

Sample: Desktop Style

This sample demonstrates a "Desktop Style" web application object (cWebApp) containing a command bar (cWebCommandBar) with embedded menu bar (cWebMenuBar) and tool bar (cWebToolbar) followed by use statements for the web application's views.

The psTheme property setting specifies the application's visual theme. The psEncryptPassword property setting gives the web application a unique encryption key.

Object oApplication is a cApplication
    Object oConnection is a cConnection
        Use LoginEncryption.pkg

Object oWebApp is a cWebApp
    Set psTheme to "Df_Flat_Desktop"

    Object oCommandbar is a cWebCommandbar
        Object oMenuBar is a cWebMenuBar
            Object oFileMenu is a cWebMenuItem
            // ...
            // child objects not shown
            // ...
        Object oFileToolBar is a cWebToolBar
            // ...
            // child objects not shown
            // ...

    // Use statements for Web Views and Web Services are located here
    Use MyView.wo

Send StartWebApp of ghoWebApp

Sample: Mobile/Touch Style

This sample demonstrates a "Mobile/Touch Style" web application object (cWebApp) containing a view stack (cWebViewStack) and a header panel (cWebPanel) followed by use statements for the web application's views.

The peApplicationStyle property is set to wvsDrillDown to specify that the application uses Mobile/Touch Drill Down navigation.

Mobile/Touch web applications do not use command bar objects, instead a structure of panels is used to organize items such as: a menu button (cWebMenuButton), breadcrumb trail (cWebBreadcrumb) and an action bar (cWebActionBar).

Object oWebApp is a cWebApp
    Set psTheme to "Df_Flat_Touch"
    Set psEncryptPassword to "0cOT<]/d0>[xR7fE>cN?TS}yC[[hOTbOU@AQ)#"
    Set peAlignView to alignCenter
    Set peApplicationStyle to wvsDrillDown    

    Object oViewStack is a cWebViewStack
    Object oHeaderPanel is a cWebPanel
        Set peRegion to prTop
        // additional property settings not shown
        Object oMenuPanel is a cWebPanel
            Set peRegion to prLeft
            // additional property settings not shown
            Object oMenuButton is a cWebMenuButton
                // property settings and child objects not shown

        Object oCaptionPanel is a cWebPanel
            // property settings not shown

            Object oCaptionBreadcrumb is a cWebBreadcrumb
                // property settings not shown

        Object oActionPanel is a cWebPanel
            Set peRegion to prRight
            // additional property settings not shown

            Object oMainActions is a cWebActionBar
                Set psGroupName to "MainActions"
                // additional property settings not shown

    // Use statements for Web Views and Web Services are located here
    Use ZoomMyView.wo

Send StartWebApp of ghoWebApp

View Stacks

If your web application uses the "Mobile/Touch Style" then the web application object (cWebApp) must contain a view stack (cWebViewStack) object.

The view stack stores information about each view that is navigated to. When the user drills down by navigating to another view, this information is passed to the new view and that view is added to the stack.

Height and Width

When your web application is loaded into the client (browser), it is rendered inside a special div element with the attribute id="viewport". You can find this div element inside your web application's HTML file.

The overall height and width of your web application is determined by the height and width style settings of this div element.


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

In the above example the web application will occupy 100% of the height and width of the space occupied by the host web page.


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

In the above example, the web application will have a fixed width of 900 pixels but the height is 100% of the height occupied by the host web page.


Control your web application's overall appearance by selecting a Theme. The themes are defined in CSS, you can create your own theme or choose one of the themes already provided with the Web Framework.

Set psTheme to the name of the theme you want to apply to your web application.

User Login

The Web Framework provides default user login, security, and session management features.

Set peLoginMode to: disable user login requirements (lmLoginNone), support user login but not require it (lmLoginSupported), or enforce a user login (lmLoginRequired).

By default, the Web Framework provides a login dialog that handles user ID and password verification.

To use a different user login dialog, set phoLoginView to the object handle of the Web Dialog (cWebModalDialog) you wish to use.

Session Management

The Web Framework's session manager interface is defined by the cWebSessionManager class. A default session manager object is created for your web application using a subclass, cWebSessionManagerStandard, that provides the following features: session key creation and maintenance, login, logout, rights management and view access control. See Session Management and Logins for further details.

Security and Encryption

Your web application will use encryption and checksums when sending certain data to and from the client: Data Dictionary RowId values are accompanied by a checksum to ensure that row id values are not tampered with at the client. Secure file download services use encrypted strings pass the requested file URL to the client.

Set psEncryptPassword to a value that is unique for your web application. This will be used as a key for generating encrypted strings in the above services. It is an important security consideration that each web application uses a different key than the default psEncryptPassword value.

Default View

After your web application has been loaded to the client and the session key and user credentials have been established, it will attempt to load the default view if one has been specified.

To specify a default view, set phoDefaultView to the object handle of your default Web View (cWebView) or Web Dialog (cWebModalDialog).


Augment OnLoad to set specific property values for individual client sessions before the web application is loaded to the client.

Call UrlParameter to get the value of a URL parameter that was passed with the web application URL when the web application was loaded.

When the web application is first started (on the server), a special property is set to True. While this property is True, it means that your web application is not yet fully initialized and has not yet been loaded on any client device. During this time, your application should not attempt to access any synchronized web properties (via the WebGet or WebSet commands), because the synchronized properties system is not yet ready and there is no client data to be synchronized. You can check AppSynching to ensure you are safe to proceed.

Client Synchronization

The Web Application Framework's client synchronization feature simplifies some of the complexities of web application development. It means that each time a client device makes a call to the server, the server will synchronize all of the appropriate web properties and data dictionaries to the current values on the client. Once the server is synchronized to the client, the incoming call is processed.

During the synchronization, it is likely that some server events will be fired. These are mostly data dictionary related events, for example: The Refresh event in a cWebForm object or the OnNewCurrentRecord event in a data dictionary object. If you are augmenting these events, then you might want to prevent your code from being executed during synchronization to the client. Call the AppSynching function to test whether or not the web application is in the process of synchronizing its properties and data dictionaries to the client.

For more information, see Client Synchronization.

Navigation Support

The cWebApp object will typically contain various objects that will be used to navigate around the application. The structure and type of navigation objects will vary depending on whether it is a Desktop or Mobile/Touch style web application.

For desktop style the cWebApp object supports a command bar object that can contain a menu system and a set of tool bars (as shown in the desktop sample above). The Studio's Create New Desktop Web Project wizard builds a cWebApp object containing a default cWebCommandBar containing a structure of menus and tool bars. For more information, see cWebCommandBar, cWebMenuBar, cWebToolBar.

For mobile/touch style the cWebApp object will usually contain a set of panels that will position various navigation objects. Typically these will be a menu button, caption, breadcrumb and an action bar (as shown in the mobile/touch sample above). For more information, see cWebMenuButton, cWebBreadcrumb, cWebActionBar.

Currency, Date and Number Format

The currency symbol, date format and numeric format that are used at the client can be specified by setting the psCurrencySymbol, psDateFormat, psDateSeparator, psThousandsSeparator and psDecimalSeparator properties.

Message Box Support

A special interface for displaying various message boxes on the client with callback functions to the server is supported.

Send ShowInfoBox to display a simple dialog with a title, message string and OK button.

Send ShowYesNo to display a dialog with a title, message plus Yes and No buttons. A callback function can be specified that passes which button was clicked.

Send ShowMessageBox to display a message dialog with an arbitrary set of buttons and customizable appearance.

URL Navigation

Call UrlParameter to get the value of a URL parameter that was passed with the web application URL when the web application was loaded.

Send NavigateToPage to open a URL in a new browser tab, a new browser window or to replace your web application.

Send NavigateNewWindow to open a URL in a new browser window with specified height and width.

Send NavigatePath to navigate to a path registered for an object.

Send NavigateRefresh to reload your web application in the browser. Note: you will lose all data that is cached at the client other than the session key.

You can create a line break in message string by inserting the '\n\r' characters.


This example displays a message using ShowInfoBox where the message string is broken into two lines.

Object oWebButton1 is a cWebButton
    Set piColumnSpan to 0
    Set psCaption to "button"

    Procedure OnClick
        Send ShowInfoBox "Here is a message.\n\rHave a nice day!" "Title"

Global Scope Web Properties

The web properties of your application's cWebApp object are special in that they have a global scope. This means that their values are synchronized to the client with every call made by the client.

Any child web objects defined inside your cWebApp object that do not belong to a Web View or Web Dialog are also in the global scope.

The web properties belonging to a Web View or Web Dialog are scoped to that view or dialog. For Web Views or Dialogs, only the web properties of the currently focused Web View or Web Dialog are synchronized during a call made by the client.

Global scope web properties can be created and used as a global storage for such purposes as transferring data from one view to another. Since global web properties are synchronized with every call, they will add overhead to every call.

Web properties are sent to the client, so they should not be used to store secure or sensitive unencrypted information.

Cookie API

DataFlex functions are now available for reading and writing cookies. The GetCookie function reads a cookie key using its name directly from the HTTP Header. The SetCookie method can be used to update the cookie key by passing its name, value and expiration in hours. When the expiration time is set to 0 it will set the cookie as a session cookie. Note that SetCookie is implemented as a client-action, which makes it asynchronous and GetCookie will not return the new value until the next call arrives.

Drag and Drop Support

This control can be used as a valid drop target by registering it as such in a cWebDragDropHelper object.

The supported actions for this control are:
- C_WebDropOnControl

This allows the control to accept data dragged from elsewhere in the control (if configured that way) and can also be used to accept files when registered within a cWebDragDropFileHelper.

See Also

Developing Web Applications