La classe Calendar_Decorator est fournie pour vous aider à ajouter des fonctionnalités à des objets Calendar existants sans avoir besoin de les dériver. Cela est utile dans plusieurs situations, comme, permettre d'afficher le résultat d'une requête sous forme d'un Calendrier ou encore pour modifier les valeurs retournées par les méthodes de Calendar (convertir un numéro de mois en nom de mois).
Quelques décorateurs concrets sont fournis avec PEAR::Calendar, pour répondre aux problèmes communs que vous pouvez rencontrer en utilisant cette librairie. Ils ne sont pas faits pour répondre aux besoins particuliers de chacuns, mais ils pourront vous servir de base pour résoudre vos problèmes. Ils ne seront analysés par PHP que si vous les incluez explicitement dans votre code. Un exemple d'utilisation :
<?php
require_once 'Calendar/Day.php';
require_once 'Calendar/Decorator.php';
class WorkingDay extends Calendar_Decorator {
function WorkingDay(& $Calendar) {
parent::Calendar_Decorator($Calendar);
}
// On écrase la méthode fetch de l'objet Calendar
function fetch() {
if ( $Hour = parent::fetch() ) {
// Mode récursif, on ne retourne que les heures entre 8 heures du matin et 6 heures du soir
if ( $Hour->thisHour() < 8 || $Hour->thisHour() > 18 ) {
return $this->fetch();
} else {
return $Hour;
}
} else {
// Assurez-vous de retourner FALSE lorsque la vrai méthode fetch n'a rien retourné
// sinon vous aurez une boucle infinie
return FALSE;
}
}
}
// On crée la date du jour et on construit les heures
$Day = new Calendar_Day(date('Y'), date('n'), date('d'));
$Day->build();
// On crée le décorateur en passant la date du jour
$WorkingDay = new WorkingDay($Day);
// Seule les heures de travail sont affichées
while ( $Hour = $WorkingDay->fetch() ) {
echo ( $Hour->thisHour().'<br />' );
}
?>
La classe de base Calendar_Decorator permet d'accéder à l'API combinée de toutes les sous-classes de Calendar. Son constructeur doit recevoir un objet Calendar. La classe Calendar_Decorator prend alors le dessus sur l'API de cet objet vous permettant d'y accéder directement à travers le nouvel objet créé. Calendar_Decorator route tous les appels vers l'objet qu'il agrémente et renvoie les valeurs appropriées.
Une des fonctionnalités intéressante des décorateurs permet d' "injecter" des données dans la boucle permettant de créer les calendriers. Celà peut par exemple vous permettre d'intéragir avec une base de données. Lorsque un tableau sélectionné est passé à n'importe quelle méthode build(), les objets date sélectionnés remplaceront les objets construits par défaut, vous permettant de les récupérer en utilisant une boucle fetch(), utilisant la méthode isSelected(). Vous trouverez dans un exemple de celà sur la page de PEAR::Calendar. Il doit toujours être possible de récupérer les données d'un évènement dont vous avez besoin avec une simple requête à la base de données.
PEAR::Calendar fournit de base quelques décorateurs :
Calendar_Decorator_Textual
Décorateur permettant de récupérer les représentations textuelles des mois ainsi que des jours de la semaine.
Calendar_Decorator_Uri
Décorateur permettant la construction des liens HTML pour la navigation dans le calendrier.
Calendar_Decorator_Weekday
Décorateur pour récupérer le jour de la semaine.
Calendar_Decorator_Wrapper
Décorateur permettant la construction d'un fils dans un autre décorateur.
Ce décorateur définit quelques méthodes qui peuvent être utiles pour gérer les noms des mois et des jours :
monthNames($format ='long')
Retourne un tableau contenant les noms des mois ; le format des mois retournés dépend du paramètre format (one, two, short ou long)
weekdayNames($format ='long')
Retourne un tableau contenant les noms des jours ; le format des jours retournés dépend du paramètre format (one, two, short ou long)
prevMonthName($format ='long')
Retourne une représentation textuelle du mois précédent de l'objet calendar décoré
thisMonthName($format ='long')
Retourne une représentation textuelle du mois de l'objet calendar décoré
nextMonthName($format ='long')
Retourne une représentation textuelle du mois suivant de l'objet calendar décoré
prevDayName($format ='long')
Retourne une représentation textuelle du jour précédent de l'objet calendar décoré
thisDayName($format ='long')
Retourne une représentation textuelle du jour de l'objet calendar décoré
nextDayName($format ='long')
Retourne une représentation textuelle du jour suivant de l'objet calendar décoré
orderedWeekdays($format ='long')
Retourne le jour de la semaine en utilisant l'ordre défini dans l'objet calendar décoré. Uniquement utile pour Calendar_Month_Weekdays, Calendar_Month_Weeks et Calendar_Week. Autrement, le tableau retourné commencera par Samedi.
Méthodes définies par ce décorateur :
setFragments($y, $m=null, $d=null, $h=null, $i=null, $s=null)
Définie les noms des variables utilisées dans l'URI pour chaque élément de la date
setSeparator($separator )
Définie le séparateur, pour les instances '/' (défaut: &).
setScalar(boolean $state =TRUE)
Met les décorateurs d'URI dans le mode "scalaire" - les noms des variables de l'URI ne sont pas retournés
prev($method )
Récupère la chaîne URI pour la précédente unité calendar (année, mois, semaine ou journée etc.)
this($method )
Récupère la chaîne URI pour l'unité courante calendar (année, mois, semaine ou journée etc.)
next($method )
Récupère la chaîne URI pour l'unité suivante calendar (année, mois, semaine ou journée etc.)
Un exemple simple d'utilisation :
<?php
$Day = new Calendar_Day(2003, 10, 23);
$Uri = & new Calendar_Decorator_Uri($Day);
$Uri->setFragments('year', 'month', 'day');
echo $Uri->prev('day');
// Affiche year=2003&month=10&day=22
?>
Méthodes définies par ce décorateur :
setFirstDay($firstDay)
Définie le premier jour de la semaine (0 = Dimanche, 1 = Lundi [Défaut] etc.)
prevWeekDay($format='int')
Retourne le jour précédent de la semaine, formatté en accord avec le paramètre $format (int, array, object, timestamp)
thisWeekDay($format='int')
Retourne le jour courant de la semaine, formatté en accord avec le paramètre $format (int, array, object, timestamp)
nextWeekDay($format='int')
Retourne le jour suivant de la semaine, formatté en accord avec le paramètre $format (int, array, object, timestamp)
Exemple :
<?php
$Day = new Calendar_Day(2003, 10, 23);
$Weekday = & new Calendar_Decorator_Weekday($Day);
$Weekday->setFirstDay(0); // définie le premier jour de la semaine à Dimanche (défaut : Lundi)
echo $Weekday->thisWeekDay(); // Affiche 5 - cinquième jour de la semaine par rapport à Dimanche
?>
<?php
require_once 'Calendar/Month.php';
require_once 'Calendar/Decorator.php'; // Pas vraiment nécessaire mais ajouter pour aider à donner un sens
require_once 'Calendar/Decorator/Wrapper.php';
class MyBoldDecorator extends Calendar_Decorator
{
function MyBoldDecorator(&$Calendar)
{
parent::Calendar_Decorator($Calendar);
}
function thisDay()
{
return '<strong>'.parent::thisDay().'</strong>';
}
}
$Month = new Calendar_Month(date('Y'), date('n'));
$Wrapper = & new Calendar_Decorator_Wrapper($Month);
$Wrapper->build();
echo '<h2>The Wrapper decorator</h2>';
echo '<i>Day numbers are rendered in bold</i><br /> <br />';
while ($DecoratedDay = $Wrapper->fetch('MyBoldDecorator')) {
echo $DecoratedDay->thisDay().'<br />';
}
?>