Re: SingleControl
By default, UserControlRenderer creates an intermediary Container and put a user control to its ContentControls.
Let's consider an example.
Page
<%@ Page Language="C#" %>
<%@ Register Assembly="Ext.Net" Namespace="Ext.Net" TagPrefix="ext" %>
<script runat="server">
protected void RenderUserControl(object sender, DirectEventArgs e)
{
UserControlRenderer.Render(new UserControlRendererConfig()
{
Element = this.Panel1.ClientID,
UserControlPath = "TestUC.ascx",
Mode = RenderMode.AddTo
});
}
</script>
<!DOCTYPE html>
<html>
<head runat="server">
<title>Ext.NET v2 Example</title>
</head>
<body>
<form runat="server">
<ext:ResourceManager runat="server" />
<ext:Button runat="server" Text="Render User Control" OnDirectClick="RenderUserControl" />
<ext:Panel
ID="Panel1"
runat="server"
Title="Panel"
Height="200"
Layout="FitLayout" />
</form>
</body>
</html>
User Control
<%@ Control Language="C#" %>
<ext:Container runat="server" Html="User Control" StyleSpec="background-color: yellow;" />
If you run it, you will see that the Panel1's FitLayout doesn't affect the Container inside the user control. It is because there is an intermediary Container between them. So, the Panel1's FitLayout affects that intermediary Container which has no layout itself.
A developer can set up SingleControl="true" (or ControlIdToRender) to avoid that intermediary Container. In other words, a developer can define an intermediary Container himself if there are several controls to render, not just the only one.
But an intermediary Container is required in a general case, because a user control can look like this one:
User Control
<%@ Control Language="C#" %>
<script>
alert("Hello!");
</script>
<asp:Panel runat="server">
ASP.NET Panel
</asp:Panel>
<ext:Container runat="server" Html="User Control" StyleSpec="background-color: yellow;" />
Generally speaking, the SingleControl option is quite out-of-date, becase now there is this setting.
With this setting the UserControlRender will extract all the Ext.NET controls (top level) from the user control and render it without an intermediary Container.
Though, we keep SingleControl to avoid making a breaking change just removing that.
Re: UserControlRenderer vs UserControlLoader
I said that the UserControlRenderer cannot retrieve Ext.NET controls from a user control, but I just forgot about the "Items = true" option. So, it is not the benefit of UserControlLoader and you can use UserControlRenderer reliably.
Re: getting the user control in the BeforeRender handler
void cfg_BeforeRender(ComponentAddedEventArgs args)
{
UserControl uc = ((args.Control as Container).ContentControls[0]) as UserControl;
}
Honestly, I don't know where this class is documented well enough to understand all all the variations and how it can be properly used.
The lack of good docs is one of our main problems. We apologize for the inconveniece. Hopefully, my explanation helps a bit.