Form Parameters

Form parameters can be used to share data between the server side and the browser side of a Form. Every time you create a Form in the Morfik Workspace you are actually creating two common object classes in your code: one for the server and one for the browser side of the application. These two entities have very different behaviors at runtime but which, at the same time, are very tightly integrated. At runtime, the Morfik Application Framework makes sure that the correct, updated, values of these parameters are transferred from one side to the other. This ensures that no matter where your code is running those parameters hold the correct, valid, values.

Form parameters cross the browser/server border

A Form’s parameters are, therefore, very important since they are shared between the server and browser sides of the XApp and thus becoming the path to keep information in synch between the two sides of an application. In this way you can write applications that have complete knowledge of their current state stored on the browser side, making the server completely stateless, but which you can program as if that information was on the server.

Looking at the parameter list that is shown in figure 4, you will notice that some of the parameters appear in a lighter color. These grayed items are either system parameters, defined for all forms, or parameters of a query which has been defined as a data source for the Form.

Figure 5: Parameters dialog box showing a large set of them defined for a form

Using form parameters to pass information from the browser side to the server side

Parameter values specified at the time of opening a form are accessible from the form's server-side code. For example, suppose one wants to show or hide a checkbox depending on the end user's level of expertise with your application. Here is one way it could be achieved:

(a) Add a parameter pUserInterface to the form (using the Parameters dialog).

(b) specify the parameter's value in the browser-side code used to open the form:

FX Code

OpenForm('Form1', '...', '"pUserInterface=Advanced"');

OpenForm("Form1", "...", """pUserInterface=Advanced""")

OpenForm("Form1", "...", "\"pUserInterface=Advanced\"");

(c) Use the parameter's value in server-side code like this:

FX Code

Procedure Form1.CheckBox1BeforePrint(Sender: TWebControl; Canvas: TWebCanvas; Var Print: Boolean);
Begin
    CheckBox1.Visible := pUserInterface.Equals('Advanced');
End;

Published Message Sub Checkbox1BeforePrint(Sender As TWebControl, Canvas As TWebCanvas, ByRef Print As Boolean)
    Checkbox1.Visible = pUserInterface.Equals("Advanced")
End Sub

published message void Checkbox1BeforePrint(TWebControl Sender, TWebCanvas Canvas, ref Boolean Print)
{
     Checkbox1.Visible = pUserInterface.Equals("Advanced");
}

Using form parameters to pass information from the server side to the browser side.

Suppose one wants to make a value stored in the database available in browser-side code. Here is one way it could be achieved:

(a) Add a parameter pLookupValue to the form, and set its In/Out status to "Out".

(b) Add the following code to the server-side OnBeforeExecute event:

FX Code

Procedure Index.WebFormBeforeExecute(Sender: TWebDocument; Var PContinue: Boolean);
Var
    RecordSet    : TRecordSet;
Begin
    pLookupValue := '';
    RecordSet    := DefaultDBConnection.CreateRecordSet('SELECT "Field1" FROM "Table1" WHERE ID=4');
    Try
        RecordSet.First;
        If Not RecordSet.EOF Then
            pLookupValue := RecordSet.FieldByName('Field1').AsString;
    Finally
        DefaultDBConnection.DestroyRecordSet(RecordSet);
    End;
End;

Published Message Sub WebFormBeforeExecute(Sender As TWebDocument, ByRef PContinue As Boolean)
     Dim RecordSet As TRecordSet
     pLookupValue = ""
     RecordSet = DefaultDBConnection().CreateRecordSet("SELECT ""Field1"" FROM ""Table1"" WHERE ID=4")
     Try
         RecordSet.First()
         If Not RecordSet.Eof Then pLookupValue = RecordSet.FieldByName("Field1").AsString
     Finally
         DefaultDBConnection().DestroyRecordSet(RecordSet)
     End Try
End Sub

published message void WebFormBeforeExecute(TWebDocument Sender, ref Boolean PContinue)
{
    TRecordSet RecordSet;
    pLookupValue = "";
    RecordSet = DefaultDBConnection().CreateRecordSet("SELECT \"Field1\" FROM \"Table1\" WHERE ID=4");
    try
    {
        RecordSet.First();
        if (!RecordSet.Eof)
            pLookupValue = RecordSet.FieldByName("Field1").AsString;
    }
    finally
    {
        DefaultDBConnection().DestroyRecordSet(RecordSet);
    }
    }
}

(c) Retrieve the parameter's value in the form's OnReady event like so:

FX Code

Var Gv_LookupValue : String;
 
Procedure Index.WebFormReady(Var Ready: Boolean);
Begin
    Gv_LookupValue := pLookupValue;
End;

Private Dim Gv_LookupValue As String
 
Published Message Sub WebFormReady(ByRef Ready As Boolean)
    Gv_LookupValue = pLookupValue
End Sub

private String Gv_LookupValue;  
 
published message void WebFormReady(ref Boolean Ready)
    {
         Gv_LookupValue = pLookupValue;
    }

Parameters and their default values are defined at design time within the IDE. A copy of these default values are compiled into the browser and server side of the application code. When a form is opened default values are overridden by those assigned through the OpenForm function. Any parameter whose value is not set will assume its default value.

The following diagram shows the life cycle of parameters after the OpenForm method is called.

Parameters Life Cycle

Setting parameter values at run-time when the OpenForm function is called explicitly is straight forward (See OpenForm function) . However, when the OpenForm function is called implicitly, such as when a form is opened as part of a page or when a form is assigned to a Subform in the Form designer, setting parameter values requires some understanding of the sequence of events so the parameter values are set at the right time.

Changing parameter default value in browser side - Although in the diagram above there are various points where parameters can be set, the most effective place to set parameters are within the OnCreate event of the form. At this point you can override parameter values before they are sent to the server. One caveat is that in the OnCreate event only those parameters that are not explicitly set through OpenForm function are allowed to be modified - any value that has been changed is forced back to the original value by the Framework once this event returns. This means that if you have set parameter values through the Properties Panel for a given Subform at design time they will take precedence over the values set in the OnCreate event.

FX Code

Procedure Content.WebFormCreate(Sender: TObject);
Begin
    MyParameter := 'some value';
End;

Published Message Sub WebFormCreate(Sender As TObject)
    MyParameter = "some value"
End Sub

published message void WebFormCreate(TObject Sender)
{
    MyParameter = "some value";
}

Changing parameter default value in server side - On the server side the value of a parameter can be changed by overriding the Load method of the Form class. Please note that in the case of a parametric Query being used as the data source for a Form chaning parameter values in the OnBeforeExecute event would not affect the data fetched form the Query as the Query is already created before this event is invoked.

FX Code

Unit Content;
 
Interface
 
Type
Content=Class(Form)
    TextLabel1 : TextLabel;
    TextLabel2 : TextLabel;
  Private
    { Private declarations }
  Protected
    Procedure   Loaded; Override;
  Public
    { Public declarations }
End;
 
Implementation
 
Procedure Content.Loaded;
Begin
    Inherited Loaded;
    MyParameter := 'some value';
End;
 
End.

Namespace Content
    Public Class Content
        Inherits Form
        Published TextLabel1 As TextLabel
        Published TextLabel2 As TextLabel
 
        Protected Overrides Sub Loaded
            MyBase.Loaded()
            MyParameter = "some value"
        End Sub 
 
    End Class
End Namespace

namespace Content
{
    public class Content : Form
    {
        published TextLabel TextLabel1;
        published TextLabel TextLabel2;
        protected override void Loaded()
        {
            base.Loaded();
            MyParameter = "some value";
        }
    }
}

NOTE: If a parameter is introduced to a Form by the underlying Query the parameter is always set to "In" and consequently its default value cannot be changed at run time (the compiler will not allow any value to be assigned to this parameter). To get around this you need to use the following technique:

FX Code

Procedure Form1.Loaded;
Var
    URLParameter : TURLParameter;
Begin
    Inherited Loaded;
    URLParameter := HttpServer.Request.GetURLParameterByName('MyParameter');
    If URLParameter <> Nil Then
       URLParameter.Value := 'some value';
End;

Public Overrides Sub Loaded
    Dim URLParameter As TURLParameter
    MyBase.Loaded()
    URLParameter = HttpServer.Request.GetURLParameterByName("MyParameter")
    If URLParameter <> Nothing Then URLParameter.Value = "some value"
End Sub

public override void Loaded()
{
    TURLParameter URLParameter;
    base.Loaded();
    URLParameter = HttpServer.Request.GetURLParameterByName("MyParameter");
    if (URLParameter != null)
        URLParameter.Value = "some value";
}

• OpenForm Function