Class: cWebView

Properties  Events  Methods    Index of Classes

The Web Framework data entry view class

Hierarchy

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseContainer
---------------cWebWindow
------------------cWebView
---------------------cWebModalDialog

Library: Web Application Class Library

Package: cWebView.pkg

Mixins: cWebNavPathHelper_mixin cWebOnCallEndHandler_mixin

Description

Use the cWebView class to create the wrapper object for a data entry view. Each view in your web application will be used to perform some discrete purpose or operation. For example: a Customer Maintenance view for browsing, editing, creating and deleting customer records in the application database.

A view will typically contain other web controls such as web panels, forms, buttons, tab dialog, etc. If the view will access your application's database, then it will contain a DataDictionary object (DDO) structure.

Sample

Object oSalesPersonView is a cWebView
    Set piColumnCount to 10
    Set psCaption to "Sales Person Maintenance"
    Set piWidth to 550

    Object oSalesP_DD is a SalesP_DataDictionary
    End_Object 

    Set Main_DD To oSalesP_DD
    Set Server  To oSalesP_DD

    Object oSalesPID is a cWebForm
        Entry_Item SalesP.ID
        Set piColumnSpan to 3
        Set piColumnIndex to 0
        Set psLabel to "ID:"
        Set piLabelOffset to 50
    End_Object 

    Object oSalesPName is a cWebForm
        Entry_Item SalesP.Name
        Set piColumnSpan to 7
        Set piColumnIndex to 3
        Set psLabel to "Name:"
        Set piLabelOffset to 50
    End_Object 
End_Object

The above example demonstrates a simple data entry view for maintaining data from the Sales Person database table. A single DDO performs database services to the sales person table. Each cWebForm object has a data binding to a column in the sales person table and is connected to the data dictionary for database services via the view's Server property setting.

Object Name

Each view object in your web application must have a unique name.

Object Placement

View objects are placed as the root object inside their own source file (e.g. Customers.wo). This source file is included in your web application by placing a Use statement inside your global cWebApp object, below the application's command bar.

The Studio's Workspace Explorer can generate the Use statement for you when you select the Add Component menu option. If you create a web view using the Studio wizard, then the wizard will place the Use statement for this view in the correct location and will generate a menu item in the application's View menu for activating (displaying) the view.

Activating a View

Send Show to activate a View. Only one view in your web application can be active at any given time.

Object oSalesPersonItem is a cWebMenuItem
    Set psCaption to "Sales Person Maintenance"

    Procedure OnClick
        Send Show to oSalesPersonView
    End_Procedure
End_Object

The above example demonstrates a menu item object that activates a view (oSalesPersonView) in its OnClick event.

The first time a view is activated, it must be loaded from the Server to the Client. During this process (before the view is sent to the client) the OnLoad event will be sent to the view object. You can augment the OnLoad event to make changes to the view's attributes before it is sent to the client.

If the dialog's pbServerOnShow property is True then the OnShow event will be sent to the view object each time it is shown (activated) at the client.

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).

Restricting Access

Augment the AllowAccess event to determine whether the client session has rights to the view. If this function returns False, then the client will not be allowed to show the view or perform any action in that view.

Function AllowAccess Returns Boolean
    Boolean bAccess
    Integer iUserRights
    
    Forward Get AllowAccess to bAccess
    
    If (bAccess) Begin
        Get piUserRights of ghoWebSessionManager to iUserRights
        
        If (iUserRights < 1) Begin
            Move False to bAccess
        End
    End
    Function_Return bAccess
End_Function

In the above example, the view can only be accessed if the piUserRights property of the session manager is 1 or higher. See cWebSessionManagerStandard for more information

Closing a View

A view is considered closed when a different view in you web application is activated. You may also send Hide to a view to close it without displaying any other view in its place.

If the dialog's pbServerOnHide property is True, then the OnHide event will be sent to the view object each time it is hidden (closed) at the client.

Unloading Views for Security

When a view is loaded and displayed on the client, a cached copy of the view (including sub objects and web property values) will remain even after the view has been closed. Normally this does not present a security problem, as the logged in user should already have access rights to the view in order to load it in the first place.

A potential security consideration occurs if, after a view has been loaded, the current user logs out and a new user, with different access rights, logs in. The safest approach here is to ensure that the entire web application is reloaded whenever a new user tries to log in. This will ensure that all cached data is removed from the client.

Send NavigateRefresh to the global cWebApp object (ghoWebApp) to reload the entire web application.

Sometimes you may wish to retain the web application's current state, but remove specific views or dialogs from the client. Send UnloadView to remove a specific view or dialog from the client.

Database Access

You can provide database support for a view by creating a data dictionary object (DDO) structure. A DDO structure is comprised of one or more DDOs. Each DDO represents a table in the application's database. DDOs are connected to each other, via the DDO_Server property, in a hierarchy that typically matches the database relationship hierarchy of their respective tables.

Set the Server and Main_DD properties to enable data binding in your view's data entry objects (cWebForm, cWebList, cWebCheckbox, etc).

Refer to Creating Data Dictionary Object Structures for more information.

Database Actions

Saving

Send Request_Save to save changes to the current records. The save operation is applied via the data dictionary object (DDO) structure that applies all of the associated validation tests before the save can be committed.

Set Verify_Save_msg if you wish to display a confirmation message before the save operation is executed. By default, this property is set to execute the SaveConfirmation message. Set Verify_Save_msg to 0 if you do not wish to display a confirmation message.

Deleting

Send Request_Delete to delete the current records. The delete operation is applied via the data dictionary object structure that applies all of the associated validation tests before the delete can be committed.

Set Verify_Delete_msg if you wish to display a confirmation message before the delete operation is executed. By default, this property is set to execute the DeleteConfirmation message. Set Verify_Delete_msg to 0 if you do not wish to display a confirmation message.

Clearing

Send Request_Clear or Request_Clear_All to clear the current records in the data dictionary objects (DDOs).

Set Verify_Data_Loss_msg if you wish to display a confirmation message before the clear operation is executed. By default, this property is set to execute the DataLossConfirmation message. Set Verify_Data_Loss_msg to 0 if you do not wish to display a confirmation message.

Refer to Using Data Dictionary Objects in Your Components for more information on saving, deleting and clearing.

View Synchronization

Each time a client makes a call to the server (for example an OnClick event, or Request_Save), before the call is processed, the server will automatically synchronize itself to the currently active view on the client. The following occurs in a view during this synchronization:
- Each data dictionary object in the view is synchronized to the current RowId's from the client. The corresponding records are read from the database and loaded into each data dictionary. Any data dictionary constraints are re-established during this synchronization process.
- Each web property of each web object in the view (including the cWebView object) is synchronized to the current value of the web properties at the client.

During DDO synchronization, certain data dictionary events may be fired. For example: OnPostFind, OnNewCurrentRecord, etc. If you have augmented these events in your DDO, you probably do not want that code to execute during the synchronization process. Call the AppSynching function to test whether the synchronization process is still executing or has been completed.

Object oInvt_DD is a Invt_DataDictionary
    Procedure OnPostFind Integer eMessage Boolean bFound
        Boolean bSynching
        Get AppSynching to bSynching
        // Do not perform this action while synchronizing DDO's 
        // to the WebApp Client
        If (not(bSynching)) Begin
            Send SetPriceDefault of oOrderDtl_DD Invt.Unit_Price
        End
    End_Procedure
End_Object

The above example demonstrates a DDO where the OnPostFind event has been augmented. The action performed by this event cannot be executed during the data dictionary synchronization process.

Refer to Web Application Synchronization for more information.

For each server call that is received, the active view (or dialog) will receive the OnSyncView event. This is received after the view's DDOs have been synchronized, the DDO constraints re-established and the web property values are synchronized but before the call action is executed. You can augment this event to perform any additional synchronization of data required by the view. For example: you may need to re-establish secure data that is stored in some location on the server.

Switching Between Views and Dialogs

In desktop-style view navigations, the web properties set within a view are maintained when you switch between views. It is clear that this is the behavior you'd want with these kinds of views, as it allows you to switch between views without losing content. The key word here is switch.

With modal-dialogs (desktop style or drill-down), web property changes are not maintained across multiple invocations. In this case, you are not switching view, you are invoking a dialog and then conceptually closing it. The next time you invoke it, you are starting over. When starting over, all web properties are reset to their original value. The reason we do it this way is that this is the most controlled mechanism for handling dialogs. If the old web property contents were maintained (which would include data in forms, etc.) you would end up with whatever just happened to be in that last view. To make this more complicated, some web properties are being set by the server during the invocation and others are "left over" on the client. This is hard to control. We would advise that you WebSet your web properties each time the object is being invoked.

Drill-down views behave the same as modal dialogs. You can think of them as being invoked and then closed. When closed, you start all over. This is even more important with drill-down views, because the same view may be invoked from a number of different places in a breadcrumb, where they may do very different things. This makes the "left-over" client properties seem even more confusing.

There is a property that controls this - pbOverrideStateOnShow. By default, it is set to False in desktop-style views and set to True with modal dialogs and drill-down style views. If you set this to False, you will get the persistent web property value behavior. You will also have to deal with the "left-over" property value issue just discussed. Our advice would be to not change this property and to use the OnNavigateForward event or OnShow to set these properties during each invocation.

Synchronizing and Refinding DDO Records


At various times DDOs must be resynchronized to their client. When this happens all records in your view's DDO structure are re-found. These synchronizations can fail for expected and unexpected reasons. When a record cannot be re-found, OnRefindRecordError will get called. This event normally does nothing, as the framework will handle the missing records as best it can. Mostly these errors are the result of expected multi-user activities. They might also be caused by programming errors. Refer to OnRefindRecordError for a complete description of this process.

Multiple Data Dictionary Object Structures

Implementing a single DDO structure per view is sufficient for most requirements. There are some special cases where you may need to display data from two separate data entities (i.e. unrelated database tables), where more than one DDO structure is required.

Another use of multiple DDO structures is when you may wish to represent two records from the same database table at the same time.

The DataFlex Web Framework supports multiple data dictionary object (DDO) structures in a single view. You can declare multiple DDO structures in the same way you would declare a single DDO structure. You must select one of the DDO structures as the default: The view's Server and Main_DD property must be set to the Main_DD of the default DDO structure. For each additional DDO structure, you must send the AddDDOStructure message.

Refer to AddDDOStructure for more information.

Toolbars

A view may contain one or more toolbars that are only displayed when the view is displayed. To define a toolbar, create a command bar (cWebCommandBar) object inside your cWebView, then nest each desired toolbar (cWebToolbar) inside the command bar. You cannot create a menu bar inside a view's command bar. Views do not support an embedded menu bar.

See cWebToolBar for more information.

Appearance

The appearance of a view is determined by the web application's CSS theme (psTheme). You can define additional or replacement CSS styles in your web application's application.css file. Set psCSSClass to the CSS class name you would like to be applied to a view.

Set psBackgroundColor to directly override the control's CSS themed color.

Set piHeight and piWidth to specify the height and width of a view (in pixels).

Set psCaption to display a descriptive caption (heading) for the view.

See Also

cWebModalDialog | Styling Web Applications