Intégration du CAML dans une WebPart

Pour commencer nous allons créer un nouveau projet dans Visual Studio, comme ceci :

Nous choisissons un projet de type WSPBuilder, avec pour template "WSPBuilder Project". Nous nommerons ce projet "CAMLWebPart".

Nous devons maintenant ajouter notre WebPart à notre solution, pour cela il faut se placer dans la fenêtre "Solution explorer", sélectionner notre projet, puis faire un click droit, "Add" puis "new item...".

Maintenant nous allons ajouter la WebPart que l'on nommera "CAML" :

Nous choisirons la "scope" site . Libre à vous de placer ce que vous voulez dans le titre et la description de la WebPart.

Une fois cette étape terminée, nous allons pouvoir commencer à visualiser ce que les assistants ont fait pour nous.

Tout d'abord, dans la fenêtre "Solution explorer", on constate qu'il existe plusieurs dossiers.

Ces différents dossiers correspondent à la hiérarchie de Microsoft Office Sharepoint. Plus particulièrement à la hiérarchie du dossier système ou toutes les informations brutes de Sharepoint sont stockées, à savoir, tout ce qui n'est pas directement dans la base de données SQL Server.

Si vous êtes curieux et souhaitez en apprendre d'avantage, je vous invite à aller jeter un coup d'oeil directement dans ce dossier qui se trouve dans " C:\Program Files\Common Files\Microsoft Shared\web server extensions\12 ".

Dans notre dossier "CAML", il existe trois fichiers :

CAML.webpart

Ici nous retrouvons la définition de la WebPart, les informations basiques qui seront fournis à l'utilisateur lors de sa mise en place.

• elements.xml Ici nous retrouvons les données relatives à l'emplacement de la WebPart dans le menu de SharePoint, ici on constate notamment que la WebPart est par défaut dans un groupe appelé "MyGroup".
• feature.xml Ici nous retrouvons les données qui correspondent au versioning ainsi qu'à l'identification de la feature. On y trouve notamment l'Id de la feature mais aussi le titre, la description la version etc... Ces données correspondent aux informations que l'on retrouvera dans la liste des features présentent dans notre collection de site SharePoint.

Un autre dossier à également été créé, il s'agit du dossier "WebPartCode", celui ci contient le code c# de notre WebPart, il est donc pour le moment presque vide.

Comme je vous l'ai précisé au début de cet article, le CAML est un langage intégré dans SharePoint 2007 qui nous permet de rechercher des informations contenues dans notre site.

Mais pour ce faire, faut-il encore avoir des données à aller chercher. Nous allons donc créer une liste dans SharePoint afin d'avoir des données à aller chercher.

Je suppose que vous savez comment créer une liste, je ne vais donc pas détailler cette partie, je vais juste vous montrer la liste que je vais utiliser pour l'exemple afin de vous permettre de mieux comprendre la suite. Voici donc la liste que j'ai appelée "CamlSearch" :

Comme vous pouvez le constater une liste très simple, avec uniquement trois champs ajoutés, à savoir "Nom", "Prénom" et "Date".

SharePoint est un outil destiné à un large panel d'utilisation et d'utilisateurs. Afin que votre site paraissent le mieux possible, SharePoint utilise ce que l'on appel les "custom errors", ce qui veux dire que si une erreur intervient lors d'une manipulation, un gentil message apparait afin de vous informer que l'opération désirée n'est pas possible et qu'il faut contacter votre administrateur afin d'obtenir d'avantages de renseignements. Etant des développeurs, comment faire pour savoir d'où provient notre erreur si nous ne pouvons pas visualiser son contenu? Pour éviter ce désagrément et avoir le vrai message d'erreur, il faut modifier le fichier "web.config" de votre site web. Celui-ci se trouve dans le dossier "C:\ Inetpub\wwwroot\wss\VirtualDirectories\Port_Number ", le "Port_Number" correspond bien entendu au numéro du port que vous avez déterminé lors de la création de votre site. Il existe deux balises à modifier : (je vous invite à effectuer une recherche afin de les trouver)

• <customErrors mode="On"> : Cette balise permet à SharePoint d'utiliser ces propres messages d'erreur, il faut donc la changer pour mettre "Off".
• <CallStack="false"> : Cette balise va vous permettre d'afficher la pile d'appel de l'application, elle peut vous permettre d'obtenir d'avantage d'information, il faut donc la modifier pour mettre "true".

Parfait nous allons pouvoir commencer à coder.

Comme je viens de vous le préciser, le fichier contenant le code c# de notre WebPart n'est pas complètement vide. En effet WSPBuilder a déjà rempli ce fichier avec quelques fonctions, mais nous n'aurons pas besoin de tout cela, nous allons donc nettoyer ce fichier, voici le contenu du fichier que vous devez obtenir :

Nous avons ici le strict minimum dont nous avons besoin, à savoir le constructeur et la méthode "CreateChildControls" qui n'est autre que la méthode de création de nos différents composants.

En premier lieu il est important de lister les différents éléments dont on va avoir besoin.

• Le nom de la liste : CamlSearch
• Le nom de la colonne sur laquelle va se porter notre recherche : Nom
• Le type de l'élément de la recherche : en fonction des tests
• La valeur que l'on recherche : en fonction des tests
• Afficher le résultat

Nous pouvons désormais coder.

Nous allons commencer par créer un Label, celui-ci va nous permettre d'afficher le résultat de notre requête dans la WebPart.

public class CAML : Microsoft.SharePoint.WebPartPages.WebPart
{
    private Label lbl_Result;

Parfait maintenant nous allons créer un méthode, que nous nommerons "ExecuteQuery", qui comme sont nom l'indique va nous permettre d'exécuter la requête CAML.

Pour cela nous allons procéder en plusieurs étapes.

1. Les variables d'environnement▲

private int ExecuteQuery()
{
    int nbRow = 0;
    SPWeb rootWeb = SPContext.Current.Web;
    SPList spList = rootWeb.Lists["CamlSearch"];
    SPQuery spQuery = new SPQuery();

2. Le CAML▲

spQuery.Query = "<Where><Eq><FieldRef Name='Nom'/><Value Type='Text'>Toto</Value></Eq></Where>";

3. Exploitation de la requête▲

SPListItemCollection collectionListItems = spList.GetItems(spQuery);
foreach (SPListItem oListItem in collectionListItems)
     nbRow++;

private int ExecuteQuery()
{
   int nbRow = 0;
   try
   {
       SPWeb rootWeb = SPContext.Current.Web;
       SPList spList = rootWeb.Lists["CamlSearch"];
       SPQuery spQuery = new SPQuery();
       spQuery.Query = "<Where><Eq><FieldRef Name='Nom'/><Value Type='Text'>Toto</Value></Eq></Where>";
    
       SPListItemCollection collectionListItems = spList.GetItems(spQuery);
       foreach (SPListItem oListItem in collectionListItems)
           nbRow++;
   }
   catch (Exception ex)
   {
       lbl_Result = new Label();
       lbl_Result.Text = ex.Message;
   }
   return nbRow;
}

L'interface utilisateur se gère dans la méthode "CreateChildControls", pour nous il s'agit ici d'afficher notre label créé précédement, le code se résume donc à cela :

protected override void CreateChildControls()
{
    base.CreateChildControls();
    lbl_Result = new Label();
    lbl_Result.Text = ExecuteQuery().ToString();
    this.Controls.Add(lbl_Result);
}

Ici nous n'avons rien de particulier, on instancie le label, ensuite on lui attribue le résultat de notre méthode "ExecuteQuery", sans oublier la méthode "ToString" car le label contient uniquement du texte, hors notre méthode retourne un entier. Ensuite il reste à ajouter le label à la WebPart grâce à la méthode "Controls.add".

Parfait, nous pouvons maintenant compiler notre projet à l'aide de WSPBuilder. Pour cela, suivez ces étapes :

• Placez-vous dans la fenêtre "Solution Explorer"
• Sélectionnez votre projet, puis click droit
• Sélectionnez "WSPBuilder"
• Sélectionnez "Build WSP"

Maintenant il ne nous reste qu'à déployer notre WebPart, pour cela il existe trois méthodes :

• WSPBuilder : Pour cette méthode, c'est l'outil WSPBuilder qui va travailler pour nous. Il nous suffit dans Visual Studio de sélectionner "Deploy" après avoir fait les mêmes manipulations que ci-dessus. Il va s'en dire que c'est la méthode la plus simple surtout lors de la phase de tests.
  
• SharePoint Solution Installer : Cet outil est très pratique, il permet de déployer votre WebPart n'importe où. Il vous suffit de placer votre fichier WSP dans le dossier SharePoint Solution Installer, puis de modifier le fichier "Setup.exe.config" directement dans Visual Studio. Pour plus d'information je vous invite à vous rendre à cette adresse : http://SharePointinstaller.codeplex.com
• Stsadm : Il s'agit de l'outil de base proposé avec Visual Studio, celui-ci s'utilise directement dans l'invite de commande de Visual Studio. Le descriptif de cet outil est disponible à cette adresse : http://technet.microsoft.com(Pour information, les autres outils font également appel à celui-ci, mais cela reste invisible pour l'utilisateur)

Nous allons maintenant pouvoir aller visualiser le résultat dans SharePoint. Pour cela nous devons accéder à la liste des feature de notre site, dans le menu "Site Actions" de SharePoint et sélectionner "Site Settings".

Ensuite dans le menu "Site Collection Administration" vous devez sélectionnez "Site collection features"

Nous pouvons visualiser notre feature dans la liste :

Il faut maintenant activer la feature, si l'opération se déroule correctement, vous devez voir apparaitre un rectangle bleu dans sur la droite de la feature, comme ceci :

Parfait, nous pouvons maintenant aller ajouter notre WebPart à une page de composants WebPart. Pour créer cette page, il suffit de se rendre dans le menu "Site Actions" et de sélectionner "Create". Ensuite dans la section "Web Pages", sélectionnez "Web Part Page".

Nous nommerons notre page, "TestWebPart".

Maintenant il nous suffit d'ajouter notre WebPart dans la page, pour cela cliquer sur "Add a Web Part", puis sélectionner votre WebPart.

Si vous avez laissé les valeurs par défaut, vous devriez trouver votre WebPart dans la section du bas nommée "MyGroup". Cochez la case correspondante puis cliquez "Add" en bas de page.

Nous pouvons tout de suite visualiser le résultat de notre requête, ici "1". Félicitation! Vous venez de créer votre première WebPart contenant une requête CAML.

Maintenant, comme je vous l'ai promis, je vais vous donner quelques petits morceaux de code, afin de vous simplifier la création de requêtes CAML dans vos WebPart. Comme nous avons pu le voir, il existe quatre points indispensables dans une requête CAML :

• La liaison
  • And
  • Or
• Le type de comparaison

  CAML	Définition	Traduction
  <Eq>	Equal	Egal
  <Neq>	Not Equal	Différent
  <Gt>	Greater Than	Supérieur
  <Geq>	Greater than or Equal	Supérieur ou égal
  <Lt>	Lower Than	Plus petit
  <Leq>	Lower than or Equal	Plus petit ou égal
  <IsNull>	Is Null	Est nul
  <Contains>	Contains	Contient
  <Begins With>	Begins With	Commence par

• Les champs où porte la recherche
• Le type de la recherche
  • Text
  • Number
  • DateTime

Ces différents éléments sont assez longs à mettre en place dans le code, c'est pourquoi je vous propose ces différents codes que vous pourrez aisément glisser dans votre WebPart, afin de permettre à l'utilisateur de choisir les différents éléments de sa recherche. Il s'agit de "switch case" pour l'implémentation d'une DropDownList pour l'exemple (Le code se divise en deux parties, la première contient le code pour alimenter la "DDL" dans l'éditeur personnalisé, la seconde contient un "switch case" à placer dans le code de la WebPart). Je pense que le nom des différentes variables est assez explicite pour ne pas avoir besoin de détailler le code.

• La Liaison :
• Le Type de comparaison :
• Le Type de la recherche :

C'est bien beau tout ce code, mais par forcément parlant, voici donc un exemple de sont utilisation :

SPQuery.Query = "<Where>"
                   + linkOperator
                       + camlOperator +
                           "<FieldRef Name='"
                           + column1 
                           + "'/><Value Type='"
                           + camlValueType + "'>"
                           + filter +
                           "</Value>"
                       + camlOperator_close
                       + camlOperator2 +
                           "<FieldRef Name='"
                           + column2 
                           + "'/><Value Type='"
                           + camlValueType2 + "'>"
                           + filter2 +
                           "</Value>"
                       + camlOperator2_close
                   + linkOperator_close +
                "</Where>";

Dans ce code, toutes les valeurs remplaçables par des variables, le sont, cela nous permet d'obtenir une requête qui peut être entièrement paramétrée par l'utilisateur.

Voici quelques astuces afin de répondre à quelques besoins récurents :

• Operation sur un champ de type Lookup
   

  Sélectionnez

  <Where>
  	<Eq>
  		<FieldRef Name="RefCountry" LookupId="TRUE" />
  		<Value Type="Lookup">10</Value>
  	</Eq>
  </Where>

• Operation sur un champ de type User
   

  Sélectionnez

  <Where>
  	<Eq>
  		<FieldRef Name="AssignedTo" LookupId="TRUE"/>
    		<Value Type="Integer">
      		<UserID/>
    		</Value>
  	</Eq>
  </Where>

• Operation sur un champ de type DateTime
   

  Sélectionnez

  <Where>
  	<Geq>
    		<FieldRef Name="MyDateColumn" />
    		<Value Type="DateTime">
      		<Today OffsetDays="-5" />
    		</Value>
  	</Geq>
  </Where>

• Operation sur un champ de type DateTime avec récurrence
   

  Sélectionnez

  <Where>
  	<DateRangesOverlap>
    		<FieldRef Name="EventDate" />;
    		<FieldRef Name="EndDate" />
    		<FieldRef Name="RecurrenceID" />
    		<Value Type="DateTime">
      		<Week />
    		</Value>
  	</DateRangesOverlap>
  </Where>

Dans l'utilisation des bibliothèques de formulaires avec InfoPath, il existe une subtilité qui peux rapidement vous faire tourner en rond et perdre beaucoup de temps. En effet dans un formulaire InfoPath, il est arrive très souvent, pour ne pas dire chaque fois, que certain champs comportent un underscore, hors dans la bibliothèque de formulaire associé dans SharePoint, les colonnes correspondantes ont des espaces à la place. Voici un exemple concret :

• Dans InfoPath : Request_Date (vue source de données)
• Dans SharePoint : Request Date (en-tête de colonne)

Le problème est donc que dans votre WebPart vous n'aurez donc pas le bon nom. SharePoint n'a pas supprimer le underscore, mais il l'a remplacé par le code :"_x0020_".

Il existe donc une solution, utiliser la méthode "Replace" de la variable de type string. Pour reprendre l'exemple précédent, il suffit de modifier deux lignes :

column1 -> column1.Replace("_","_x0020_");

column2 -> column2.Replace("_","_x0020_");

Voilà, vous savez maintenant tout ce qu'il vous faut pour commencer à utiliser le CAML avec SharePoint. Bon courage a tous et bon code.

Un grand merci à blade159 pour la relecture de cet article ainsi qu'à nonoxpProfil de nonoxp pour sa contribution