La présente version de darkPoll est prévue pour fonctionner avec PHP4. Cependant, et après quelques tests (merci à "Tomate Powa" pour avoir signalé les problèmes), il est possible de le faire fonctionner avec PHP3, moyennant quelques modifications dans le code.

L'installation de darkPoll nécessite quelques étapes :

En premier lieu, il convient de créer les tables nécessaires au fonctionnement de darkPoll, ces dernières étant présentes dans le fichier dump.sql (soit à l'aide de phpMyAdmin, soit directement en mode console (avec une commande du type : mysql -u utilisateur -p -h serveur_sql ma_base_de_données < dump.sql)). Si jamais vous utilisiez déjà darkPoll v0.3 et que vous souhaitez garder vos sondages, dans ce cas utilisez plutot le fichier update.sql, qui met à jour la structure des tables de darkPoll v0.3 pour être utilisables avec darkPoll v0.5 (si vous n'avez pas gardé les noms de tables par défaut, vous devez dans ce cas les modifier dans ce dernier fichier)

Ensuite, il convient de configurer l'accès à la base de données, en précisant le serveur, l'utilisateur, le mot de passe ainsi que la base de données à utiliser. Vous pouvez soit l'écrire en brut dans les variables de classe de darkDB (voir partie configuration), soit utiliser la méthode set_database() de darkPoll. (voir partie mode paramétrage)

Il convient également de configurer darkPoll. Au même titre que l'accès à la base de données, vous pouvez soit l'écrire en brut dans les variables de classe de darkPoll (voir partie configuration), soit utiliser les méthodes prévues à cet effet (set_images(), set_tables(), set_random() etc.. - voir partie mode paramétrage)

Incluez le fichier class.darkPoll.php au début de chacun de vos scripts (attention aux chemins !)

Insérez (ou reliez) dans/à vos pages HTML la feuille de style darkPoll.css, nécessaire à la personnalisation visuelle de darkPoll (voir à l'intérieur du fichier pour les détails)

Voilà, maintenant vous pouvez coder :)

Nous allons à présent évoquer dans cette partie la configuration par l'intermédiaire des variables de classe en brut (la configuration via les setters viendra après)

var $DB_HOST = "myhost" ; // serveur SQL var $DB_LOGIN = "myuser" ; // login var $DB_PWD = "mypwd" ; // mot de passe var $DB_DATABASE = "mydatabase" ; // base de données

Pas grand chose de plus à dire, les noms des variables et les commentaires étant assez explicites.

var $DB_TABLE = "darkpoll" ; var $DB_TABLE_OPTIONS = "darkpoll_options" ; var $DB_TABLE_LOG = "darkpoll_log" ; var $POLL_IMG = "./images/darkPoll.gif" ; var $POLL_IMG_LEFT = "./images/darkPoll_left.gif" ; var $POLL_IMG_RIGHT = "./images/darkPoll_right.gif" ; var $POLL_IMG_BLANK = "./images/darkBlank.gif" ; var $POLL_VOTETEXT = "Voter"; var $POLL_DOLOG = true ; var $POLL_VOTETIMEOUT = 24 ; var $POLL_TOTALDISP = true ; var $POLL_STATSDISP = 1 ; var $POLL_RANDOM = false ; var $POLL_USEDATE = false ; var $POLL_SIZEFACTOR = 1 ;

Les 3 premières variables correspondent aux noms des tables à utiliser, celles-ci étant par défaut et respectivement initialisées à "darkpoll", "darkpoll_options" et "darkpoll_log". Notez que c'est ainsi que les tables sont nommées dans le fichier dump.sql.

Les 4 variables suivantes correspondent aux noms et chemins des images pour les barres de sondage. Ne perdez pas de vue que ces chemins ne correspondent pas forcément aux chemins du fichier class.darkPoll.php aux images, mais de votre script qui inclue class.darkPoll.php aux images. Notez également qu'il en est de même pour la directive require_once ("./modules/class.darkDB.php") ;, qui inclue le fichier class.darkDB.php dans darkPoll (cette dernière directive se trouve à la ligne 31, et est la toute première commande du fichier class.darkPoll.php)

$POLL_VOTETEXT : correspond au texte qui apparait sur le bouton (submit) de validation du formulaire. (valeurs : toute chaine de caractères)

Les variables restantes correspondent quant à elles à la configuration proprement dite des fonctionnalités de darkPoll :

$POLL_DOLOG : détermine si l'on doit logger les IP des visiteurs dans la table $DB_TABLE_LOG, et ce pour les empêcher de voter à nouveau pendant une durée déterminée (par la variable suivante). Ceci ajoute une protection supplémentaire à l'utilisation des cookies, ces derniers étant aisément contournables (par simple suppression du cookie dans le répertoire correspondant) (valeurs : true ou false).

$POLL_VOTETIMEOUT : détermine, en heures, la durée pendant laquelle les visiteurs ne peuvent plus voter après un vote. (valeurs entières > 0)

$POLL_TOTALDISP : détermine si l'ont doit afficher le nombre total de votes dans la partie "résultats" du sondage (valeurs : true ou false).

$POLL_STATSDISP : détermine si l'on affiche les statistiques a coté des barres de sondages. Cette variable peut prendre 3 valeurs : 0 indique que l'on n'affiche pas de statistique, 1 indique que l'on affiche les statistiques sous forme de pourcentages (ie : 32.5%), 2 indique que l'on affiche le nombre de votes par rapport au nombre total de vote (ie : 12/34). (valeurs : 0, 1 ou 2)

$POLL_RANDOM : détermine si l'on effectue un choix aléatoire des sondages. Attention, cette fonctionnalité ne fonctionnera que si vous avez MySQL version 3.23 ou supérieur ! (valeurs : true ou false) (Voir la partie mode utilisateur pour comprendre les implications de cette variable).

$POLL_USEDATE : détermine si les dates de début et dates de fin de sondage (ie : date_debut et date_fin) doivent être prises en compte pour la détermination du sondage (valeurs : true ou false) (Voir la partie mode utilisateur pour comprendre les implications de cette variable).

$POLL_SIZEFACTOR : détermine le coefficient de largeur d'affichage des barres de sondage. Par défaut initialisé à 1, cela signifie que la barre de sondage d'une option qui remporte 100% des votes fera 100 pixels de largeur. Dans une situation similaire, cette variable initialisée à 0.5 donnera une barre de sondage de 50 pixels de largeur. Initialisée à 2, cela donnera une barre de 200 pixels de largeur. A utiliser afin d'ajuster la largeur du sondage par rapport a son emplacement dans l'interface de votre site. (valeurs entières > 0)

La première chose à faire, après avoir inclue le fichier class.darkPoll.php, est de créer une instance de notre classe :

<?php   require_once ("./modules/class.darkPoll.php") ;   $mypoll = new darkPoll($PHP_SELF, 0, $PHP_SELF."?act=archives") ;   (...) ?>




darkPoll(string url_redirect, int IDpoll_user [, string url_archives])

Le constructeur de la classe prend 3 paramètres, le dernier étant facultatif ; le premier paramètre correspond à l'adresse à laquelle l'utilisateur doit être redirigé lors d'un vote - cela peut être la même page ou non, le second correspond à l'ID du sondage, et le troisième correspond à l'adresse de la page des archives. Ce dernier paramètre étant facultatif, si aucune adresse n'est précisée, le lien permettant d'accéder à la page des archives ne sera pas affiché. Notez qu'ici l'ID du sondage est 0, ce qui n'est pas un ID de sondage valide (les ID commençant à 1). Ceci sera expliqué un peu plus loin dans la partie mode utilisateur.

Notez que vous devez inclure et instancier un objet de la classe avant tout "affichage" dans la page. Le cas échéant, l'ajout de cookies et les redirections (page des archives) ne pourront avoir lieu. Une manière simple de ne pas rencontrer ce problème est d'inclure et d'instancier directement un objet au début de vos scripts (comme montré dans l'exemple précédent).

darkPoll dispose de 4 modes de fonctionnement : les modes paramétrage, utilisateur, archives et administrateur. Nous allons maintenant voir en détail les spécificités de chacun de ces modes, et les méthodes qui y sont respectivement utilisables. Notez que darkPoll dispose de bien plus de méthodes que celles présentées ici, vous vous en apercevrez vous même en jettant un coup d'oeil au code source. PHP n'offrant aucun mécanisme de droits (methodes/variables privées/publiques), considérez que les méthodes qui ne sont pas décrites dans ce manuel sont des méthodes privées (de même pour les variables).

Après avoir instancié un objet de la classe, vous êtes directement dans le mode paramétrage. Lorsque vous sortez du mode utilisateur, administrateur ou archives, vous revenez dans le mode paramétrage. Ce mode, comme son nom l'indique, vous permet de paramétrer via des méthodes setters darkPoll. En outre, ce mode permet de redéfinir, pour une instance donnée de la classe darkPoll, les paramètres par défaut du sondage que vous avez déterminé précédemment dans la partie configuration. Cela vous permet notamment d'avoir des paramètres par défaut pour tous vos sondages (sizefactor, images, etc..), mais que vous pouvez modifier pour un sondage donné, vous offrant ainsi la possibilité d'avoir sur la même page (ou sur différentes pages) des sondages aux comportements différents.

Les méthodes utilisables dans le mode paramétrage sont les suivantes :

(Toutes ces méthodes retournent une variable de type booléen. Elles retournent en effet true si le paramètre a été modifié et que vous êtes bien dans le mode paramétrage, false sinon.

Exemple d'utilisation :

<?php   require_once ("./modules/class.darkPoll.php") ;   $mypoll = new darkPoll($PHP_SELF, 0, $PHP_SELF."?act=archives") ;   $mypoll->set_totaldisp(false) ;   $mypoll->set_sizefactor(2) ;   $mypoll->set_random(true) ; ?>

Une fois que vous avez paramétré selon vos besoins votre instance de darkPoll, vous pouvez entrer soit dans le mode utilisateur, soit dans le mode archives ou soit dans le mode administrateur.

Le mode utilisateur est le mode permettant de mettre en oeuvre de manière proprement dite le sondage. Il convient en premier lieu d'entrer dans le mode utilisateur, et ce grâce à la méthode user_start(). Une fois dans le mode utilisateur, vous pouvez afficher le sondage, avec la méthode user_display(). Vous sortez ensuite du mode utilisateur avec la méthode user_end().

soit IDpoll_user : l'ID du sondage donné en paramètre du constructeur
soit IDpoll : l'ID du sondage courant de l'instance
              (initialement non affectée)

si IDpoll_user <> 0 alors
  IDpoll := IDpoll_user
sinon	       /* si IDpoll_user = 0 */
  si $POLL_RANDOM = vrai alors
    si $POLL_USEDATE = vrai alors
      IDpoll := ID de sondage déterminé aléatoirement parmis ceux dont 
      la date de début est antérieure (ou égale) à la date courante
      et dont la date de fin (expiration) est strictement postérieure
      à la date courante.
    sinon
      IDpoll := ID de sondage déterminé aléatoirement parmis tous
      ceux présents.
    fsi
  sinon
    si $POLL_USEDATE = vrai alors
      IDpoll := ID du dernier sondage inséré dont 
      la date de début est antérieure (ou égale) à la date courante
      et dont la date de fin (expiration) est strictement postérieure
      à la date courante.
    sinon
      IDpoll := ID du dernier sondage inséré.
    fsi
  fsi
fsi

Les méthodes utilisables dans le mode utilisateur sont les suivantes :

  $curpoll = $mypoll->user_display() ;
  /* les 4 éléments sont $curpoll["poll"], $curpoll["desc"], 
  $curpoll["date_debut"] et $curpoll["date_fin"] ; */

Exemple d'utilisation :

<?php   require_once ("./modules/class.darkPoll.php") ;   $mypoll = new darkPoll($PHP_SELF, 0, $PHP_SELF."?act=archives") ;   $mypoll->set_totaldisp(false) ;   $mypoll->set_sizefactor(2) ;   $mypoll->set_random(true) ;   if ($mypoll->user_start()) {     $str = $mypoll->user_display() ;     echo "<table border=0 width=150><tr><td>" ;     echo $str["desc"]."(du ".$str["date_debut"]." au ".$str["date_fin"].")" ;       echo "</td></tr><tr><td>" ;     echo $str["poll"] ;     echo "</td></tr></table>";   }   $mypoll->user_end() ; ?>

Le mode archive est le mode qui vous permet d'afficher les archives des sondages. Par le biais de la méthode archives_set(), vous définissez le nombre de sondages que vous souhaitez récupérer ainsi que "la position" à partir de laquelle vous souhaitez commencer. Ensuite, vous récupérez chacun des sondages grâce à la méthode archives_display(). Pour entrer dans le mode archives, vous devez utiliser la méthode archives_start(), et en sortir avec la méthode archives_end().

Les méthodes utilisables dans le mode archives sont les suivantes :

Exemple d'utilisation :

<?php   require_once ("./modules/class.darkPoll.php") ;   $mypoll = new darkPoll($PHP_SELF, 0) ;   if ($mypoll->archives_start()) {     $mypoll->archives_set(5,1) ;     while ($str = $mypoll->archives_display()) {       echo "<table border=0 width=150><tr><td>" ;       echo $str["desc"]."(du ".$str["date_debut"]." au ".$str["date_fin"].")" ;       echo "</td></tr><tr><td>" ;       echo $str["poll"] ;       echo "</td></tr></table>";     }   }   $mypoll->archives_end() ; ?>

Le mode administrateur, comme son nom l'indique, permet d'administrer les sondages. En effet, il n'y a pas d'interface a proprement parler d'administration (sous forme de script ou autre), simplement des méthodes qui permettent d'administrer les sondages. Ceci étant, vous pouvez très bien développer votre propre interface d'administration, basée sur ces méthodes. (si réaliser une telle interface vous tente, vous pouvez toujours me la faire parvenir à yogi@darkmag.net ;)

Au même titre que le mode utilisateur et que le mode archives, vous devez utiliser une méthode afin de rentrer dans le mode administrateur (admin_start()), et une autre pour en sortir (admin_end()).

Une fois dans le mode administrateur, vous devez déterminer le sondage sur lequel vous allez opérer (à moins que vous souhaitiez en ajouter un). Pour ce faire, vous disposez de 2 méthodes :

Une fois que vous avez déterminé le sondage (et plus précisément son ID) sur lequel vous allez opérer, vous pouvez utiliser les méthodes suivantes (qui retournent toutes false si elles ne sont pas invoquées dans le mode administrateur) :

Exemple d'utilisation :

<?php   require_once ("./modules/class.darkPoll.php") ;   $mypoll = new darkPoll($PHP_SELF, 0) ;   if ($mypoll->admin_start()) {     $mypoll->admin_add("Sublime, n'est ce pas ?",60,"2002-01-28") ;     $mypoll->admin_add_option("Evidemment") ;     $mypoll->admin_add_option("Non, sans façon non.") ;     $mypoll->admin_add_option("ObiVan Kenobi !") ;     $rang=1 ;     while ($txt = $mypoll->admin_display_option($rang)) {       echo $txt["texte"]."<br>" ;       $rang++ ;     }     $mypoll->admin_mod_option(3,"nbvotes","Obiwan Kenobi !") ;     $str = $mypoll->admin_display(true) ;     echo $str["poll"] ;   }   $mypoll->admin_end() ; ?>

Bien que longuement testé, des bugs doivent toujours subsister. Donc si vous rencontrez des problèmes avec darkPoll, ou si vous avez des questions/suggestions à me faire parvenir, un seul mail : yogi@darkmag.net. En dehors des éventuelles corrections de bugs, je doute qu'il y aura d'autres versions de darkPoll, ne voyant plus vraiment quoi lui ajouter. Cependant, si vous avez des idées d'amélioration (en dehors d'une interface d'administration :p), ou si vous l'améliorez vous même, je vous serais reconnaissant de m'en faire part.

Je tiens à remercier tout particulièrement les personnes qui m'ont écrit à propos de darkPoll v0.3 pour me signaler des problèmes/bugs, ou tout simplement pour me faire part de leurs impressions à son sujet. Je tiens également à remercier Nescafé(c) (open up !) pour leur café qui m'a aidé a tenir éveillé, et Dark Funeral, Belenos, Tidfall, Anorexia Nervosa ainsi que Furia dont les musiques ont rythmé le développement de darkPoll ;)

In blackness,

YoGi - le 26/12/2001