Web Properties Methods and Events

Creating and Maintaining a Web Application

Web Application Flow

 

The functional behavior of your web application can be coded in your DataFlex server-side application by setting properties, creating methods and creating event handlers.

Loading a View

The first time when a client (Browser) calls the server to load a view, the server will send to the client a structure of data that describes the view. This structure will contain a nested list of all web objects in the view and the set of properties belonging to each web object. The client uses these to create the visual representation of each web object and set up the user interface.

 

Web Properties

Web Properties are used to define data that are sent to the client for each web object. Only subclasses of the cWebObject class understand the web property interface.

A special meta-tag { WebProperty=True } is used to identify which properties of a web object are published to the client. For example: the psLabel property is understood by all web controls. The declaration for psLabel is as follows:

{ WebProperty=True }

Property String psLabel ""

If an object sets the psLabel property...

Object oName is a cWebForm

    Set psLabel to "Name:"

End_Object

Then the value of the psLabel property (“Name:”) is sent to the client when that object’s view is loaded.

Normally, the client object handles each web property that is sent to it and will perform defined actions according to their values. If a web property is sent to the client that the client object does not know, then its value is simply stored in the client object. This means that you can declare your own web properties and use them to store values at the client. For example:

Object oClicker is a cWebButton

    { WebProperty=True }

    Property Integer piCountClick 0

End_Object

In this example, the name-value pair piCountClick=0 is sent to the client when that object’s view is loaded.

Only simple data types can be declared as web properties, e.g. Integer or String. Structures data-types such as structs or arrays are not supported web property types.

To learn about passing structured data to and from the client refer to "Communication".

See also "Data Types, Variables and Constants"

 

Accessing Web Properties

Both the client and the server keep track of any changes to the value of a web property. After the first time the value of a web property is changed, its value will be passed to the server with each client call (e.g. during a save request). If a web property is changed during a call to the server, then the changed value is sent back to the client in the call response.

This is the basic mechanism of data synchronization in a web application. Web properties allow the server application to host multiple client sessions simultaneously without the property changes of one client crossing over to the properties of another.

A special syntax (WebGet and WebSet) is used to get and set the value of a web property.

WebGet psValue to sValue

  

WebSet psValue to sValue

This will get and set the value of the psValue web property of some web object. Only web properties can be used with WebSet or WebGet.

 

Regular Properties vs. Web Properties

In a web application regular (non-synchronized) property values should be considered static. Only web properties should be changed during the lifetime of the web application (using WebSet).

Changes made to a web property (by the client or via WebSet) do not affect the original property value. The original property value can always be retrieved via a regular Get statement. For example:

{ WebProperty=True }

Property Integer piCountClick 0

WebGet piCountClick to iSyncValue   // iSyncValue = 0

WebSet piCountClick to 5

WebGet piCountClick to iSyncValue   // iSyncValue = 5

Get piCountClick to iValue          // iValue = 0

Regular property values should only be set inside an object declaration or a class’s Construct_Object method (e.g. Set pbEnabled to False). If they are never changed, then these properties will be equal for each client that makes a call to the server. Setting a regular property value (using the Set command) during a server call can cause “cross contamination” of property values from one client instance to another and should be considered a programming error. Always use web properties (using WebSet\WebGet) for this purpose.

The only time a regular property value can be modified might be to temporarily store some value during a server call. Before the call is finished, you should discard the property value or restore it to its original value. Use this technique with due care.

The WebGet and WebSet commands do not delegate like the normal Get and Set command. If a WebSet or WebGet command cannot find the web-property a runtime error will be declared. Therefore, your object destinations for WebGet or WebSet should either be self or explicitly declared:

WebSet piCountClick of oCustomerView to True

 

Responsive Web Properties

A web application must adjust to different size clients. Changes in client size can be a one-time thing (e.g. loading on a phone vs loading on an iPad) or it can be dynamic (changing between landscape and portrait mode). The process of making adjustments based on client screen size is referred to as being “responsive”.

Responsiveness is accomplished by using Web Properties that adjusts their value on the client based on the current device size and orientation. The size/orientation specific values are defined by using the WebSetResponsive command.

 

Handling Events

While your web application is in use, various events are triggered. Writing code to handle these events is the main technique you will use to define the behavior of your web objects, and thus the behavior of your web application.

Each web object class has a specific event interface relevant to that class. Below are some examples of web object classes and events.

 

Below is an example of how web properties can be used in the OnClick event of a cWebButton:

Object oLimitedClicks is a cWebButton

    Set psCaption to "click me"

    

    { WebProperty=True }

    Property Integer piCount 0

    

    Property Integer piMaxCount 5

    Procedure OnClick

        Integer iCount iMaxCount

        

        WebGet piCount to iCount

        Get piMaxCount to iMaxCount

        Increment iCount

        

        If (iCount <= iMaxCount) Begin

            Send ShowInfoBox ("Hello world wide web " + String(iCount))

            WebSet piCount to iCount

        End

        If (iCount = iMaxCount) Begin

            WebSet pbEnabled to False

        End

    End_Procedure

End_Object

In this example when the button is clicked on the client an OnClick event will be sent to the corresponding cWebButton object on the server. A web property is used to keep track of how many times the button has been clicked at the client. Once the pre-defined maximum is reached, the button’s pbEnabled web property is set to false.

Enabling Server Events

By default, clicking on a button will always trigger the OnClick event in the server’s cWebButton object. In order to make web applications run efficiently, not all events of a web object’s event interface are automatically sent to the server.

Each event in a web object’s client-server event interface has a Boolean property that controls whether or not the client will send the event to the server. For a cWebButton’s OnClick event the controlling property is called pbServerOnClick. This value is true by default.

The cWebView class has an OnShow event that is triggered in the server object when the view is made active on the client. The controlling property for this event is pbServerOnShow and it is false by default. If you want a view object’s OnShow event to fire you must set pbServerOnShow to true.

In general, the name of an event’s controlling property is:

pbServer{event-name}

By default, most events in the web-object event interface do not fire on the server.

Handling Events on the Client

In addition to server-side event handling, you can also specify a client side event listener. Each event in the web object’s event interface has an associated property that can be set to the name of a JavaScript event listener on the client.

In general, the name an event’s client-side handler property is:

psClient{event-name}

For a cWebButton’s OnClick event the client-side listener property is called psClientOnClick. Below is an example of how you might declare a cWebButton with a client-side event listener:

Object oMyButton is a cWebButton

    Set psCaption to "Click Me"

    Set psClientOnClick to "oMyButtonClick"

    Set pbServerOnClick to False

End_Object

In the above code when oMyButton is clicked on the client the server-side OnClick event is not sent but a JavaScript function “oMyButtonClick” is called. In order to make this button work you would also need to implement the JavaScript function.

Client-side event handling is an advanced technique that requires good knowledge of the JavaScript programming language.

Web Methods

Web Methods are used to define a web object’s external interface. A method declaration becomes a web method by publishing it as a web published method. Only subclasses of the cWebObject class understand the interface for publishing a web method.

For security reasons, only a web object’s web methods may be directly called by the client. Each method of a web object’s client-server event interface is a published web method.

Normally, you do not need to web publish a method declaration unless you are writing your own JavaScript class that needs to call messages on the server. One case where you will need to publish a web method is when you declare a callback method for a particular operation, i.e. when you pass the name of a web object’s web method to the client so the client can call-back this method at some later time.

A method can be published as a web method using the WebPublishProcedure command for procedures and the WebPublishFunction command for functions. In an object declaration you would publish your method after the method declaration. In a class declaration you must publish your methods inside End_Construct_Object before Forward Send End_Construct_Object.

The following example demonstrates how to publish a web method in an object declaration.

Object oConfirmBtn is a cWebButton

    Set psCaption to "Confirm"

        

    Procedure ConfirmResponse Integer iResult

        WebSet pbEnabled to (iResult <> 1)

    End_Procedure

    // Publish the response method

    WebPublishProcedure ConfirmResponse

        

    Procedure OnClick

        Send ShowMessageBox of oWebApp (Self) (RefProc(ConfirmResponse)) ;

             "Do you want to disable this button?" "Question title!"

    End_Procedure

End_Object

In this example the procedure ConfirmResponse is declared and web published. In the object’s OnClick event the ShowMessageBox client message is sent passing a reference to the ConfirmResponse web message. When the message box is closed on the client it will call back ConfirmResponse on the server passing the iResult parameter.

Web Property Scope

To make web applications more efficient, not every web property value is sent by the client when it makes a call to the server. Only the web properties belonging to objects of the currently active view (and any active modal dialog) are sent, plus the web properties of the global cWebApp object and its local child web objects.

This means, for example, that when the Customer View is the focus when a server call is made, you cannot WebGet properties of the SalesPerson view, because those properties were not sent by the client. Attempting to WebGet a web property that is out of scope will result in an error.

You can, however, WebSet a web property of any valid web object during a server call. This value will be sent back to the client and will replace whatever value was previously stored there.

Web Property Security

Realize that Web Property values are sent to the client (browser). Even if your Web Property is not displayed in the User Interface it can still be inspected and manipulated by using a client-side debugger.  If you need to store any data that is sensitive and should not be visible to the client-side user then you should consider one of the following solutions:

 

Previous Topic: Confirmations in Web Applications

Next Topic: Web Application Flow

 

See Also

Developing Web Applications