SharePoint 2010 Dialog Framework

In MOSS 2007 werd de gebruiker voor elke actie naar een andere pagina gestuurd. In de nieuwe versie van SharePoint, 2010, is veel gedaan om de user interactie te verbeteren en de gebruiker in de context te houden van de pagina waar hij/zij zich bevindt. Met de Dialog Framework in combinatie met het Client Object Model is Microsoft erin geslaagd om het aantal roundtrips sterk naar beneden te halen. Dat dit een positieve invloed heeft op de performance kan je je wel voorstellen.

Introductie

In Windows SharePoint Services (WSS) 3.0, of te wel de teamsites stond "bol" van de infomatie en linkjes waar gebruikers gebruik van konden maken. Wanneer er op een link wordt geklikt werd de gebruiker via een redirect naar een andere pagina genavigeerd.  

figuur 1: User Interface in de teamsites van WSS 3.0
 

In SharePoint Foundation (de nieuwe naam voor WSS 4.0) is dit veranderd. Onder andere door de introductie van de Ribbon die de buttons/acties toont afhankelijk van de context waarin de gebruiker zich bevindt.

figuur 2: Ribbon geeft aan welke functies beschikbaar zijn op basis van de context waarin de gebruiker zicht bevindt.

Een tweede nieuwe feature is de Dialog Modal Window. Wanneer er bijvoorbeeld op "add new discussion" wordt geklikt, krijgt de gebruiker een scherm te zien waar de informatie staat om een nieuw item te voegen. Dit zonder een round trip naar de server. De gebruiker blijft dus in de context, geen flikkerende schermen en wanneer de gebruiker de informatie heeft opgeslagen en het venster heeft gesloten staat het nieuwe item (of gewijzigde item) in de lijst.

figuur 3: Toevoegen van items via een ModalWindow.
 

De Dialog Framework laadt de content in een iframe binnen een floating div. Doordat de rest van de pagina uitgegrijst is en niet toegankelijk, wordt de suggestie gegeven dat het om een Modal Window gaat. Al is het geen "nieuw" scherm. Echter kan je de pagina niet verlaten zonder het "scherm" af te sluiten.

Je kunt het scherm oppakken en binnen de browser verplaatsen. Ook is het mogelijk om het scherm de volledige grootte van de browser te geven.

Dialog Framework gebruiken

Het is mogelijk om zelf ook gebruik te maken van het Dialog Framework. Hiervoor is een JavaScript API ter beschikking gesteld. De content van de iFrame kan een pagina zijn (url) of een DOMelement.  Let wel, als je een DOMElement gebruikt, let dan op dat na het sluiten van de ModalDialog venster je de waarde van het DOMElement kwijt bent. Je zult zelf hiervoor iets moeten schrijven als je deze waarde zou willen bewaren.

Er kunnen parameters meegegeven worden aan het venster als title, width, height etc.

Mocht je een pagina (url) willen gebruiken en deze pagina wordt bijvoorbeeld ook gebruikt voor andere sites/doeleinden kan het zijn dat de pagina navigatie-elementen of controls bevat die je in een ModalDialog niet wilt laten zien. Ook hier is over nagedacht. Door de CSS class "s4-notdlg" te gebruiken voor deze elementen worden deze niet getoond wanneer de pagina wordt geladen in het dialoogvenster.
De default masterpage van SharePoint gebruikt deze class al. Dus mocht je de pagina meerdere keren willen gebruiken (binnen SharePoint als _layouts page bijvoorbeeld en als Dialog venster) dan wordt de navigatie elementen alvast voor je gestript.

figuur 4: application page als pagina met de default master page.

figuur 5: dezelfde pagina geladen in een Dialog window

SP.UI.ModalDialog.showModalDialog()

Als je het ModalDialog venster wilt gebruiken in je oplossing kan dit door de showModalDialog() methode aan te roepen.

listing 1: Javascript openen Dialog venster op basis van een url

listing 2: Javascript openen dialog venster op basis van een DOMElement

Aan deze methode kan je parameters mee geven in de vorm van "options". Deze settings bestaat o.a. uit:
html: hier kan het DOMElement meegegeven worden
url: te openen pagina. Aan deze pagina kunnen ook parameters meegegeven worden zodat er dynamisch informatie meegestuurd worden.  Bijvoorbeeld de items uit een list of een list name.
widht: als de breedte wordt meegegeven maar niet de hoogte wordt de hoogte berekend op basis van de pagina.
height: als er geen breedte maar wel een hoogte mee wordt gegeven wordt de breedte automatisch uitgerekend. Wanneer er geen breedte of hoogte wordt meegegeven bepaald de opmaak van de pagina/DOMelement de hoogte/breedte van het Dialog venster.
title: titel van de pagina
allowMaximize: (boolean) geeft aan of het venster de grootte van de browser aan mag nemen.
showClose: (boolean) geeft aan of het sluit knop (rechtsboven) van het venster getoond mag worden. Indien deze niet wordt getoond dien je zelf het afsluiten van het venster te regelen.
dialogReturnValueCallback: Wellicht de belangrijkste optie. Dit geeft aan wat er moet gebeuren wanneer het venster gesloten is. Dit kan een aanroep zijn naar een callback functie.  Een callback functie kan er als volgt uit zien:

listing 3: call back functie met een redirect naar een andere pagina

listing 4: call back functie die de pagina verververst zonder een full postback door de SP.UI.DialogResult.OK als parameter mee te geven.

listing 5: call back functie met die de DOMElement weer terugplaatst op het scherm.

Zoals je in de listings kunt zien kan de callbackfunctie 2 waarden meekrijgen. Deze komt mee vanuit de showModalDialog() methode. De dialogResult bestaat uit de waarde vanuit de enumeration SP.UI.DialogResult.OK, SP.UI.DialogResult.cancel of SP.UI.DialogResult.invalid.

De returnValue is van het type SP.UI.ModelDialog. Je kan deze waarden ook zelf zetten door de commonModelDialogClose() methode te gebruiken.

lising 6: Eigen code bij sluiten van het dialog venster

Omdat de showModalDialog() methode onderdeel is van het SharePoint 2010 Client Object Model is het overal te gebruiken. Of het nu een button is in de Ribbon, een custom button in een Virtual Web Part of vanuit een ander control. Meer informatie over de Dialog Framework is te vinden op de msdn site http://msdn.microsoft.com/en-us/library/ff408909(v=office.14).aspx

Echter de documentatie is daar nog minimaal. Het is dan ook zeker de moeite waard om naar de SP.UI.Dialog.debug.js file te kijken om door te hebben wat de opties en andere methoden doen. Deze file is te vinden onder {SharePointRoot}\TEMPLATE\LAYOUTS\

... en dan nu aan de slag!

Laten we eens kijken of we deze theorie in een demo kunnen laten zien. Voor deze demo wordt een vergelijking gemaakt van een aantal produkten, auto's in dit geval. Door een aantal foto's te selecteren en op "compare" te klikken verschijnt er een dialog window met daarin de details van de gekozen auto's zodat deze vergeleken kunnen worden.
(oh en voor de volledigheid... de content komt van de site Business week: http://images.businessweek.com/ss/07/11/1116_milliondollar_cars/index_01.htm)

We beginnen met het maken van een button in de Ribbon. Daarvoor maken we eerst een lege SharePoint project aan in Visual Studio 2010. Omdat we de ribbon aanpassen maken we er een Farm Solution van en gaan we de Dialog Framework gebruiken door middel van een page url. De vergelijkingspagina die we voor deze demo maken is een application page. Hiervoor zijn ook andere/betere scenario's denkbaar.

Voor de foto's gebruiken we een documentlibrary en in de contextual tab van de document library, die getoond wordt wanneer er documenten zijn geselecteerd zetten we een button die de "compare" dialoog venster gaat openen.

Aanmaken button met ShowModalDialog functie

Na het maken van een empty SharePoint project in Visual Studio 2010 maken we een een Empty Element aan. Dit doe je door in het menu te kiezen voor Project --> Add new Item --> Empty Element.

figuur 6: toevoegen button - Empty Element

In de Elements.xml zet je de volgende code:

Listing 7: code voor het toevoegen van een button

In Listing 7 zie je de definitie van de button (CommandUIDefinition). Hierin staat een Command die verwijst naar de CommandUIHandler. In de CommandUIHandler wordt de "onclick" command van de button afgehandeld. In de CommandAction staat de client code die uitgevoerd wordt als het event afgaat.  In dit voorbeeld wordt een Dialog Framework scherm geopend. Deze pagina zullen we verderop in dit artikel aanmaken.

Aan deze pagina worden de Id's van de geselecteerde foto's meegegeven samen met de GUID van de lijst. Deze variabelen zullen we op de pagina gebruiken om de te tonen informatie op te halen.

Wanneer het dialoogvenster wordt afgesloten wordt er een notificatie getoond. ("You just compared some cars!")

Wanneer er op de button wordt geklikt ziet de URL van Dialog window er als volgt uit:

Aanmaken Application Page

Voeg een application page toe aan het project door via Project --> Add new item --> Application Page. Deze application page wordt automatisch in de Layouts folder geplaatst. Deze folder is gekoppeld aan de _layouts folder in de SharePointRoot (14-hyve).
In deze demo geven we de pagina de naam Compare.aspx.

Op deze pagina zetten we een DataList waarop we de content gaan plaatsen.
In de pageLoad() lezen we eerst de carID's uit en de GUID van de lijst.

In onderstaande codelisting zie je dat er door de carId's wordt geittereerd en hiermee een datatable wordt gevuld die als DataSource dient voor de DataList.

NB: de code is niet compleet en alleen voor demo. Zoals je ziet wordt er niet gecontroleerd of de velden in de lijst wel bestaan. Als ze niet bestaan zal dit leiden tot een foutmelding.

Listing 8: Compare.aspx.cs uitlezen van de CarId's en de bijbehorende informatie uit de lijst halen.

Het resultaat...

We hebben een lijst met plaatjes en informatie over een aantal dure auto's. We selecteren er een aantal die we met elkaar willen vergelijken:

Figuur 7: Selecteren van documenten en de "Compare Cars" button

Wanneer op de "Compare Cars" button is geklikt opent het Modal Dialog Window en worden de geselecteerde auto's getoond in het scherm.

figuur 8: Tonen van de geselecteerde auto's in de Dialog Window

Wanneer het Dialog Window wordt afgesloten verschijnt er een notificatie. Deze notificatie verdwijnt vanzelf na 5 seconden.

Figuur 10: Wanneer het dialoogvenster wordt afgesloten wordt er een notificatie getoond. ("You just compared some cars!")

Conclusie

Met de komst van SharePoint 2010 is het Microsoft gelukt om van de populaire portal een volwassen produkt te maken. De user interface en daarmee gebruikersvriendelijkheid heeft een belangrijke rol gespeeld bij deze nieuwe versie. Als ontwikkelaar kan je de user experience handhaven met dezelfde out of the box functionaliteit die Microsoft biedt binnen SharePoint zelf. Het Dialog Framework is "slechts" een onderdeel ervan. De Ribbon en Theming architectuur is zeker de moeite waard verder te bestuderen om eigen/custom oplossingen in dezelfde context te brengen als ShareP