cObject
---cWebObject
------cWebBaseUIObject
---------cWebApp
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.
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.
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.
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
End_Object
End_Object
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
// ...
End_Object
Object oFileToolBar is a cWebToolBar
// ...
// child objects not shown
// ...
End_Object
End_Object
// Use statements for Web Views and Web Services are located here
Use MyView.wo
End_Object
Send StartWebApp of ghoWebApp
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
End_Object
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
End_Object
End_Object
Object oCaptionPanel is a cWebPanel
// property settings not shown
Object oCaptionBreadcrumb is a cWebBreadcrumb
// property settings not shown
End_Object
End_Object
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
End_Object
End_Object
End_Object
// Use statements for Web Views and Web Services are located here
Use ZoomMyView.wo
End_Object
Send StartWebApp of ghoWebApp
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.
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.
Example:
<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.
Example:
<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.
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.
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.
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.
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.
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.
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.
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.
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.
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"
End_Procedure
End_Object
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.
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.
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.