Architecture et développement de Yeswiki

Dossiers et fichiers de la distribution

actions : contient les actions yeswiki de base que l'on peut mettre entre accolades par ex: {{nomdelaction parametre="valeur du paramètre"}}
cache : contient les vignette, cache des flux rss , et autre (peut être vidé)
files : contient les fichiers uploades par les utilisateurs
formatters : contient les fichiers qui gerent la syntaxe wiki (les = pour titres etc)
handlers/page : actions a passer dans l'url /edit /raw /show /revisions /acls
includes : bibliothèques php utilisées par le code, dont les classes php principales de yeswiki
lang : dossier de langues
setup : dossier appelle à l'installation (s'il ne trouve pas de fichier wakka.config.php)
setup/docs : contient des fichiers <NomWikiPage>.txt avec le contenu des pages créées a l'installation d'un wiki
themes : contient les themes et les templates (voir la documentation)
tools : contient les extensions de base de YesWiki, puis celles ajoutées par l'utilisateur.
vendor : bibliothèques externes
.gitignore : fichier de config de git (pour dire les fichier et dossier qu'il ne doit pas surveiller)
COPYING : texte de présentation de licence à lire
INSTALL : texte de présentation de l'install à lire
LICENSE : texte de présentation de licence à lire
README.md : texte de présentation générale de yeswiki (apparaît en bas de github)
index.php : fichier lancé par défaut, initialise yeswiki
interwiki.conf : ancienne conf pour gérer l'inter wiki (plus trop utilisé)
robots.txt : directives pour les robots des moteurs de recherche
wakka.basic.css : graphisme par défaut de wiki si l'extension templates n'est pas utilisée
wakka.config.php : fichier de configuration de yeswiki, contient les informations pour se connecter à la base de données entre autre, si ce fichier est inexistant, la procédure d'installation se lance
wakka.css : graphisme par défaut de wiki si l'extension templates n'est pas utilisée
wakka.php : nom historique présent pour retro-compatibilité, renvoie à index.php

Créer des themes YesWiki

TODO : cours plus détaillé
Pour créer un nouveau thème, il vaut mieux dupliquer un thème existant et le glisser dans le dossier themes.

Créer des actions YesWiki

Exemple pratique de l'action {{salutations}}

si l'on ajoute un fichier salutations.php dans le dossier actions, ce sera automatiquement reconnu comme un action wiki
exemple de contenu :

affichage de base

<?php
echo "bonjour c'est moi !";

Dans ce cas {{salutations}} écrit dans une page wiki affiche "bonjour c'est moi !

utiliser des parametres

<?php
$name = $this->GetParameter("name");  // permet de recuperer le parametre "name" (nom de quelqu'un) ex: ""{{salutations name="Florian" }}"" 
$adjectif = $this->GetParameter("adjectif");  // permet de recuperer le parametre "name" (nom de quelqu'un) ex: ""{{salutations name="Florian" adjectif="le magnifique"}} ""
echo "bonjour ".$name." ".$adjectif.", c'est moi !";

test des parametres

<?php
$name = $this->GetParameter("name");  // permet de recuperer le parametre "name" (nom de quelqu'un) ex: ""{{salutations name="Florian" }} ""
if (empty($name)) {
    echo "<div class="alert alert-error">Erreur : action salutations : le paramètre 'name' est obligatoire.</div>";
} else {
    echo "Bonjour ".$name." , c'est moi !";
}

ajout au fichier de configuration wakka.config.php

'moment_de_la_journee' => "jour" // ou "nuit"

dans l'action
<?php
// travailler avec un element du fichier de configuration
if ($this->config["moment_de_la_journee"] ""<span id="TOC_5_1" class="yeswiki-title-anchor"></span>""== 'jour') {
    echo "bonjour";
} elseif ($this->config["moment_de_la_journee"] == 'nuit') {
    echo "bonsoir";
}

requetes SQL

dans l'action
<?php
// pour les insert, update, delete, actions qui ne renvoient par de resultat
// Le prefixe des tables est sauvegardé dans le fichier config (clé : table_prefix)
// efface tout l'historique des page
$this->Query('DELETE FROM '.$this->config['table_prefix'].'pages WHERE latest="N";');
// Pour les requetes de selection
$results = $this->LoadAll('SELECT * FROM '.$this->config['table_prefix'].'pages WHERE latest="Y";'); // sort tous les résultats
$result = $this->LoadSingle('SELECT * FROM '.$this->config['table_prefix'].'pages WHERE latest="Y";'); // sort uniquement le premier résultat

liens

//affiche le lien en mode edition de la page courante
echo $this->href('edit', $this->GetPageTag());
// affiche le lien en mode consultation de la page ToTo
echo $this->href('', 'ToTo');
// donne la page courante (où l'on se trouve)
echo $this->href('', $this->GetPageTag());
// ajouter des parametres GET a l'url courante
echo $this->href('', $this->GetPageTag(), 'nb=10&type=photo');

gestion des droits

$this->HasAccess('read', $this->GetPageTag() [, user= ""]);
$this->HasAccess('write', $this->GetPageTag());
$this->HasAccess('comment', $this->GetPageTag());
$this->UserIsAdmin() // l'utilisateur est il admin
$this->GetUser() // l'utilisateur est il admin


Créer des extensions YesWiki

Pour démarrer

  • Créer un dossier dans /tools.
    • Les extensions s'appuient sur l'architecture de dossiers de YesWiki. Il faut donc, lorsqu'on crée une extension, respecter l'arborescence de dossiers de l'architecture de base de YesWiki.
  • Placer un fichier desc.xml à la base du dossier /tools/monextension.
    • l'attribut active de l'élément racine de ce fichier doit valoir 1, sinon l'extension ne sera reconnue comme active par YesWiki.
    • la valeur de l'attribut name doit être le nom de l'extension.
    • (voir les autres extensions pour le format)
  • Le dossier /tools/monextension doit contenir un fichier wiki.php.
    • Ce fichier sera le premier exécuté lors de l'exécution de l'extension. C'est donc le bon endroit pour initialiser ce dont on aura besoin (créer des tables, faire des inclusions, des définitions de constantes, aller lire les paramètres par défaut dans wakka.config.php, etc. (voir les autres extensions).
    • Ce fichier doit impérativement contenir en premières lignes de code :
    • if (!defined("WIKINI_VERSION")) {
          die("acc&egrave;s direct interdit");
      }
      

Important

En cas de conflit de nom, par exemple, si plusieurs extensions ont le même nom, ou si plusieurs tools ont le même nom, ou si plusieurs actions ont le même nom (vous voyez l'idée ?)
L'exécution se fait dans l'ordre alphabétique. Ce comportement est propagé dans les actions de ces tools et entre les tools entre eux
Exemple : L'action monaction.php du tools tools1 s'exécute avant l'action monaction.php du tools2

Après, c'est plus ou moins open bar

  • Créer des actions dans le dossier actions
  • Créer des handler dans le dossier handler/Page
  • idem formatters, lang..
  • On peut exécuter des bidouilles en amont ou après l'exécution d'une action, d'un handler ou d'un formatter en mettant des underscores :
    • __nomdufichier.php pour avant,
    • nomdufichier__.php pour après,
    • dans ce contexte, $plugin_output_new contient le buffer de l'action par défaut

Piste de standardisation du code

Bonnes pratiques
Composer : https://getcomposer.org/ gestion des dependances php et autoload
Norme php :
- PSR-1 PSR-1: Basic Coding Standard
- PSR-2 Coding Style Guide

Editeur de code opensource
- Visual Studio Code https://code.visualstudio.com/
- Atom https://atom.io/
  • avec des linter : des outils pour vérifier si le code respecte des standards
- Eclipse avec PDT (Php Development Tool)
  • contient un built-in formatter pour PSR-2

documentation