LearnNowOnline

Blog

Create Child Controls - Microsoft SharePoint 2010

Excerpt by Doug Ware | December 27, 2013

Most web controls that have visual elements compose other controls into a greater whole. Every web control contains a Controls collection property that contains the controls of which it is composed. The controls in the Controls collection are called child controls because a page is easily visualized as a tree of controls with the page as the root. Each node of the tree can have zero or more children. Use the CreateChildControls to instantiate any child controls that your web control contains.

The first two things that happen when ASP.NET renders a page are the initialization and loading of each node of the tree. The next thing that happens is the loading of state into each node of the tree so that the tree correctly represents any user input. State is stored in a hidden form field named __VIEWSTATE and its contents are used to rehydrate a page between postbacks. The loading of ViewState works only if ASP.NET is able to match each node in the current rendering with the previous version-the one with which the user interacted and submitted input. Consider the following code snippet:

public class MyWebPart : WebPart { //Instantiate the button Button myButton = new Button(); protected override void CreateChildControls() { //Configure the button btnMyButton.Width = new Unit(50, UnitType.Pixel); btnMyButton.Text = _buttonText; btnMyButton.Click += new EventHandler(btnMyButton_Click); //Add it to the controls collection Controls.Add(btnMyButton); } }

  If you ran this code in ASP.NET 2.0, perhaps on a WSS 3.0 or MOSS 2007 site, the Web Part would render a button 50 pixels wide without error. However, the event handler will not fire when a user clicks the button because the MyWebPart class creates a new instance of the Button class each time it initializes. The myButton variable then references a new button. When the ViewState loads to indicate that the user clicked a button, the new button has replaced the original button in the tree and the event doesn't fire. Here's the correct way to write this code:

 public class MyWebPart : WebPart { //Declare the button Button myButton = null; protected override void CreateChildControls() { //Instantiate the button myButton = new Button(); //Configure the button btnMyButton.Width = new Unit(50, UnitType.Pixel); btnMyButton.Text = _buttonText; btnMyButton.Click += new EventHandler(btnMyButton_Click); //Add it to the controls collection Controls.Add(btnMyButton); } }

  In this example, you are still creating a new instance each time-ASP.NET is stateless after all, but the timing of the operation allows the page rendering infrastructure to correctly associate the button with its state when it adds the button to the Controls collection. When working with the page rendering life cycle, timing is everything. ASP.NET 3.5, the basis of SharePoint Foundation, is more forgiving in this regard. However, unless you know that your custom Web Part will never run in an older version of ASP.NET, it is a best practice to follow the simple rule-create your child controls inside CreateChildControls.

This post is an excerpt from the online courseware for our Microsoft SharePoint 2010 for Developers course written by expert Doug Ware.