ContentQueryWebpart en custom XSLT Alles wat je moet weten over het CQW
1
Contents Voorkennis............................................................................................................................................... 3 Het CQW volgens Microsoft .................................................................................................................... 3 Algemene werking van het CQW ............................................................................................................ 3 Het werken met slots .............................................................................................................................. 4 DataMappings ..................................................................................................................................... 4 DataMappingsViewFields .................................................................................................................... 5 De XSLT .................................................................................................................................................... 5 Header.xsl ............................................................................................................................................ 5 ItemStyle.xsl ........................................................................................................................................ 6 ContentQueryMain.xsl ........................................................................................................................ 6 Header- en ItemStyle........................................................................................................................... 6 Stappenplan............................................................................................................................................. 7 Het CQW als user control ........................................................................................................................ 7 Interessante properties ........................................................................................................................... 8 WebUrl ................................................................................................................................................ 8 QueryOverride ..................................................................................................................................... 8 PlayMediaInBrowser ........................................................................................................................... 8 SuppressWebPartChrome ................................................................................................................... 8 UseCache ............................................................................................................................................. 9 GUID vs. Namen ...................................................................................................................................... 9
2
Voorkennis -
Bekend met het exporteren en importeren van webparts. Bekend met het feit dat de XML van geëxporteerde webparts gewijzigd kan worden. Bekend met de basis van XSLT. Basiskennis van het CQW i.c.m. de Header.xsl en ItemStyle.xsl van SharePoint
Het CQW volgens Microsoft Over het algemeen zal Microsoft weinig meer uitleggen dan hoe SharePoint standaard met het CQW omgaat. Dit is namelijk niet meer dan het configureren van je query en eventueel wat wijzigingen in de stylesheets van het webpart. Meer dan dat zal je zelden horen. Het is echter mogelijk om veel meer te tweaken dan deze standaard instellingen en files. Dit maakt het mogelijk om veel vrijer met je XSLT om te gaan, alles vanuit 1 bestand te gaan beheren en mooiere schone HTML en XSLT op te leveren.
Algemene werking van het CQW Het CQW is een webpart wat je op de pagina zet en kunt gaan configureren. Eigenlijk is het een grote querytool om allerlei overzichten uit SharePoint te halen. Denk hierbij aan lijsten uitlezen, of bibliotheken. Feitelijk bestaat alle SharePoint content uit lijsten en bibliotheken. Naast het uitlezen kan er ook gefilterd, gesorteerd en zelfs gegroepeerd worden. Onder water wordt een query opgebouwd als een zogenaamde CAML query en is het resultaat wat je terug krijgt een set aan XML. De XML ziet erin de meest eenvoudige vorm als volgt uit:
|
|
|
Via XSLT wordt deze XML omgetoverd tot HTML. Het CQW gebruikt hier drie XSLT bestanden voor: -
Header.xsl ItemStyle.xsl ContentQueryMain.xsl
Deze onderdelen komen ook weer terug in het webpart. Je kunt namelijk een bepaalde style kiezen voor de header en voor elk item die je terugkrijgt. In de Header staat, zoals de naam zegt, de header. De bovenkant van je resultaat. Als je iets als een tabel zou willen maken kan je de code daarvoor in de header kwijt. In de ItemStyle komt vervolgens te staan hoe elk item eruit moet zien. Indien je een nieuwlijstje maakt kan je dus opgeven welke eigenschappen je wilt tonen van elk item en hoe dit eruit moet zien.
3
In de ContentQueryMain komt alles samen en wordt omliggende HTML toegevoegd. Denk hierbij aan bijvoorbeeld de
als het om een lijstje gaat. Daarnaast bevat de ContentQueryMain diverse functies voor het opbouwen van een URL of iets dergelijks.
Het werken met slots In SharePoint 2010 is het werken met slots flink verbeterd. Dit is een van de belangrijkste punten om te begrijpen hoe SharePoint met het CQW en XSLT om gaat. Slots geven contentbeheerders de mogelijkheid om zelf kolomnamen in te vullen in de properties van het CWQ en zo de benodigde eigenschappen van elk item te bepalen. Als je een bepaalde ItemStyle kiest in het CQW dan krijg je diverse velden waar je kolomnamen kunt invullen (zie afbeelding rechts). In de velden vul je de kolomnamen in die in je lijst of bibliotheek staan. Voor een nieuwbericht kan dit bijvoorbeeld iets zijn als titel, afbeelding, samenvatting. Als je dit opslaat zal SharePoint dit gaan vertalen naar XML code zodat het CQW weet welke velden uit je bron bij welk stukje XSLT horen. En dat stukje is het meest interessant. Als je het CQW exporteert en opent in een editor zijn er twee properties van belang. De eerste is “DataMappings” en de tweede is “DataMappingsViewFields”.
DataMappings In deze property staat de mapping van de kolommen naar XSLT. Als je de inhoud ervan goed bekijkt dan zie je een hoop extra “rommel”. Dit komt omdat SharePoint standaard een x aantal velden hierin plaatst zoals het title veld. Dit is een verplicht veld voor elk item (wordt bij elke nieuwe lijst of bibliotheek aangemaakt). Verder worden de diverse velden die in de ItemStyle.xsl staan ook meegenomen. Daarnaast worden er diverse velden uit je bron meegenomen maar alleen als je deze ook in je XSLT hebt gekoppeld. Dit laatste moet nog verder worden uitgezocht. De complete code voor een kolom ziet er in dit property als volgt uit: [NaamVoorInXSLT:{GUID-van-kolom},KolomType,Kolomnaam;|
De puntkomma en | zijn er om het einde van een kolom te markeren. Een voorbeeld van het title veld wat een tekst veld is, is dan als volgt: Title:{fa564e0f-0c70-4ab9-b863-0177e6ddd247},Title,Text;|
Wat nu het belangrijkste is om te weten is dat het allereerste woord exact zo gebruikt moet worden in de XSLT. Indien daar een verschil tussen zit dan werkt de mapping van de kolomnaam naar je XSLT niet.
4
DataMappingsViewFields In deze property staan de velden die je zichtbaar wilt tonen aan de gebruiker. Indien je bron zes kolommen heeft waar je er twee van wilt laten zien, dan moeten die twee hier ingevuld worden. Daarbij is de notatie als volgt: {GUID-van-kolom},KolomType;
Een voorbeeld voor het title veld is dan: {fa564e0f-0c70-4ab9-b863-0177e6ddd247},Text;
De XSLT Zoals eerder genoemd zijn er drie bestanden die het CQW nodig heeft. Deze drie gaan we vervangen voor eigen varianten. De Header.xsl en ItemStyle.xsl vervangen we voor twee “lege”. Ze bevatten elk 1 style waar niks in gebeurd. In onze eigen ContentQueryMain.xsl gaan we alle logica opnemen om de gewenste HTML te maken. Indien je het webpart geëxporteerd hebt zijn er voor elk XSLT bestand twee plekken die aangepast moeten worden. In één property staan alle drie de bestanden genoemd. Daarnaast heeft elk XSLT bestand een eigen property. De aanpassingen die gedaan moeten worden in de XML van het webpart zijn dan ook als volgt: -
-
-
Voor de Header.xsl o Zoek naar het property “HeaderXslLink” en zet daar de locatie naar het XSLT bestand in. Dit is je eigen Header.xsl. LET OP: deze moet in de Style Library staan! o Zoek naar het property “Xsl”. Hier staan drie referentie naar de drie XSLT bestanden. Vervang de URL voor de Header.xsl naar de nieuwe. Voor de ItemStyle.xsl o Zoek naar het property “ItemXslLink” en zet daar de locatie naar het XSLT bestand in. Dit is je eigen ItemStyle.xsl. LET OP: deze moet in de Style Library staan! o Zoek naar het property “Xsl”. Hier staan drie referentie naar de drie XSLT bestanden. Vervang de URL voor de ItemStyle.xsl naar de nieuwe. Voor de ContentQueryMain.xsl o Zoek naar het property “MainXslLink” en zet daar de locatie naar het XSLT bestand in. Dit is je eigen ContentQueryMain.xsl. LET OP: deze moet in de Style Library staan! o Zoek naar het property “Xsl”. Hier staan drie referentie naar de drie XSLT bestanden. Vervang de URL voor de ContentQueryMain.xsl naar de nieuwe.
Om sneller te starten is er voor elke XSLT al een basis gemaakt waarbij alleen de ContentQueryMain.xsl verder uitgebreid kan worden.
Header.xsl <xsl:stylesheet version="1.0" exclude-result-prefixes="x d ddwrt xsl msxsl" xmlns:x="http://www.w3.org/2001/XMLSchema"
5
xmlns:d="http://schemas.microsoft.com/sharepoint/dsp" xmlns:ddwrt="http://schemas.microsoft.com/WebParts/v2/DataView/runtime" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt"> <xsl:template name="EmptyHeader" match="*" mode="header">
ItemStyle.xsl <xsl:stylesheet version="1.0" exclude-result-prefixes="x d xsl msxsl cmswrt" xmlns:x="http://www.w3.org/2001/XMLSchema" xmlns:d="http://schemas.microsoft.com/sharepoint/dsp" xmlns:cmswrt="http://schemas.microsoft.com/WebParts/v3/Publishing/runtime" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemasmicrosoft-com:xslt"> <xsl:template name="EmptyItem" match="Row[@Style='EmptyItem']" mode="itemstyle">
ContentQueryMain.xsl <xsl:stylesheet version="1.0" exclude-result-prefixes="x xsl cmswrt cbq" xmlns:x="http://www.w3.org/2001/XMLSchema" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:cmswrt="http://schemas.microsoft.com/WebPart/v3/Publishing/runtime" xmlns:cbq="urn:schemas-microsoft-com:ContentByQueryWebPart"> <xsl:output method="html" indent="no" media-type="text/html" /> <xsl:template match="/"> <xsl:for-each select="/dsQueryResponse/Rows/Row"> <xsl:value-of select="@Title" />
Header- en ItemStyle Hiervoor is besproken dat standaard de gebruiker van het CQW uit stylen kan kiezen. Dat principe kunnen we helaas niet loslaten. In de hiervoor genoemde voorbeelden van “lege” XSLT’s staat ook een stylenaam genoemd: EmptyItem en EmptyHeader. Ook deze moeten in de XML van het CQW ingevuld worden. Zoek hiervoor de volgende twee properties op en wijzig de inhoud ervan: -
ItemStyle voor de ItemStyle.xsl GroupStyle voor de Header.xsl
6
Stappenplan Een kort stappenplan om tot een eigen CQW te komen met mooie schone XSLT bestanden is ongeveer als volgt: 1. Plaats je CQW en configureer deze zodat je de gewenste resultaten terug krijgt. 2. Eventueel kun je in de ItemStyle.xsl van SharePoint een style maken met alle properties die je nodig hebt. Vul dan de velden in bij de slots zodat alle gewenste kolommen terug komen in je resultaten. 3. Exporteer het webpart. 4. Plaats een eigen (lege) Header.xsl, ItemStyle.xsl en ContentQueryMain.xsl ergens in de Style Library. 5. Wijzig de XML van het webpart zodat deze je nieuwe XSLT files gebruikt. Let hierbij ook op het toewijzen van de ItemStyle en de GroupStyle! 6. Zorg ervoor dat de benaming in je XSLT overeenkomt met degene die in de XML van je webpart staan. Dit kan je checken in het property “DataMappings”. Zie hierboven voor meer uitleg. 7. Upload je webpart naar de galerij en plaats deze opnieuw op een pagina. Je zou nu resultaten moeten zien en vanuit je ContentQueryMain.xsl alles kunnen doen.
Het CQW als user control Naast het plaatsen van het CQW als webpart kan deze ook gebruikt worden als user control, direct in masterpages of pagelayouts. Het voordeel hiervan is dat gebruikers dit niet kunnen verwijderen en dat je zo diverse componenten kunt maken met standaard SharePoint. Denk aan een submenu, slideshow of andere zaken. Om van een CQW een user control te maken moet je als eerste het webpart exporteren. Eventueel kun je eigen XSLT eraan koppelen zoals hiervoor beschreven staat. Nu gaat het erom dat je diverse properties gebruikt die minimaal nodig zijn om een CQW werkend te krijgen. Daar omheen komen enkele tags te staan om er een user control van te maken. Uiteindelijk is de minimale set ongeveer als volgt om het webpart werkend te krijgen:
LET OP: in bovenstaand voorbeeld zijn enkele basis properties van het CQW opgenomen. Hier moeten vervolgens nog diverse properties bij die samen te query vormen en resultaten opleveren. Denk hierbij aan bijvoorbeeld alle items van een bepaald content type of items uit een bepaalde lijst. In de XML van het webpart kun je al deze properties vinden. Lege properties die je tegenkomt in de XML van het webpart hoef je NIET mee te nemen. Daarnaast zijn er een hoop ingevulde properties. Deze hebben default waardes die niet wijzigen. Als je die niet meeneemt houden ze de default waarde. 7
Interessante properties Indien je het CQW als user control gaat gebruiken krijg je veel meer opties dan wanneer je het als webpart blijft gebruiken. We lichten een aantal properties nader toe en wat je er mee zou kunnen doen.
WebUrl De WebUrl is een van de properties waarmee je de bron kunt aangeven. Bijvoorbeeld: pak alle publishing pages van die ene site. Het CQW vult vervolgens de rest voor je in. Als je het webpart configureert heb je hier dan ook drie opties voor. Wat echter niet kan is dat je aangeeft alles van de huidige site te willen laten zien. Als user control kan dat wel. Je kunt bij deze property dan het volgende invullen: ~site
Het CQW zal vervolgens verder kijken naar de rest van je configuratie maar zal alles uitvoeren binnen de site waar dit webpart of eigenlijk user control gebruikt wordt. Ideaal voor submenu’s per site bijvoorbeeld. Op deze manier kan je alle pagina’s binnen de huidige site uitlezen en op maken als submenu van die site.
QueryOverride In deze property kan je met eigen CAML queries aan de slag. Waarom? Omdat je bijvoorbeeld vijf filters wilt instellen. Standaard kan het CQW met maar drie filters overweg. Meer opties zijn er niet. Niet in de visuele configuratie als webpart en niet als user control. Om zoiets toch voor elkaar te krijgen kan je dit property gebruiken en met CAML de exacte query maken die je nodig hebt. Hierin werken alle andere opties ook nog steeds: weburl, filters, sortering etc. Je kunt zelfs expression builders hierin loslaten zodat je nog meer flexibiliteit krijgt!!!
PlayMediaInBrowser Dit is een property die je ook in de visuele configuratie kunt instellen. Het is een boolean field dat te maken heeft met video. Zolang je het CQW NIET inzet om iets met video te doen moet je dit property op “False” zetten. Indien dit property op true staat zal SharePoint onderaan je pagina, waar dit webpart op staat, een stuk javascript plaatsen die iets met video en een Silverlight player doet. Het nadeel is dat SharePoint dit stuk javascript plaatst voor elk CQW die het tegen komt. Indien je dus in je masterpage en pagelayout al drie CQW’s hebt en daarbij ook nog 2 webparts op de pagina plaatst zul je onderaan de pagina vijf keer hetzelfde stuk script zien staan. Met name voor publishing sites vrij overbodig.
SuppressWebPartChrome Deze property is alleen te gebruiken wanneer je het webpart als user control inzet. Dit zorgt voor wat minder HTML rondom het webpart.
8
UseCache Standaard kent het CQW een vrij goed mechanisme om te cachen. Hier kan ook dankbaar gebruik van worden gemaakt. Echter, dit is alleen prettig voor productie. Zodra je aan het ontwikkelen bent is het cachen van de resultaten vrij vervelend. Je ziet nooit gelijk om wijzigingen effect hebben. Door dit veld op “False” te zetten zal het CQW niet cachen. Voordeel is dat wijzigingen in XSLT bijvoorbeeld gelijk effect hebben. Zorg er wel voor dat je dit veld weer op “True” zet indien het klaar is voor test of productie.
GUID vs. Namen In diverse properties komen GUID’s voor, unieke nummers voor kolommen of lijsten. Het voordeel hiervan is dat SharePoint zo altijd de bron weet te vinden en je altijd namen kunt wijzen van kolommen en namen. Indien je een kolom of lijst aanmaakt zal de GUID ook aangemaakt worden. Deze is nooit meer te wijzen. De naamgevingen wel. Het nadeel hiervan is soms, wanneer je met (content) deployment gaat werken dat op andere omgevingen de GUID gewijzigd is. Indien je bijvoorbeeld een CQW als user control in je pagelayout hebt staan, dan wijzigt deze GUID niet mee. Dit kan anders. Je kunt in principe de GUID’s vervangen voor de meer visuele naam. Ook dan blijven je CQW’s werken. Hiervoor is echter wel één vereiste: ZORG DAT IN JE MASTERPAGE DE WEBPARTMANAGER AANWEZIG IS! Zonder de webpartmanager kan SharePoint niet overweg met naamgevingen ipv met GUID’s.
9
