====== Méthodes disponibles ======

Surcharger une classe permet d'accéder aux méthodes des classes parents.
La classe Pxxo_Widgets fournit les méthodes suivantes :

===== Accès aux répertoires de thème =====


  * **string getThemeFile(string $filename)**

Recherche le fichier $filename dans l'ensemble des répertoires des ressources, et retourne son chemin d'accès complet.
On retournera en priorité le fichier correspondant au thème courant.

  - $filename : nom du fichier que l'on recherche


<code php>
$fullname = $this->getThemeFile('fond .png');
$fullname = $this->getThemeFile('/design/logo.png');
</code>



  * **boolean addThemePath(string $path, boolean $flag)**

Ajoute le chemin $s à la liste des chemins de thèmes.

Pour l'ajouter au début de liste, on positionnera $b à true
Méthode permettant d'ajouter un fichier Javascript. Ce fichier sera interprété comme un fichier de template.
On retournera true si le chemin  a été ajouté, false sinon.

  - $path : répertoire à ajouter
  - $flag : si positionné à true, permet d'ajouter le chemin en début de liste

<code php>
$this->addThemePath('/www/images');
$this->addThemePath('/design/blue', true);
</code>


  * **void setTemplate(string $mode, string $fichier)**

Associe un fichier de template à un mode donné

  - $mode : identifiant du mode 
  - $fichier : un fichier de template disponible dans les thèmes.

 
La fonction setTemplate ne doit pas obligatoirement être utilisée. Elle s'adapte en fonction du mode courant. On peut même ne pas du tout l'utiliser si un fichier portant le nom du mode courant est suffixé par '.php.html' existe dans les répertoires de Thèmes.

Exemple :

<code php>
<?php 
class Exemple extends Pxxo_widgets {
    function __construct() {
        parent::Pxxo_Widgets(array(), __FILE__);
    }
    function defaut() {
        $this->setTemplate('template.php.html');
    }
    function monaction() {
         // utilisera le fichier monaction.php.html
    }
}
?>
</code>













===== Ajout de contenu =====

  * **''putWidget(string $id, Pxxo_Widget $child)''**

Méthode permettant d'ajouter en widget en tant que fils.

  - ''$id'' : identifiant  dans les templates
  - ''$child'' : l'instance du widget fils à afficher

<code php>
$this->putWidget('MON_WIDGET', new Pxxo_Widget_HelloWorld()); 
</code>

<code php>
<?php echo $MON_WIDGET; ?>
</code>

  * **putData($id, $value)**

Méthode permettant d'ajouter le contenu d'une variable PHP.

  - $id : identifiant  dans les templates
  - $value : des données

<code php>
$this->putData('ID1', '<b>super</b>'); 
$this->putData('ID2', array(1, 2, 3)); 
</code>


  * **putStyle($filename, $media = 'screen')**

Méthode permettant d'ajouter un fichier CSS. Ce fichier sera interprété comme un fichier de template.

  - $filename : nom d'un fichier présent dans le répertoire du thème
  - $media : nom du support auquel est destiné le style 

<code php>
$this->putStyle('style1.php.css');
$this->putStyle('style2.php.css', 'print');
</code>

Remarque :Style spécifique pour Internet Explorer

On peut maintenant attribuer des règles CSS différentes en fonction
de la version d'internet explorer. Pour cela il suffit de donner la condtion 
dans le paramètre $media de la méthode putStyle.

<code php>
$this->putStyle('fichier.css', 'if lte IE 6');
$this->putStyle('fichier.css', 'if IE 7');
$this->putStyle('fichier.css', 'if IE'); 
</code>


  * **putScript($filename, $disposition = 'file')**

Méthode permettant d'ajouter un fichier Javascript. Ce fichier sera interprété comme un fichier de template.

  - $filename : nom d'un fichier présent de le répertoire du thème
  - $disposition : méthode d'intégration du code dans la page html (file ou inline)

<code php>
$this->putScript('script1.php.js');
$this->putScript('script2.php.js', 'inline');
</code>

  * **string putImage($filename, $id = null)**

Méthode permettant d'ajouter une image. Si l'identifiant n'est pas fourni, celui-ci sera automatiquement égal au nom (en majuscule) du fichier sans son suffixe

  - $filename : nom d'un fichier présent de le répertoire du thème
  - $id : identifiant de l'image dans les templates

Retourne l'url de l'image.

<code php>
$url_de_truc_png   = $this->putImage('truc.png'); // ===> $truc_png
$url_de_machin_png = $this->putImage('machin.png', 'BIDULE'); // ===> $BIDULE
</code>

  * **putMedia($filename, $id = null)**

Ajout d'un média dynamique (calculé comme un template)

  - $filename : nom d'un fichier présent dans le répertoire du thème
  - $id : identifiant du média dans les templates

Un média est une ressource externe à la page et référencée dans celle-ci par une URL.
Comme par exemple : un fichier svg, swf, png, etc ...

Le suffixe du fichier est utilisé pour typer le contenu.
Si l'identifiant n'est pas fourni, celui-ci sera automatiquement égal au nom (en majuscule) du fichier en s'arrêtant au premier point rencontré.

<code php>
$this->putMedia('image.php.png');  // ===> $IMAGE 
$this->putMedia('duflash.xml.php.swf');  // ===> $DUFLASH
$this->putMedia('truc.php.svg', 'DUSVG'); // ===> $DUSVG 
</code>

  * **putXSLT($id, $xsl, $xml, $par = array(), $php = false, $engine = 'auto')**

Méthode permettant d'ajouter une transformation XSL.

<code php>
$this->putXSLT('TRUC', 'fichier.xsl', 'fichier.xml');

$xml = '<xml/>';
$params = array('nom'=>'valeur');
$this->putXSLT('TRUC', 'fichier.xsl', $xml, $params, true);
</code>

  * **pxxo_buffer_header_title putTitle(string $s)**

Ajoute un titre dans la liste des titres possibles pour la page HTML produite. Remarque : le widget [[:fr:doc:pxxo_widget_decorator_core|décorateur Core]] affiche automatiquement la concaténation des titres trouvés dans la hiérarchie des widgets.





===== Paramétrage =====


  * **void  setResourcePath(string $chemin)**

Fixe le chemin physique vers le répertoire $chemin contenant les ressources

  * **void setResourceURL(string $url)**

Fixe l'URL d'accès $url vers le chemin physique contenant les ressources





  * **void enableCache()**


Active le mécanisme de cache pour le widget et ses fils

  * **void disableCache()**


Désactive le mécanisme de cache pour le widget et ses fils



  * **addCacheID(...)**

Tout les paramètres transmis à cette méthode serviront à calculer un identifiant discriminant pour la mise en route du cache.
D'un appel sur l'autre, la valeur de ces variables permettra de savoir s'il s'agit d'un appel strictement identique (ne nécessitant pas une rééxécution) ou s'il s'agit d'un appel différent


__Exemple :__

<code php>
class truc {
    function __construct($a, $b) {
        $this->addCacheID($a, $b, $GLOBALS['truc']);
    }
}
</code>



  * **void setBenchmarkTimer(object &$o)**


Fixe un objet $o de type Timer, éventuellement utilisé par le widget pour calculer ses temps de traitements

  * **void setBenchmarkProfiler(object &$o)**


Fixe un objet $o de type Profiler, éventuellement utilisé par le widget pour calculer ses temps de traitements

  * **void     enableDebugMode()**


Active l'affichage de trace permettant le debugage


  * **void    disableDebugMode()**

Désactive l'affichage de traces permettant le debugage



===== Gestion du mode =====



  * **string getMode()**


Retourne le mode courant du widget, c'est-à-dire le nom de la méthode qui sera exécutée.

  * **void setMode(string $s)**


Avec $s, on impose le mode courant du widget. Si setMode  est appelée avant la méthode main  ou avant la méthode putWidget, c'est la méthode $s qui sera exécutée.

  * **void setDefaultMode(string $s)**


Fixe avec $s le nom de la méthode qui sera exécutée par defaut. Si on n'utilise pas cette méthode c'est la méthode "defaut" qui sera exécutée.

  * **getDefaultMode()**


Retourne le nom de la méthode exécutée par défaut

  * **mixed switchMode(string $s)**

Change le mode courrant avec $s et exécutant la méthode $s. Retourne le résulat de l'eéxcution de $s.

__Remarque :__ pensez à faire un ''return'' après l'appel à switchMode si vous ne désirez pas que l'exécution du code continue sur l'ancien mode.






===== Variables POST/GET/SESSION =====

  * **''null  delSessionVar(string $n)''**\\ Supprime la variable de session nommée ''$n''
  * **''mixed setSessionVar(string $n, mixed $v)''**\\ Donne la valeur ''$v'' à la variable de session nommée ''$n''
  * **''mixed    getSessionVar(string $n, mixed $v = null)''**\\ Retourne la valeur de la variable de session nommée ''$n''. Si cette variable n'existe pas, on renvoie ''$v''
  * **''mixed    getInputVar(string $n, mixed $v = null)''**\\ Retourne  la valeur de la variable nommée ''$n'' en provenance du navigateur (GET et POST). Si cette variable n'existe pas, on renvoie ''$v''
  * **''mixed    setInputVar(string $n, mixed $v)''**\\ Donne la valeur ''$v'' à la variable nommée ''$n''. On simule une variable en provenance du navigateur.
  * **''mixed    getPersistentVar(string $n, string $default)''**\\ Cette méthode retourne la valeur de la variable persistante ''$n''. Une variable persistante est une variable en provenance du navigateur, que l'on garde en mémoire (en sessions) même si le navigateur ne la renvoie plus. ''$default'' est la valeur qui sera renvoyée si aucune variable n'est trouvée.
  * **''null   delPersistentVar(string $n)''**\\ Supprime la variable persistante nommée ''$n''. Cette méthode retourne la non-valeur ''null''.
  * **''string  setPersistentVar(string $n, mixed $v)''**\\ Donne la valeur ''$v'' à la variable persistante nommée ''$n''. Cette méthode retourne ''$v''
  *  **void ''excludeVars(mixed $p1, $pn ...)''**\\ Les attributs de l'objet ayant pour nom $p1 à pn ne seront pas disponible dans le template associé. De ce faite ces variables ne seront plus serialisées lors des calcules automatiques du cache de Pxxo. Ceci est très pratique lorsque l'on manipule des objets non serialisables comme PDO en php5.




===== Contrôle et accès extérieur =====



  * **boolean  connect(string $event, pxxo_widget &$objet, string $mode, array $param = null)**

Méthode permettant de "connecter" le mode de l'objet courant avec un autre objet.
Deux cas possible en fonction de la présence ou non du paramètre $param.

Si $param vaut null et si l'objet courant est dans le mode $event, alors on positionne dans l'objet $objet le mode $mode.

Si $param est un tableau et si l'objet courant est dans le mode $event, alors on positionne dans l'objet $objet le mode $mode et on l'exécute.
Dans ce cas chaque valeur du tableau sera passée en paramètre à la méthode $mode.
Si en plus cette méthode est appelée après l'exécution du mode de l'objet courant, alors on ajoutera comme dernier paramètre à la méthode $mode, la valeur du retour de l'exécution de la méthode $event.

Cette méthode retourne TRUE, si la connexion a eu lieu.


__Exemple :__

<code php>
// Soit 3 widgets $a, $b t $c

// si $c est dans le mode `raz` 
// alors on passe l'objet $a en mode `defaut`
$c->connect('raz', $a, 'defaut');

// si $a est dans le mode `action1` 
// alors on exécute la méthode saisir de l'objet $b 
// avec les paramétres 1 et 4
$a->connect('action1', $b, 'saisir', array(1,4));

// si $b est dans le mode `somme` 
// alors on exécute la méthode `change` de  l'objet $c 
// avec comme paramétre la valeur de retour de la méthode `somme`
$b->connect('somme', $c, 'change', array());
</code>





  * **string dumphead()**

Affiche les lignes HTML nécessaires pour activer les feuilles de style et les fichiers Javascript. Ce sont des entêtes HTML : à placer dans la balise ''<head>'' de votre page.

__Remarque :__ si vous utilisez le décorateur [[:fr:doc:pxxo_widget_decorator_core|Core]], les entêtes seront automatiquement placées dans la balise ''<head>'' de votre page.

  * **mixed gethead($type = 'html')**

Très analogue à dumphead. Cette méthode n'affiche rien, elle retourne soit la chaîne de caractère des entêtes HTML du widget ($type = 'html'), soit un tableau php décrivant les ressources du widget ($type = 'array').

  * **''array getParamsArray()''**

Retourne la liste des paramètres du widget. Les clés sont les noms des paramètres et les valeurs sont les valeurs des paramètres. Cette méthode retourne en faite ce qui a été passé en paramètre au constructeur ($params) à la différence que les valeurs des paramètres peuvent avoir été modifié par l'exécution du widget suivant le moment où cette méthode est appelée.






===== Manipulation des décorateurs =====
  * **''Pxxo_Widget getDecorated()''** : cette méthode est utile lorsqu'elle est appelée depuis un décorateur, elle permet de retrouver l'instance du widget décoré. Dans le cas où elle est appelée depuis un widget classique, elle retourne ''null''.
  * **''mixed findParentWidget($classname, $onlyfirst = true)''** : Si ''$onlyfirst'' vaut true (par défaut), cette méthode retourne le premier widget parent dont le nom de la classe vaut ''$classname''. Si ''$onlyfirst'' vaut false, cette méthode retourne la liste des widgets parents dont le nom de la classe vaut ''$classname'', le tableau retourné est indexé par un identifiant de profondeur. L'identifiant de profondeur permet de savoir combien de widgets sont intercalés entre le widget courant et le widget recherché. La profondeur 0 correspond au widget courant. Une profondeur de 5 signifie donc qu'il y a 4 autres widgets dans la hiérarchie entre le widget courant et le widget recherché. Exemple :<code php>
$obj = new Pxxo_Widget_HelloWorld();
$obj->addDecorator('Pxxo_Widget_Decorator_Ajax');
$obj->addDecorator('Pxxo_Widget_Decorator_Border');
$obj->addDecorator('Pxxo_Widget_Decorator_Core');
$obj->main();

$wid = $obj->findParentWidget('Pxxo_Widget_Decorator_Border',false);
foreach($wid as $level => $w)
    echo 'level='.$level.' - widget='.$w->ClassID.'<br>';

$wid = $obj->findParentWidget('Pxxo_Widget_Decorator_Ajax');
echo $w->ClassID.'<br>';
</code> affichera <code>
level=3 - widget=Pxxo_Widget_Decorator_Border
Pxxo_Widget_Decorator_Ajax
</code>