EnglishFrançais

Documentation pour miniGos v1

Copyright 1998-2012 - François Mizessyn - francois.mizessyn@orange.fr

Qu'est-ce que miniGos ?

MiniGos est un outil permettant de rejouer des parties ou des problèmes de go au format sgf dans une page web (miniGos est une version simplifiée du lecteur/éditeur sgf Gos).

Il est composé d'un ensemble de scripts php et javascript.

Vous pouvez utiliser miniGos gratuitement pour votre site (licence de type BSD).

Comment installer miniGos ?

MiniGos s'installe sur un serveur web disposant de php (version 5 ou ultérieure).

Il suffit de télécharger l'archive contenant miniGos, la décompresser et copier l'ensemble des dossiers et fichiers n'importe où dans l'arborescense des sites web en ayant besoin.

Une fois l'installation effectuée, vous pouvez tout de suite regarder un exemple de rejoueur de partie ou un exemple de rejoueur de problème pour vérifier que cela fonctionne.

L'utilisateur final n'a aucune installation à faire sur sa machine. Il doit uniquement avoir laissé javascript activé dans son navigateur.

Comment utiliser miniGos ?

Pour intégrer miniGos dans une page web, il suffit d'y insérer une ligne de php/html.

Eventuellement, on peut modifier la configuration (via un fichier de configuration php), ou le style de l'affichage (via u fichier css).

La ligne à insérer dans vos pages web

On inclut à l'endroit où doit s'afficher miniGos dans la page une ligne du genre :

<script type="text/javascript" src="_mGos/sgfreader.php?sgf=xxx.sgf"></script>

Il faut évidemment adapter le chemin préfixant le script php utilisé (ici "sgfreader.php"), que l'on appelle le lanceur, en fonction de l'endroit où vous avez installé miniGos sur votre site, et de l'endroit où se trouve votre page. Il s'agit du chemin relatif entre votre page et le script php du lanceur.

On peut ajouter autant de miniGos que l'on veut dans une page. On n'est limité que par les possibilités du serveur web et celles de la machine de l'utilisateur.

Le paramètre "sgf" de l'url du lanceur permet de spécifier le fichier sgf à lire.

Si le fichier est préfixé par un chemin, il est prudent d'utiliser la fonction php "urlencode()". Par exemple, si le fichier sgf est dans le répertoire parent du lanceur, on utilisera :

sgf=<?php print urlencode("../xxx.sgf"); ?>

Le chemin relatif à indiquer est celui entre le lanceur et le fichier qui est en paramètre (et non pas le chemin relatif entre le script de la page et le fichier qui est en paramètre).

Le fichier sgf peut être distant, et dans ce cas, on peut remplacer son nom par une url.

Par exemple :

sgf=<?php print urlencode("http://xxx.org/sgf/file.php?id=77"); ?>

Les lanceurs

MiniGos a deux lanceurs de base, sgfreader.php pour rejouer des parties (miniGos se contente d'afficher les coups de la partie), et sgfproblem.php pour rejouer des problèmes (l'utilisateur peut placer des coups sur le goban et miniGos y répond en fonction de ce qu'il lit dans le fichier sgf).

Voici un exemple de ligne complète pour rejouer une partie :

<script type="text/javascript" src="_mGos/sgfreader.php?sgf=<?php print urlencode("../Hon-1941-1.sgf"); ?>"></script>

Et voici un exemple de ligne complète pour rejouer un problème :

<script type="text/javascript" src="_mGos/sgfproblem.php?sgf=<?php print urlencode("../p1.sgf"); ?>"></script>

Les fichiers Sgf

On peut utiliser n'importe quel fichier sgf valide.

Si miniGos est employé comme rejoueur de partie, il n'affichera que les coups de la variation principale du sgf.

Si miniGos est employé comme rejoueur de problème, il considérera toutes les variations du sgf. Si l'une de ces variations est un coup en dehors de la partie visible du goban ou un passe, miniGos acceptera n'importe quel coup de l'utilisateur et le placera sur le goban. Ceci est utile quand on souhaite inclure dans le sgf une suite à jouer quelque soit le coup de l'utilisateur.

Configuration

Il est éventuellement possible de paramétrer miniGos en modifiant sa configuration.

Une configuration consiste en une série d'instructions php. Pour la configuration de rejoueur de partie, ces instructions sont dans le fichier _mgos/_cfg/reader.cfg. Pour la configuration de rejoueur de problème, elles sont dans le fichier _mgos/_cfg/problem.cfg.

Les informations de configuration sont stockées dans un tableau php ayant pour nom "$gosParam".

Pour indiquer à miniGos la valeur d'un paramètre, la ligne de code php à mettre dans un fichier de configuration est de la forme :

$gosParam["NomDeParametre"]="ValeurDuParametre";

Il faut bien faire attention aux majuscules et minuscules.

Par exemple, pour indiquer qu'on souhaite ne pas afficher une marque sur le dernier coup, on insérera la ligne :

$gosParam["markOnLastOn"]=0;

S'il s'agit d'une chaine de caractères, il ne faut pas oublier les guillemets. Par exemple :

$gosParam["initMethod"]="last";

Les paramètres que l'on peut modifier sont :

ParamètreNatureValeurs possiblesValeur par défautRejoueur de partieRejoueur de problème
initMethodAction initiale : aller au début du Sgf ("first") ou aller à la fin du Sgf ("last")."first" ou "last""last""last""first"
markOnLastOnS'il vaut 1, miniGos affiche une marque sur le dernier coup.0 ou 1010
in3dOnS'il vaut 1, miniGos affiche les pierres avec un effet 3d.0 ou 1011
stretchOnS'il vaut 1, le goban a une hauteur d'environ 10% supérieure à sa largeur.0 ou 1011
canUndoS'il vaut 1, miniGos ajoute un bouton "Reprendre un coup" (uniquement pour la configuration rejoueur de problème).0 ou 10-1

Note : pour changer le rayon des pierres, la couleur du fond et des lignes du goban, la taille et la couleur des icones dans les boutons, utilisez les css (voir ci-dessous).

Style

Un rejoueur miniGos est un ensemble de composants, chaque composant étant affiché dans un tag html <div>, l'ensemble étant affiché dans un <div> global ayant pour classe :

On peut personnaliser les styles des composants via des feuilles de style. Voici la liste des classes utilisées :

Classe Commentaire
mReaderGlobalBoxDiv ou mProblemGlobalBoxDiv <div> entourant le rejoueur
mGobanDiv <div> entourant le goban
mNavigationDiv <div> entourant les boutons de navigation pour le rejoueur de partie
mSolveDiv <div> entourant les boutons de navigation pour le rejoueur de problème
mCommentDiv <div> entourant les commentaires

La feuille de style pour le rejoueur de partie est reader.css, et celle pour le rejoueur de problème est problem.css.

Le goban est dessiné dans un canvas (<canvas></canvas>). Pour donner un style à ce canvas, utilisez "div.mGobanDiv canvas" dans une des feuilles de style.

Par exemple, pour que la couleur du goban soit #f00, celle de ses lignes #fff et le rayon des pierres 9 pixels pour le rejoueur de partie, utilisez :

.mReaderGlobalBoxDiv div.mGobanDiv canvas {background-color:#f00;color:#fff;font-size:12px;}

Les boutons de navigation sont de type button (<button><canvas></canvas></button> ou <button><span>...</span></button>). Pour changer le style des boutons, utilisez "div.mNavigationDiv button canvas" ou "div.mSolveDiv button span" dans une des feuilles de style.

Par exemple, pour changer la couleur des icones en rouge et leur taille à 12 pixels dans les boutons de navigation du rejoueur de partie, utilisez :

.mReaderGlobalBoxDiv div.mNavigationDiv button canvas {color:#f00;font-size:12px;}

Note : il est prudent d'imposer la couleur des icones même si l'on souhaite qu'elle soit noire, car la couleur par défaut d'un bouton peut varier selon le navigateur et le contexte (bouton désactivé par exemple).

Annexe 1 : tous les fichiers

Contenu du dossier "_mgos"

Annexe 2 : questions et réponses

Question : en partant de rien, que dois-je faire au minimum pour insérer un miniGos dans une page php ?

  1. Décompressez l'archive contenant miniGos (un fichier nommé "_miniGosnnn.zip" où nnn est la version de miniGos) : le contenu se retrouve dans un dossier nommé "_miniGos".
  2. Copiez tel quel le dossier "_miniGos" et tout ce qu'il contient dans le dossier racine du site (on peut le mettre n'importe où, mais il faut ensuite adapter les chemins indiqués dans la ligne à insérer dans la page qui contiendra le rejoueur miniGos).
  3. Supposons que la page devant contenir le rejoueur s'appelle "page1.php" et qu'elle est dans un sous-dossier du dossier racine du site nommé "_pages".
  4. Supposons que le fichier sgf à afficher est une partie qui s'appelle "partie1.sgf" et qu'il est dans un sous-dossier du dossier racine du site nommé "_sgf".
  5. Le chemin devant le lanceur doit être le chemin relatif entre la page devant contenir le rejoueur (ici "page1.php") et le lanceur (ici "sgfreader.php").
  6. Le chemin devant le fichier sgf (ici "partie1.sgf") doit être le chemin relatif entre le lanceur (ici "sgfreader.php") et le fichier sgf (ici "partie1.sgf").
  7. Insérez dans la page "page1.php" à l'endroit où vous voulez que le rejoueur apparaisse la ligne :
    <script type="text/javascript" src="../_miniGos/_mgos/sgfreader.php?sgf=<?php print urlencode("../_sgf/partie1.sgf"); ?>"></script>
  8. Et voilà !

Question : avec quels navigateurs miniGos fonctionne-t-il ?

MiniGos devrait fonctionner avec Firefox (v4 et postérieure), Safari (v5 et postérieure), Internet Explorer (v9 et postérieure), Chrome. Il ne fonctionne pas avec Internet Explorer v8 ou antérieures.

Question : miniGos peut-il afficher sur le goban des indices, la numérotation, les marques, les variations... ?

MiniGos v1 se veut rudimentaire. Il ne peut pas faire tout ça. Si vous avez ce besoin, utilisez plutôt miniGos v2 ou gos !