I. Vous avez dit wiki ?

Quand on parle wiki, on pense tout de suite à wikipedia : un site collaboratif où tous les savoirs du monde sont concentrés, discutés et archivés en plusieurs langues. Mais un wiki peut être aussi utilisé dans une entreprise, une association ou tout simplement par un groupe d'individu ayant besoin de collaborer sur un même thème. Nous allons voir dans ce tutoriel comment une association de quartier peut utiliser XWiki pour son site.

II. Expression des besoins

La Commune Libre d'Aligre (CLA) est une association de quartier qui organise des événements culturels de tout type : repas de quartier, vide grenier, fête des commerçants, jardin communautaire... Comme toute association, elle a des membres actifs qui font partie du conseil administratif, un président et une flopée de sympathisants. L'association a besoin d'un site web répertoriant ses évènements et permettant ainsi aux internautes d'être au courant de ses activités. Le site doit être mis à jour fréquemment par les membres du conseil et par le président. De plus, des dossiers sont produits de manière collaborative sur des thèmes plus complexes comme la diversité des commerçants dans le quartier ou l'aménagement de la voie publique en concertation avec la mairie.

Le site est entièrement consultable par n'importe quel internaute sauf une partie privée, accessible uniquement aux membres du conseil concernant l'administration de l'association (réunion, assemblée générale, budget, juridique...). Le président est le seul habilité à inscrire de nouveaux membres. Pour créer ce site, la CLA (Commune Libre d'Aligre) décide d'utiliser XWiki.

III. Présentation de XWiki

XWiki est un wiki Open-Source de seconde génération (ou "wiki applicatif") écrit en Java. Il offre non seulement les fonctions principales d'un wiki (édition collaborative, suivi d'information, gestion de l'accès des membres), mais aussi des possibilités de développement avancées comme :

  • créer et utiliser de nouveaux templates dans la création de page wiki grâce à l'intégration de Velocity
  • créer des pages wiki "applicative" grâce à l'intégration du langage de script Groovy
  • créer de nouveaux objets xwiki en plus des objets prédéfinis (albums photo, calendrier, blog) grâce à une API de plugin Java.
  • gérer finement les droits d'accès : cela permet de restreindre certaines actions (lecture, écriture, administration) à une certaine population (un simple internaute, un membre du wiki ou un administrateur) et ceci, par page ou par section/espace du wiki.

IV. Installation de XWiki

Comme énoncé dans le guide d'administration de XWiki, il y a plusieurs manières d'installer XWiki. La plus simple étant l'utilisation de l'installateur Windows qui vient avec la base de données HSQLDB et le moteur web Jetty. XWiki peut aussi s'exécuter sur tout conteneur de servlet récent (Tomcat, JBoss, GlassFish...) et avec plusieurs bases de données relationnelles (comme HSQL et MySQL). Pour ce tutoriel on utilisera Tomcat et MySQL.

Tout d'abord, il faut télécharger les deux fichiers XWiki, c'est à dire :

  • xwiki-1.0.war qui contient l'application à proprement parlé
  • xwiki-1.0.xar qui contient des modules XWiki déjà créés (le user admin, des panneaux, des pages...).

Versions utilisées dans ce tutoriel
JDK 1.5.0_12
MySQL Server 5.0.41
Tomcat 5.5.23
XWiki 1.0

Configurer Tomcat

L'installation de XWiki dans Tomcat est très simple. Une fois votre Tomcat téléchargé et installé, il suffit de décompresser le fichier xwiki-1.0.war dans le répertoire %TOMCAT_HOME%\webapps\xwiki. Dans le reste du tutoriel, ce répertoire sera nommé %XWIKI_HOME%.

Configurer MySQL

XWiki stocke ses pages dans une base de données. Il faut donc que vous ayez téléchargé et installé MySQL. Il vous faut ensuite créer une base pour XWiki. Pour cela :

  • démarrez MySQL (mysqld --console)
  • créez la base de données xwikiDB en tapant la commande mysql --user=root --execute="create database xwikiDB"
  • donnez les droits d'accès à l'utilisateur xwikiUser (mot de passe xwikiPwd) sur la base de données xwikiDB en tapant la commande mysql --user=root --execute="grant all privileges on xwikiDB.* to xwikiUser@localhost identified by 'xwikiPwd'"
  • vérifiez que la base de données xwikiDB a bien été créé en tapant mysql --user=root --execute="show databases"

Pour obtenir de l'aide sur les commandes en ligne de MySQL tapez mysql -?
http://dev.mysql.com/doc/refman/5.0/en/mysql.html

XWiki utilise Hibernate comme moteur de persistance. Il faut donc lui fournir tous les paramètres de connexion à la base de données xwikiDB. Pour cela, modifiez le fichier %WIKI_HOME%\WEB-INF\hibernate.cfg.xml.

Fichier hibernate.cfg.xml
Sélectionnez

<property name="connection.url">jdbc:mysql://localhost/xwikiDB?useServerPrepStmts=false</property>
<property name="connection.username">xwikiUser</property>
<property name="connection.password">xwikiPwd</property>
<property name="connection.driver_class">com.mysql.jdbc.Driver</property>
<property name="dialect">org.hibernate.dialect.MySQLDialect</property>

Démarrer XWiki

Il ne nous reste plus qu'à démarrer Tomcat (%TOMCAT_HOME%\bin\startup.bat) et nous rendre à l'URL http://localhost:8080/xwiki. Une première page s'affiche sur votre navigateur vous informant que l'installation de XWiki est imminente.

Page d'accueil de XWiki
Page d'accueil de XWiki

Il vous suffit de cliquer sur le lien "XWiki Home Page" et d'attendre un petit moment, le temps qu'Hibernate crée les tables dont XWiki a besoin. Si vous voulez voir la liste des tables créées, tapez la commande suivante : mysql --user=xwikiUser --password=xwikiPwd --database=xwikiDB --execute="show tables".

Ca y est, XWiki est configuré et la page d'accueil par défaut s'affiche :

XWiki est configuré
XWiki est configuré

Cette page vous indique que le wiki est prêt à l'emploi mais qu'il est vide, c'est-à-dire qu'il ne contient ni page ni utilisateur, charge à vous de les créer. Pour se faciliter la tâche, il est préférable d'importer l'archive xwiki-1.0.xar qui permet de charger un ensemble de pages par défaut.

Importer les pages par défaut

XWiki utilise des fichiers d'extension xar (XWiki Archive) pour exporter et importer ses pages. Le fichier xwiki-1.0.xar, que vous avez téléchargé auparavant, contient des utilisateurs (admin, guest...) et des modules standards (possibilité de rechercher des pages dans le wiki, d'obtenir des statistiques de consultation des pages, d'organiser les blogs et photos...). Pour pouvoir importer ces pages, cliquer sur le lien "Administration" (http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences) puis sur l'onglet "Import". Dans la section "Upload a new archive to import" sélectionnez le fichier xwiki-1.0.xar que vous avez téléchargé et cliquez sur "Attach this file". Ensuite, dans la section "Available files to import" cliquez sur le lien "xwiki-1.0.xar". La section "Available documents to import" vous affiche la liste des documents que vous pouvez importer. Décochez ceux qui ne vous intéresseraient pas (comme par exemple les pages Sandbox qui sont utilisées pour se familiariser avec XWiki), ou sinon importez la totalité en cliquant sur le bouton "Import" qui se trouve tout en bas de la page.

Importer les pages
Importer les pages

Si vous avez des problèmes pour uploader un fichier à partir du Wiki: il faut indiquer un répertoire autorisant l'écriture par exemple sous Linux, il faut rajouter la ligne xwiki.upload.tempdir=/tmp dans le fichier %WIKI_HOME%/WEB-INF/xwiki.cfg.

V. Modifier le wiki par défaut

Une fois l'import terminé, rendez-vous ensuite sur la page d'accueil par défaut de XWiki (http://localhost:8080/xwiki/bin/view/Main/)

Les sections de la page d'accueil
Les sections de la page d'accueil

Cette page vous montre les éléments essentiels que nous allons manipuler tout au long de ce tutoriel. Tout en haut vous avez la barre d'action. Selon les droits de l'utilisateur connecté, elle permet d'imprimer la page en cours, de la modifier, de consulter ses commentaires... Viennent en dessous le logo et les menus d'accès (login, logout, enregistrement d'un nouvel utilisateur...). Juste en dessous vous avez la barre de navigation qui vous permet de suivre le chemin de chaque page et de pouvoir facilement revenir à la page racine. Enfin, la page centrale du wiki est constituée du corps et de panneaux posés à droite et/ou à gauche (panneaux de recherche et de navigation dans cet exemple).

Modifier et créer de nouvelles pages

Comme vous pouvez vous en douter, la page d'accueil par défaut de XWiki ne convient pas à l'association. Elle souhaite donc en modifier le contenu et créer de nouvelles pages. Mais avant de nous lancer dans cet exercice, il nous faut définir certains concepts importants de XWiki :

  • Une page. Tout est page dans XWiki. La page est l'élément que l'on crée, met à jour, supprime et que l'on organise. Pour en modifier le contenu, XWiki vous permet d'utiliser un éditeur WYSIWYG ainsi qu'un éditeur en mode texte utilisant les macros Radeox pour la mise en page (par exemple 1, 1.1, 1.1.1 pour les niveaux de titres, *gras* pour mettre en gras du texte...).
  • Espace (space). Un espace regroupe des pages (un peu comme un répertoire contenant des fichiers). Il peut être utile de répartir ses pages dans des espaces différents pour mieux les retrouver, mais aussi pour avoir des accès différents. Par exemple, comme nous le verrons plus bas dans ce tutoriel, nous allons créer un espace privé, c'est à dire un espace dont le contenu est uniquement accessible par l'administrateur. Toute page associée à cet espace, partage ses droits. L'espace par défaut est Main, celui de l'administration est XWiki et ainsi de suite.
  • Panneau (panel). C'est une page qui peut être rajoutée dans une des colonnes du wiki (navigation, recherche...).

Pour créer de nouvelles pages, il existe différents moyens :

  • Utilisez le panneau "New Page" (http://localhost:8080/xwiki/bin/view/Panels/NewPage), qui se trouve par défaut en bas à droite du wiki.
  • Editez une page, insérez un lien [xxx] (notez qu'un lien en Radeox se définit par un texte, ici xxx, entre crochets []) vers une page inexistante, enregistrez cette page puis cliquez sur le lien xxxxImage non disponible. XWiki se chargera alors de créer cette nouvelle page.
  • Vous pouvez aussi changer l'URL de la page en cours et rajouter un nom de page (XXX par exemple) http://localhost:8080/xwiki/bin/view/Main/XXX. Vous aurez alors la possibilité de créer la page XXX.

Tout d'abord commençons par modifier le contenu de la page principale. Par défaut, pour modifier ou créer des pages dans XWiki, il faut se connecter avec un utilisateur ayant ses droits. Pour l'instant, utilisons l'utilisateur d'administration par défaut. Dans le menu d'accès, cliquez sur Log-in et saisissez le user Admin (A majuscule) et mot de passe admin (a minuscule). La barre d'action s'enrichit alors d'un menu "Edit". Cliquez dessus. Vous tomberez alors sur une page spéciale qui contient plusieurs onglets. Deux de ces onglets peuvent être utilisé pour modifier la page : "WYSIWYG" et "Wiki" (syntaxe radeox). Vous pouvez maintenant supprimer le texte par défaut et saisir une page d'accueil pour l'association de la Commune Libre d'Aligre.

Editeur WYSIWYG
Editeur WYSIWYG

Si vous utilisez la syntaxe wiki (onglet Wiki), notez le panneau d'aide "XWiki syntax help" sous forme d'accordéon vous permettant de vous déplacer dans plusieurs menus (Titles, Paragraph, Emphasizing, Links...) et d'utiliser les macros Radeox appropriées. Cliquez sur "Save & View", voilà, votre page d'accueil est modifiée.

Comme vous pouvez le constater, l'éditeur comporte quatre boutons :

  • Cancel : annule les modifications que vous auriez pu apporter à la page
  • Preview : ne sauvegarde pas la page mais permet de la visualiser
  • Save & Continue : sauvegarde la page et vous permet de continuer à l'éditer
  • Save & View : sauvegarde la page et l'affiche.

Ensuite, nous allons créer un panneau qui nous permettra de naviguer dans les pages. Pour cela aller à la page affichant tous les panneaux disponibles (http://localhost:8080/xwiki/bin/view/Panels/) et dans la section "Create new panels" saisissez "MenuCLA" (le nom du panneau) puis cliquez sur "Create". Apparaît alors un écran vous demandant de saisir les informations de ce panneau. Dans "category" choisissez "navigation" saisissez le texte suivant dans "content".

Panneau utilisant les macros Radeox et Velocity
Sélectionnez

#panelheader('Menu')
* [Agenda]
* [Agora]
* [Café associatif]
* [Cinémaligre]
* [L'Aligresse]
* [L'Association]
* [Les activités de nos amis]
* [Manifestations passées]
#panelfooter()

Ce texte utilise les macros Radeox pour la mise en page. Chaque ligne débutant par un caractère "*" se transforme en une liste à puce et le texte entre crochet devient un lien vers une page. Les macros Velocity #panelheader et #panelfooter permettent de rajouter un titre ou un bas de page au panneau. Notez que la page MenuCLA que nous venons de créer se trouve dans l'espace Panels (l'espace par défaut contenant tous les panneaux). Le nom complet de cette page est donc Panels.MenuCLA.

Pour rajouter ce panneau dans la colonne de gauche, il faut aller dans les préférences de XWiki (http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences) et modifier la présentation (onglet "skin"). Rajoutez "Panels.MenuCLA" dans "Left Panel" et sélectionnez "Yes" dans "Show Left Panel". Cliquez sur "Save & View".

Ajout du panneau
Ajout du panneau

Si vous retournez vers la page d'accueil, vous verrez le panneau Menu dans la colonne de gauche. Notez que les liens se terminent par le symbole Image non disponible. Cela signifie que le lien pointe vers une page inexistante. Pour la créer, il vous suffit de cliquer sur ce lien. XWiki se charge de créer la page, de la rajouter dans l'espace courant (c'est-à-dire Main) et d'afficher l'éditeur WYSIWYG pour en modifier le contenu. Charge à vous de saisir le contenu de toutes ces pages.

Le panneau Menu est ajouté
Le panneau Menu est ajouté

VI. Créer les utilisateurs

Maintenant que nous avons modifié et créé de nouvelles pages, nous pouvons nous concentrer sur les besoins d'accès de l'association. Celle-ci veut que le président soit le seul à posséder les droits d'administration et à pouvoir créer de nouveaux membres. Les membres (Cécile, Daniel et Annie) peuvent créer et modifier les pages, alors que les internautes n'ont qu'un droit de lecture et la possibilité de laisser des commentaires.

Le président

Le président de l'association est en fait l'administrateur du site. Il est le seul à pouvoir créer de nouveaux utilisateurs et à administrer le site. Pour créer ce nouvel administrateur, cliquez sur Administration dans le menu d'accès, puis sur l'onglet "Users & Groups" et enfin sur le lien "the users page" puis Register. Ce formulaire nous permet de créer l'utilisateur "Le président" (login Lepresident) et comme mot de passe "monsieur".

Ajout de l'utilisateur Lepresident
Ajout de l'utilisateur Lepresident

Il faut ensuite l'ajouter dans le groupe des administrateurs. Pour cela retournez dans le menu d'administration en cliquant sur Users & Groups puis sur le lien the groups page. Cette page affiche tous les groupes disponibles dans le wiki. Sélectionnez XWiki Admin Group puis cliquez sur l'icône en forme de crayon (après le titre Members) pour éditer le contenu de la page. Le groupe XWikiAdminGroup contient les administrateurs du wiki.

Ajout du président dans le groupe administrateur
Ajout du président dans le groupe administrateur

Rajoutez l'utilisateur XWiki.Lepresident (XWiki est le nom de l'espace, Lepresident le nom de l'utilisateur) et cliquez sur "Save & Continue". Déconnectez-vous en cliquant sur "Log-out" (souvenez-vous que vous êtes toujours connecté en tant qu'Admin) puis reconnectez-vous en tant que président (Lepresident/monsieur). Profitez-en pour supprimer l'administrateur par défaut (Admin) qui a été importé (aller à l'adresse http://localhost:8080/xwiki/bin/view/XWiki/Admin puis cliquez sur le lien Delete de la barre d'action).

Le président a le droit d'administrer (admin) le site, de créer/mettre à jour/supprimer (edit, delete) des pages, de rajouter des commentaires (comment) et il est le seul à pouvoir créer de nouveaux membres (register). On peut maintenant modifier légèrement son profil (http://localhost:8080/xwiki/bin/view/XWiki/Lepresident) en le passant en mode avancé (cliquez sur "Switch to Advanced edit mode") et en rajoutant l'url de son blog et sa photo.

Les membres du conseil

Les membres du conseil sont enregistrés dans le wiki par le président de l'association dans le groupe XWikiAllGroup. Ils ont les droits de créer/mettre à jour/supprimer (edit, delete) des pages et de rajouter des commentaires (comment). Il faut auparavant enregistrer ses nouveaux utilisateurs (http://localhost:8080/xwiki/bin/register/XWiki/Register) (Annie, Daniel, Cécile) qui seront automatiquement rajoutés au groupe XWiki All Group. Le groupe XWikiAllGroup représente le groupe de tous les utilisateurs du wiki possédant un compte et pouvant se connecter

Contenu du groupe XWikiAllGroup
Contenu du groupe XWikiAllGroup

VII. Modifier les droits d'accès

XWiki possède une gestion fine des droits d'accès. A partir de menus (lien "Administration" puis onglet "Global Rights"), on peut autoriser ou non certaines actions sur une page, un espace ou pour la totalité du wiki. La liste des actions est la suivante :

  • admin : administration du site
  • view : lecture de pages
  • edit : édition des pages
  • comment : l'ajout de commentaires aux pages
  • delete : la suppression d'une page
  • register : la création d'un nouvel utilisateur
  • programming : l'utilisation de la programmation dans les pages. Attention, cette fonctionnalité est à mettre entre des mains expertes car une mauvaise utilisation pourrait s'avérer dangereuse.

L'autorisation ou non à ces actions peut ensuite être attribuée à un utilisateur en particulier (Le président, Cécile...) ou à un groupe. XWiki possède des notions par défaut importantes :

  • l'utilisateur XWikiGuest est l'internaute par défaut, celui qui n'est pas connecté au site
  • le groupe XWikiAllGroup représente le groupe de tous les utilisateurs du wiki possédant un compte et pouvant se connecter
  • le groupe XWikiAdminGroup contient les administrateurs du wiki.

Dans le cas de l'association, nous avons le président qui est administrateur, les membres du conseil, et l'internaute (l'utilisateur XwikiGuest) qui est autorisé à consulter des pages (view) et de rajouter des commentaires (comment). La matrice ci-dessous nous montre les utilisateurs du wiki ainsi que leurs droits.

Utilisateur Groupe admin view edit comment delete register programming
XWikiGuest     X   X      
  XWikiAdminGroup X X X X X X X
  XWikiAllGroup   X X X X    

Pour mettre en place ces droits, il faut aller dans le menu d'administration puis cliquer sur "Global Rights".

Gestion des droits
Gestion des droits

Vous venez de créer ces droits d'accès pour la totalité du wiki, c'est-à-dire que tous les espaces et toutes les pages ont les mêmes droits.

Créer un espace privé

Par contre, l'association a besoin d'un espace privé dans lequel uniquement le président et les membres peuvent travailler de manière collaborative. Pour cela il faut tout d'abord créer un nouvel espace que vous nommez "Private".

Création d'un espace privé
Création d'un espace privé

Après avoir cliqué sur "Create", un éditeur vous permet de saisir du texte pour la page principale de cet espace. Les pages que l'on créera dans cet espace devront être préfixées par le nom de cet espace : "Private" (Private.Budget, Private.Subventions...).

Il faut ensuite se rendre dans l'administration pour modifier les droits d'accès et interdire la lecture de ces documents aux internautes. Cliquez sur l'onglet "Space Rights" et sectionnez "Private". Ajoutez un droit d'accès en cliquant sur le bouton "Add Access Right Entry" et sélectionnez l'utilisateur XwikiGuest, l'action view et deny.

Gestion des droits pour l'espace privé
Gestion des droits pour l'espace privé

VIII. Modifier certaines préférences

XWiki est extrêmement customizable et la plupart de ces ajustements peuvent se faire via le menu d'administration et l'onglet "Preferences". Par exemple, le titre par défaut du navigateur est XWiki. On peut le remplacer par le nom de l'association en allant sur l'onglet "Presentation" et modifier le champ "Browser Title Bar Text" par "Site de la Commune Libre d'Aligre". On peut en profiter pour modifier les métas information de la page dans le champ "HTTP Meta Information".

Modifier le skin

XWiki vient avec trois skins différents qui se trouvent dans le répertoire %XWIKI_HOME%\skins. Chacun porte un nom d'oiseau, le défaut étant albatross. Vous pouvez en avoir un rapide aperçu en rajoutant à la fin de chaque URL ?skin= et le nom du skin. Ainsi, la page d'accueil peut se décliner en trois différents look&feel.

Pour utiliser de manière définitive la skin "finch" par exemple, il suffit d'aller dans les préférences de l'administration et, dans l'onglet skin, saisir le texte "finch" dans la zone "Skin". Sauvegardez, vous devriez voir votre site se transformer.

Le look and feel Finch
Le look and feel Finch

IX. Administrer le site

XWiki vient aussi avec certains utilitaires d'administration. Par exemple, pour connaître les statistiques d'accès aux pages pour le mois ou le jour en cours, il suffit de se rendre à l'adresse http://localhost:8080/xwiki/bin/view/Admin/Stats.

Les statistiques sont désactivées par défaut pour améliorer les perfs. Pour les réactiver il faut modifier la valeur xwiki.stats du fichier %WIKI_HOME%\WEB-INF\xwiki.cfg comme suit: xwiki.stats=1.

Pour sauvegarder toutes les modifications que vous avez apporté au site (pages, utilisateurs...), il faut les exporter. Un fichier backup.xar est alors sauvegardé sur votre disque contenant toutes les pages, les espaces et les utilisateurs de votre wiki. Si vous installez une nouvelle version de XWiki from scratch, il suffira d'importer ce fichier pour retrouver votre wiki.