Controls 101: Repeating sections

Applies to
Microsoft Office InfoPath™ 2003 Service Pack 1 or later

In InfoPath, the text boxes and other graphical objects on a form are called controls. Controls let people enter, view, or otherwise specify information on their forms. In this article, you'll learn about a useful InfoPath control called a repeating section (repeating section: A control on a form that contains other controls and that repeats as needed. Users can insert multiple sections when filling out the form.), which can help you provide users with a more flexible, interactive form. In particular, this article explores the following topics:

Why use a repeating section?

The user experience

Design considerations

The data source

Customization options

Related controls

Why use a repeating section?

A repeating section is useful when you need to collect or display multiple instances of the same type of data.

Imagine an insurance application form in which applicants must list the names and ages of their dependents. In a paper version of this form, you might see three placeholder fields, which assumes that most people have three or fewer dependents. Those who have more than three dependents would be forced to squeeze information about additional dependents under the existing fields or write on the back of the form.

In an InfoPath version of this form, you can use a repeating section so that applicants can easily add as many dependents as necessary. The following illustration shows how this might look to the person filling out the form.

Shortcut menu overlapping repeating section on form

With repeating sections, you can avoid empty placeholder areas that take up critical space on your form. This results in a more efficient, polished design.

You can also use repeating sections to display variable amounts of data on a form. For example, if your form is connected to a database of employee records, you can use a repeating section to display matching records when a user queries the database from within InfoPath. If one record is returned, the user sees only one section on the form; if 10 records are returned, the user sees 10 sections.

Here are more ways to use repeating sections in your forms:

  • In a sales report, you can use a repeating section to collect sales objectives from your sales team.
  • In a purchase order, you can use a repeating section to gather office supply orders from employees.
  • In a medical form, you can use a repeating section to collect the medical history for each relative in a patient's family.

The user experience

When users move the pointer over a repeating section, a small blue button, called the shortcut menu button, appears in the upper-left corner of the section.

Shortcut menu button for repeating section

When users click this button, a shortcut menu appears. This menu contains commands for inserting, removing, cutting, copying, or pasting the section. Users can also insert sections in other ways. For example, users can quickly insert a section by pressing CTRL+ENTER on their keyboard or by clicking the Insert item text that appears by default under the section. Depending on how the form was designed, users also might be able to insert or remove a section by clicking a custom command on one of the main program menus, such as the Insert or Edit menu.

Design considerations

When you design a form from scratch, you can click Repeating Section in the Controls task pane to insert a repeating section into your form. The following illustration shows how the repeating section looks after you first insert it.

Empty repeating section in design mode

In design mode (design mode: The InfoPath design environment in which you can create or modify a form template.), you see a single, empty repeating section into which you can insert text boxes or other controls. When users fill out the form, they can add as many copies of this section as necessary.

The gray border around the repeating section is a design aid that users won't see when they fill out the form. However, you can add a visible border if you want.

Before you insert controls into the repeating section, think about how you want to arrange those controls. You can add controls in a freeform fashion by dragging them into the section wherever you want. Or, if you want more control over the layout, you can add a layout table (layout table: A collection of cells used to arrange form content such as text or controls.) inside the repeating section, and then insert labels and controls inside the individual cells so that they align nicely.

Controls inside layout table in repeating section

 Note   If you want users to be able to add multiple rows to a table, rather than multiple sections to the form, you can use a repeating table (repeating table: A control on a form that contains other controls in a table format and that repeats as needed. Users can insert multiple rows when filling out the form.) instead of a repeating section. For more information about repeating tables, see the Related controls section at the end of this article.

As you design your repeating section, keep the following in mind:

Don't nest too many sections    It's possible to nest repeating sections — that is, insert one repeating section inside another. This can be a useful way to collect separate sets of related data. For example, in a medical form, you can use a repeating section to collect personal information about each patient in a clinical trial. Inside that repeating section, you can insert another repeating section to record the patient's medications. However, too many levels of nesting can complicate your design, making it hard for users to decide exactly where they should click in the form in order to insert the correct section.

Create visual interest     By default, the borders around repeating sections are invisible to users filling out the form. As a result, users see only the controls inside the section when they open your form. To visually separate a repeating section from the text and controls surrounding it, or to simply draw users' attention to the section, you can use the Borders and Shading dialog box to add borders or color to the repeating section.

Test your design thoroughly    Before distributing your form to others, be sure to test your repeating section. If you customized the menu commands on the repeating section's shortcut menu, open the shortcut menu and check for typos and consistency. If your form contains nested sections, move the pointer over each section in the InfoPath preview window. If you have trouble figuring out where to click because of competing icons and shortcut menus, your users probably will, too.

The data source

The data source, which stores all the data entered into a form, is made up of fields and groups that appear in a hierarchical view in the Data Source task pane. Repeating sections are usually bound (bind: To connect a control to a field or group in the data source so that data entered into the control is saved. When a control is unbound, it is not connected to a field or group, and so data entered into the control will not be saved.) to groups. Groups contain fields in the same way that repeating sections contain controls.

The structure of the data source must match the layout of the repeating section. In other words, if a text box is inside a repeating section, the field that the text box is bound to must be part of the group that the repeating section is bound to. For example, in the following illustration, the Last name text box in the Dependents repeating section is bound to the LastName field in the Dependent group.

Relationship between text box in form and field in data source

If you design a new, blank form, InfoPath automatically creates the data source for you as you add repeating sections and other controls to your form.

If you base the design of your form on an existing Extensible Markup Language (XML) (Extensible Markup Language (XML): A condensed form of Standard Generalized Markup Language (SGML) that enables developers to create customized tags that offer flexibility in organizing and presenting information.) file, database, or Web service, InfoPath derives the fields and groups in the Data Source task pane from that data source. In this scenario, you can insert a repeating section by dragging a repeating group (repeating group: A group in the data source that can occur more than once. Controls such as repeating sections and repeating tables are bound to repeating groups.) from the Data Source task pane onto the form. If you choose to insert a repeating section from the Controls task pane instead, InfoPath prompts you to bind the control to a repeating group or field in the data source.

 Note   Avoid moving a control that is already on the form into a repeating section, unless the control's field is already part of the repeating section's group in the data source. Otherwise, the binding for the control may break, and the information a user enters into that control cannot be saved.

Customization options

Like other InfoPath controls, you can customize a repeating section by changing its properties. To access the Repeating Section Properties dialog box, double-click the repeating section in design mode. From this dialog box, you can do the following things.

Customization Details
Change field or group name On the Data tab, you can change the default field or group name to something that is easier to identify when working with the data source. For example, in the insurance form mentioned earlier in this article, you can change "group3" to "Dependent."
Prevent users from inserting and deleting the sections On the Data tab, the Allow users to insert and delete the sections check box is selected by default. If you clear the check box, users won't be able to insert or delete the section. This is useful in reporting scenarios where you want to display repeating data but you don't want users to change that data or add more sections.
Customize menu commands In the Customize Commands dialog box, accessed from the Data tab, you can customize the names and locations of the menu commands used to insert or remove sections in your form. This type of customization makes your form easier to use. For example, you can add custom commands to the Edit menu for removing sections.
Edit default values In the Edit Default Values dialog box, accessed from the Data tab, you can specify default values for one or more controls in a repeating section. You can specify both the initial values of a section when a form is opened and the values of a section when it is first inserted by a user.
Show or customize hint text On the Data tab, the Show insert button and hint text check box is selected by default. You can clear this check box if you don't want users to see instructional text on the form, or you can customize the instructional text. For example, you can change "Insert item" to "Insert additional dependent."
Apply rules In the Rules dialog box, accessed from the Data tab, you can use rules to apply actions when users insert or work with controls inside the repeating section.
Add conditional formatting In the Conditional Formatting dialog box, accessed from the Display tab, you can change the appearance of a control, including its visibility, based on values entered into the form. For example, you might choose to hide a section unless a specific check box is selected.
Filter data In the Specify Filter Conditions dialog box, accessed from the Display tab, you can enable users to filter data in a repeating section, based on values that the user enters or selects elsewhere on the form. For example, if you use a repeating section to collect information about current projects, you can design a list box that allows users to filter projects by status.
Set up a master/detail relationship On the Master/Detail tab, you can establish a master/detail relationship between a repeating table (the master control) and a repeating section (the detail control). If you set up this type of relationship, related data will appear in the repeating section whenever a user selects an item in the repeating table.
Adjust size

On the Size tab, you can adjust the height and width of a repeating section.

 Note   If you want to change the default width at which InfoPath inserts repeating sections, you can adjust that setting on a view-by-view basis in the View Properties dialog box, which is accessible from the Format menu. You might do this, for example, if you are optimizing a view for printing and the repeating section is cut off when the form is printed.

Adjust padding On the Size tab, you can change the amount of space between the repeating section and any surrounding text.
Adjust margins On the Size tab, you can specify the amount of space between the controls inside the repeating section and the boundary of the repeating section.
Change tab index order On the Advanced tab, you can change the position of the repeating section in the form's overall tab order (tab order: The order in which the focus moves in a form from one field or object to the next as you press TAB or SHIFT+TAB.).
Specify a ScreenTip On the Advanced tab, you can add an explanatory note to the repeating section, which appears when a user moves the pointer over the section on the form.
Find programming information

On the Advanced tab, you can find the xCollection value, which is useful if you want to use the InfoPath object model (object model: A hierarchical library of objects and collections that represents the content and functionality of an application. Objects and collections have properties, methods, and events that can be used to manipulate and interact with an application.) to further customize a repeating section.

ShowTechnical details

You can use the DOM property of the XDocument object to access the XML Document Object Model (DOM) implemented by Microsoft XML Core Services (MSXML) 5.0 to work directly with the form's underlying data, or you can use the ExecuteAction method of the View object to execute InfoPath editing actions on the repeating section's data. To use the ExecuteAction method, you specify an xCollection action, such as "xCollection::insert" or "xCollection::removeAll", and the xmlToEdit name, which identifies the particular xCollection to work with. The xCollection value for a repeating section appears on the Advanced tab in the Repeating Section Properties dialog box.

For example, you could add a button to your form named "Remove All" and have it remove all of the repeating section items by using an ExecuteAction method call such as the following:

("xCollection::removeAll", "group2_1");

For more information about the InfoPath object model, press F1 to open Help, and then click Table of Contents. In the table of contents, click InfoPath Developer's Reference, and then click InfoPath Object Model Reference.

 Note   If you based the design of your form on a database, schema, or other existing data source, you may not be able to customize all aspects of a repeating section. For example, you may be able to change the size of the repeating section but not its group name, which is derived from the existing data source.

Related controls

InfoPath includes other controls that are similar to repeating sections but serve different purposes. To decide which of these controls works best on your form, refer to the following list:

Repeating table    If you want users to be able to add multiple rows to a table, consider using a repeating table instead of a repeating section. For example, you can present itemized data, such as invoice items, in a table format so that users can add additional rows to the table as necessary. Ultimately, using a repeating table instead of a repeating section is a matter of preference; both controls allow you to collect or display multiple instances of the same type of data.

Section    Sections are used to organize groups of related controls. If you use a section instead of a repeating section, users can't add additional sections to their form.

Repeating choice group    Choice groups contain two or more sections. By default, one of these sections appears on the form. Users can choose to replace it with a different section. Choice groups can also repeat — that is, be inserted in a form multiple times by the user.

Repeating recursive section    Like a repeating section, a repeating recursive section can be inserted multiple times in a form. When users insert multiple instances of a repeating section, each new section is inserted beneath the preceding section, one after the other. With a repeating recursive section, however, each new section is inserted within an existing section, resulting in a set of nested sections. This is useful when you want to create hierarchical content, such as an outline.

Optional section    If you add a repeating section to your form, it will always appear in the form when a user first opens it. Optional sections, on the other hand, are hidden by default. They let your users choose whether to include a particular section in the form. For example, in a purchase order form, some users may want to comment on the supplies that they plan to order. You can insert an optional section and add a rich text box labeled "Notes" inside that optional section. Users can choose to add the optional section if they need it by clicking instructional text beneath the optional section.

List control    List controls are the simplest type of repeating control and are useful when you want users to be able to add as many items as necessary to a bulleted, numbered, or plain list. For example, you can use a bulleted list control to collect multiple action items in an issues list.

Master/detail control    A master/detail control is a set of two related controls. The master control is always a repeating table. The detail control can be either a repeating table or a repeating section. You can use the master/detail control to link one control to another, so that the selection in the first control determines what appears in the second control.

Applies to:
InfoPath 2003