ASP.net AJAX en DotNetNuke
In de sessie over DotNetNuke en AJAX tijdens het SDE van december heb ik kort laten zien hoe ASP.net AJAX toegepast kan worden in custom modules voor DotNetNuke. Naar aanleiding van vragen en opmerkingen na de sessie ontstond het idee om in het magazine wat dieper op deze materie in te gaan. Dit artikel beoogt derhalve een stap voor stap handleiding te zijn voor het gebruiken van ASP.net AJAX in DotNetNuke modules.
Custom module: een module die niet vast in DotNetNuke is opgenomen, maar los te installeren is in iedere DotNetNuke installatie.
Achtergrond
AJAX (Asynchronous Javascript And Xml) is de naam die gekozen is voor de techniek waarmee in een webapplicatie niet steeds een pagina in zijn geheel wordt ververst, maar alleen dat deel dat wijzigt. Het voornaamste voordeel van het toepassen van deze techniek is dat een webapplicatie in de beleving van de gebruiker sneller zal reageren en daardoor veel gebruiksvriendelijker is.
Wanneer geen AJAX wordt toegepast, wordt vanuit de browser direct een postback naar de webserver uitgevoerd. Op de webserver wordt dit request verwerkt met als resultaat een volledig opnieuw opgebouwde HTML pagina. Dit resultaat wordt naar de browser gestuurd die vervolgens de pagina zichtbaar maakt voor de gebruiker.
Request: een verzoek van de gebruiker dat door de webserver verwerkt moet worden.
Postback: een actie van de gebruiker die, na verwerking op de webserver, leidt tot het volledig opnieuw opbouwen van een pagina in de browser van de gebruiker.
Callback: een actie van de gebruiker die, na verwerking door de webserver, leidt tot het bijwerken van slechts een deel van een pagina in de browser van de gebruiker.
Wanneer wel AJAX wordt toegepast, wordt de actie van de gebruiker afgehandeld in de browser, meestal met behulp van Javascript. Vanuit deze Javascript-code wordt, net als in het klassieke model, een callback naar de webserver gedaan. Echter, het resultaat van dit request zal nu worden afgevangen en verwerkt door diezelfde Javascript code. De verwerking zal zorgen dat een deel van de pagina wordt bijgewerkt, zonder dat de hele pagina opnieuw moet worden opgebouwd voor de gebruiker. ASP.net AJAX zorgt ervoor dat deze Javascript-code niet door de ontwikkelaar hoeft te worden geschreven of aangepast: het wordt automatisch gegenereerd door ASP.net AJAX controls.
Benaderingen
Er zijn verschillende manieren denkbaar om ASP.net AJAX toe te passen in een DotNetNuke module. De meest voor de hand liggende manier is om het geheel binnen de module te implementeren. Daarmee heeft de ontwikkelaar volledige controle over het gebruik van ASP.net AJAX in de module.
Er kan ook worden gekozen om ASP.net AJAX te implementeren op het niveau van de container. Bij deze benadering maakt een module pas gebruik van ASP.net AJAX wanneer de juiste container is gespecificeerd binnen DotNetNuke. Alle zogenaamde postbacks vanuit de module worden automatisch als callback uitegvoerd.
Container: een container maakt deel uit van de “skin” (het uiterlijk, de layout) van DotNetNuke. De Skin bepaalt hoe een volledige pagina wordt getoond, de Container bepaalt hoe een enkele module wordt getoond.
In dit artikel zal alleen de eerstgenoemde benadering worden beschreven. Voor de tweede benadering is in de weblog van Jon Henning informatie te vinden, op: http://www.dotnetnuke.com/default.aspx?Tabid=825&EntryID407
Uitgangssituatie
Voordat er daadwerkelijk met ASP.net AJAX kan worden begonnen moet er aan enkele voorwaarden voldaan zijn:
- Visual Web Developer Express Edition of Visual Studio 2005 (hierna VS2005) is geïnstalleerd op het systeem;
- Er is een SQL Server beschikbaar (mag een andere server zijn);
- DotNetNuke is geïnstalleerd; het handigst is het om hiervoor de Startkit te gebruiken.
- ASP.net AJAX is geïnstalleerd op het systeem (te downloaden vanaf http://www.asp.net/)
Wanneer aan deze voorwaarden is voldaan, moeten nog enkele kleine aanpassingen aan de DotNetNuke website in VS2005 worden gedaan:
- Voeg aan DotNetNuke een referentie toe naar de ASP.net AJAX assembly.
- Registreer de ASP.net AJAX HTTPHandler in de HTTPHandlers sectie van web.config:
type="Microsoft.Web.Handlers.ScriptResourceHandler"
validate="false"/>
- Wijzig het element xhtmlConformance in web.config in:
Starterkit: na installatie voegt de DotNetNuke starterkit enkele onderdelen toe aan VS2005. De belangrijkste is het template “DotNetNuke Web Application Framework” in het “New Web Site”scherm. Van http://www.dotnetnuke.com/ is deze starterkit te downloaden en in het (eveneens te downloaden) document “DotNetNuke Installation Guide” staat beschreven hoe de starterkit gebruikt wordt. Binnen enkele minuten is de installatie gerealiseerd.
ASP.net AJAX assembly: dit is de DLL van ASP.net AJAX waarnaar een referentie moet bestaan om in een website-project gebruik te kunnen maken van ASP.net AJAX. Rightclick hiervoor in VS2005 in het Solution Explorer window op de DotNetNuke website (dit is het bovenste element) en selecteer “Add Reference”. Selecteer vervolgens op het tabje “Browse” het bestand Microsoft.Web.Extensions.dll in de directory
%Program Files%\Microsoft ASP.NET\ASP.NET 2.0 AJAX Extensions\v1.0.61025 en click OK.
HTTPHandlers sectie: het web.config bestand van DotNetNuke maakt reeds gebruik van een httpHandlers sectie. Deze sectie begint met het element . Direct na dit element kunnen bovenstaande regels worden toegevoegd.
xhtmlConformace: voor geïnteresseerden is de reden voor het gebruiken van de zogenaamde Legacy modus door DotNetNuke hier gedocumenteerd:
http://forums.asp.net/thread/1239671.aspx
Een module maken
Hierna wordt stap voor stap beschreven hoe een basale module gemaakt wordt welke gebruik maakt van ASP.net AJAX. Op die manier wordt een helder overzicht gegeven van het toepassen van ASP.net AJAX in een module. Hiervoor is wel een basis nodig aan kennis van DotNetNuke. In dit artikel zullen DotNetNuke-specifieke zaken zo veel mogelijk worden toegelicht. Voor het overige wijst de weg zich doorgaans vanzelf.
Stap 1
Om te beginnen moet er een directory worden aangemaakt waar DotNetNuke de Module Controls zal kunnen vinden. Creëer hiervoor in het Solution Explorer Window van VS2005 een nieuwe directory onder “DesktopModules”. Noem de directory “AjaxDemo”.
Module Controls: custom modules in DotNetNuke worden gerealiseerd in Web User Controls (.ascx bestanden). In DotNetNuke wordt geconfigureerd welke Module Controls bij welke Module horen. Alle Modules en Module Controls bevinden zich in de directory DesktopModules, direct onder de root van de DotNetNuke installatie.
Stap 2
Voeg in de nieuwe directory een nieuwe Web User Control toe. Noem het bestand AjaxDemo.ascx. Op dit moment is dit uiteraard nog geen DotNetNuke Module Control, maar een normale ASP.net Web User Control. Het verschil is echter niet groot. Een Web User Control overerft van de ASP.net klasse System.Web.UI.UserControl, terwijl een DotNetNuke Module Control de DotNetNuke klasse van DotNetNuke.Entities.Modules.PortalModuleBase overerft. Deze basisklasse vormt voor DotNetNuke de manier om met het control om te kunnen gaan.
In het codebestand van het nieuwe Web User Control moet derhalve
System.Web.UI.UserControl
worden veranderd in
Inherits DotNetNuke.Entities.Modules.PortalModuleBase
Stap 3
Om de nieuwe module binnen DotNetNuke te configureren is natuurlijk wel een menu-optie in DotNetNuke beschikbaar, maar de meest eenvoudige optie is het gebruik van een .dnn configuratiebestand.
.dnn configuratiebestand: voor superusers (normaal “Host”) is er via de menu-optie Host Module Definitions functionaliteit beschikbaar om een module binnen DotNetNuke bekend te maken. Alle opties die via die menu-optie instelbaar zijn, zijn ook via een xml bestand in te lezen. Een dergelijk bestand heeft de extensie “.dnn”.
Voeg in de “AjaxDemo” directory een tekstbestand toe (dat kan gewoon via de Solution Explorer) en noem dit “AjaxDemo.dnn”. Neem de volgende XML over als inhoud van het bestand:
AjaxDemo
AjaxDemo
AjaxDemo
AjaxDemo
A AjaxDemo module
01.00.00
AjaxDemo
0
DesktopModules/AjaxDemo/AjaxDemo.ascx
View
AjaxDemo.ascx
AjaxDemo.ascx.vb
In de Solution Explorer zal het resultaat er nu ongeveer als volgt uit zien:
Fig. 1: Solution Explorer
Stap 4
Op zich is het niet noodzakelijk om nu al de nieuwe module in DotNetNuke te configureren, maar om zeker te zijn dat alles tot nu toe gelukt is, kan dat geen kwaad. Klik hiervoor op “Run” in VS2005. Log vervolgens in als gebruiker “Host” en kies in het menu voor Host Module Definitions. Op dat scherm bevindt zich de functie “Create New Module”:
Fig. 2: Create New Module
Op het scherm “Create New Module” kan het bestand AjaxDemo.dnn worden gekozen uit een keuzelijst. Een klik op “Install” doet de rest: de module is nu geconfigureerd in DotNetNuke en kan op een pagina worden geïnstantieerd. Overigens zal de module nu vanzelfsprekend nog leeg zijn.
ASP.net AJAX gebruiken
De module werkt technisch, maar doet nog niets. Er moet nog functionaliteit aan worden toegevoegd. De opzet van dit artikel is een idee te geven van het verschil tussen het wel en niet toepassen van de AJAX techniek. Om dit verschil te illustreren worden de volgende User Interface elementen toegevoegd:
- een label dat alleen gevuld wordt bij een postback;
- een knop die een postback veroorzaakt;
- een UpdatePanel met daarin een Label en een knop.
UpdatePanel: dit is een ASP.net AJAX control. Alle controls die in dit panel worden geplaatst, worden bijgewerkt bij een AJAX callback. Een knop binnen een updatepanel veroorzaakt een callback.
Stap 5
De User Interface moet in het .ascx bestand worden gedefinieerd. Daarvoor moeten we een aantal dingen doen. Eerst moet in het .ascx bestand worden aangegeven dat de ASP.net AJAX controls gebruikt gaan worden:
<%@ Register Assembly="Microsoft.Web.Extensions,
Version=1.0.61025.0, Culture=neutral,
PublicKeyToken=31bf3856ad364e35"
Namespace="Microsoft.Web.UI" TagPrefix="asp" %>
Vervolgens moet de zogenaamde ScriptManager worden opgenomen. Deze ASP.net AJAX control zorgt voor het genereren van de juiste Javascript code. Zonder deze control op een pagina kan ASP.net AJAX niet functioneren:
En tot slot kunnen de eerder genoemde UI-elementen worden toegevoegd:
CssClass="SubHead" />
This is the updatepanel
CssClass="SubHead" />
Text="Button 1" OnClick="Button1_Click" />
Text="Button 2" />
Stap 6
De laatste stap is het toevoegen van code in het Form.Load event en in de Eventhandlers van de Click events van beide knoppen. Deze code bevindt zich in het bestand AjaxDemo.ascx.vb.
In het Form.Load event worden beide labels gevuld met de systeemdatum en –tijd wanneer de module voor de eerste keer wordt getoond. In de beide click-eventhandlers worden eveneens beide labels gevuld met de huidige systeemdatum en –tijd. Op deze manier kan goed het verschil worden bekeken tussen de controls binnen en buiten het updatepanel:
Protected Sub Page_Load(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Me.Load
If Not IsPostBack Then
Label1.Text = DateTime.Now.ToString()
Label2.Text = DateTime.Now.ToString()
End If
End Sub
Protected Sub Button1_Click(ByVal sender As Object, _
ByVal e As System.EventArgs)
Label1.Text = DateTime.Now.ToString()
Label2.Text = DateTime.Now.ToString()
End Sub
Protected Sub Button2_Click(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Button2.Click
Label1.Text = DateTime.Now.ToString()
Label2.Text = DateTime.Now.ToString()
End Sub
Het bewijs
Wanneer de module nu op een pagina in DotNetNuke wordt geïnstantieerd, dan zal het er ongeveer als volgt uit zien:
Fig. 3: De draaiende module
Het gele vlak markeert het UpdatePanel. Wanneer de pagina voor de eerste maal wordt geladen, zullen beide labels dezelfde waarden bevatten. Wanneer op “Button 1” wordt geklikt zal, hoewel in de code beide labels een nieuwe waarde krijgen, alleen de waarde van het label binnen het updatepanel worden bijgewerkt. Dat bijwerken gebeurt wel ogenschijnlijk direct. In ieder geval zonder volledige post, maar door een callback.
Wanneer op “Button 2” wordt geklikt, vindt er wel een volledige postback plaats en worden beide labels voorzien van een nieuwe waarde.
Conclusie
Ik denk dat dit artikel duidelijk maakt dat ASP.net AJAX, zeker voor degenen die al bekend zijn met DotNetNuke, eenvoudig kan worden gebruikt in DotNetNuke modules. Tegelijkertijd is het duidelijk dat over dit onderwerp, net als over DotNetNuke en ASP.net AJAX zelf, nog veel meer verteld kan worden. Hopelijk is dit artikel een goed uitgangspunt voor ontwikkelaars om zelf te gaan experimenteren met DotNetNuke, ASP.net AJAX en de combinatie van deze twee.