EnglishFrançais

Documentation pour maxiGos v6.48

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

Qu'est-ce que maxiGos ?

MaxiGos est un outil permettant d'insérer des parties ou des problèmes de go enregistrés au format sgf dans une page web. Il peut être utilisé d'une multitude de manières différentes, comme lecteur avec ou sans commentaires, éditeur, n'afficher que la position finale de la variante principale, ...

Il est composé d'un ensemble de scripts en php et javascript, et de feuilles de style css.

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

Quels sont les prérequis ?

Le navigateur de l'utilisateur final doit pouvoir interpréter du HTML5 (c'est le cas de nombreux navigateurs en 2014).

Si on utilise uniquement les lecteurs autonomes de maxiGos, il n'y a aucun prérequis en ce qui concerne le serveur sur lequel il est installé.

Si on utilise la version complète de maxiGos, le serveur sur lequel il est installé doit disposer de php version 5 ou postérieure.

Comment installer maxiGos ?

Il suffit de télécharger l'archive contenant maxiGos, la décompresser et copier l'ensemble des dossiers et fichiers n'importe où dans l'arborescense de votre site. Aucune base de données n'est nécessaire.

Une fois l'installation effectuée, recherchez sur votre site la page "_maxigos/fr/documentation.php" (il s'agit de la même page que celle-ci, mais stockée sur votre site) et regardez les exemples suivants pour vérifier que cela fonctionne :

• Lecteurs autonomes "minimalistes" avec différents styles : 1, 2, 3, 4, 5, 6
• Lecteurs autonomes "classiques" sans personnaliation

• Lecteur basique
• Rejoueur de problème
• Affichage de diagramme ou figure
• Lecteur avec cartouche
• Affichage en boucle
• Lecteur avec commentaire
• Lecteur avec commentaire et arbre des coups
• Editeur de fichier sgf
• Rejoueur de leçon
• Affichage d'un kifu
• Texture
• Ambiance minimaliste
• Ambiance réaliste
• Ambiance japonaise
• Ambiance chinoise
• Ambiance rfg.jeudego.org
• Lecteur façon eidogo
• Ambiance forum.jeudego.org
• Ambiance tsumego.org, ancien style
• Ambiance tsumego.org, nouveau style
• Ambiance fm
• Ambiance tactigo.free.fr
• Ambiance en noir et blanc 1
• Ambiance en noir et blanc 2
• Version Tiger
• Kifu manuscrit
• Iroha, kifu à l'ancienne
• St Valentin
• Couleurs de carte à jouer
• Lecteur alternatif (sans HTML5)
• Règle du go
• Fancy go

• Méthodes variées pour inclure du sgf
• Lanceur multiple
• Tests de charset

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

Comment utiliser maxiGos ?

Langue

La langue par défaut utilisée par maxiGos est le français. Si vous utilisez maxiGos uniquement dans cette langue, vous n'avez pas besoin de lire le reste de ce chapitre.

Vous pouvez changer cette langue par défaut pour l'anglais en incluant la ligne suivante avant tout appel à maxiGos :

<script>mxG={L:"en"};</script>

Si vous ne pouvez pas ou ne souhaitez pas à avoir à insérer cette ligne dans chacune de vos pages, vous pouvez simplement ajouter if (typeof mxG=='undefined') mxG={};mxG.L="en"; au début de "_mgos/_js/mgos_lib.js" (si vous utilisez la version complète de maxiGos) et au début des scripts javascript dans "_alone" (seulement si vous les utilisez explicitement dans vos pages).

Pour une autre langue, incluez avant tout appel à maxiGos un script de traduction pour cette autre langue. Par exemple, pour le japonais, incluez le script "mgos-loc-ja.js" qui se trouve dans "_local/" (remplacez "ppp" par un chemin relatif entre votre page et le dossier "_maxigos") via  :

<script src="ppp/_local/mgos-loc-ja.js"></script>

Si vous ne pouvez pas ou ne souhaitez pas à avoir à insérer cette ligne dans chacune de vos pages, vous pouvez simplement ajouter le code contenu dans le script de traduction correspondant à la langue choisie au début de "_mgos/_js/mgos_lib.js" (si vous utilisez la version complète de maxiGos) et au début des scripts javascript se trouvant dans un dossier "_alone" (seulement si vous les utilisez explicitement dans vos pages). Le script "addLocalization.php" peut effectuer cette tache pour vous automatiquement (une aide est fournie dans le script lui-même).

Tous les scripts de traduction fournis avec maxiGos sont dans le dossier "_local". Si le script de traduction n'existe pas encore, vous pouvez essayer d'en créer un (inspirez-vous de celui du japonais). Vous pouvez aussi jeter un coup d'oeil aux "Questions et réponses" pour en savoir plus à ce propos.

Note 1 : tous les lecteurs maxiGos d'une page doivent utiliser la même langue.

Note 2 : si vous créez un fichier de traduction, c'est une bonne pratique de choisir un code langue qui soit ISO 639.

Note 3 : quand on utilise un lanceur (voir le chapitre sur les lanceurs plus loin dans ce document) le plus simple est de garder le français comme langue par défaut et d'utiliser le paramètre "mxL" dans l'URL du lanceur pour changer la langue.

Méthode utilisant un "lecteur autonome" en javascript

On utilisera un lecteur autonome dans les cas où on souhaite faire simple.

Le principe est d'inclure un script javascript unique qui contient tout le code nécessaire à chaque endroit de la page où doit s'afficher un lecteur.

Le code à insérer dans vos pages

On insère un couple de balises <script> et </script> dans la page à l'endroit où doit s'afficher le lecteur sgf, avec comme valeur de l'attribut "src" le script de l'un des lecteurs autonomes fournis avec maxiGos.

Ces lecteurs ont chacun une utilisation spécifique. Les scripts correspondants aux configurations classiques de maxiGos, regroupés dans le dossier "_alone", sont :

• maxigos-basic.js (lecteur basique)
• maxigos-comment.js (lecteur avec commentaire)
• maxigos-diagram.js (lecteur affichant un diagramme ou une figure)
• maxigos-edit.js (éditeur)
• maxigos-game.js (lecteur avec cartouche)
• maxigos-kifu.js (lecteur qui affiche un kifu)
• maxigos-problem.js (lecteur rejouant un problème)
• maxigos-tree.js (lecteur avec commentaire et arbre des coups)

D'autres lecteurs autonomes sont disponibles dans les dossiers "_alone" de certains exemples fournis avec maxiGos.

Par exemple, on inclut à l'endroit où doit s'afficher maxiGos dans la page web un code du genre :

<script src="ppp/maxigos-problem.js">
(;FF[4]CA[UTF-8]GM[1]SZ[19]VW[aa:lh]
EV[N° 1 .|. Niveau 1]
FG[1]ST[2]
AW[ab][bb][cb][db][da]
AB[bc][cc][dc][ec][eb][gb][be]
C[À Noir de jouer]
;B[ba]C[Correct !])
</script>

Il faut évidemment adapter le chemin (ici "ppp/") préfixant le script "maxigos-problem.js", en fonction de l'endroit où vous l'avez installé sur votre site, et de l'endroit où se trouve votre page. Il s'agit du chemin relatif entre votre page et le script javascript du lecteur autonome.

Rappel : par défaut, ces lecteurs maxiGos sont en français. Si vous souhaitez utilisez une autre langue, ajoutez au début de leurs fichiers le contenu du script de traduction (un certain nombre sont dans le dossier "_local/") correspondant à cette autre langue. À noter que pour l'anglais, il suffit d'ajouter if (typeof mxG=='undefined') mxG={};mxG.L="en";. Relisez le chapitre "Langue" ci-dessus pour plus d'information à ce sujet.

Note 1 : il est possible d'indiquer un nom de fichier sgf (mais pas une url pouvant générer du sgf) au lieu d'un enregistrement sgf entre les balises <script> et </script>.

Note 2 : il est possible pour un utilisateur avancé de fabriquer un lecteur autonome à l'aide de la fonction "makeAlone" du script php "_mgos/_php/GGosLib.php" (voir le script "aloneMaker.php" dans le dossier "_alone/").

Note 3 : pour faire fonctionner les lecteurs autonomes, on n'a pas besoin d'installer l'ensemble de maxiGos sur le serveur. Il suffit d'y copier le script du lecteur choisi. Si on utilise une langue autre que le français ou l'anglais, on aura besoin des scripts de traduction (ceux qui sont dans le dossier "_local").

Note 4 : en théorie, un lecteur autonome ne peut pas utiliser de ressources externes (scripts, images, ...). Lorsqu'une ressource externe est manquante, un lecteur autonome fonctionne comme ci-dessous :
s'il y a un bouton "Kifu", il est caché (pour le faire ré-apparaitre, il faut déposer sur le serveur le script "_alone/maxigos-kifu.js", en supposant que le lecteur est dans le dossier où il a été fabriqué. On peut mettre le script et le lecteur ailleurs, mais dans ce cas, il faut adapter en conséquence la ligne mxG.D[mxG.K]._alone="../_alone/"; dans le code du lecteur autonome pour que celui-ci puisse retrouver où est le script "maxigos-kifu.js"),
s'il y a un bouton "Aide", il est caché (pour le faire ré-apparaitre, il faut déposer sur le serveur un fichier d'aide approprié dans "_help/", en supposant que le lecteur est dans le dossier où il a été fabriqué. On peut mettre le fichier d'aide et le lecteur ailleurs, mais dans ce cas, il faut adapter en conséquence la ligne mxG.D[mxG.K]._help="../_help/"; dans le code du lecteur autonome pour que celui-ci puisse retrouver où est le fichier d'aide).

Personnalisation des lecteurs autonomes

La personnalisation de ces lecteurs peut être faite en utilisant des attributs dans la balise <script>.

Pratiquement tout peut être modifié en utilisant les attributs. Le nom de ces attributs est de la forme "data-maxigos-xxx" avec "xxx" le nom d'un paramètre de maxiGos (voir le chapitre "Paramétrage des composants" pour en savoir plus sur ces paramètres). Du fait que seuls les lettres en minuscule sont permises dans le nom des attributs, on remplace les majuscules des noms des paramètres maxiGos par leurs équivalents en minuscule précédés d'un "-". Par exemple, l'attribut correspondant au paramètre maxiGos "in3dOn" sera "data-maxigos-in3d-on".

Par exemple, pour afficher un diagramme sans effet 3D et avec un goban transparent :

<script src="../../_alone/maxigos-diagram.js" data-maxigos-in3d-on="0" data-maxigos-goban-bk="transparent">
(;FF[4]CA[UTF-8]GM[1]SZ[19]VW[al:ls]
AB[cp]ST[2]FG[1]
;W[ep];B[eq];W[fq];B[dq];W[fp];B[cn];W[jp])
</script>

On peut aussi personnaliser les lecteurs en modifiant leur feuille de style (comme pour la couleur du fond du goban de l'exemple ci-dessus). Mais les modifications s'appliqueront alors à l'ensemble des lecteurs de la même sorte.

Méthode utilisant un "lanceur" en php

Il s'agit d'une méthode plus sophistiquée que celle utilisant les lecteurs autonomes, mais qui n'a aucune limite en terme de présentation et de fonctionnalité.

On insère une ligne de php/html dans la page à l'endroit où doit s'afficher le lecteur sgf, qui décenche l'exécution d'un script php qui lui-même va générer un script javascript contenant le code du lecteur, en fonction d'informations contenues dans un fichier de configuration.

La ligne à insérer dans vos pages web

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

<script src="ppp/_mgos/sgfplayer.php?sgf=xxx.sgf&cfg=yyy.cfg&mxL=zz"></script>

Il faut évidemment adapter le chemin (ici "ppp/") préfixant le script "_mgos/sgfplayer.php", que l'on appelle le lanceur, en fonction de l'endroit où vous avez installé maxiGos 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. MaxiGos est fourni avec un lanceur, sgfPlayer.php, qui suffit dans la plupart du temps. Ce lanceur est dans le dossier "_mgos" de maxiGos. L'url de ce lanceur peut avoir quatre paramètres : "sgf", "cfg", "mxL" et "plc", qui sont tous optionnels (voir ci-dessous pour plus d'informations sur ces paramètres).

On peut ajouter autant de maxiGos 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"

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

Note : au lieu d'utiliser ce paramètre "sgf", on peut aussi simplement insérer du sgf ou le nom d'un fichier sgf entre les balises <script> et </script>, ou spécifier le nom d'un fichier sgf comme valeur de l'attribut "data-sgf-file" de la balise <script>.

Si aucun sgf n'est spécifié via l'une des méthodes ci-dessus, maxiGos affichera un goban 19x19 vide.

Le fichier sgf peut être n'importe où. Si le nom du 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 dossier parent du dossier où se trouve le lanceur, on utilisera :

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

Le chemin relatif à indiquer est celui entre le lanceur et le fichier sgf (et non pas le chemin relatif entre le script de la page et le fichier sgf).

Le fichier sgf peut être distant, et dans ce cas, on peut remplacer son nom par une url (vérifiez si votre serveur web accepte cela : ce n'est pas toujours le cas).

Par exemple :

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

Enfin, on peut aussi simplement ajouter un enregistrement sgf comme valeur du paramètre.

Par exemple :

sgf=<?php print urlencode("(;FF[4]CA[UTF-8]GM[1]SZ[19];B[qd])");?>

Tout code sgf valide peut être utilisé. Notez que cette méthode ne fonctionne qu'avec des petits enregistrements sgf, car en pratique les url ne peuvent pas être infiniment longues (la longueur maximum dépend du paramétrage des serveurs webs et des navigateurs utilisés).

Le paramètre "cfg"

Le paramètre "cfg" de l'url du lanceur permet de spécifier le fichier de configuration à utiliser.

Si le paramètre "cfg" n'est pas présent dans l'url, maxiGos fonctionnera en tant que "Lecteur basique" (dont le fichier de configuration est "_cfg/basic.cfg").

Le fichier de configuration peut être n'importe où, mais ceux livrés avec maxiGos sont dans le dossier "_cfg" qui est un sous-dossier de celui où se trouve sgfplayer.php.

Si le nom du fichier est préfixé par un chemin, il est prudent d'utiliser la fonction php "urlencode()". Par exemple, si le fichier de configuration est dans le dossier parent du dossier où se trouve le lanceur, on utilisera :

cfg=<?php print urlencode("../yyy.cfg");?>

Un certain nombre de fichiers de configuration dits "classiques" sont livrés avec maxiGos. Testez-les :

• "_cfg/basic.cfg" (voir l'exemple "lecteur basique")
• "_cfg/problem.cfg" (voir l'exemple "rejoueur de problème")
• "_cfg/diagram.cfg" (voir l'exemple "affichage de diagramme ou figure")
• "_cfg/game.cfg" (voir l'exemple "lecteur avec cartouche")
• "_cfg/comment.cfg" (voir l'exemple "lecteur avec commentaire")
• "_cfg/tree.cfg" (voir l'exemple "lecteur avec commentaire et arbre des coups")
• "_cfg/edit.cfg" (voir l'exemple "éditeur de fichier sgf")
• "_cfg/lesson.cfg" (voir l'exemple "rejoueur de leçon")
• "_cfg/kifu.cfg" (voir l'exemple "affichage d'un kifu")
• "_cfg/loop.cfg" (voir l'exemple "affichage en boucle")

Vous pouvez aussi vous inspirer des fichiers de configuration des autres exemples qui sont plus complexes.

Le paramètre "plc"

Le paramètre "plc" de l'url du lanceur permet de spécifier l'identifiant d'une balise dont le contenu est éventuellement du sgf ou le nom d'un fichier sgf. Si c'est bien le cas, ce contenu est remplacé par un lecteur maxiGos qui affiche ce contenu.

Le paramètre "mxL"

Le paramètre "mxL" de l'url du lanceur permet de spécifier la langue utilisée par maxiGos.

Les valeurs de "mxL" sont un code langue sur deux caratères : "en" pour anglais, "fr" pour français...

Si le paramètre "mxL" n'est pas présent dans l'url, maxiGos fonctionnera en français.

Attention : tous les maxiGos d'une même page doivent fonctionner dans la même langue !

Note pour les candidats traducteurs : dans le code de maxiGos, tout ce qui peut être traduit est stocké dans un tableau unique javascript nommé mxG.Z, dont les valeurs sont définies au début de chaque script javascript, sauf les fichiers d'aide.

Personnalisation des lecteurs insérés par un lanceur

Comme pour les lecteurs autonomes, on peut personnaliser un lecteur inséré par un lanceur en utilisant des attributs de la forme "data-maxigos-xxx" dans la balise où s'affiche ce lecteur (voir le chapitre "Personnalisation des lecteurs autonomes" pour plus de détails).

Méthode utilisant un "chargeur" en javascript

Cette méthode permet de ne pas avoir à insérer le code de maxiGos à chaque endroit de la page où doit s'afficher un lecteur. Elle est par contre sensiblement plus lente que les précédentes. Il est conseillé de ne l'utiliser que si aucune des deux méthodes précédentes n'est possible.

On insère dans une page web aux endroits où l'on souhaite afficher un lecteur des balises <div> et </div> dont l'un des attributs est "data-maxigos". La valeur de cet attribut est le nom d'une configuration de maxiGos. Le nom du fichier de configuration correspondant étant la concaténation de la valeur de "_cfg/", qui est la valeur par défault du dossier contenant les fichiers de configuration (ce qui signifie que les fichiers de configuration sont supposés être dans "_maxigos/_mgos/_cfg"), suivi du nom de la configuration suivi de ".cfg". Et l'on insère le sgf (ou le nom d'un fichier sgf, mais pas une url pouvant générer du sgf) entre ces balises <div> et </div>.

On insère ensuite le script "mgosLoader.js", que l'on appelle le chargeur (qui lui-même appelle un lanceur spécial "sgfmultipleplayer.php"), après toutes les balises <div> et </div> dont l'un des attributs est "data-maxigos".

Par exemple :

<div data-maxigos="problem">
(;FF[4]CA[UTF-8]GM[1]SZ[19]VW[aa:lh]
EV[N° 1 .|. Niveau 1]
FG[1]ST[2]
AW[ab][bb][cb][db][da]
AB[bc][cc][dc][ec][eb][gb][be]
C[À Noir de jouer]
;B[ba]C[Correct !])
</div>
<div data-maxigos="problem">
(;GM[1]FF[4]ST[2]SZ[19]VW[aa:lh]
EV[N° 2 .|. Niveau : 1]
AW[da][ea][fb][dc][ec][fc][ad][bd][cd]
AB[ba][cb][db][eb][ac][bc][cc]
C[À Noir de jouer]
;B[ab]C[Correct !])
</div>
<script src="ppp/_mgos/mgosLoader.js"></script>

Il faut évidemment adapter le chemin (ici "ppp/") préfixant le script "_mgos/mgosLoader.js", en fonction de l'endroit où vous avez installé maxiGos sur votre site, et de l'endroit où se trouve votre page.

Eventuellement, pour utiliser un fichier de configuration qui n'est pas dans le dossier par défaut "_cfg/", on préfixe la valeur du paramètre "data-maxigos" par un chemin relatif entre le dossier "_cfg/" et le dossier où se trouve le fichier de configuration. Par exemple, si l'on souhaite utiliser le fichier de configuration "minimalComment.cfg" qui se trouve dans "_maxigos/_sample/minimal/_cfg" :

<div data-maxigos="../_sample/minimal/_cfg/minimalComment">

Eventuellement, pour changer la langue par défaut (qui est le français), on insère avant le script "mgosLoader.js" un script de traduction correspondant à la langue choisie. Par exemple, pour le japonais, on peut inclure le script "mgos-loc-ja.js" se trouvant dans "_local/" (remplacez "ppp" par le chemin relatif entre votre page et le dossier "_mgos") :

<script src="ppp/_local/mgos-loc-ja.js"></script>

Personnalisation des lecteurs insérés par un chargeur

Comme pour les lecteurs autonomes, on peut personnaliser un lecteur inséré par un chargeur en utilisant des attributs de la forme "data-maxigos-xxx" dans la balise où s'affiche ce lecteur (voir le chapitre "Personnalisation des lecteurs autonomes" pour plus de détails).

Utilisation avancée

Ce qui suit ne concerne que les utilisateurs avancés qui voudraient modifier certaines parties de maxiGos.

Lanceur sur mesure

Dans la plupart des cas, "sgfplayer.php" suffit comme lanceur. Mais on peut avoir besoin dans certains cas de se créer son propre lanceur. Un tel lanceur doit contenir l'instruction header("content-type: application/x-javascript;charset=UTF-8");, inclure le script "GGosLib.php" qui est dans le dossier "_mgos_php" de maxiGos via une instruction du type include("ppp/GGosLib.php"); où ppp est le chemin relatif entre le lanceur et "CGosLib.php", et appeler la fonction php "gosStart()". Celle-ci est définie dans "GGosLib.php".

La fonction "gosStart()" a pour but de générer un script javascript qui sera exécuté par le navigateur de l'utilisateur.

Cette fonction prend plusieurs paramètres. Le premier paramètre est le sgf à utiliser, le deuxième un fichier de configuration, le troisième un code langue, le quatrième un switch qui s'il vaut 1 indique qu'il ne faut pas inclure les fichiers css et js de la configuration dans la page, le cinquième l'identifiant d'un couple de balises de la page.

La fonction renvoie une chaine de caractère contenant le script javascript généré.

Un appel à gosStart() sera par exemple print gosStart($sgf,$cfg,$lang,0,"");".

$sgf contient le nom d'un fichier sgf, ou l'url d'un fichier sgf, ou encore une chaine de caractères représentant un enregistrement sgf (correspond au paramètre "sgf" de l'url du lanceur "sgfplayer.php"), $cfg le nom d'un fichier de configuration (correspond au paramètre "cfg" de l'url du lanceur "sgfplayer.php"), et $lang un code langue, comme "fr" (français) ou "en" (anglais) (correspond au paramètre "mxL" de l'url du lanceur "sgfplayer.php").

Si le quatrième paramètre vaut 1, maxiGos n'inclut aucun fichier css ou js dans le script javascript généré. Cela permet de réduire la taille du code en cas de présence de plusieurs lecteurs maxiGos de même configuration dans une même page. Il ne peut bien évidemment être utilisé qu'à partir du deuxième lecteur de la page, et à condition que le premier lecteur soit de même configuration.

Le cinquième paramètre contient éventuellement l'identifiant d'un élément HTML contenant éventuellement du sgf, et destiné à contenir un lecteur maxiGos (correspond au paramètre "plc" de l'url du lanceur "sgfplayer.php"). En pratique, il est rarement utilisé et on lui donne la valeur "", qui signifie que le lecteur s'affichera dans la balise du script ayant déclenché l'exécution de "gosStart()". Il est par contre essentiel si on utilise un chargeur tel que "mgosLoader.js".

On peut donner n'importe quel nom à ce lanceur.

Certains exemples fournis avec maxiGos ont leur propre lanceur. Inspirez-vous en !

Les composants

Le code de maxiGos a été découpé en composants, chaque composant correspondant à une partie du lecteur. Par exemple le goban, la boite à commentaire, ou la barre de navigation sont des composants.

La liste des composants d'un lecteur se définit dans son fichier de configuration.

Liste des composants prédéfinies

• "BackToMain" (bouton qui permet de revenir au coup le plus proche dans la variation principale et qui n'a pas été ajouté par l'utilisateur),
• "Comment" (boite à commentaire simple, où s'affiche le contenu de la propriété sgf C et éventuellement un contenu généré par le composant "Header"),
• "Cut" (bouton pour supprimer une branche, ne doit pas être utiliser avec le composant "Edit"),
• "Diagram" (fonctions d'affichage des indices, de la numérotation, des marques et des étiquettes sur le goban),
• "Edit" (fonctions d'édition pour créer ou modifier un fichier sgf, à utiliser avec "Info" et "Menu"),
• "File" (fonctions pour créer, ouvrir, fermer, enregistrer ou envoyer par email un fichier sgf, à utiliser avec "Sgf" et éventuellement "Menu"),
• "Goban" (goban où s'affiche le contenu des propriétés sgf B, W, AB, AW, AE, LB, MA, CR, SQ, TR, TB, TW, ST, PL, et FG),
• "Goto" (fonctions de déplacement pour changer le coup courant, via une barre de déplacement, ou un champ de saisie du numéro du coup, ou en cliquant sur une pierre du goban).
• "Guess" (fonction de devinette de l'un des coups suivants, et barre d'affichage du résultat),
• "Header" (bouton et boite d'entête, où s'affiche le contenu des propriétés sgf EV, RO, PB, PW, BR, WR, DT, PC, RU, TM, KM, HA, RE et GC),
• "Help" (bouton et boite d'affichage de l'aide),
• "Image" (bouton pour générer une image png),
• "Info" (formulaire de modification des propriétés sgf EV, RO, DT, PC, PB, PW, BR, WR, KM, HA, RE, GC, AN, CP, SO, US, RU, TM, OT, ON, BT, WT, GN),
• "Lesson" (boite à commentaire sous forme de bulle avec un assistant, où s'affiche le contenu des propriétés sgf C, BM, DO, IT et TE),
• "Kifu" (bouton pour générer un kifu, a besoin du composant "sgf"),
• "Loop" (boutons d'affichage en boucle),
• "Menu" (gestionnaire de menu, à utiliser avec au moins l'un des composants suivants : "File", "Edit" et "View"),
• "MoveInfo" (indicateur de la couleur, du numéro, et des coordonnés du dernier coup),
• "Navigation" (boutons permettant de naviguer d'un coup à un autre),
• "NotSeen" (boite listant les coups numérotés déjà joués qui ne sont plus visibles sur le goban, avec leurs coordonnées), a besoin du composant "Diagram"
• "Options" (panneau d'options, pour modifier la numérotation, l'affichage d'une marque sur le dernier coup,...),
• "Pass" (bouton de passe),
• "Sgf" (bouton et boite d'affichage du sgf),
• "Solve" (boutons "recommencer tout" et "reprendre un coup", et affichage d'une réponse au coup de l'utilisateur, à utiliser pour les rejoueurs de problème),
• "Speed" (barre de réglage de la vitesse d'affichage des coups, à utiliser en conjonction avec "Loop"),
• "Title" (titre, où l'on affiche le contenu des propriétés sgf EV et RO),
• "Tree" (arbre des coups),
• "Variations" (affichage et éventuellement ajout des variations sur le goban ou dans la boite du composant),
• "Version" (affichage de la version de maxiGos).
• "View" (fonction pour modifier l'affichage, éventuellement à utliser avec "Menu").

On n'est pas obligé d'utiliser tous les composants, et seul "Goban" est obligatoire.

En utilisant uniquement les composants dont on a vraiment besoin pour une utilisation donnée, on diminue parfois considérablement la taille du code qui sera téléchargé sur la machine de l'utilisateur, et donc le temps que mettra maxiGos à démarrer.

Utiliser un composant prédéfini

Les codes des composants est écrit en javascript.

Les codes des composants sont dans des fichiers ayant un nom de la forme "mgosNomDuComposant.js".

Pour pouvoir utiliser des composants, il faut soit ajouter dans un fichier de configuration des lignes du type $gosParam["Script"][]="mgosNomDuComposant.js"; (simple et suffisant dans la plupart des cas), soit ajouter les fichier javascript correspondants directement dans la partie "head" de la page via des lignes comme <script src="chemin/mgosNomDuComposant.js"></script> (quand on le peut, c'est mieux car plus efficace).

Si l'on veut utiliser les composants "Comment" et "Navigation" par exemple (en plus du composant "Goban" évidemment), on ajoutera leurs codes, ainsi que les fichiers "mgos_lib.js", "mgos_rls.js", "mgos_prs.js", et "mgos.js" qui sont des fichiers communs qu'il faut ajouter dans toutes les configurations, en utilisant l'une ou l'autre (mais pas les deux) des méthodes suivantes :

• Soit on ajoute les lignes suivantes dans un fichier de configuration :

  $gosParam["Script"][]="mgos_lib.js"; // fonctions communes à tous les composants
  $gosParam["Script"][]="mgos_rls.js"; // gestion de la règle
  $gosParam["Script"][]="mgos_prs.js"; // parser sgf
  $gosParam["Script"][]="mgos.js"; // code de base de maxiGos
  $gosParam["Script"][]="mgosGoban.js"; // composant "Goban"
  $gosParam["Script"][]="mgosComment.js"; // composant "Comment"
  $gosParam["Script"][]="mgosNavigation.js"; // composant "Navigation"

• Soit on ajoute les lignes suivantes dans la partie head de la page (en supposant que le chemin entre le fichier source de la page et le dossier "_js" de maxiGos est "../../_mgos/_js") :

  <script src="../../_mgos/_js/mgos_lib.js"></script> <!-- fonctions communes à tous les composants -->
  <script src="../../_mgos/_js/mgos_rls.js"></script> <!-- gestion de la règle -->
  <script src="../../_mgos/_js/mgos_prs.js"></script> <!-- parser sgf -->
  <script src="../../_mgos/_js/mgos.js"></script> <!-- code de base de maxiGos -->
  <script src="../../_mgos/_js/mgosGoban.js"></script> <!-- composant "Goban" -->
  <script src="../../_mgos/_js/mgosComment.js"></script> <!-- composant "Comment" -->
  <script src="../../_mgos/_js/mgosNavigation.js"></script> <!-- composant "Navigation" -->
  

On peut aussi créer ses propres composants qu'il faut alors définir dans un fichier javascript du même genre que pour les composants prédéfinis.

Dans ce fichier il suffira de définir les fonctions "createNomDuComposant()", appelée par maxiGos lors du chargement de la page, "initNomDuComposant()" appelée par maxiGos juste après le chargement de la page, "updateNomDuComposant()" appelée par maxiGos après chaque action de l'utilisateur, et "refreshNomDuComposant()" appelée en boucle (par défaut une fois par seconde). Il faut déclarer ces fonctions en tant que prototype pour la classe "mxG.G" (qui est définie par ailleurs dans "mgos.js"). Par exemple, si l'on souhaite créer un composant appelé "Cute" dont l'unique action est d'afficher lors du chargement de la page la phrase "Je suis là !", le code correspondant sera :

mxG.G.prototype.createCute=function()
{
document.write("<p>Je suis là !</p>");
};

La définition de "createNomDuComposant()" est obligatoire, mais la définition des autres fonctions est facultative.

Il faut enfin déclarer ces fichiers javascript dans le fichier de configuration comme pour les composants prédéfinis par une ligne du type :

$gosParam["Script"][]="NomDuFichierContenantLeComposant.js";

"NomDuFichierContenantLeComposant" peut être n'importe quel nom. Il n'a pas besoin d'être préfixé par "mgos" ni même de contenir le nom du composant.

Par défaut, maxiGos considère que les fichiers javascript définissant les composants sont dans le dossier "_mgos/_js". Mais on peut les mettre ailleurs, et dans ce cas, il convient de préfixer le nom de ces fichiers javascript déclarés dans les fichiers de configuration par un chemin relatif entre le dossier "_mgos/_js" et le dossier où ils sont stockés.

Important : ne pas oublier d'ajouter dans tous les cas les fichiers "mgos_lib.js", "mgos_rls.js", "mgos_prs.js" et "mgos.js".

Les boites contenant les composants

Pour que le code du composant soit exécuté (qu'il soit prédéfini ou non), il faut aussi ajouter une ligne de code php dans un fichier de configuration de la forme :

$gosParam["NomDeBoite"][]="NomDeComposant";

"NomDeBoite" est l'identifiant d'une boite qui finit obligatoirement par "Box" (par exemple "XxxBox", "Xxx" pouvant être toute chaine de caractères alplanumériques). Une boite sert à regrouper les composants de maxiGos (essentiellement pour faciliter la mise en page).

"NomDeComposant" est le nom d'un des composants pouvant être utilisé par maxiGos.

Á chaque fois qu'un nouveau nom de boite est rencontrée dans le fichier de configuration, maxiGos insère dans votre page un <div class="gosNomDeBoiteDiv" id="identifiantObjetNomDeBoiteDiv">. Ensuite, chaque instruction du fichier de configuration déclarant un composant a pour effet d'inclure le composant ayant pour nom "NomDeComposant" dans le code html de la page, entre les balise <div> et </div> de la boite ayant pour nom "NomDeBoite", et dans l'ordre dans lequel ces instructions sont placées dans le fichier de configuration. On peut évidemment avoir plusieurs composants par boite, puisque les boites ont pour fonction première de regrouper les composants.

Les identifiants des objets (appelés "identifiantObjet") sont de la forme "d" + un numéro qui est incrémenté automatiquement de 1 à chaque nouvel objet maxiGos inséré dans une page, le premier objet maxiGos de la page ayant le numéro 1.

Par exemple, le goban du deuxième objet maxiGos d'une page est dans la boite :

<div class="mxGobanDiv" id="d2GobanDiv">...</div>

Voici un exemple de ce que ça peut donner en pratique (ici, on utilise trois composants : "Goban", "Navigation" et "Comment") :

<?php
$gosParam["Script"][]="mgos_lib.js";
$gosParam["Script"][]="mgos_rls.js";
$gosParam["Script"][]="mgos_prs.js";
$gosParam["Script"][]="mgos.js";
$gosParam["Script"][]="mgosGoban.js";
$gosParam["Script"][]="mgosNavigation.js";
$gosParam["Script"][]="mgosComment.js";

$gosParam["LeftBox"][]="Goban";
$gosParam["LeftBox"][]="Navigation";
$gosParam["RightBox"][]="Comment";
?>

Un composant peut ne pas avoir de boite d'affichage dédiée (cas par exemple d'un composant qui se contenterait de modifier l'affichage du goban), voire même n'effectuer aucun affichage. Si on veut en utiliser un, il faudra néanmoins le déclarer dans un fichier de configuration via une ligne du type "$gosParam["NomDeBoite"][]="NomDeComposant";" afin que maxiGos puisse savoir à quel moment il conviendra d'exécuter les actions qui y sont définies.

Paramétrage des composants

Un composant peut être paramétré via les fichiers de configuration.

Pour indiquer à maxiGos la valeur d'un paramètre, la ligne de code php à placer 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 afficher une marque sur le dernier coup, on insérera la ligne :

$gosParam["markOnLastOn"]=1;

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

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

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 de préférence les css (voir le chapitre "Style").

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

Paramètres généraux

Composant "Comment"

Composant "Edit"

Composant "Diagram"

Composant "File"

Composant "Goban"

Note : pour changer le rayon des pierres, la meilleure manière est d'utiliser les css : ce rayon est égal au 3/4 environ de la valeur de la propriété "font-size" du tag HTML dans lequel est dessiné le goban (voir le chapitre "Style"). Ceci permet d'harmoniser plus facilement ce rayon avec la taille des caractères affichés sur le goban dans tous les cas (comme par exemple celui où un utilisateur fait un "zoom texte seulement" dans son navigateur.

Composant "Goto"

Composant "Guess"

Composant "Header"

Note 1 : si headerBoxOn et headerBtnOn vallent tous les deux 0, maxiGos n'affiche pas du tout la boite du composant "mxHeaderDiv" (mais il peut bien sûr afficher le contenu du composant ailleurs comme par exemple dans la boite à commentaire si "headerInComment" vaut 1).

Note 2 : la différence entre le composant "Header" et le composant "Info" est que le composant "Header" ne fait qu'afficher les informations tandis que le composant "Info" permet de les modifier.

Composant "Help"

Composant "Info"

Note 1 : si infoBoxOn et infoBtnOn vallent tous les deux 0, maxiGos n'affiche pas du tout la boite du composant "mxInfoDiv" (mais on pourra quand même afficher le formulaire de modification des informations via l'outil "Entête" du composant "Edit").

Note 2 : la différence entre le composant "Header" et le composant "Info" est que le composant "Header" ne fait qu'afficher les informations tandis que le composant "Info" permet de les modifier.

Composant "Lesson"

Composant "Loop"

Composant "Menu"

Composant "Navigation"

Composant "NotSeen"

Composant "Options"

Composant "Pass"

Composant "Sgf"

Composant "Solve"

Composant "Title"

Composant "Tree"

Composant "Variations"

Composant "Version"

Composant "View"

Les feuilles de style

Généralités

MaxiGos est livré avec quelques feuilles de style, mais souvent, on préfèrera utiliser des feuilles de style personnalisées.

On pourra les inclure soit en ajoutant dans les fichiers de configuration une ligne du genre $gosParam["Style"][]="xyz.css"; (simple et suffisant dans la plupart des cas), soit les inclure dans la partie "head" de la page via une ligne comme <link rel="stylesheet" type="text/css" href="chemin/xyz.css"> (quand on le peut, c'est mieux car plus efficace).

Par défaut, maxiGos considère que les feuilles de style déclarées dans les fichiers de configuration sont dans "_css". Mais on peut les mettre ailleurs et dans ce cas, il convient de préfixer le nom du fichier des feuilles de style déclarée dans les fichiers de configuration par le chemin relatif entre "_css" et le dossier où elles sont en fait stockées.

Les objets html principaux de maxiGos ont été définis avec une classe et un id. On peut soit utiliser les classes si l'on a qu'un seul type d'objet dans une page donnée, où plus rarement les ids si l'on souhaite afficher différemment certains objets dans une même page quand il y en a plusieurs.

Par précaution, il conviendra de veiller à ce que la valeur du paramètre "globalBox" ne soit pas sa valeur par défaut ("GlobalBox") afin de pouvoir faire cohabiter dans une même page des objets maxiGos ayant des configurations différentes.

On a comme tags :

• Le div global,
• Les div des boites regroupant les composants,
• les tags encapsulants les composants (des <div> ou des <h1>),
• les tags des éléments internes des composants.

Le div global est de la forme :

<div class="mxGlobalBoxDiv mxNomDelaBoiteGlobaleDiv" id="identifiantObjetNomDelaBoiteGlobaleDiv">...</div>

Le nom de la boite globale est par défaut "GlobalBox" et peut être modifié via le paramètre "globalBox" dans un fichier de configuration.

Les div des boites regroupants les composants sont de la forme :

<div class="mxNomDeBoiteDiv" id="identifiantObjetNomDeBoiteDiv">...</div>

Les noms des classes des tags des composants commencent par "mx", suivi du nom du composant, suivi du nom du tag html. Les noms d'ids commencent par l'identifiant de l'objet maxiGos, suivi du nom du composant, suivi du nom du tag html :

<div class="mxNomDeComposantDiv" id="identifiantObjetNomDeComposantDiv">...</div>

Pour certains composants (comme "Title"), on remplace "div" par "h1".

A l'intérieur de certains composants, on rencontre d'autres tags dont certains ont aussi des classes ou des ids, mais c'est moins systématique

Rappel : les identifiants des objets (appelés "identifiantObjet") sont de la forme "d" + un numéro qui est incrémenté automatiquement de 1 entre chaque objet maxiGos quand il y en a plusieurs dans une page, le premier objet ayant le numéro 1.

Par exemple, le goban du deuxième objet d'une page est dans la boite :

<div class="mxGobanDiv" id="d2GobanDiv">...</div>

Liste des tags et classes utilisés par maxiGos

Voici une liste des tags que l'on peut styler et le nom des classes associées :

1) Boite globale

La boite globale est particulière. Elle a trois classes :

2) Boites de regroupement

3) Boites des composants et tags internes (liste non exhaustive)

Attention : les composants "diagram" et "loop" n'ont pas de boite, et certains composants ne sont affichés qu'à la place du goban (voir ci-dessous).

4) Boites éventuellement affichées à la place de div.mxGobanDiv

Quelques précisions

Certains composants ont des fonctionnements particuliers qui nécessitent de prendre quelques précautions d'emploi.

Le composant "Comment"

Sa boite principale est div.mxCommentDiv à laquelle il est conseillé de donner la propriété css "overflow:auto".

Si le paramètre adjustCommentWidth vaut 1 (respectivement adjustCommentHeight vaut 1) dans les fichiers de configuration, maxiGos ajuste la largeur (respectivement la hauteur) de sa boite principale sur celle du goban. Dans ce cas là, il ne sert donc à rien de lui donner une largeur (respectivement une hauteur) dans un fichier css via les propriétés "width" ou "height".

Le composant "Edit"

Sa boite principale div.mxEditDiv contient une boite div.mxEditToolBarDiv (boite de la barre d'outils), et une boite div.mxCommentToolDiv (boite de saisie des commentaires).

La boite div.mxEditToolBarDiv contient des tags internes de différents types (button canvas, button img, button span et input). Suivant qu'ils sont ou pas sélectionnés par l'utilisateur, maxiGos donne à ces tags la classe .mxSelectedEditTool ou .mxUnselectedEditTool.

MaxiGos calcule la largeur et la hauteur des outils de div.mxEditToolBarDiv. Il ne sert donc à rien de vouloir leur donner une largeur et une hauteur dans un fichier css via les propriétés "width" et "height".

La boite div.mxEditCommentToolDiv contient un textarea. On peut les styler tous les deux comme on voudra.

Lors de l'affichage d'une fenêtre d'aide ou autre à la place du goban, maxiGos modifie l'opacité (propriétés css "opacity") de tous les outils sauf celui qui a éventuellement permis l'affichage de cette fenêtre.

Le composant "Goban"

Sa boite principale div.mxGobanDiv contient une boite interne div.mxInnerGobanDiv qui contient un canvas (<canvas></canvas>) dans lequel est dessiné le goban.

Pour donner un style à ce canvas, utilisez "div.mxGobanDiv canvas" dans une des feuilles de style.

• Le fond du goban sera celui du canvas (propriété css "background", "background-color", "background-image" ... du tag "canvas").
• La couleur des lignes du goban sera la couleur du texte du canvas (propriété css "color" du tag "canvas").
• Le rayon des pierres sera égal aux trois quarts environ (il est arrondi) de la taille de la police du texte du canvas (propriété css "font-size" du tag "canvas").

Par exemple, pour que la couleur du goban soit #f00, celle de ses lignes #fff et le rayon des pierres 9 pixels, et en supposant que la classe du <div> global soit .mxBasicGlobalBoxDiv, utilisez :

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

MaxiGos calcule la hauteur et la largeur de div.mxGobanDiv, en tenant compte de la présence éventuelle des paramètres maximizeGobanWidth et maximizeGobanHeight dans les fichiers de configuration. Si maximizeGobanWidth vaut 1 (respectivement maximizeGobanHeight vaut 1), maxiGos donne à div.mxGobanDiv la largeur (respectivement la hauteur) maximale que peut avoir le goban (goban de 19x19 + indices éventuels), même si un goban plus petit est affiché, ou qu'une partie du goban seulement est effectivement affichée, ou encore si les indices sont cachés. Sinon, maxiGos donne à div.mxGobanDiv la largeur et la hauteur de la partie du goban effectivement affichée à l'écran. Il ne sert donc à rien de vouloir lui donner une largeur et une hauteur dans un fichier css via les propriétés "width" et "height".

La boite interne div.mxInnerGobanDiv a exactement la taille du canvas qu'elle entoure. Elle sert à donner une ombre au goban avec la propriété css box-shadow. Si on utilise box-shadow directement sur le canvas du goban, l'ombre peut disparaitre selon les circonstances (en particulier avec de nombreuses versions de safari).

Le canvas de div.mxGobanDiv est en "position:relative" et a un "display:block". Quand div.mxGobanDiv est plus grand que le canvas représentant le goban, maxiGos centre le canvas à l'intérieur en modifiant ses propriétés "left" et "top".

MaxiGos cache parfois div.mxGobanDiv via un "display:none", pour afficher l'une des boites .mxNumberingDiv, .mxNewDiv, .mxOpenDiv, .mxSaveDiv, .mxSendDiv, .mxShowHeaderDiv, .mxShowHelpDiv, .mxShowInfoDiv, .mxShowOptionDiv, .mxShowSgfDiv via un "display:block" sur ces boites.

Le composant "Guess"

Sa boite principale div.mxGuessDiv ne contient qu'un tag interne canvas.

MaxiGos modifie la largeur de ce canvas pour afficher le résultat des devinettes (plus l'utilisateur clique proche du coup à deviner sur le goban, plus la largeur du canvas se rapproche de celle de div.mxGuessDiv).

Le composant "Info"

Sa boite principale div.mxInfoDiv contient soit un bouton, soit une boite div.mxShowInfoDiv, qui à son tour contient une boite div.mxInfoContentDiv qui contient elle-même trois boites : une boite div.mxInfoPageMenuDiv et deux boites div.mxInfoPageDiv. La boite div.mxInfoPageMenuDiv contient deux boutons (tag button).

Quand l'utilisateur clique dans le menu div.mxInfoPageMenuDiv sur l'un des deux boutons pour sélectionner une page, maxiGos change la propriété "display" (en "table" ou "none" selon les cas) des div.mxInfoPageDiv afin d'afficher la page en question. Il modifie aussi la classe des boutons du menu en .mxInfoSelectedPageBtn ou .mxInfoPageBtn selon que la page correspondante est affichée ou pas.

Chaque page div.mxInfoPageDiv contient une série de label+champ. Chaque label a une classe ayant pour nom ".m" suivi du nom de la propriété sgf à laquelle ils correspondent (par exemple, .mxEV pour la propriété sgf EV). Chaque champ dans le cas général est un input text qui a une classe ayant pour nom ".m" suivi du nom de la propriété sgf à laquelle ils correspondent (par exemple, .mxEV pour la propriété sgf EV). Pour la propriété RE (le résultat de la partie), on a trois champs au lieu d'un seul qui ont pour classe .mxWN (champ de type select pour choisir le gagnant), .mxHW (champ de type select pour choisir le type de victoire) et .mxSC (input text pour le score). Pour la propriété GC, le champ est un textarea.

Si maxiGos juge que la saisie dans l'un des champs d'une page div.mxInfoPageDiv est incorrecte, il ajoute à ce champ la classe .mxBadInput (attention : les vérifications faites par maxiGos sont très approximatives).

Le composant "Pass"

Il ne contient qu'un tag interne : button.

Ce bouton a pour classe .mxPassBtn, mais cette classe est remplacée par d'autres en fonction des circonstances :

• MaxiGos remplace .mxPassBtn par .mxOnFocusPassBtn si le coup du noeud sgf courant est un passe,
• MaxiGos remplace .mxPassBtn par .mxOnVariationPassBtn si le coup suivant est un passe,
• MaxiGos remplace .mxPassBtn par .mxOnFocusAndOnVariationPassBtn si le coup courant et le coup suivant sont des passes.

Gràce à ce mécanisme, on peut définir dans un fichier css quel aspect devra avoir le bouton en fonction de la situation.

Le composant "Lesson"

Sa boite principale est div.mxLessonDiv et contient une boite div.mxBalloonDiv (bulle à commentaire), et une image img.mxAssistantImg qui représente l'assistant.

Si le paramètre adjustLessonWidth vaut 1 (respectivement adjustLessonHeight vaut 1) dans les fichiers de configuration, maxiGos ajuste la largeur (respectivement la hauteur) de sa boite principale sur celle du goban. Dans ce cas là, il ne sert donc à rien de vouloir lui donner une largeur et une hauteur dans un fichier css via les propriétés "width" et "height".

Pour les commentaires longs, le composant utilise la propriété css "animation" dont la valeur est calculée via javascript en fonction des circonstances.

Le composant "Menu"

Sa boite principale contient une série de couples de boites (div.mxOneMenuDiv, div.mxSubMenuDiv) correpondant chacun à un menu. La boite div.mxOneMenuDiv, toujours visible, contient un seul bouton qui est le titre du menu. La boite div.mxSubMenuDiv, initialement cachée (via un "display:none"), contient une série de boutons, chaque bouton correspondant à un choix possible du menu.

Quand l'utilisateur clique sur le bouton d'un div.mxOneMenuDiv, le div.mxSubMenuDiv correspondant devient visible (via un "display:block").

La boite div.mxSubMenuDiv sera à nouveau cachée par maxiGos (via un "display:none") si l'utilisateur a fait un choix en cliquant sur l'un des boutons que cette boite contient, ou si l'utilisateur clique sur le bouton de la boite div.mxOneMenuDiv associée, ou si l'utilisateur clique ailleurs, ou si aucun choix n'est effectué au bout de quelques secondes.

Le composant "Navigation"

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.mxNavigationDiv button canvas" ou "div.mxSolveDiv button span" dans une des feuilles de style.

• La couleur des icones dans les boutons sera la couleur du texte de ces boutons (propriété css "color" du tag "canvas").
• La taille des icones dans les boutons sera égale à la taille de la police du texte de ces boutons (propriété css "font-size" du tag "canvas").

Par exemple, pour changer la couleur des icones en rouge et leur taille à 12 pixels dans les boutons de navigation du lecteur de partie, et en supposant que la classe du <div> global soir .mxBasicGlobalBoxDiv, utilisez :

.mxBasicGlobalBoxDiv div.mxNavigationDiv 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).

Le composant "Tree"

Sa boite principale div.mxTreeDiv a les styles suivants imposés : "position:relative;" et "height" (pour ce dernier, uniquement si adjustTreeHeight vaut 1).

Sa boite principale contient des canvas qu'il ne faut pas chercher à styler.

Il est recommandé de donner à div.mxTreeDiv une hauteur si adjustTreeHeight vaut 0 car tous ses tags internes sont en position:absolute, ce qui lui donne une hauteur nulle par défaut (maxiGos ne calcule pas la largeur et la hauteur du composant car dans le cas général, on n'en affiche de toute façon qu'une partie en ajoutant une propriété css "overflow" à div.mxTreeDiv).

Lors de l'affichage d'une fenêtre d'aide ou autre à la place du goban, maxiGos modifie l'opacité (propriété css "opacity") de div.mxTreeDiv.

Styles et classes modifiés par maxiGos

Voici en résumé la liste des styles et classes que maxiGos modifie ou impose via des instructions javascript.

Styles modifés dans le code javascript

• Composant Comment
• "width" de .mxCommentDiv (uniquement si adjustCommentWidth=1)
• "height" de .mxCommentDiv (uniquement si adjustCommentHeight=1)
• Composant Edit
• "width" et "height" des button canvas, button img, button span et input de .mxEditToolBarDiv (concerne tous les outils)
• "opacity" des button canvas, button span, button img et input de .mxEditToolBarDiv (concerne tous les outils)
• "opacity" du textarea de .mxEditCommentToolDiv
• Composant Goban
• "width" et "height" de .mxGobanDiv
• "display:none" ou "display:block" de .mxGobanDiv
• "display:block" et "position:relative" du canvas de .mxGobanDiv
• "left" et "top" du canvas de .mxGobanDiv
• Composant Goto
• "position:relative" de .mxGotoDiv
• "display:block" et "position:relative" du canvas de .mxGotoDiv
• "left" du canvas de .mxGotoDiv
• Composant Guess
• "display:block" et "position:relative" du canvas de .mxGuessDiv
• "width" du canvas de .mxGuessDiv
• Composant Header
• "width" de .mxHeaderDiv (uniquement si adjustHeaderWidth=1)
• "height" de .mxHeaderDiv (uniquement si adjustHeaderHeight=1)
• Composant Info
• "display" des .mxInfoPageDiv
• Composant Lesson
• diverses modifications sur le style des tags internes de .mxLessonDiv
• Composant NotSeen
• "width" des tags internes de .mxNotSeenDiv
• Composant Speed
• "position:relative" de .mxSpeedDiv
• "display:block" et "position:relative" du canvas de .mxSpeedDiv
• "width" du canvas de .mxSpeedDiv
• Composant Tree
• "height" de .mxTreeDiv (uniquement si adjustTreeHeight vaut 1)
• "position:relative" de .mxTreeDiv
• "opacity" de .mxTreeDiv
• certains styles (non listés) des tags internes à .mxTreeDiv
• Note : les tags internes de .mxTreeDiv étant tous en "position:absolute", sa largeur est par défaut celle de son conteneur (mais on peut le modifier via les feuilles de style)
• Boites venant s'afficher à la place du goban
• "display:none" ou "display:block" de .mxNumberingDiv, .mxNewDiv, .mxOpenDiv, .mxSaveDiv, .mxSendDiv, .mxShowHeaderDiv, .mxShowHelpDiv, .mxInfoDiv, .mxShowOptionDiv, .mxShowSgfDiv
• "width" et "height" de .mxNumberingDiv, .mxNewDiv, .mxOpenDiv, .mxSaveDiv, .mxSendDiv, .mxShowHeaderDiv, .mxShowHelpDiv, .mxShowInfoDiv, .mxShowOptionDiv, .mxShowSgfDiv

Classes modifées dans le code javascript

• ajoute .mxBM à .mxLessonDiv si le noeud sgf courant a une propriété BM
• ajoute .mxDO à .mxLessonDiv si le noeud sgf courant a une propriété DO
• ajoute .mxIT à .mxLessonDiv si le noeud sgf courant a une propriété IT
• ajoute .mxTE à .mxLessonDiv si le noeud sgf courant a une propriété TE
• remplace .mxPassBtn par .mxOnFocusPassBtn si le coup du noeud sgf courant est un passe
• remplace .mxPassBtn par .mxOnVariationPassBtn si le coup suivant est un passe
• remplace .mxPassBtn par .mxOnFocusAndOnVariationPassBtn si le coup courant et le coup suivant sont des passes
• remplace .mxUnselectedEditTool par .mxSelectedEditTool en cas de sélection d'un outil dans la barre d'outils du composant "Edit"
• remplace .mxSelectedEditTool par .mxUnselectedEditTool en cas de désélection d'un outil dans la barre d'outils du composant "Edit"
• remplace .mxInfoSelectedPageBtn par .mxInfoPageBtn en cas de sélection d'une page dans le composant "Info"
• remplace .mxInfoPageBtn par .mxInfoSelectedPageBtn en cas de désélection d'une page dans le composant "Info"
• ajoute .mxBadInput à un input si l'utilisateur a entré dans un champ une valeur non conforme selon maxiGos dans une des pages du composant "Info"

Encodage

Encodage de la page dans laquelle on souhaite insérer un lecteur maxiGos

MaxiGos fait tout en UTF-8, mais la page dans laquelle est inséré un lecteur maxiGos peut être dans n'importe quel encodage.

Lorsqu'on utilise un lanceur tel que "sgfplayer.php" ou le chargeur "mgosLoader.js" qui lui-même appelle le lanceur "sgfmultipleplayer.php", on n'a rien de spécial à faire pour que maxiGos fonctionne. En effet, ce sont les lanceur de maxiGos qui indiquent au navigateur que maxiGos produit du contenu en UTF-8 (via la fonction php header()), et c'est le navigateur qui peut alors transformer automatiquement ce que lui fourni maxiGos (qui est donc encodé en UTF-8) dans l'encodage de la page.

Par contre, si la page dans laquelle est inséré un lecteur maxiGos n'est pas en UTF-8 et qu'on utilise un lecteur autonome maxiGos comme "maxigos-basic.js", "maxigos-comment.js, ... ou qu'on insère l'un des scripts de traduction "mgos-loc-<xy>.js" qui sont tous des fichiers javascript fournissant du contenu en UTF-8, on doit ajouter dans leur balise <script> l'attribut charset avec la valeur "UTF-8". En effet, ces scripts n'ont pas de moyens par eux-même, contrairement aux scripts php via la fonction php header(), d'indiquer à la page qu'ils fournissent du contenu en UTF-8. Ainsi, le navigateur pourra tout de même transformer de manière appropriée ce contenu dans l'encodage de la page.

Il est à noter que lorsqu'on insère directement du sgf dans la page (sans utiliser de fichier sgf donc), maxigos ignore la propriété CA de ce sgf puisque de facto, ce sgf a le même encodage que la page et non l'encodage indiqué dans sa propriété CA. A priori, on n'a rien de spécial faire dans ce cas, car quand on copie du sgf à l'aide d'un logiciel de traitement de texte dans le code d'une page html/php, c'est le logiciel de traitement de texte qui fait la conversion appropriée (il faut tout de même que l'encodage réel de la page corresponde au charset spécifié d'une manière ou d'une autre comme par exemple via un <meta charset="...">, mais c'est en général le cas sans quoi tout texte dans la page risque d'être mal affiché, et pas seulement ce que produit maxiGos).

Encodage des fichiers sgf

L'encodage d'un fichier sgf doit être indiqué dans sa propriété CA. Et par défaut, quand un fichier sgf n'a pas de propriété "CA", cela signifie qu'il doit être encodé en ISO-8859-1. Si la propriété CA est présente dans le fichier sgf, l'encodage réel du fichier doit correspondre à la valeur de la propriété CA.

MaxiGos utilise cette propriété CA pour déterminer l'encodage du fichier sgf, et transforme tout en UTF-8 (il sera donc toujours un peu plus rapide d'utiliser des fichiers sgf en UTF-8). Il est de ce fait possible d'utiliser des fichiers sgf d'encodages variés au sein d'une même page.

Quand l'affichage n'est pas celui attendu, c'est le plus souvent dû au fait que le fichier a un encodage réel différent de celui qui a été spécifié dans sa propriété CA (faute malheureusement extrêmement courante dans les fichiers sgf d'origine asiatique). Pour corriger ce problème, il faut soit modifier la propriété CA du fichier sgf pour que sa valeur corresponde à son encodage réel, soit ré-enregistrer le fichier dans l'encodage spécifié dans sa propriété CA (on peut faire tout ça avec la plupart des éditeurs de texte, le plus difficile étant de déterminer quel est l'encodage réel du fichier).

Ceci étant, bien qu'en théorie maxiGos peut fonctionner dans une page qui n'est pas en "UTF-8", et lire des fichiers qui ne sont pas en "UTF-8", il vaut mieux quand on le peut tout faire en UTF-8.

Encodage et langue

Encodage et langue sont deux choses différentes. "UTF-8" est adapté pour toute(?) langue, aussi c'est le meilleur choix quand on peut l'utiliser. Quand cele n'est pas possible, attention, car certains encodages peuvent ne pas afficher certains caractères de certaines langues. Par exemple, les mots en japonais d'un fichier sgf en Shift-JIS ne pourront pas être transformés automatiquement et s'afficher correctement dans une page en "ISO-8859-1". Par contre, ils pourront être transformés automatiquement et s'afficher correctement dans une page en 'UTF-8". N'utilisez pas des noms d'encodage tels que "UTF-8", "ISO-8859-1", "Shift-JIS", "Big5", "GB18030" comme valeur de $mxL et mxG.L. Utilisez un code langue comme "en", "fr", "ja", zh", "zh-tw", ...

Diagnostic à effectuer en cas de mauvais affichage (caractères illisibles ou douteux)

Vérifier l'encodage du fichier sgf

Le fichier sgf n'a pas de propriété CA

Si le fichier sgf n'a pas de propriété CA, et si en ouvrant le fichier avec un éditeur de texte, celui-ci détecte un autre encodage que "ISO-8859-1", et si l'affichage du contenu dans l'éditeur semble bon (pas de caractère illisble ou douteux), il devrait suffire d'ajouter dans le fichier sgf après le premier ";" la propriété CA avec comme valeur le nom de l'encodage détecté par l'éditeur (par exemple CA[UTF-8]).

Si le fichier sgf n'a pas de propriété CA, et si l'encodage détecté par l'éditeur est "ISO-8859-1", et si l'affichage dans l'éditeur semble mauvais (caractères illisibles ou douteux), alors le problème vient bien du fichier sgf (le fichier a probablement mal été enregistré par son auteur et retrouver le bon encodage sera plus ou moins facile : si l'on arrive à retrouver le bon encodage il faudra transformer (la méthode dépend de ce que l'auteur a fait) le fichier et l'enregistrer dans cet encodage, en n'oubliant pas de donner aussi à la propriété CA du fichier sgf le nom de cet encodage).

Si le fichier sgf n'a pas de propriété CA, et si l'encodage détecté par l'éditeur est "ISO-8859-1", et si l'affichage dans l'éditeur semble bon, alors le problème ne vient probablement pas du fichier sgf.

Le fichier sgf a une propriété CA

Si le fichier sgf a une propriété CA, et si en ouvrant le fichier avec un éditeur de texte, celui-ci détecte un autre encodage que celui indiqué par la propriété CA, et si l'affichage du contenu dans l'éditeur semble bon (pas de caractère illisble ou douteux) il devrait suffire de remplacer la valeur de la propriété CA par le nom de l'encodage détecté par l'éditeur.

Si le fichier sgf a une propriété CA, et si l'encodage détecté par l'éditeur correspond à celui indiqué dans la propriété CA du fichier sgf, et si l'affichage dans l'éditeur semble mauvais (caractères illisibles ou douteux), alors le problème vient bien du fichier sgf (le fichier a probablement mal été enregistré par son auteur et retrouver le bon encodage sera plus ou moins facile : si l'on arrive à retrouver le bon encodage il faudra transformer (la méthode dépend de ce que l'auteur a fait) le fichier et l'enregsitrer dans cet encodage, en n'oubliant pas de donner aussi à la propriété CA du fichier sgf le nom de cet encodage).

Si le fichier sgf a une propriété CA, et si l'encodage détecté par l'éditeur correspond à celui indiqué dans la propriété CA du fichier sgf, et si l'affichage dans l'éditeur semble bon, alors le problème ne vient probablement pas du fichier sgf.

Vérifier l'encodage de la page

Si la page n'est pas encodée en "UTF-8", vérifiez que l'encodage employé dans le fichier sgf peut effectivement être transformé et affichée avec l'encodage de la page.

Si la page n'est pas encodée en "UTF-8", et si vous utilisez un lecteur maxiGos autonome, vérifiez que vous avez bien un charset="UTF-8" dans la balise <script> du lecteur, et éventuellement dans la balise <script> d'un fichier de langue maxiGos.

Si vous avez créé un composant, ou modifié un composant de maxiGos, vérifiez que vous l'avez bien enregistré en "UTF-8" (attention au copier-coller d'un code source affiché par un navigateur : les caractères non latin peuvent y être mal codés).

Sinon, dans les autres cas, le problème vient d'ailleurs.

Annexe 1 : tous les fichiers

• le dossier "_alone" qui contient les scripts des lecteurs autonomes et le script "aloneMaker.php" permettant de les générer,
• le dossier "_help" qui contient les fichiers d'aide,
• le dossier "_local" qui contient les scripts de traduction,
• le dossier "_mgos" qui contient les fichiers de configuration, les feuilles de styles, les images, les scripts javascript et les scripts php indispensables au fonctionnement de maxiGos,
• le dossier "_sample" qui contient des exemples en plusieurs langues,
• addLocalization.php qui permet de fabriquer des lecteurs maxiGos traduits en une autre langue,
• documentation.php qui est le présent document en plusieurs langues (voir dans les sous-dossiers "en", "fr", ...),
• download.php qui est une page de téléchargement de maxiGos en plusieurs langues (voir dans les sous-dossiers "en", "fr", ...),
• licence.txt qui rappelle les conditions d'utilisation de maxiGos,
• version.php qui contient le numéro de version de maxiGos.

Contenu du dossier "_mgos"

• le chargeur "mgosLoader.js" qui permet d'insérer des lecteurs maxiGos entre des balises <div> et <div>,
• le lanceur "sgfplayer.php" utilisés par les webmestres pour inclure maxiGos dans leurs pages sans l'aide de "mgosLoader.js",
• le lanceur "sgfmultipleplayer.php" utilisé par "mgosLoader.js",
• le dossier "_mgos/_cfg" qui contient les fichiers de configuration,
• le dossier "_mgos/_css" qui contient les feuilles de style,
• le dossier "_mgos/_img" qui contient les images,
• le dossier "_mgos/_js" qui contient les scripts javascript qui s'exécutent sur l'ordinateur de l'utilisateur,
• le dossier "_mgos/_php" qui contient les scripts php qui permettent au serveur de générer le code javascript qui est envoyé au navigateur de l'utilisateur lors du téléchargement de la page contenant un maxiGos.

Annexe 2 : questions et réponses

EnglishFrançais