Web properties are the main concept of the framework that facilitates the synchronization between the client and the server. They are represented by actual properties both in DataFlex and JavaScript code and can be used like actual properties. The main difference is that the framework can sends their values to the server with a request and can update them with a new value after the response is received. The framework also sets the default value after the object is created (after the constructor is executed before the create function is called).
To define web properties there is the prop function on the cWebObject class. It creates the actual property and stores the property type. The type is needed for type casting as a properties are all sent back and forth as strings. This casting is needed even while JavaScript is not a strongly typed language because for example "false" evaluates to true.
this.prop(df.tInt, "piSpinValue", 1);
The example above shows how a property is defined. The last parameter is the initial value which is only used if the property is not (yet) defined on the server or if the control can also be used as a standalone control.
The types that are currently available are:
Framework Identifier |
DataFlex Type |
JavaScript Type |
df.tString |
String |
String |
df.tInt |
Integer |
Number |
df.tNumber |
Number |
Number |
df.tDate |
Date |
Date object |
df.tBool |
Boolean |
Boolean |
df.tAdv |
Non scalar type (struct / array) |
Non scalar type (struct / array) |
df.tAdv is a non scalar type (struct / array) that is handled very differently than the scalar types (ValueTrees).
If an item is not in this list, it means that the JavaScript Engine has no special conversion logic for it as a web property type and you should just handle it as a string.
While implementing the JavaScript control web properties can be accessed as regular properties. So this.pbShowHeader reads the current value of the pbShowHeader web property but without executing a getter method.
bResult = oWebApp.oView.oSpinFrm.get("piSpinValue");
The get method can be used the get a properties current value making sure that the getter method is executed. Changing a property value can also be done by directly accessing the property but note that this doesn´t mark the property as changed. If a property is not marked as synchronized / changed its current value will not be sent to the server during a call so a WebGet will result in the wrong value.
oWebApp.oView.oSpinFrm.set("piSpinValue", 25);
The set function can be used to change a property and mark it as changed. It will also execute the setter method if available. Its main purpose is to be called from outside the control.
If a property value changes at runtime it is common to update the user interface. This can be done by defining a setter function. The setter will be called by the framework when the value is changed at runtime using a WebSet in DataFlex code or the set function in JavaScript. Note that the setter is not called during initialization. It is common practice to call these setters manually
set_piSpinValue(iVal){
if(this._eControl){
df.dom.setText(this._eControl, iVal);
}
}
The example shows a setter for the piSpinValue property that updates the DOM by updating the text inside a span element. Note that this.piSpinValue still holds the old value when the setter is called, the framework will update it after calling the setter.
A getter will be executed before a call involving this object will be sent to the server if a property is marked as synchronized. Since this can be quite regularly a getter should always be as efficient as possible and only be used when needed. A common task for a getter would be to read a value from the DOM.
get_psValue(){
if(this._eControl){
return this._eControl.value;
}
return "";
}
The example above shows a typical getter method that checks if the DOM elements are available and if so it will return the value directly from the DOM.
A synchronized web property is sent to the server with each request as part of the application state. If a property is changed on the server using WebSet the framework will make sure that the property is marked as synchronized. Properties can also change on the client (for example on user input) and then the control is responsible for marking it as synchronized / changed. One method for doing this can be use the set command which will also execute the setter method. Another method is use the addSync function.
this.addSync("piSpinValue");
Some properties are always marked as synchronized. For example psValue and pbChanged for all data entry objects.
Previous Topic: Framework DOM Functions
Next Topic: Communication