DB Web Control Wizard Overview

Note: DB Web Controls (Borland.Data.Web namespace) are being deprecated in 2007. You should use standard Web controls instead.

The CodeGear DB Web Controls are data-aware web components. These DB Web Controls allow you to encapsulate data-aware functionality into standard web controls. One benefit of this approach is that the data binding function is fulfilled by the control itself, eliminating the need to add a call to the DataBind method.

The basic concepts involved in creating DB Web Controls are:

The ASP.NET Control Execution Lifecycle
Data Binding Concepts
Overriding ASP.NET Methods
Implementing DB Web Interfaces
Essential Code Modifications

The ASP.NET Control Execution Lifecycle (CEL)

Anytime an ASP.NET web forms page is displayed, ASP.NET performs what Microsoft calls the CEL. This consists of a number of steps, which are represented by methods:

Initialize
Load view state
Process postback data
Load
Send postback change notifications
Handle postback events
Prerender
Save state
Render
Dispose
Unload

You can add logic to any or all of these events by adding code to given methods, such as the Page_Load method or the OnInit method. Most often, however, you will need to override the Render method.

Data Binding

In ASP.NET you can bind to a variety of data sources including databases, text files, XML files, arrays, and collections. In RAD Studio, controls provide a simple property-based interface to data sources. In the Object Inspector, you can bind a selected control to a data source that is identified to your project by way of the BDP.NET controls, SQL client controls, or other data or file controls. Each type of data control has different sets of binding requirements. For instance, any collection control, such as the listbox control, data grid, or listview control, must bind to a data source that implements the ICollection interface. Other controls, like buttons and text boxes, do not have this requirement.

When you are programming with web controls, you must add the code to perform the data binding. For example, if you created an instance of a data grid, the command that you would add would look like:

Copy Code

dataGrid1.DataBind();

When using DB Web Controls, you no longer need to add this code. DB Web Controls handle the data binding operation for you. The DBWebDataSource component serves as a bridge between your data source component and the specific DB Web control you want to use. The DBWebDataSource creates and manages the data binding between the data source and the control. Although you can physically add the code to instantiate a DB Web control and to perform the data binding, it is unnecessary to do so. You can drop your components onto a web form and select the linkages from property drop down list boxes in the Object Inspector.

Note: When creating a new DB Web control or extending an existing control, you may need to add code to perform binding of some properties.

Overriding ASP.NET Methods

The main method you will need to override is the Render method (or the RenderContents method). The Render method is responsible for displaying your controls visibly on the web page. When you define Rendere the Render method and pass it an instance of the HtmlTextWriter class, you are indicating that whatever you code in the method is to be written to the ASP.NET page in HTML. The Write method of the HtmlTextWriter class writes a sequential string of HTML characters onto a Web Forms page.

The following example shows how the control is declared in the file that is built by the DB Web Control Wizard. This is only a small segment of the code that is provided for you.

Copy Code

  
/// TWebControl1 inherits from the WebControl class of System.Web.UI.WebControls.

TWebControl1 = class(System.Web.UI.WebControls.WebControl)

When creating your own controls or extending existing controls, you must override the Render method to display your control. The Render method is responsible for sending output to an instance of an HtmlTextWriter class. HtmlTextWriter sends a sequence of HTML characters to the web forms page. The HTML characters are the representation in HTML of your control. For example, a web grid control is represented on a web forms page as an HTML table. Each control has its own HTML representation, but when you extend a control, you need to modify how the HTML is emitted to accurately represent your new control.

Copy Code

/// The following lines declare the Render method. 
/// Output represents an instance of the HtmlTextWriter class.
/// HtmlTextWriter is the class that writes HTML characters to
/// the ASP.NET Web Forms page.

 strict protected
    procedure Render(Output: HtmlTextWriter); override;

implementation

{$REGION 'Control.Render override'}

/// The following procedure is the overridden Render method
/// You can include additional logic in the procedure to affect
/// the behavior of the control. This method, as written, does 
/// nothing but write out a sequence of HTML characters that 
/// define TWebControl1. 

procedure TWebControl1.Render(Output: HtmlTextWriter);
begin
  Output.Write(Text);
end;

You would need to implement the preceding code even if you were trying to extend the capabilities of a standard web control. To extend one of the DB Web Controls you need to make more adjustments to this code.

Implementing DB Web Interfaces

When you run the DB Web Control Wizard, the wizard creates a code file for you, containing the basic code you need to extend a DB Web control. This file is similar to the file you would create if you were trying to extend a standard web control. The major difference is that the DB Web Control Wizard adds implementations of specific DB Web interfaces, which provide automatic access to a data source, tables, columns and their respective properties. Because the DB Web Controls handle so much of the postback and data binding automatically, you need to implement several specific interfaces to add this functionality to your control.

Essential Code Modifications

When you create a new DB Web Control Library, the DB Web Control Wizard creates a file template for you. This file contains the major elements you need to include in your project to create or extend a control. You will need to add or modify the following elements:

Change the ToolboxBitmap attribute to specify your own icon for the Tool Palette, if necessary.
Change the control declaration to specify the control you intend to inherit.
Declare the correct Render method.
Implement the IDBWebDataLink interface.
Implement the IDBWebColumnLink and IDBWebLookupColumnLink interfaces, if necessary.
Modify or extend the Render method.
Modify hidden field registration, if necessary.
Set data binding on specific properties, if necessary.

Change the ToolboxBitmap Attribute

If you have a bitmap icon available for use in the Tool Palette, specify its path in the ToolboxBitmap attribute in the DB Web Control Library file. The code might look something like this:

Copy Code

[ToolboxBitmap(typeof(WebControl1)]
['WebControl1.bmp')]

Make sure that you include the bitmap file in your project.

Change the Control Declaration

You can specify the ancestor more specifically. For example, if your control is an extended version of a DBWebGrid control, the code would look like this:

Copy Code

    MyDataGrid = class(Borland.Data.Web.DBWebGrid, IPostBackDataHandler, IDBWebDataLink)

Declare the Correct Render Method

Your control can inherit from either the Control namespace or the WebControls namespace. WebControls actually derives from the Control namespace.

The major difference for you is that WebControls defines all of the standard web controls, so if you plan on extending the capabilities of a web control like a textbox or a data grid, your control needs to inherit from WebControls.

By inheriting from WebControls, you are able to use all of the appearance properties of your base control. Typically, if you want to create a control that has a UI, inherit from System.Web.UI.WebControls. In the DB Web Control Library file, you will override the RenderContents method.

If your control inherits from Control, you need to supply the UI definition when you override the Render method. Typically, if you want to create a control that has no UI, you inherit from System.Web.UI.Control. In the DB Web Control Library file, you will override the Render method.

Implement the IDBWebDataLink Interface

This interface provides the access to a data source. You need to implement this interface for any DB Web control you intend to extend. The implementation is handled for you in the DB Web Control Library file.

Modify or Extend the Render Method

In the Render or RenderContents method, depending on which namespace you inherit from, you can override the properties of the base class. In the DB Web Control Library file the following code is automatically included for you:

Copy Code

procedure TWebControl1.Render(Output: HtmlTextWriter);
    begin
      Output.Write(Text);
    end;

This method passes the definition of your control to an instance of HtmlTextWriter, called Output in this case. The Text property will contain the HTML text that is to be rendered. If you wanted to code directly within the method, You could add code, as follows:

Copy Code

procedure TWebControl1.Render(Output: HtmlTextWriter);
    begin
     Output.WriteFullBeginTag("html");
         Output.WriteLine();

         Output.WriteFullBeginTag("body");
         Output.WriteLine();

         Output.WriteEndTag("body");
         Output.WriteLine();

     Output.WriteEndTag("html");
         Output.WriteLine();
    end;

This results in an ASP.NET web page with the following HTML code:

Copy Code

<html>
    <body>
    </body>
</html>

The use of the Text property, however, makes the code easier to work with. Once you have defined your control and its properties, along with various HTML tags, you can pass the entire structure to the Text property. From that point forward, you need only refer to the Text property to act upon the control. You define the properties of your control and pass them to the HtmlTextWriter by creating a Text property that contains the control definition. It is instructive to look at the source code for some of the existing DB Web Controls. For example, the following code shows the definition of the Text property for the DBWebNavigator control.

Copy Code

protected string Text{  
  get
       {

// Create a new instance of StringWriter.
                    StringWriter sw = new StringWriter(); 

// Create a new instance of HtmlTextWriter.
                    HtmlTextWriter tw = new HtmlTextWriter(sw); 
     
// Call the DataBind procedure.
                    DataBind(); 

// Call the AddButtons procedure.
     AddButtons();  

// Call the SetButtonsWidth procedure.
     SetButtonsWidth();  

// Add a style to a panel.
     ClassUtils.AddStyleToWebControl(FPanel, this.Style); 

// Render the HTML start tag for a panel control.
        FPanel.RenderBeginTag(tw);  

// Call the HtmlTextWriter.Write method and pass the table 
//  and tablerow tags to the web forms page.
        tw.Write("<table><tr>");  
                                                                                                                            

// If the ButtonType is set to ButtonIcons, iteratively create and render buttons
// to the web forms page.
    
     if( ButtonType == NavigatorButtonType.ButtonIcons )
   {
                    for( int i = 0; i < IconNavButtons.Count; i++ )
                    {

// Write the first table cell tag.
        tw.Write("<td>");  

// Instantiate an image button.
               ImageButton b = (IconNavButtons[i] as ImageButton); 

// Render the button on the web page.
                        b.RenderControl(tw); 

// Write the closing table cell tag.
      tw.Write("</td>");  
                    }
   }
  else
        
        // If the ButtonType is something other than ButtonIcons, iteratively create and 
  // Render default navigation buttons to the web forms page. 

      {
    for( int i = 0; i < NavButtons.Count; i++ )
          {

// Write the first table cell tag.
        tw.Write("<td>");  

// Instantiate a button.
              Button b = (NavButtons[i] as Button); 

// Render the button on the web page.
              b.RenderControl(tw); 

// Write the closing table cell tag.
     tw.Write("</td>"); 
          }
   }

// Write the closing row and table tags.
 tw.Write("</tr></table>"); 

// Render the Panel end tag.
 FPanel.RenderEndTag(tw);    
 return sw.ToString(); 
    }
}

Modify Hidden Field Registration

The DB Web Control Library file includes a call to register a hidden field, which identifies the key for a read-write control. If you are creating a read-only control, you can remove or comment out this call. The call is as shown in the following sample:

Copy Code

Page.RegisterHiddenField(DBWebDataSource.IdentPrefix + 
DBWebConst.Splitter + IDataLink.TableName, self.ID);

Set Data Binding on Specific Properties

If you need other properties data bound, other than the Text property, you can add that data binding code in the same location where you find that the Text property is being bound. Typically, there is a call to DataBind in the PreRender method. The DataBind procedure itself is similar to the following sample, taken from the DBWebLabeledTextBox control source code. You can see in the following code that a number of properties are set after checking to see if the FColumnLink (from the IDBWebDataColumnLink interface) is bound to some data source.

Copy Code

public override void DataBind()
{
    try
  {
    FTextBox.ReadOnly = FReadOnly;
    FTextBox.ID = this.ID;
        base.DataBind();
    ClassUtils.SetBehaviorProperties(FPanel, this);
    ClassUtils.SetOuterAppearanceProperties(FPanel, this);
    ClassUtils.SetSizeProperties(FPanel, this);
       if( !ClassUtils.IsEmpty(FLabel.Text) )
            {
                ClassUtils.SetInnerAppearanceProperties(FLabel, this);
              SetProportionalSize();
           SetLabelFont();
           FTextBox.Text = null;
           }

  // If there is a data source.
            if( IColumnLink.DBDataSource != null ) 
                {

// And if there is bound data.
                    if( FColumnLink.IsDataBound )  
                    {

// Then set behavior properties.
                        ClassUtils.SetBehaviorProperties(FTextBox, this); 

// Set appearance properties. 
                          ClassUtils.SetAppearanceProperties(FTextBox, this); 

 // Set size properties.
                          ClassUtils.SetSizeProperties(FTextBox, this);      
                          object o = IColumnLink.DBDataSource.GetColumnValue(Page, IColumnLink.TableName, IColumnLink.ColumnName);

// If the page and the table and column names are not null, 
// it means there is already bound data. 
//  Put the string representation of the page, table, and
// column names into the textbox.       
                    if( o != null ) 
                                                                                    
                            FTextBox.Text = Convert.ToString(o);


                    else

// Otherwise, clear the textbox and bind it and 
// its properties to the specified column.                                                                                  
                            FTextBox.Text = "";  
                        FTextBox.DataBind();
    }
}