I den här genomgången ska vi skapa en AjaxControlToolkit Extender som man hakar på en TextBox. När användaren skriver in ett datum i något av de tillåtna formaten kommer datumet att formateras om till ett angivet format. Om användaren skriver in "070519" kommer det att formateras om till "2007-05-19". Detta sker på klienten utan något anrop till webbservern.

För att kunna göra detta måste du ha laddat ner och installerat ASP.NET 2.0 AJAX Extensions 1.0 och ASP.NET AJAX Control Toolkit från http://ajax.asp.net/downloads/.

Länk till projektet finns längst ner

Klientkoden – översikt

Microsoft har utökat Date-proptotypen med metoden Date.parseLocale(value, validFormats) som givet en sträng returnerar ett datum om värdet matchade något av de angivna formaten. De har också utökat med en format(displayFormat) metod för att formattera ett datum.

Med dessa två metoder har vi allt vi behöver. Genom att hantera change-eventet på en input-textbox får vi reda på när dess värde ändrats. När värdet ändrats skickas det till parseLocale som antingen returnerar null, eller ett datum. Om ett datum returneras så formatteras det med format och den resulterande strängen åker tillbaka till input-textboxen.

Nytt Ajax Control Project

Börja med att skapa ett nytt ASP.NET AJAX Control Project. (File > New > Project. Välj Visual C# och under My Templates välj ASP.NET AJAX Control Project). Ge projektet ett valfritt namn, t.ex. DateParser. Ett nytt projekt sätts upp med tre filer: DateParserBehavior.js, DateParserDesigner.cs och DateParserExtender.cs. (Dessa filer kan du även få i ett befintligt projekt genom att högerklicka på projektet och välja Add New Item och sen välja ASP.NET AJAX Control.)

En extender består av en server del, DateParserExtender.cs, och en klientdel, DateParserBehavior.js. Genom att sätta properties i server-kontrollen kan vi påverka hur klientdelens beteende ska vara. Den tredje filen är en designer-klass men den behöver man sällan in och peta i.

Det första man måste göra när man lagt till en ny extender är att verifiera att javascript-filen kommer att bäddas in som en resurs. Kolla att propertyn Build Action är satt till Embedded Resorce.
Javascript file, Build Action: Embedded Resource

Om du glömmer att bädda in den som en resurs kommer du att få ett meddelande om att resursen inte finns när du försökèr köra applikationen.

Serverkontrollen

DateParser Extendern (i DateParserExtender.cs) ska ha två properties: ValidFormats och DisplayFormat för att man ska kunna ange tillåtna format samt hur det formatterade datumet ska se ut. DateParserExtender.cs utgör själva server-kontrollen och den ärver av ExtenderControlBase från AjaxControlToolkit. Inledningsvis innehåller vår nya kontroll en property; MyProperty som fungerar som en mall för hur properties ska skrivas.

[ExtenderControlProperty]
[DefaultValue("")]
public string MyProperty
{
  get
  {
      return GetPropertyValue("MyProperty", "");
  }
  set
  {
      SetPropertyValue("MyProperty", value);
  }
}

Attributet ExtenderControlProperty signalerar att det här är en property vars värde ska ner till klienten. Om attributet saknas kommer värdet aldrig att föras över till Behaviorn (man kan alltså ha "vanliga" properties vars värden inte direkt påverkar klient-beteendet).

DefaultValue-attributet har att göra med hur koden för att skapa den här kontrollen ska se ut (och ligger utanför detta ämne) och ska sättas till propertyns defaultvärde.

För att hämta och sätta värden används metoderna GetPropertyValue resp. SetPropertyValue. I samband med att man hämtar värdet anger man det värde som ska gälla ifall propertyn inte har satts tidigare. Se till att det motsvarar DefaultValue-attributet.

Våra properties blir då alltså:

private const string _Default_ValidFormats = "yyMMdd;yyyyMM;ddyyyy-MM-dd;yy-MM-dd;yyyyMM-dd;yyyy-MMdd;yyMM-dd;yy-MMdd;dd MMM yyyy;MM/dd/yy;MM/dd/YYYY";
private const string _Default_DisplayFormat = "yyyy-MM-dd";

[ExtenderControlProperty]
[DefaultValue(_Default_DisplayFormat)]
public string DisplayFormat
{
  get
  {
      return GetPropertyValue("DisplayFormat", _Default_DisplayFormat);
  }
  set
  {
      SetPropertyValue("DisplayFormat", value);
  }
}

[ExtenderControlProperty]
[DefaultValue(_Default_ValidFormats)]
public string ValidFormats
{
  get
  {
      return GetPropertyValue("ValidFormats", _Default_ValidFormats);
  }
  set
  {
      SetPropertyValue("ValidFormats", value);
  }
}

Vi använder konstanter för defaultvärdena för att se till att attributet och GetPropertyValue använder samma värde (sen är det dessutom snyggare att göra så och vi gillar ju att skriva snygg kod). Då var serverdelen klar.

Klientens Behavior

En behavior kan ses som en klass. Den har en konstruktor, där dess privata variabler definieras; den har properties; publika och privata metoder samt en initialize och en dispose-metod. När en behavior skapas körs först konstruktorn, eventuell properties från servern sätts, varpå initialize körs. I initialize bygger man upp det som behaviorn behöver för att fungera, registrerar events, etc. När behaviorn ska tas bort körs dess dispose-metod. Här avregistrerar man sig från event och rensar upp efter sig. Observera att dispose kan komma att anropas flera gånger så det gäller att se till att koden klarar det.

Properties

Även filen DateParserBehavior.js innehåller lite exempelkod för att visa hur den ska kodas. En property på klientsidan består av tre delar: en privat variabel som skapas i konstruktorn högt upp i filen, en get-metod och en set-metod som man använder för att sätta värdet på propertyn. Så för propertyn MyProperty så skriver man inte obj.MyProperty="value"; istället gör man anropet obj.set_MyProperty("value");.

Så för våra properties behöver vi två variabler för att hålla deras värden. Vi anger också default-värden.

DateParser.DateParserBehavior = function(element) {

  DateParser.DateParserBehavior.initializeBase(this, [element]);

  // Property variables
  this._displayFormat = "yyyy-MM-dd";
  this._validFormats = "yyMMdd;yyyyMMdd;yyyy-MM-dd;yy-MM-dd;yyyyMM-dd;yyyy-MMdd;yyMM-dd;yy-MMdd;dd MMM yyyy;MM/dd/yy;MM/dd/YYYY";
}

Efter dispose-metoden lägger vi in get- och set-metoderna

dispose : function() {
// TODO: add your cleanup code here

DateParser.DateParserBehavior.callBaseMethod(this, 'dispose');
},

// Properties ------------------------------------------------
get_DisplayFormat : function() {
 return this._displayFormat;
},
set_DisplayFormat : function(value) {
 this._displayFormat = value;
}, 


get_ValidFormats : function() {
 return this._validFormats;
},
set_ValidFormats : function(value) {
 this._validFormats = value;
}

De privata variablerna (signaleras med att de börjar med ett understreck) kan namnges som man vill men namnen på get- och set-metoderna måste motsvara server-kontrollens properties. Eftersom vi har en ExtenderControlProperty-markerad property i server-kontrollen som heter ValidFormats måste vi även ha en get_ValidFormats och en set_ValidFormats metod på klienten.

ParseDate, sträng till datum

Innan vi skriver kod för eventhanteringen behöver vi en hjälpmetod för att anropa Date.parseLocale(value,formats). Se mitt tidigare inlägg om varför detta behövs.

_parseDate : function(value,formats)
{
//Create an array that initially will contain value.
//Add the elements from formats after the value.
var args=[value];
Array.addRange(args,formats);

//args contains now: [value, formats[0], formats[1], ... ]  
//Call the parseLocale method using our args array as parameters
return Date.parseLocale.apply(Date,args);
}

Uppdatera inputboxen

Metoden som kommer att anropas när eventet change höjs:

_updateTargetElement : function()
{
var targetElement = this.get_element();
var value=targetElement.value;
if(value)
{
  var parsedDate = this._parseDate(value,this._validFormatsArr);
  if(parsedDate)
  {
    targetElement.value=parsedDate.format(this._displayFormat);
  }
  //Else, on parse error, do nothing.
}
}

Metoden börjar med att ta reda på vårt targetElement, dvs. vår inputbox, genom att anropa metoden get_element() (en metod vi ärvt från vår basklass). Om värdet har satts, försök att tolka det som ett datum. Om vi lyckades tolka det som ett datum, formattera det enligt specificerat format och uppdatera inputboxens value. Det enda som behöver en förklaring är den privata variabeln this._validFormatsArr.

Tillåtna format som array

Vi anger formatet som en semikolonseparerad sträng av godkända format, t.ex. "yyyyMMdd;yyMMdd". Strängen kommer vi att göra om till en array ["yyyyMMdd","yyMMdd"] och det är alltså det this._validFormatsArr innehåller. Vi deklarerar den i konstruktorn ihop med de andra.

    // Property variables
  this._displayFormat = "yyyy-MM-dd";
  this._validFormats = "yyMMdd;yyyyMMdd;yyyy-MM-dd;yy-MM-dd;yyyyMM-dd;yyyy-MMdd;yyMM-dd;yy-MMdd;dd MMM yyyy;MM/dd/yy;MM/dd/YYYY";

  // Internal variables
  this._validFormatsArr=null;

Arrayen fylls i Initialize-metoden.

initialize : function() {
DateParser.DateParserBehavior.callBaseMethod(this, 'initialize');

this._validFormatsArr=this._validFormats.split(";");
},

Event-hantering

Det sista som återstår är att registrera en eventhanterare för inputboxens change-event. Mönstret för event består typiskt av fyra delar (ibland vill man göra på andra sätt men det är överkurs):

Skapa en funktion för eventhantering
Deklarera en privat variabel i konstruktorn som kommer att innehålla en delegat (kan betraktas som en funktionspekare) för din eventhanterare.
I initialize skapar man delegaten och registrerar den på eventet.
I dispose avregistrerar man delegaten från eventet och sätter den privata variablen till null.

I vårt exempel blir det då så här.

Skapa en funktion för eventhantering

//Event handlers -----------------------------------------------
_onValueChange : function(e)
{
this._updateTargetElement();
}

Deklarera en privat variabel i konstruktorn som kommer att innehålla en delegat (kan betraktas som en funktionspekare) för din eventhanterare.
```
//Event handlers
this._valueChangeHandler=null;
```

I initialize skapar man delegaten och registrerar den på eventet.

initialize : function() {
DateParser.DateParserBehavior.callBaseMethod(this, 'initialize');

var targetElement = this.get_element();

this._validFormatsArr=this._validFormats.split(";");

//Register Event handlers
this._valueChangeHandler = Function.createDelegate(this, this._onValueChange);
$addHandler(targetElement, 'change', this._valueChangeHandler);
},

I dispose avregistrerar man delegaten från eventet och sätter den privata variablen till null.

dispose : function() {
//Reminder: Might be called several times.

var targetElement = this.get_element();

if (this._valueChangeHandler)
{
  $removeHandler(targetElement, 'change', this._valueChangeHandler);
  this._valueChangeHandler = null;
}

DateParser.DateParserBehavior.callBaseMethod(this, 'dispose');
},

Sisådär då borde allt vara klart för en testtur.

Testprojekt

För att kunna testa behöver vi en testsajt. Lägg till en ny Ajax-webbsajt (File > Add > New Web Site ... > ASP.NET AJAX-enabled Web site). Lägg till en referens till vår DateParser (högerklicka på webbsajten i Solution Explorer och välj Add Reference > Projects > Date Parser > OK).

Öppna default.aspx och dra in en TextBox från toolboxen. Växla till source-läge och lägg till följande direktiv ovanför DOCTYPE-raden för att göra vår extender tillgänglig på sidan:

<%@ Register tagprefix="myExtenders" Namespace="DateParser" Assembly="DateParser" %>

Nedanför TextBox1 lägger du till:

<myExtenders:DateParserExtender ID="TextBox1Extender"
 runat="server" TargetControlID="TextBox1" />

Sätt webbprojektet till att vara startprojekt och kör igång genom att trycka F5. Om allt fungerar som det ska, ska du kunna mata in 070519 i rutan, trycka tab och det formatteras om till 2007-05-19. Om du missat att säga till att JavaScript-filen ska bäddas in som en resurs är det nu du kommer att få ett felmeddelande om att resursen saknas i assembly:t.

Om du vill byta datumformat är det bara att göra det på DateParserExtendern:

<myExtenders:DateParserExtender ID="TextBox1Extender"
 runat="server" TargetControlID="TextBox1"
 DisplayFormat="MMM ddd dd yyyy" ValidFormats="yyMMdd" />

Dessa format kan du använda: http://msdn2.microsoft.com/en-us/library/bb79761a-ca08-44ee-b142-b06b3e2fc22b.aspx

För att slippa lägga till ett register-direktiv på alla sidor kan du lägga till följande i Web.Config.

<system.web>
<pages>
  <controls>
<add tagPrefix="asp" namespace="System.Web.UI" assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
<add tagPrefix="myExtenders" namespace="DateParser" assembly="DateParser"/>
</controls>
</pages>

En bra sak att alltid lägga in i sina behaviors är en metod för att trigga beteendet. Om beteendet är att poppa upp en ruta när något händer, lägg till en metod som poppar upp den. I vårt fall behöver vi en metod för att parse:a inputboxen och formattera om den, så vi lägger till följande publika metod:

//Public Methods -----------------------------------------------
updateTargetElement : function()
{
 this._updateTargetElement();
}

Metoder som denna gör det möjligt att via kod trigga ett beteende och det är ibland väldigt praktiskt. Tyvärr är det något de flesta AjaxControlToolkit Extenders saknar.

Ladda ner projektet

Hocke - Tankar, tutorials, tips och tricks

2007-05-20

Skapa en AjaxControlToolkit Extender