Using a UserControl

No capítulo anterior nós criamos um UserControl, e agora tentaremos utilizá-lo pela primeira vez. Escolha uma página em seu projeto, ou simplesmente crie uma nova para isso, e abra-a. A primeira coisa que temos que fazer, é declarar nosso UserControl. Isto pode ser feito tanto em cada página onde será utilizado, ou globalmente no arquivo web.config. Não há diferença de desempenho, mas quando declaramos UserControls no arquivo web.config, os controle precisam estar em uma pasta diferente que as páginas os utilizando se encontram.

Por enquanto, vamos apenas declará-lo dentro da página. Adicione as seguintes linhas após as declarações padrão da página:

<%@ Register TagPrefix="My" TagName="UserInfoBoxControl" Src="~/UserInfoBoxControl.ascx" %>

Certifique-se de que o valor de src esteja igual ao caminho do seu arquivo UserControl. Agora você pode utilizar o UserControl em sua página, como qualquer outro controlador. Por exemplo, assim:

<My:UserInfoBoxControl runat="server" ID="MyUserInfoBoxControl" />

Se você olhar a página agora, verá o nosso UserControl em ação, apesar de que a informação será um pouco... limitada. Nós teremos que colocar um valor para a propriedade que definimos, para as coisas ficarem um pouco mais interessantes. Felizmente, é muito fácil:

<My:UserInfoBoxControl runat="server" ID="MyUserInfoBoxControl" UserName="John Doe" UserAge="45" UserCountry="Australia" />

Perceba que cada membro público ou protegido pode ser acessado de forma declarada, permitindo fácil acesso à eles quando usamos nosso controle. Porém, com este UserControl específico, há chances de que você receberá informações(ou dados) de uma fonte externa, como um Banco de Dados, e então popular o UserControl com estes dados. Isto geralmente envolve o CodeBehind da página, então como podemos fazer isto? É muito simples, na verdade. No CodeBehind da página, tente algo assim:

protected void Page_Load(object sender, EventArgs e)
{
    // These values can come from anywhere, but right now, we just hardcode them
    MyUserInfoBoxControl.UserName = "Jane Doe";
    MyUserInfoBoxControl.UserAge = 33;
    MyUserInfoBoxControl.UserCountry = "Germany";
}

Carregando dinamicamente

Às vezes você quer adicionar UserControls à sua página dinamicamente, ao invés de declará-los. É bem simples também. Você pode de um controle existente onde você possa adicionar o UserControl, em um Panel por exemplo. Se não há controles lógicos em sua página para adicionar, você pode criar um para este fim - o controle PlaceHolder é para este tipo de situações.

Em sua página, defina desta forma:

<asp:PlaceHolder runat="server" ID="phUserInfoBox" />

No CodeBehind da página, adicionar o controle assim:

phUserInfoBox.Controls.Add(LoadControl("~/UserInfoBoxControl.ascx"));

Nós usamos o método LoadControl para instanciar o UserControl especificando o caminho. Isto é muito fácil, mas também é anônimo - porque apenas usamos o método LoadControl, nós não podemos usar nosso próprio, com propriedades personalizadas. Para fazer isto, precisamos fazer o .NET ficar sabendo disto. Na página, adicione a seguinte declaração no topo do código:

<%@ Reference Control="~/UserInfoBoxControl.ascx" %>

Agora nós podemos acessar a classe UserInfoBoxControl como se fosse uma classe normal, o que também significa que podemos usar typecast no UserControl retornado pelo método LoadControl deste tipo. No próximo exemplo, nós fazemos exatamente isto, então nós setamos as propriedades e, por fim, adicionamos ao PlaceHolder:

UserInfoBoxControl userInfoBoxControl = (UserInfoBoxControl)LoadControl("~/UserInfoBoxControl.ascx");
userInfoBoxControl.UserName = "John Doe";
userInfoBoxControl.UserAge = 78;
userInfoBoxControl.UserCountry = "Spain";
phUserInfoBox.Controls.Add(userInfoBoxControl);

Isto será útil quando, por exemplo, você estiver adicionar várias instâncias do mesmo UserControl a uma única página, porque você pode fazer isto dentro de um loop.