Visual Basic Concepts

Using the DataRepeater Control

See Also

The DataRepeater control functions as a data-bound container of any user control you create. For example, imagine creating a user control that contains three TextBox controls, and a CheckBox control. This user control is designed to show one record of an employee database — displaying name, birth date, employee number, and marital status of the employee.

After compiling the control into an .ocx, the DataRepeater control's RepeatedControlName property is set to the user control. The DataRepeater is then bound to a data source, such as the ADO Data Control, which sets up a connection between the user control and the employee database. At run time, the DataRepeater displays several instances of the user control—each in its own row, and each bound to a different record in the database. The result can resemble the figure below.

Employee Records Repeated in DataRepeater Control

At run time, the user can scroll through a recordset using the HOME, END, PAGEUP, PAGEDOWN, and arrow keys.

Possible Uses

Creating a Data-bound User Control for use in the DataRepeater Control

The first step when using the DataRepeater control is to create a data-bound user control. The procedure below creates a simple control that can be repeated in the DataRepeater.

For More Information   Details about creating a data-bound user control can be found in "Binding a Control to a Data Source."

Creating a data-bound User control for use in the DataRepeater Control

  1. Create a new ActiveX Control project.

  2. In the Properties window, rename Project1 to ProductsCtl.

  3. In the Properties window, rename UserControl1 to ctlProducts.

  4. Add two TextBox controls and two Label controls to the form, and set their properties as shown in the table below.
    Object Property Setting
    Text1 Name txtProductName
    Text2 Name txtUnitPrice
    Label1 Caption Product Name
    Label2 Caption Unit Price

    Because the user control will be repeated, you may want to minimize its height; the simple user control described above looks like this:

  5. Add the code below to the control to create Let and Get properties of the user control. 
    Public Property Get ProductName() As String
    ProductName = txtProductName.Text
End Property

Public Property Let ProductName(ByVal newProductName As String)
    txtProductName.Text = newProductName
End Property

Public Property Get UnitPrice() As String
    UnitPrice = txtUnitPrice.Text ' Return a String!
End Property

Public Property Let UnitPrice(ByVal newUnitPrice As String)
    txtUnitPrice.Text = newUnitPrice ' NewUnitPrice is a String!
End Property

Private Sub txtProductName_Change()
    PropertyChanged "ProductName"
End Sub

Private Sub txtUnitPrice_Change()
    PropertyChanged "UnitPrice"
End Sub

    Important   Notice in the above code that the UnitPrice property is declared as a string. This is to allow the user of the DataRepeater control to use the DataFormat object to format the string as Currency. If you type the new value as Currency (what you might expect), the formatting supplied by the DataFormat object will be stripped.

  6. Use the Procedure Attributes dialog box to make the properties data-bound.

    On the Tools menu click Procedure Attributes. On the Procedures Attributes dialog box, click Advanced. The Name box contains the property you want to make data-bound, and should contain ProductName. Click Property is data bound, then click Show in DataBindings collection at design time. Click the Name box and click UnitPrice. Once again, click Property is data bound, then click Show in DataBindings collection at design time. Click OK to close the dialog box.

  7. Using the Windows Explorer, create a new folder on your hard disk named ProductsCtl.

  8. On the File menu click Save Project. Save the project in the new folder using the names provided in the dialog boxes.

  9. On the File menu click Make ProductsCtl.ocx. Save the .ocx to the same folder.

When you compile the user control into an .ocx, Visual Basic registers the control for you, allowing you to use it in the DataRepeater control.

Using the Data-bound User Control in the DataRepeater Control

Once you have built and compiled a data-bound user control, you can have it repeated in the DataRepeater control.

Using a data-bound user control in the DataRepeater control

  1. Create a new Standard Exe project.

  2. Set the following properties for the project and form:
    Object Property Setting
    Project1 Name prjRepeater
    Form1 Name frmRepeater

  3. Add the DataRepeater control and ADO Data Control to the Toolbox.

    On the Project menu, click Components. In the Components dialog box, click the Controls tab, and check Microsoft Data Repeater Control and Microsoft ADO Data Control. Click OK to close the dialog box.

  4. Draw a DataRepeater control on the form. Make the control large enough to accommodate several "rows" of the control you want to repeat. One "row" is the height of the repeated control, as determined by the size of the UserControl object's designer.

  5. Draw an ADO Data Control on the form, beneath the DataRepeater control.

  6. Click the ADO Data Control to select it. Then, on the Properties window, click the ConnectionString property. Using the ConnectionString dialog box, create a connection string that accesses the Northwind database.

  7. On the Properties window, click Source, and type the following SQL statement: 
    SELECT * FROM Products
  8. Click the DataRepeater control to select it. On the Properties window, click DataSource, and click ADODC1 to set the data source.

  9. In the Properties window, click RepeatedControlName to display a drop-down list of all controls available on the computer. On the list, click ProductsCtl.ctlProducts. The selected control will be repeated in the DataRepeater control.

Binding the User Control Properties to the ADO Data Control

Once the user control is contained by the DataRepeater control, you must bind the user control's properties to the record source.

  1. Right-click the DataRepeater control, and then click DataRepeater Properties. On the Property Pages dialog box, click the RepeaterBindings tab.

  2. Click the PropertyName box to display a drop-down list of the data-bound properties of the repeated control. Click ProductName.

  3. Click the DataField box to display a drop-down list of available data fields from the data source. Click ProductName.

  4. Click the Add button to add the pair of property and data field to the RepeaterBindings collection.

  5. Repeat steps 2 through 4 for the remaining property (UnitPrice).

  6. Click the Format tab.

  7. In the Format Item box, click UnitPrice.

  8. In the Format Type box, click Currency. In the Symbol box, select a currency character appropriate to your country.

  9. Click OK to close the dialog box.

  10. Press F5 to run the project. You can then use the scroll bar to scroll through the recordset, or click the ADO Data Control's navigation buttons.

Setting Public Properties Affect only the Current Control

When creating a user control to be used in a DataRepeater control, be aware that public properties of the control will be set only on the current control (the "live" control with the focus). For example, if you expose the Font property of a user control, at run time, resetting that property (as shown in the example code below) will only affect the current control in the DataRepeater control. The font of repeated controls will not be affected.

Private Sub Command1_Click()
   ' Only the current control's Font will be affected.
   DataRepeater1.RepeatedControl.FontName = "Courier"
End Sub

To actually change the font for every control, you must expose the Font object's Name property as a public property of the contained control:

Public Property Get FontName() As String  
   FontName = txtProductName.Font.Name
End Property
Public Property Let FontName(ByVal newFontName As String)
   txtProductName.Font.Name = newFontName
End Property