Web user control (ascx)

Kontrolka użytkownika (web user control) jest komponentem, który działa bardzo podobnie do zwykłej strony ASP.NET. Elementy, metody oraz akcje definiuje się zupełnie identycznie. Różnica jest taka, że kontrolki ascx umieszcza się na stronach aspx. Jest to świetny sposób na zgromadzenie w oddzielnym pliku współpracujących ze sobą kontrolek, a co za tym idzie odseparowanie ich zdarzeń od pozostałej logiki. Artykuł ten opisuje, jak w łatwy i szybki sposób zbudować i następnie korzystać z dwóch kontrolek użytkownika: UpDownControl oraz DatePickerControl. Do ich stworzenia wykorzystałem jQuery UI oraz AjaxControlToolkit. Pominąłem opis konfiguracji i deklaracji skryptów z tychże bibliotek.

W pierwszej kolejności zdefiniowałem strukturę kontrolki ascx, na którą składają się następujące elementy:

TextBox – pole do wpisywania wartości,
NumericUpDownExtender – rozszerzenie z AjaxControlToolkit pozwalające inkrementować i dekrementować wartość z pola tekstowego po kliknięciu w kontrolkę,
Input – dwa pola HTML typu przycisk do inkrementacji i dekrementacji,
RangeValidator – kontrolka do walidacji wpisanej wartości.

Definicja pliku ascx, a co za tym idzie struktura kontrolki, przedstawiała się następująco:

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="UpDownControl.ascx.cs"
	Inherits="WebUserControl.Controls.UpDownControl" %>

<table border="0" cellpadding="0" cellspacing="0">
	<tr>
		<td rowspan="2">
			<asp:TextBox ID="tbValue" runat="server" Width="35px"></asp:TextBox>
			<ajx:NumericUpDownExtender ID="nudValue" runat="server" TargetControlID="tbValue"
				TargetButtonDownID="downValue" TargetButtonUpID="upValue" />
		</td>
		<td>
			<input type="button" runat="server" id="upValue" value="▲" style="border: 1px outset;
				font-family: Tahoma,Arial,sans-serif; font-size: 5pt; font-weight: bold; line-height: 1em;
				height: 10px; width: 24px;" />
		</td>
		<td rowspan="2" style="padding-left: 5px;">
			<asp:RangeValidator ID="rvValue" runat="server" 
				ControlToValidate="tbValue" Display="Dynamic" Type="Double" 
				ErrorMessage="Wartość wykracza poza przedział">*</asp:RangeValidator>
		</td>
	</tr>
	<tr>
		<td>
			<input type="button" runat="server" id="downValue" value="▼" style="border: 1px outset;
				font-family: Tahoma,Arial,sans-serif; font-size: 5pt; font-weight: bold; line-height: 1em;
				height: 10px; width: 24px;" />
		</td>
	</tr>
</table>

Od strony kodu zdefiniowałem szereg publicznych właściwości, które udostępniły mi funkcjonalność w plikach aspx:

#region Properties

public double Value
{
	get { return double.Parse(tbValue.Text); }
	set { tbValue.Text = value.ToString(); }
}

public int MaxLength
{
	get { return tbValue.MaxLength; }
	set { tbValue.MaxLength = value; }
}

public Unit Width
{
	get { return tbValue.Width; }
	set { tbValue.Width = value; }
}

public double MinValue
{
	get { return nudValue.Minimum; }
	set { nudValue.Minimum = value; rvValue.MinimumValue = value.ToString(); }
}

public double MaxValue
{
	get { return nudValue.Maximum; }
	set { nudValue.Maximum = value; rvValue.MaximumValue = value.ToString(); }
}

public double Step
{
	get { return nudValue.Step; }
	set { nudValue.Step = value; }
}

public string ValidationGroup
{
	get { return rvValue.ValidationGroup; }
	set { rvValue.ValidationGroup = value; }
}

#endregion

Wykorzystanie kontrolki na dowolnych stronach ASP.NET sprowadza się tylko do rejestracji oraz deklaracji kontrolki:

<%@ Register src="~/Controls/UpDownControl.ascx" tagname="UpDownControl" tagprefix="uc" %>
<%-- ... --%>
<uc:UpDownControl ID="udTest" runat="server" MaxLength="1" MinValue="1" MaxValue="7" Value="3" />

Efekt jest następujący:

Do budowy DatePickerControl wykorzystałem:

JavaScript – funkcja wywołująca kalendarz z jQuery UI,
TextBox – pole do wpisania daty,
Image – ikonka do wywoływania kalendarza,
MaskedEditExtender – rozszerzenie z AjaxControlToolkit narzucające format wpisywanej daty.

Struktura pliku ascx oraz kod źródłowy przedstawiają się jak poniżej:

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="DatePickerControl.ascx.cs"
	Inherits="WebUserControl.Controls.DatePickerControl" %>

<script type="text/javascript">
	function dpinit(ctrl) {
		var year = new Date().getFullYear();

		ctrl.datepicker({
			changeYear: true,
			firstDay: 1,
			yearRange: (year - 80).toString() + ':' + (year + 10).toString(),
			showButtonPanel: false,
			showWeek: false,
			dateFormat: 'yy-mm-dd',
			firstDay: 1,
		}).focus();

		return ctrl;
	}
</script>

<asp:TextBox ID="tbDate" runat="server" Width="70px" />
<asp:Image ID="iCalendar" runat="server" ImageUrl="~/App_Themes/Def/cal.png" AlternateText="Kalendarz" />
<ajx:MaskedEditExtender ID="meDate" runat="server" TargetControlID="tbDate" MaskType="Date"
	Mask="9999/99/99" />

public string DateString
{
	get { return tbDate.Text; }
	set { tbDate.Text = value; }
}

public DateTime? Date
{
	get { DateTime temp; if (DateTime.TryParse(tbDate.Text, out temp)) return temp; else return null; }
	set { tbDate.Text = value.HasValue ? value.Value.ToString("yyyy-MM-dd") : string.Empty; }
}

protected void Page_Load(object sender, EventArgs e)
{
	iCalendar.Attributes["onclick"] = string.Format("javascript:dpinit($('#{0}'));", tbDate.ClientID);
}

Wykorzystanie oraz efekt końcowy kontrolki DatePickerControl:

<%@ Register Src="~/Controls/DatePickerControl.ascx" TagName="DatePickerControl" TagPrefix="uc" %>
<%-- ... --%>
<uc:DatePickerControl ID="dpTest" runat="server" DateString="2012-12-12" />

Kontrolki użytkownika są niedocenianym oraz ignorowanym bogactwem technologii ASP.NET. Dlatego też zachęcam do tworzenia własnych kontrolek ascx, ponieważ dają one duże możliwości oraz znacząco przyspieszają proces implementacji modułów aplikacji webowej.