dcTips()

Changement d'herbage...

Kozlika — Sun, 09 Mar 2008 07:56:00 +0100

Comme je vous l'avais annoncé il y a quelques semaines, ce site est désormais fondu avec celui de mes thèmes pour Dotclear 1 et celui de mes thèmes pour Dotclear 2.

L'URL http://dissitou.klafoutis.org ne répondra plus d'ici quelques semaines, pensez à modifier vos marque-page et vos abonnements RSS.

Rendez-vous désormais dans Les Ateliers du klafoutis.

Clearbricks : quelques autres fonctions de dbLayer

Moe — Mon, 31 Dec 2007 18:06:00 +0100

Dans le billet d'introduction (qu'il est préférable d'avoir lu avant d'aborder ce billet) nous avons vu comment effectuer des requêtes avec la fonction select() de dbLayer. Après avoir découvert comment lire les enregistrements dans la base de données, nous allons ici voir comment insérer, mettre à jour et effacer des enregistrements.

Voici pour rappel la table des lecteurs que nous avons utilisé comme exemple dans le billet d'introduction :

La table lecteurs

lecteurs
id	nom	role
1	Pierre	clown
2	Paul	développeur
3	Jacques	soutien moral
4	Olivier	chef
5	Kozlika	fée

Le curseur

Pour insérer ou mettre à jour un enregistrement avec dbLayer, il faut d'abord ouvrir un curseur. Cela se fait avec la commande openCursor() et permet de définir sur quelle table on va agir. Ici ce sera la table lecteurs.

Ouvrons un curseur :


$cur = $con->openCursor('lecteurs');

$cur est un cursor, ou curseur en français. Nous allons lui attribuer des variables qui correspondent aux colonnes de la table et des valeurs grâce à la syntaxe suivante :


$cur->variable = valeur;

Exemples :

Pour définir le nom :


$cur->nom = 'César';

Pour définir le rôle :


$cur->role = 'empereur';

Insérer un enregistrement avec la fonction `insert()`

Un nouveau lecteur est arrivé, il s'appelle Hector et son rôle est "évangéliste". Comment faire pour l'ajouter à la table des lecteurs ? On ouvre un curseur, on lui attribue des valeurs :


$cur = $con->openCursor('lecteurs');
$cur->nom = 'Hector';
$cur->role = 'évangéliste';

Ensuite on utilise la fonction insert(), elle va récupérer les variables et les valeurs pour les insérer dans la table :


$cur->insert();

Voici le code complet :


$cur = $con->openCursor('lecteurs');
$cur->nom = 'Hector';
$cur->role = 'évangéliste';
$cur->insert();

Et la table après l'insertion :

lecteurs
id	nom	role
1	Pierre	clown
2	Paul	développeur
3	Jacques	soutien moral
4	Olivier	chef
5	Kozlika	fée
6	Hector	évangéliste

Un enregistrement a été créé. Notez que l'id de cet enregistrement vaut 6 car la base de données a été configurée pour incrémenter l'id à chaque nouvel enregistrement.

Modifier un enregistrement avec la fonction `update()`

Pierre n'est plus clown, il est devenu professeur. Comment mettre à jour l'enregistrement de la table qui le concerne ? On ouvre un curseur et on attribue les nouvelles valeurs :


$cur = $con->openCursor('lecteurs');
$cur->role = 'professeur';

Puis on utilise la fonction update(), Le mot-clé WHERE permet de définir quel enregistrement nous allons mettre à jour, ici on veut modifier l'enregistrement de Pierre donc nous allons sélectionner l'enregistrement où le nom est "Pierre" :


$cur->update('WHERE nom = \'Pierre\';');

Voici le code complet :


$cur = $con->openCursor('lecteurs');
$cur->role = 'professeur';
$cur->update('WHERE nom = \'Pierre\';');

Et le résultat :

lecteurs
id	nom	role
1	Pierre	professeur
2	Paul	développeur
3	Jacques	soutien moral
4	Olivier	chef
5	Kozlika	fée
6	Hector	évangéliste

L'enregistrement a été mis à jour.

Effacer un enregistrement avec la fonction `execute()`

Il n'y a pas de fonction spéciale pour effacer un enregistrement, nous allons utiliser la commande execute() qui sert à exécuter des requêtes SQL.

Jacques n'est plus lecteur, Comment effacer l'enregistrement qui le concerne ? Voici la requête SQL qui va effacer l'enregistrement avec l'id 3 : DELETE FROM lecteurs WHERE id = 3;

On exécute la requête :


$query = 'DELETE FROM lecteurs WHERE id = 3;';
$con->execute($query);

Et la table devient :

lecteurs
id	nom	role
1	Pierre	professeur
2	Paul	développeur
4	Olivier	chef
5	Kozlika	fée
6	Hector	évangéliste

Notez qu'on aurait pu réaliser la même action avec cette requête SQL :


$query = 'DELETE FROM lecteurs WHERE nom = \'Jacques\';';

Quelques fonctions supplémentaires pour les recordsets

Ces fonctions permettent d'obtenir des informations sur les requêtes SELECT décrites dans le billet d'introduction.

`isEmpty()`

Cette fonction retourne true si un recordset est vide ou false sinon. Elle s'utilise dans une condition, pour voir si un recordset contient des enregistrements. Ici on va afficher les noms des lecteurs dont l'id est supérieur à 3 :


$query = 'SELECT nom FROM lecteurs WHERE id > 3;';
$rs = $con->select($query);

if ($rs->isEmpty())
{
    echo('aucun lecteur');
}
else
{
    while ($rs->fetch()) {echo($rs->f('nom').' ');}
}

Ce code affichera "aucun lecteur" si le recordset est vide et affichera les noms des lecteurs s'il y en a.

Pour ne pas afficher de message spécifique en cas de recordset vide on utilisera le code suivant :


$query = 'SELECT nom FROM lecteurs WHERE id > 3;';
$rs = $con->select($query);

if (!$rs->isEmpty())
{
    while ($rs->fetch()) {echo($rs->f('nom').' ');}
}

`count()`

Cette fonction retourne le nombre d'enregistrements présents dans un recordset :


$query = 'SELECT nom FROM lecteurs WHERE id > 3;';
$rs = $con->select($query);

echo('nombre d\'enregistrements : '.$rs->count);

Ceci affichera par exemple "nombre d'enregistrements : 2".

Conclusion

Grâce au billet précédent et à ce billet, vous savez lire et modifier des enregistrements dans des tables d'une base de données. Pour apprendre comment créer ou modifier des tables, voyez la documentation de Dotclear, Vous êtes prêts à gérer des tables dans une base de données avec Clearbricks.

Si les commentaires sont fermés, vous pouvez commenter ce billet sur mon blog.

Clearbricks : découverte de dbLayer et de sa fonction select()

Moe — Thu, 22 Nov 2007 19:22:00 +0100

Introduction à Clearbricks

Dotclear utilise son propre framework qui n'est pas un framework : Clearbricks, il est composé d'une ensemble de classes et de fonctions, on y trouve par exemple une classe destinée à traiter les chaînes HTML ou une classe servant à formater les dates. Nous allons nous intéresser à la classe dbLayer.

La base de données

Comme son nom l'indique, c'est une base ... de données. Concrètement, ça stocke des informations sous forme de tables (qui sont des tableaux) dans lesquelles on peut sélectionner des informations, les trier ou ajouter une information, etc. Pour cela on utilise des requêtes écrites en langage SQL. Ce langage est un standard et permet de faire des requêtes à différents types de base de données^[1]. Clearbricks peut se connecter à trois types de bases de données : MySQL, PostgreSQL (noté aussi PGSQL) et SQLite (très peu utilisé).

La classe dbLayer

dbLayer est le diminutif de database layer, ou couche de la base de données en français. C'est une couche d'abstraction, ce qui signifie qu'on fait appel à dbLayer pour réaliser des actions (ici des requêtes SQL) sans se soucier de ce qu'il y a en-dessous. Au lieu d'utiliser les fonctions de PHP telles que mysql_query() et pg_query() on utilisera les fonctions de dbLayer en faisant abstraction du type de la base de données.

On peut schématiser ainsi le cheminement d'une requête SQL :

Grâce à Clearbricks et dbLayer, on a un code qui gère indifféremment les 2 types de base de données.

La table lecteurs

Imaginons qu'on ait créé une table lecteurs :

lecteurs
id	nom	role
1	Pierre	clown
2	Paul	développeur
3	Jacques	soutien moral
4	Olivier	chef
5	Kozlika	fée

Cette table est un tableau composé de 3 champs (les colonnes) : id (l'identifiant de la ligne) correspondant à l'ordre dans lequel les lecteurs se sont enregistrés, nom (le nom des utilisateurs) et role qui est le rôle de l'utilisateur. Cette table compte 5 enregistrements (les lignes). Elle servira d'exemple dans ce billet.

Admettons que la connexion a la base de données a été effectuée, c'est l'objet $con. Nous allons voir comment utiliser la fonction select().

Première requête sur un enregistrement et un champ

Comment faire pour afficher le nom du premier lecteur ?

Voici la requête en pseudo-code : "sélectionner nom dans la table lecteurs où id = 1" et en SQL :

$query = 'SELECT nom FROM lecteurs WHERE id = 1;';

Effectuons la requête :

$rs = $con->select($query);

$rs est un recordset, c'est un groupe d'enregistrements (ici un seul) qui contient les champs (ici le champ nom). On accède au champ nom grâce à la fonction field() ou sa version raccourcie f(), on l'affiche ainsi :

echo($rs->f('nom'));

Ceci affichera "Pierre". Notez qu'il existe une syntaxe simplifiée pour afficher le même résultat :

echo($rs->nom);

On peut aussi effectuer la même opération en une ligne :

echo($con->select($query)->nom);

Une requête sur un champ avec plusieurs enregistrements

Comment afficher les noms des derniers lecteurs ?

Voici la requête en pseudo-code : "sélectionner nom dans la table lecteurs en rangeant par id décroissant en se limitant à 2 enregistrements" et en SQL :

$query = 'SELECT nom FROM lecteurs ORDER BY id DESC LIMIT 2;';

Effectuons la requête :

$rs = $con->select($query);

Le recordset $rs contient 2 enregistrements, on ne peut plus accéder directement au champ nom des 2 enregistrements avec f('nom'). On va parcourir les enregistrements avec une boucle grâce à la fonction fetch() :

while ($rs->fetch()) {echo($rs->f('nom').' ');}

Ceci va afficher "Kozlika Olivier".

Une requête sur plusieurs champs de plusieurs enregistrements

Comment afficher les noms et les rôles des 3 premiers lecteurs ?

Voici la requête en pseudo-code : "sélectionner nom et rôle dans la table lecteurs par id croissant en se limitant à 3 enregistrements" et en SQL :

$query = 'SELECT nom,role FROM lecteurs ORDER BY id ASC LIMIT 3;';

Effectuons la requête :

$rs = $con->select($query);

Le recordset $rs contient 3 enregistrements et 2 champs, on va devoir parcourir les enregistrements comme précédemment :

while ($rs->fetch()) {echo($rs->f('nom').' : '.$rs->f('role').' ');}

Ceci va afficher "Pierre : clown Paul : développeur Jacques : soutien moral".

Conclusion

Désormais vous savez utiliser les fonctions de dbLayer pour effectuer des requêtes SQL de type SELECT.

Si les commentaires sont fermés, vous pouvez commenter ce billet sur mon blog en attendant la réouverture des commentaires sur ce blog.

Merci à Kozlika, Franck Paul et Biou pour leurs conseils et le temps qu'ils m'ont accordé.

Notes

[1] le langage peut différer d'un type à l'autre

Fermeture pendant les travaux

Kozlika — Thu, 22 Nov 2007 10:53:00 +0100

Les commentaires et rétroliens sont fermés pour quelque temps pendant la refonte de l'organisation de klafoutis.org

C'est pas grave, de toutes façons le meilleur endroit pour poser des questions c'est http://dotclear.net/forum/ :)

Balises : 9. Afficher un billet ou un texte fixe

Franck — Fri, 13 Jul 2007 11:24:00 +0200

Continuons (et terminons) notre exercice pratique dont je rappelle l'énoncé :

J'ai prévu d'afficher un bloc particulier sur la page d'accueil. Ce bloc contiendra le dernier billet publié d'une catégorie précise ou à défaut, un texte fixe. Cette catégorie s'appellera Flash et ne servira qu'à gérer ce genre de petits messages et par conséquent ses billets ne devront pas apparaitre dans le flux normal^[1].

Nous savons maintenant comment déterminer correctement si nous nous trouvons sur la première page (page d'accueil), il s'agit maintenant de faire en sorte d'afficher le dernier billet publié de la catégorie Flash, ou, s'il n'en existe aucun, d'afficher un texte fixe.

Voilà le code utilisé :

<tpl:FlagFirstPageIf true="1">

  {{tpl:FlagFlashPost}}

  <!-- # Last published post from Flash category (if exists) -->
  <tpl:Entries category="Flash" lastn="1">
    <h2 class="intro" id="p{{tpl:EntryID}}">
    <strong>{{tpl:EntryTitle encode_html="1"}}</strong></h2>
    <tpl:EntryIf extended="1"><span>{{tpl:EntryExcerpt}}</span></tpl:EntryIf> 
    <div class="post-content">{{tpl:EntryContent}}</div>
    {{tpl:FlagFlashPost true="1"}}
  </tpl:Entries>

  <tpl:FlagFlashPostIf true="0">
    <!-- # Standard text if there is no published post from Flash category -->
    <h2 class="intro"><strong>{{tpl:BlogDescription}}</strong></h2>
    <div class="post-content">
      <p>Ze best blog on ze best world of ze universe.</p>
    </div>
  </tpl:FlagFlashPostIf>

</tpl:FlagFirstPageIf>

J'ai mis l'emphase sur l'utilisation de deux nouvelles balises ({{tpl:FlagFlashPost}} et <tpl:FlagFlashPostIf> qui sont exactement les mêmes que celles décrites dans les deux billets précédents à ceci près qu'elles utilisent une autre variable dans le code PHP.

Ces nouvelles balises me servent à positionner un drapeau (variable à true ou à false) en fonction de la présence ou pas d'un billet publié dans la catégorie Flash, et de tester la valeur de ce drapeau ce qui me permet, plus bas, d'afficher le texte standard si nécessaire.

Il n'y a absolument rien de nouveau ici, uniquement l'utilisation de techniques déjà expliquées précédemment ou reprises dans les fichiers standards du thème defaut. Rien de plus à mettre en place pour terminer notre exercice, on peut sauvegarder le fichier _intro.html et vérifier que tout fonctionne comme attendu.

Voilà qui conclut cette série de billets sur les templates de Dotclear 2. J'espère que cela aura permis d'éclairer quelques zones d'ombres dans ce système qui peut — qui doit même pour certains — paraitre bien compliqué au premier abord. Je parle en connaissance de cause, je suis passé par cette phase ;-)

Notes

[1] Par contre j'ai choisi de laisser l'accès à tous ces billets particuliers dans la liste des catégories ou dans les archives.

Balises : 8. Le fichier _public.php en détail

Franck — Mon, 09 Jul 2007 23:15:00 +0200

Si vous voulez plus d'information sur ce fichier _public.php qui accompagne parfois les thèmes, alors continuez la lecture de ce billet, sinon rendez-vous au prochain pour la suite de l'exercice.

Voilà, pour l'instant, à quoi ressemble notre _public.php :

<?php

class dcFallSeason
{

  static public function FlagFirstPage($attr)
  {
    if (isset($attr['true'])) {
      $flag = 'true';
    } else {
      $flag = 'false';
    }
    return '<?php $dcFallSeasonFlagFirstPage = '.$flag.'; ?>';
  }

  static public function FlagFirstPageIf($attr,$content)
  {
    $if = '';

    if (isset($attr['true'])) {
      $sign = (boolean) $attr['true'] ? '' : '!';
      $if = $sign.'$dcFallSeasonFlagFirstPage';
    }

    if ($if != '') {
      return '<?php if('.$if.') : ?>'.$content.'<?php endif; ?>';
    } else {
      return $content;
    }
  }

}

// Add Flag management to the template scheme
$core->tpl->addValue('FlagFirstPage',
    array('dcFallSeason','FlagFirstPage'));
$core->tpl->addBlock('FlagFirstPageIf',
    array('dcFallSeason','FlagFirstPageIf'));

?>

Détaillons-le un peu. Première et dernière lignes classique dans un fichier PHP, <?php et ?>. À l'intérieur de ceci nous y trouvons deux parties. La première définit une classe dcFallSeason, un nom qui reprend le nom du thème précédé de dc. Cette classe sert à définir les fonctions de traitement des nouvelles balises qui seront utilisées au sein du thème. La deuxième partie permet de déclarer à DotClear 2 les nouvelles balises template et les fonctions de traitement qui en dépendent.

Le plus simple d'abord, la déclaration des nouvelles balises. Je rappelle qu'il y en a deux, une de type simple <tpl:FlagFirstPage> et une de type bloc <tpl:FlagFirstPageIf>, respectivement déclarées de la manière suivante :

$core->tpl->addValue('FlagFirstPage',
    array('dcFallSeason','FlagFirstPage'));

$core->tpl->addBlock('FlagFirstPageIf',
    array('dcFallSeason','FlagFirstPageIf'));

Le premier paramètre définit le nom utilisé dans la balise — ce qui suit le <tpl:, le deuxième, sous forme de tableau (array), définit le nom de la classe (dcFallSeason dans notre cas) et le nom de la fonction associée. addValue() est utilisée pour une balise simple, addBlock() pour une balise de type bloc. De cette manière, lorsque Dotclear 2 rencontrera une de nos balises dans un fichier du thème, il saura quelle est la fonction de traitement qui doit être utilisée.

Voyons maintenant les fonctions de traitement. La première, FlagFirstPage() reçoit un paramètre, sous forme de tableau, contenant les attributs éventuels et leurs valeurs utilisés dans la balise. La deuxième, FlagFirstPageIf() reçoit en plus un paramètre contenant le contenu de ce qui est encadré par la balise (de type bloc). Les deux fonctions doivent retourner le code PHP (ou HTML) correspondant à la balise.

Je vais détailler le code de la première, la seconde devrait être comprise assez facilement. Voilà le code :

1. static public function FlagFirstPage($attr)
2. {
3.  if (isset($attr['true'])) {
4.    $flag = 'true';
5.  } else {
6.    $flag = 'false';
7.  }
8.  return '<?php $dcFallSeasonFlagFirstPage = '.$flag.'; ?>';
9. }

Ligne 1, il s'agit de la déclaration de la fonction et des paramètres attendus (un seul dans ce cas). Les lignes 2 et 9 délimitent le code de la fonction. Ligne 3, je contrôle qu'un attribut intitulé true a ou n'a pas été spécifié dans la balise (ex <tpl:FlagFirstPage> ou <tpl:FlagFirstPage true="1">). Ligne 4, interprétée si l'attribut a été utilisé, permet de positionner la valeur 'true' à une variable texte ($flag). La ligne 6, interprétée dans le cas contraire, permet de positionner la valeur 'false' à cette même variable. La ligne 8, enfin, retourne le texte par lequel sera remplacée la balise.

Exemple :

Si j'utilise la balise <tpl:FlagFirstPage>, la fonction va alors retourner ceci <?php $dcFallSeasonFlagFirstPage = false; ?>, ce qui revient à déclarer et à initialiser une variable avec la valeur false (faux).

Si j'utilise la balise <tpl:FlagFirstPage true="1">, la fonction va retourner cela <?php $dcFallSeasonFlagFirstPage = true; ?>, ce qui revient à déclarer et à initialiser une variable avec la valeur true (vrai).

Cette variable, $dcFallSeasonFlagFirstPage, positionnée à true ou false, sera ensuite testée avec la balise <tpl:FlagFirstPageIf> dans le thème, permettant de conditionner l'apparition d'un bloc en fonction du résultat, l'affichage du bloc d'intro dans notre cas.

Vous devriez maintenant comprendre un peu mieux comment s'opère la phase de traitement des balises template de Dotclear 2.

À suivre …

Balises : 7. Exercice pratique, développer ses propres balises

Franck — Mon, 09 Jul 2007 23:10:00 +0200

Nous avons un petit problème à résoudre (voir ce billet pour en retrouver l'énoncé). Dotclear 2 inclut la possibilité de définir ses propres balises template au niveau du thème^[1]. Pour cela, il faut créer un fichier _public.php qui contiendra tout le code PHP nécessaire au traitement de ces balises.

Revenons à notre problème. Nous avons besoin d'éviter l'imbrication de deux balises <tpl:Entries> (lignes 1 et 4) :

1. <tpl:Entries category="!Flash" no_content="1">
2.   <tpl:Pagination>
3.     <tpl:PaginationIf start="1">
4.       <tpl:Entries category="Flash" lastn="1">
5.         …
6.       </tpl:Entries>
7.     </tpl:PaginationIf>
8.   </tpl:Pagination>
9. </tpl:Entries>

L'idée que j'ai retenue est de faire en sorte de positionner une variable si l'on est sur la première page, juste après la ligne 3, puis de tester cette même variable une fois sorti du bloc template <tpl:Entries> (ligne 9). Voilà le nouveau code (j'ai mis l'emphase sur ce qui est nouveau) :

{{tpl:FlagFirstPage}}
<tpl:Entries category="!Flash" no_content="1">
  <tpl:Pagination>
    <tpl:PaginationIf start="1">
      {{tpl:FlagFirstPage true="1"}}
    </tpl:PaginationIf>
  </tpl:Pagination>
</tpl:Entries>
<tpl:FlagFirstPageIf true="1">
  <tpl:Entries category="Flash" lastn="1">
    …
  </tpl:Entries>
</tpl:FlagFirstPageIf>

Deux nouvelles balises doivent être développées. La première, {{tpl:FlagFirstPage}}, sert à positionner la variable dont je ai parlé précédemment. Si la balise est utilisée sans aucun paramètre, la variable sera initialisée à false (faux). Si la balise contient un attribut true="1" alors la variable sera initialisée à true (vrai). La deuxième, sous forme de bloc de test (<tpl:FlagFirstPageIf> … </tpl:FlagFirstPageIf>) sert à tester la valeur de la variable ce qui permettra de réutiliser une balise <tpl:Entries> pour récupérer le dernier billet de la catégorie Flash^[2].

Voyons maintenant à quoi ressemble ce fichier _public.php qui contiendra tout le code nécessaire.

<?php

class dcFallSeason
{

  static public function FlagFirstPage($attr)
  {
    if (isset($attr['true'])) {
      $flag = 'true';
    } else {
      $flag = 'false';
    }
    return '<?php $dcFallSeasonFlagFirstPage = '.$flag.'; ?>';
  }

  static public function FlagFirstPageIf($attr,$content)
  {
    $if = '';

    if (isset($attr['true'])) {
      $sign = (boolean) $attr['true'] ? '' : '!';
      $if = $sign.'$dcFallSeasonFlagFirstPage';
    }

    if ($if != '') {
      return '<?php if('.$if.') : ?>'.$content.'<?php endif; ?>';
    } else {
      return $content;
    }
  }

}

// Add Flag management to the template scheme
$core->tpl->addValue('FlagFirstPage',
    array('dcFallSeason','FlagFirstPage'));
$core->tpl->addBlock('FlagFirstPageIf',
    array('dcFallSeason','FlagFirstPageIf'));

?>

Que fait tout ce code ? La première fonction, FlagFirstPage, est utilisée lors du remplacement de la balise {{tpl:FlagFirstPage}} et donnera le code PHP suivant :

<?php $dcFallSeasonFlagFirstPage = false; ?>

<?php $dcFallSeasonFlagFirstPage = true; ?>

si on utilise l'attribut true="1" dans la balise. La deuxième fonction, FlagFirstPageIf, est utilisée lors du remplacement de la balise <tpl:FlagFirstPageIf> … </tpl:FlagFirstPageIf> et donnera le code suivant (si on l'utilise tel que je l'ai fait plus haut) :

<?php if($dcFallSeasonFlagFirstPage) : ?>
 …
<?php endif; ?>

Je vais arrêter là pour la description du code PHP du fichier _public.php pour le reprendre plus en détail dans le prochain billet.

À suivre …

Notes

[1] Il est également possible d'en définir avec un plugin mais ça dépasse le cadre de ce tutoriel.

[2] Vous aurez surement remarqué que ce bloc a été déplacé plus bas et en dehors du premier bloc de même nature.

Balises : 6. Exercice pratique, se limiter à la première page

Franck — Mon, 09 Jul 2007 23:06:00 +0200

Je continue la suite du petit exercice commencé dans ce billet. Pour rappel voilà son énoncé :

J'ai prévu d'afficher un bloc particulier sur la page d'accueil. Ce bloc contiendra le dernier billet publié d'une catégorie précise ou à défaut, un texte fixe. Cette catégorie s'appellera Flash et ne servira qu'à gérer ce genre de petits messages et par conséquent ses billets ne devront pas apparaitre dans le flux normal.

Nous avons vu comment exclure une catégorie du flux normal des billets, la catégorie Flash. Voyons maintenant comment traiter le bloc qui doit être affiché sur la première page. J'ai choisi de mettre tout ce qui sera utilisé pour ce bloc dans un fichier particulier, nommé _intro.html, et qui est inclus juste après la balise <div id="wrapper"> du fichier home.html^[1]. Voilà la portion de code du fichier home.html (j'ai mis l'emphase sur ce que j'ai rajouté) :

<div id="wrapper">

<!-- # Franck Paul : ajout du bloc d'intro -->
{{tpl:include src="_intro.html"}}

Ce sera la dernière modification du fichier home.html, et vous aurez certainement remarqué au passage le signe # utilisé dans le commentaire pour qu'il ne soit pas inclus dans le code HTML généré par DotClear 2.

Voyons maintenant le contenu du fichier _intro.html. Première chose à faire, encadrer tout le bloc dans une balise <div> afin de pouvoir lui appliquer des styles particuliers :

<div id="introcontent">
…
(contenu du bloc)
…
</div>

Passons maintenant au contenu du bloc. Celui-ci, billet ou texte fixe, doit être affiché uniquement sur la première page. Pour le déterminer, il faut utiliser le code suivant :

<tpl:Entries category="!Flash" no_content="1">
   <tpl:Pagination>
      <tpl:PaginationIf start="1">
      …
      (affichage du dernier billet Flash ou d'un texte fixe)
      …
      </tpl:PaginationIf>
   </tpl:Pagination>
</tpl:Entries>

Normalement vous devez avoir reconnu la première ligne, <tpl:Entries category="!Flash" no_content="1">, qui permet de retrouver la liste des billets ne faisant pas partie de la catégorie Flash. On utilise l'attribut no_content="1" car nous n'avons pas besoin du contenu des billets. Vous reconnaitrez sans difficulté la balise qui ferme le bloc à la fin : </tpl:Entries>.

À l'intérieur de ce bloc, qui définit une sorte de contexte où nous avons à notre disposition la liste des billets, nous pouvons utiliser un bloc spécifique à la pagination, <tpl:Pagination> et </tpl:Pagination>, qui permettra ensuite de tester la page courante à l'aide, encore une fois d'un bloc de test, <tpl:PaginationIf start="1"> et </tpl:PaginationIf>. L'attribut start="1" permet de tester si on est sur la première page^[2].

Pour résumer, on définit le contexte servant à déterminer le nombre de page (nombre de billets retrouvés divisé par le nombre de billets par page précisé dans les préférences du blog) et on vérifie que la page courante est la première.

Une fois ce test effectué, nous allons récupérer, s'il existe, le dernier billet publié de la catégorie Flash. Le bloc nécessaire pour obtenir celui-ci est le suivant :

<tpl:Entries category="Flash" lastn="1">
…
</tpl:Entries>

Ici on ne retient que la catégorie Flash (attribut category="Flash") et uniquement le dernier publié (attribut lastn="1"^[3]).

Intégrons maintenant ce code dans le code précédent (test de la première page). Cela donne cela :

<tpl:Entries category="!Flash" no_content="1">
   <tpl:Pagination>
      <tpl:PaginationIf start="1">
         <tpl:Entries category="Flash" lastn="1">
         …
         </tpl:Entries>
      </tpl:PaginationIf>
   </tpl:Pagination>
</tpl:Entries>

Allo … Houston ? On a un problème !

En effet il s'avère qu'on ne peut imbriquer des blocs template de même nature^[4] (<tpl:Entries> en ce qui nous concerne) ! Comment contourner ce soucis ? Et bien en développant nos propres balises (ou fonctions) template qui serviront à stocker le résultat des tests que nous effectuons (première page, présence d'au moins un billet publié dans la catégorie Flash).

Rendez-vous au prochain billet pour la suite des templateurs fous \o/

Notes

[1] Je rappelle que ce bloc ne doit être affiché que sur la page d'accueil. On pourra si nécessaire ré-utiliser ce fichier _intro.html dans d'autres contextes si nécessaire.

[2] On peut également savoir si on est sur une autre page que la première en utilisant l'attribut start="0". De même, on peut utiliser l'attribut end="1" pour déterminer si l'on est sur la dernière page, ou end="0" pour les autres pages.

[3] Si vous voulez les trois derniers billets, il vous suffit d'utiliser l'attribut lastn="3".

[4] J'en avais détaillé la raison dans ce billet.

Balises : 5. Exercice pratique, utiliser les attributs des balises

Franck — Mon, 09 Jul 2007 23:03:00 +0200

Maintenant que nous avons vu l'essentiel de ce qu'il faut savoir à propos des templates de Dotclear 2 nous allons faire un petit exercice pratique. Nous y verrons comment personnaliser un peu notre thème et au passage comment développer quelques petites fonctions très basiques en PHP.

Prêts ? Alors voilà l'énoncé de l'exercice :

J'ai prévu d'afficher un bloc particulier sur la page d'accueil. Ce bloc contiendra le dernier billet publié d'une catégorie précise ou à défaut, un texte fixe. Cette catégorie s'appellera Flash et ne servira qu'à gérer ce genre de petits messages et par conséquent ses billets ne devront pas apparaitre dans le flux normal^[1].

Traduit en pseudo langage informatique cela donnera ceci :

si premiere_page alors
   si billet_flash existe alors
      afficher billet_flash
   sinon
      afficher un texte fixe
   fin_si
fin_si
afficher billets_non_flash

Par où commencer ? Ce traitement doit s'appliquer uniquement sur la page d'accueil donc on fera les modifications sur le fichier home.html du thème^[2].

Dans ce fichier on trouve normalement un bloc template de cette forme :

<div id="main">
   <div id="content">
      <tpl:Entries>
…
      </tpl:Entries>
   </div>
</div>

Première chose à faire, surtout la plus aisée, exclure la catégorie Flash de la liste des billets affichés normalement. Pour cela il suffit de rajouter l'attribut category="!Flash" dans la balise <tpl:Entries>. Voilà le code modifié :

<div id="main">
   <div id="content">
      <tpl:Entries category="!Flash">
…
      </tpl:Entries>
   </div>
</div>

Vous aurez peut-être remarqué, dans le fichier home.html, un autre endroit où apparait la balise <tpl:Entries no_content="1">, dans la section <head>. Ici aussi il faut rajouter l'attribut category="!Flash" ce qui donnera :

 <tpl:Entries category="!Flash" no_content="1">

Dernière précision, le ! utilisé devant le nom de la catégorie sert à exclure les billets de cette dernière de la liste de ceux qui seront traités (affichés)^[3].

Nous voilà donc avec une page d'accueil dont les billets de la catégorie Flash ne seront pas affichés. Prochaine étape, le bloc d'introduction sur la première page. Nous verrons dans le prochain billet comment déterminer si l'on est sur la première page ou pas et le problème — facile à résoudre — que cela peut poser pour la suite de notre exercice.

Notes

[1] Par contre j'ai choisi de laisser l'accès à tous ces billets particuliers dans la liste des catégories ou dans les archives.

[2] Si votre thème ne possède pas un tel fichier, il suffit de faire une copie de celui qui est présent dans le répertoire du thème par défaut (répertoire default) et de le copier dans le répertoire de votre thème.

[3] Vous pouvez si nécessaire mettre une liste de catégorie dont les noms seront séparés par une virgule. Tous les billets de ces catégories seront alors ignorés. Bien sûr la réciproque est vraie. En ne mettant pas le ! devant la ou les catégories, nous ne récupérerons que les billets de cette ou de ces catégories.

Balises : 4. Ne pas imbriquer des balises de même nom

Franck — Mon, 09 Jul 2007 23:01:00 +0200

Vous savez maintenant qu'il y a deux formes de balises pour les templates, les simples ({{tpl:…}}) et les blocs (<tpl:…> et </tpl:…>).

Une des précautions à prendre à propos des blocs est qu'il ne faut pas imbriquer deux blocs de même nom. Je m'explique sur un exemple. Voyez le code suivant :

1. <tpl:PaginationIf start="1">
2.   <div id="intro">
3.   <p>Début du blog</p>
4.   <tpl:PaginationIf end="1">
5.     <p>Fin du blog</p>
6.   </tpl:PaginationIf>
7.   </div>
8. </tpl:PaginationIf>

Logiquement il signifie ceci :

Si c'est la première page alors on ouvre une <div> avec un texte particulier (Début du blog), puis, si de plus, c'est également la dernière page — donc il n'y a qu'une page, alors on rajoutera un autre texte (Fin du blog). Chacune des conditions est testée à l'aide d'une balise intitulée <tpl:PaginationIf …>.

Au moment d'interpréter les balises <tpl:…> pour les remplacer par le code PHP nécessaire, Dotclear 2 va trouver la première balise sur la ligne 1. C'est une balise ouvrante et il va ensuite chercher la première balise fermante de même nom. Celle-ci se trouve sur la ligne 6. Ce sont donc les lignes 2 à 5 qui vont dépendre de la condition testée à la ligne 1 :

1. <tpl:PaginationIf start="1">
2.   <div id="intro">
3.   <p>Début du blog</p>
4.   <tpl:PaginationIf end="1">
5.     <p>Fin du blog</p>
6.   </tpl:PaginationIf>
7.   </div>
8. </tpl:PaginationIf>

Bien sûr Dotclear 2 va traiter ces lignes pour éventuellement y chercher des balises templates à remplacer, et il va trouver celle qui se trouve sur la ligne 4, seulement cette balise n'a pas de balise fermante associée et par conséquent sera ignorée.

Une fois ce premier bloc de balise traité (lignes 1 à 6), Dotclear 2 va traiter la suite — c'est à dire les lignes 7 à 8, y trouver une balise fermante sur la ligne 8 mais comme aucune balise ouvrante n'a été trouvée auparavant, elle sera également ignorée :

Conclusion nous allons nous retrouver avec le code suivant (l'emphase est mise sur les balises non traitées)^[1] :

1. <?php if (page_courante == 1) : ?>
2.   <div id="intro">
3.   <p>Début du blog</p>
4.   <tpl:PaginationIf end="1">
5.     <p>Fin du blog</p>
6.   <?php endif; ?>
7.   </div>
8. </tpl:PaginationIf>

C'est ce code qui va être ensuite pris en charge par le serveur pour interpréter le code PHP inséré et il va ignorer les balises laissées par Dotclear 2, éventuellement en vous gratifiant d'un petit message au passage. Bref pas glop !

Donc pour résumer, si vous utilisez une balise ouvrante quelque part, pensez à insérer la balise fermante correspondante avant de la réutiliser. Parfois cette limitation peut poser problème et je vous expliquerai dans un prochain billet comment écrire vos propres balises pour palier ce problème.

Notes

[1] La ligne 1 est un exemple de code PHP plausible mais n'est pas la ligne réellement insérée par Dotclear 2. J'ai préféré mettre quelque chose de simple pour éviter d'encombrer la démonstration.

Balises : 3. les deux formes de balises

Franck — Mon, 09 Jul 2007 22:55:00 +0200

Je continue ma petite série sur les templates utilisés pour les thèmes de Dotclear 2. Je vous avais parlé dans ce premier billet des deux formes de balises spécifiques aux templates :

celles qui sont sous la forme {{tpl:…}}
celles qui sont sous la forme <tpl:…> et </tpl:…>

Ces balises sont remplacées par Dotclear 2 par des instructions PHP qui seront ensuite traitées par le serveur.

La première forme est principalement utilisée pour générer du contenu comme par exemple l'affichage de la description du blog dans l'entête avec la balise suivante :

{{tpl:BlogDescription}}

Que va faire Dotclear 2 avec cette balise ? Et bien il va simplement la remplacer par le code PHP suivant :

<?php echo context::global_filter($core->blog->desc,0,0,0,0,0); ?>

Ensuite le serveur interprètera cette instruction qui sert à récupérer la description du blog dans la base de donnée et à l'afficher^[1].

La deuxième forme, composée de deux balises, une ouvrante (<tpl:…>) et une fermante (</tpl:…>), permet principalement de traiter un contenu HTML^[2] seulement si une condition est remplie (balise de test) ou autant de fois que nécessaire (balise de boucle).

Deux exemples, un pour pour chaque type :

Imaginons que je souhaite afficher un texte uniquement si on se trouve sur la page numéro 1 du blog et pas sur les suivantes. Je vais utiliser le code suivant dans mon thème :

<tpl:PaginationIf start="1">
  <p>Un joli texte affiché uniquement sur la première page.</p>
</tpl:PaginationIf>

La première balise permet de tester une condition, ici Est-on au début de la pagination, c'est-à-dire sur la page 1 ?. Ensuite nous trouvons le contenu qui sera traité uniquement si la condition est remplie, puis une balise qui indique la fin de ce qui est dépendant de la condition testée.

Imaginons maintenant que je souhaite afficher les 10 derniers billets d'une catégorie. Je vais utiliser le code suivant :

<tpl:Entries category="Flash" lastn="10">
  …
  affichage du contenu du billet (titre, introduction, …)
  …
</tpl:Entries>

La première balise permet de définir ce qu'on veut récupérer, ici les 10 derniers billets (lastn="10") de la catégorie Flash (category="Flash"). Puis pour chacun de ces 10 billets, tout ce qui se trouve jusqu'à la balise de fin (</tpl:Entries>) sera répété.

J'espère que c'est suffisamment clair pour tout le monde. Si vous avez tout compris jusqu'ici et bien vous savez tout (ou presque) du système de template de Dotclear 2. Je vous parlerai bientôt de ce qu'on peut faire avec tout ça, des quelques précautions qu'il faut prendre et tout ça sur un exemple concret^[3].

Notes

[1] L'instruction PHP echo est utilisée pour afficher quelque chose dans la page que l'on est en train de visualiser.

[2] Ce contenu peut également comporter des balises templates, des deux formes.

[3] Il s'agit de mon futur thème Dotclear 2, mais chut, personne n'est au courant !

Balises : 2. les commentaires invisibles et le PHP dans les thèmes

Franck — Mon, 09 Jul 2007 22:39:00 +0200

Vous savez maintenant qu'il y a une étape de plus dans le traitement des thèmes avec Dotclear 2. Avant d'aller plus loin dans les explications sur ces fameuses balises template dont je vous parlais précédemment (voir ce billet), deux petites remarques :

Pas la peine de mettre des instructions en PHP dans les fichiers du thème vu qu'elles sont supprimées par Dotclear 2 lors du traitement.^[1] Si vous avez besoin de fonctions particulières en PHP pour obtenir ce que vous souhaitez, c'est prévu dans Dotclear 2 et je vous en dirai rapidement comment le faire.

Les commentaires HTML ayant la forme  — notez le # au début — seront également supprimés pendant le traitement. Ce qui veut dire que vous pouvez — c'est même fortement conseillé — commenter à loisir toutes les modifications que vous ferez sans pour cela surcharger la page qui résultera du traitement.

Un exemple étant plus parlant, voilà un exemple de fichier HTML :

1. <div id="intro">
2.
3. <!-- # Affichage du résultat d'un appel de fonction PHP -->
4. <?php echo dcMyTemplate::myFunction(); ?>
5.
6. <!-- Debut du bloc -->
7. <p>Lorem Ipsum …</p>
8. </div>

Et voilà ce qu'il en ressortira une fois passé dans les fourches caudines de Dotclear 2 :

1. <div id="intro">
2. 
3. 
4.
5.
6. <!-- Debut du bloc -->
7. <p>Lorem Ipsum …</p>
8. </div>

Les lignes 3 et 4 qui contenaient respectivement un commentaire masquable (avec le # au début) et du code PHP ont été supprimées. Vous remarquerez que le commentaire de la ligne 6 est resté tel quel et qu'il sera donc visible dans le code HTML final de la page.

Notes

[1] Bien sûr il y a un moyen de désactiver ceci, ce qui permettra l'interprétation du code par le serveur, mais cela reste spécifique à votre installation et n'est en aucun cas la configuration standard. Il est donc illusoire de vouloir distribuer un thème nécessitant ce changement de configuration.

Balises : 1. Introduction aux balises de Dotclear 2

Franck — Mon, 09 Jul 2007 22:35:00 +0200

Voilà un premier billet à propos des thèmes de Dotclear 2 et plus particulièrement au sujet des balises templates.

Un thème Dotclear 1 est constitué de fichiers PHP directement interprétés par le serveur pour générer la page HTML qui sera affichée^[1], alors qu'un thème Dotclear 2 est constitué de fichiers HTML contenant des balises spéciales qui seront traitées par Dotclear 2 pour générer des fichiers PHP qui seront ensuite, comme Dotclear 1, interprétés par le serveur pour générer la page HTML qui sera affichée.

C'est clair ? Comment ça non ? Bon d'accord, comme une image vaut pas mal de mots, voilà un petit schéma qui montre la différence :

À savoir :

Le serveur comprend le langage PHP et est capable de l'interpréter pour produire finalement une page HTML
Le navigateur ne comprend que le langage HTML

Le traitement supplémentaire, noté [1] sur le schéma, est fait par Dotclear 2 juste avant l'interprétation du code PHP par le serveur, noté [2] sur le schéma. Le résultat de ce traitement supplémentaire est d'ailleurs conservé dans un répertoire cache (voir le dossier tmp et son contenu) pour gagner du temps les fois suivantes.

Que fait Dotclear 2 pendant cette étape 1 ? Et bien il recherche et remplace deux types de balises présentes dans les fichiers HTML du thème :

celles qui sont sous la forme {{tpl:…}}
celles qui sont sous la forme <tpl:…> et </tpl:…>

Je vous expliquerai à quoi elles servent dans un prochain billet.

Pour en savoir plus :

À propos de l'étrange conversation entre le serveur et votre navigateur, je vous conseille ce billet
La documentation officielle bien sûr
Tous les billets indispensables chez Mme la fée
Le forum, en cherchant un peu

Notes

[1] J'ai décrit dans ce billet comment ceci fonctionne.

Faire l'inventaire

Kozlika — Sun, 01 Jul 2007 10:57:00 +0200

Le blog est installé, il est en ligne et tout fonctionne correctement. Si vous êtes satisfait de ce premier blog et du thème que vous avez choisi parmi ceux disponibles (un tutoriel indique comment installer un nouveau thème), il ne vous reste plus qu'à rédiger vos billets, en vous référant au manuel d'utilisation pour découvrir plus avant votre outil et les fonctionnalités de l'interface d'édition du billet. De façon générale d'ailleurs, survoler la doc, même si vous ne l'apprenez pas par cœur, vous permettra de vous souvenir vaguement « avoir lu quelque part quelque chose là-dessus » dont vous pourriez avoir besoin ultérieurement. Si le manuel ne répond pas à vos questions, rendez-vous sur le forum, il se trouvera bien quelqu'un pour vous orienter.

Si vous ne vous sentez pas encore tout à fait chez vous, vous pouvez procéder à des personnalisations. Ne cherchez pas à tout changer d'un coup, surtout si vous débutez (mais pas que). Procédez par petites étapes successives afin de maîtriser les changements que vous opérez et pouvoir revenir en arrière facilement car vous vous souviendrez de la manip que vous venez de faire.

Ce qu'il vous faut savoir

Pour éviter les grosses bêtises et surtout faciliter votre travail, avoir une idée générale du fonctionnement et de l'organisation de la mécanique qui pilote votre blog peut vous être fort utile.

Le fonctionnement global

Si vous avez suivi le conseil ci-dessus et que vous avez regardé la doc, vous avez sûrement lu le comment ça marche ?. Je le répète ici sommairement pour les feignasses : tout ce qui concerne le contenu du blog est stocké dans une base de données placée sur un serveur spécifique (le fameux « serveur sql » dont on vous demande le nom et les login et mot de passe lors de l'installation) ; ce qui se trouve sur votre serveur de fichiers (ou serveur ftp) ce sont tous les fichiers qui s'occupent du traitement et de la présentation de ces données.

Les fichiers de Dotclear

Situés donc, sur votre serveur de fichiers, ils sont regroupés dans le répertoire dotclear (ou tout autre nom que vous lui aurez donné lors de l'install). Parcourons-les rapidement (en souligné, les noms de sous-répertoires) :

admin : contient tous les fichiers de l'administration du blog. Pas touche.
cache : un répertoire qui stocke des informations au fur et à mesure pour éviter à dotclear d'avoir à tout « recalculer » à chaque fois. Il se vide périodiquement quand il a atteint sa taille maximale, vous n'aurez en principe pas à vous en occuper.
CHANGELOG : un fichier informatif qui accompagne chaque version de dotclear et indique ce qui a été modifié depuis la version précédente. Pas touche.
db : je ne sais même pas à quoi ça sert, c'est vous dire si vous pouvez laisser tomber et ne pas vous en préoccuper...
inc : le cœur du moteur. C'est là que se situent tous les outils de traitement, évidemment : pas touche (note : on verra que certains fichiers peuvent néanmoins réclamer une attention particulière mais nous n'en sommes pas là).
index.php : la page de démarrage ; elle sert de centre d'aiguillage vers votre (ou vos) blog(s). (Note : si vous connaissez un peu le html, ne faites pas l'erreur de croire qu'il s'agit de la page d'accueil comme c'est généralement le cas des pages ainsi nommées.)
locales : contient tous les fichiers de traduction permettant de basculer sur une interface dans une autre langue ou d'afficher les termes standards des thèmes dans la langue du blog. Pour le moment, ce répertoire contient par défaut les répertoire de l'anglais et du français. Les traducteurs vers d'autres langues ajoutent ici d'autres sous-répertoires.
plugins : contient les répertoires d'extensions des fonctionnalités du blog. Lorsqu'on ajoute un plugin, son répertoire vient se placer ici. Il vous faudra d'ailleurs parfois le faire manuellement si la configuration de votre hébergeur interdit l'installation automatique.
public : c'est le répertoire des médias : images, sons, vidéos, fichiers que vous souhaitez mettre en pièce jointe, etc. On les atteint via le ftp ou depuis l'interface d'administration -> Gestionnaire de médias.
themes : répertoire des thèmes, autrement dit des fichiers déterminant la présentation du blog. C'est ici que 90% du travail de personnalisation s'effectue.

On commence par...

Quelle pourrait être la première étape de personnalisation ?

Tout un blog bac à sable...

Pourquoi ne pas créer tout de suite un second blog qui vous servira de bac à sable ? Dotclear 2 offre la possibilité de créer facilement plusieurs blogs sur la même installation. Vous pourrez ainsi y trafiquer tout à loisir sans craindre de casser autre chose qu'un laboratoire et vos lecteurs continueront de lire tranquillement vos billets sans être gênés par vos expérimentations. Si vous optez pour cette solution, créez un deuxième blog et par exemple importez-y un blog de test. Voilà, votre chantier est prêt.

... ou au moins un nouveau thème

L'étape ci-dessus n'est en aucun cas obligatoire. Vous pouvez tout à fait travailler directement à vos personnalisations si créer un nouveau blog spécialement dédié vous semble inutile ou compliqué. A vous de voir. Vous pouvez alors passer directement au paragraphe suivant :

Et en tous les cas, créer un nouveau thème

On l'a vu, l'essentiel des personnalisations passe par des modifications de thème. Le billet suivant traitera donc de l'articulation d'un thème, des fichiers qui le composent et de l'étape préalable à toute personnalisation de celui-ci.

Bonjour, c'est pour un sondage...

Kozlika — Sat, 21 Apr 2007 05:46:00 +0000

La rédaction de la documentation pour les versions 1.2 et 2.0 de Dotclear arrivant à son terme (du moins pour les parties dont je peux m'occuper), je vais pouvoir reprendre les tutoriels pour dc 2.0 ici. J'en vois quatre catégories possibles pour ce qui concerne les thèmes :

Portage des thèmes de 1.2 vers 2.0
Comment personnaliser un thème existant (en partant de celui par défaut par exemple) ?
Un thème en kit (dans l'esprit de celui pour 1.2)
Créer un thème pour Dotclear de A à Z.

Par quoi je commence ? Ou vous avez d'autres besoins / souhaits non compris dans l'un des quatre sujets précédents ?

Et je recrute aussi. Par ailleurs, pour ceux qui voudraient donner un coup de main, j'ai quelques idées sur la question :)

Total Validator

Kozlika — Tue, 10 Apr 2007 19:22:00 +0200

Pinaise les gens, je viens de trouver l'arme ultime, le couteau suisse de la validation, le top du must : Total Validator. C'est pas trop d'la bombe de balle ? (Via Veerle Blog.)

Apportez votre pierre à l'édifice !

Kozlika — Thu, 08 Mar 2007 10:22:00 +0000

Vous avez constaté des trous dans la documentation de Dotclear

Vous y avez relevé des erreurs ou fautes d'orthographe ?

Vous trouvez telle explication peu claire ou incomplète, telle formulation à revoir ?

Vous avez installé un blog sur un autre hébergement que ceux déjà listés et vous pourriez rédiger un pas à pas sur l'un de ces modèles ?

Vous avez installé plusieurs blogs avec une autre méthode que celles-ci ?

Vous avez des suggestions diverses et variées ?

Contribuez à l'amélioration de la documentation, envoyez vos mails à documentation(@)dotclear(.)net. Quel que soit votre niveau vous pouvez nous aider, ne serait-ce qu'en expérimentant son utilisation.

Et si vous faites partie des pressés pour la sortie de la release, sachez qu'elle ne se fera pas sans que la doc soit complète, vous pouvez donc faire avancer le schmilblick vous aussi ;)

Je ne vous laisserai pas vous lancer sans avoir insisté sur deux-trois trucs importants

Kozlika — Thu, 01 Feb 2007 20:52:00 +0100

Non parce que vraiment, vous pouvez lire en diagonale tout ce que vous voudrez mais là je vais carrément vous donner des ordres :

Sauvegardez souvent, sauvegardez proprement.
Soyez toujours capables de revenir en arrière.
Ne vous lancez jamais dans aucune modification sans du temps et de la zénitude devant vous.
Faites un pas après l'autre.

Ça vous l'écrivez en gros sur une feuille, vous le signez avec votre sang et vous me l'envoyez sous contrôle d'huissier. Je détaille.

Les sauvegardes

Quel que soit le soin que vous apporterez à votre blog, vous ne serez jamais à l'abri d'une fausse manip, d'un coup de grisou chez votre hébergeur, d'un acte malveillant (beaucoup plus rares que les légendes urbaines le racontent mais ça existe). Parfois vous pourrez réparer et parfois non. Et dans ce cas seule la sauvegarde que vous aurez précieusement conservée par devers vous vous permettra de redonner à votre blog allure ~~humaine~~ bloguienne.

Ce qu'il faut sauvegarder :

le contenu de votre blog (billets, utilisateurs, commentaires...)
les medias (images, mp3, séquences vidéo...)
les fichiers personnalisés de présentation

Je ne vous explique pas comment ni pourquoi puisque tout ça est dans la documentation. Retenez juste que dès l'ouverture de votre blog il vous faudra le faire régulièrement. A mon sens, selon la fréquence à laquelle vous publiez entre une fois par semaine et une fois par mois est le minimum pour le contenu et les medias. Pour les fichiers personnalisés il vous suffira de faire une sauvegarde systématique de tous vos changements au fur et à mesure. En principe ces fichiers ne sont pas modifiés tous les quatre matins.

Soyez toujours capables de revenir en arrière

A chaque fois que vous devrez intervenir sur des fichiers placés dans votre espace web, faites-en une copie de l'état avant vos changements et conservez-la sur votre disque dur. Vous pourrez ainsi bidouiller en toute tranquillité avec la sécurité de pouvoir remettre l'ancienne version du fichier si vous avez fait trop de bêtises.

Ne vous lancez jamais dans les modifications directes sans cette précaution, même, surtout quand vous aurez pris de l'assurance. C'est à ce moment-là que vous vous direz à la fois que vous savez vachement bien ce que vous faites et que vous pouvez vous lancer dans les modifs les plus hardies. Eh bien c'est à ce moment-là que vous devrez le plus être capables de revenir en arrière ;)

Du temps, du calme

Les aménagements de blog c'est comme pour tous types de travaux : on se dit qu'on aura pour une heure et on y est encore trois heures plus tard. Et comme on n'avait prévu qu'une heure et qu'on a d'autres choses à faire, on s'énerve, on va trop vite, on ne prend pas assez de précautions... et on fait de grosses bêtises qui demanderont encore plus d'heures à rectifier.

N'intervenez sur votre blog que quand vous disposez du triple de temps que vous y prévoyez !

Un pas après l'autre

Ne faites pas plusieurs changements importants à la fois. N'en faites qu'un, testez si tout va bien, passez au suivant.

Quand vous installerez Dotclear, faites une installation basique, exactement comme expliqué dans le tutoriel. Testez. Si tout va bien, alors vous pourrez créer un deuxième blog, ou faire des redirections ou passer de tel type d'URL à tel autre, ou essayer de retirer « index.php » de l'adresse, ou installer un plugin, un thème, etc.

Quand vous installerez un plugin, laissez-lui ses paramétrages par défaut, testez que tout va bien. Revenez-y seulement après pour vos réglages personnels.

Si vous installez un autre thème, installez-le dans sa version originelle, testez que tout va bien. Passez ensuite aux personnalisations, une par une, en testant à chaque fois.

Vous voyez le principe ? Ça ira beaucoup plus vite pour identifier à quelle étape s'est produit l'erreur et y remédier, vous y gagnerez du temps en plus et de l'énervement en moins.

Et tout de suite

Vous créez un répertoire sur votre disque dur : MonBlog. C'est votre centre névralgique anti-migraines. Vous y placerez une version intacte de dotclear, un sous-répertoire sauvegardes dans lequel vous créerez un sous-répertoire genre sauv070201 pour chaque sauvegarde hebdomadaire, un répertoire modifs avec pareil un sous-répertoire par date et les fichiers avant intervention.

C'est une question d'habitude, et ça vaut vraiment le coup pour être tranquilles !

Aorakits en thèmes paramétrables

Kozlika — Tue, 30 Jan 2007 16:54:00 +0100

Dans le billet consacré aux structures prêtes à l'emploi pour Dotclear 2.0, j'ai ajouté au téléchargement de la feuille de style la possibilité de télécharger sous forme de thème en « prêt à personnaliser » chacune de ces structures.

Installez-le en le décompressant dans le répertoire /themes de votre blog.

Vous y trouverez le fichier layout.css correspondant à la structure choisie, le fichier style.css comportant l'import de ce layout et toutes les balises courantes d'un thème pour Dotclear 2.0, le fichier _define.php à modifier pour y placer le nom que vous aurez donné à votre nouveau thème et votre signature.

Le fichier config.php et le répertoire /locales ont été mis en place pour que vous puissiez éditer la feuille de style directement depuis le Tableau de bord -> Paramètres des thèmes -> Sélection de l'Aorakit choisi -> Onglet Paramètres du thème.

N'hésitez pas à me signaler d'éventuelles erreurs : j'ai procédé un peu « à la chaîne » pour les préparer, j'ai pu faire quelques bourdes au passage (je me connais ;)) !

Enjoy !

Ce dont vous aurez besoin avant de télécharger Dotclear 2.0

Kozlika — Mon, 29 Jan 2007 10:42:00 +0100

Vous avez examiné les différentes possibilités qui s'offrent à vous pour ouvrir un blog et avez choisi d'adopter Dotclear. Quelles sont les conditions à réunir pour pouvoir vous lancer ?

Bon allez, je me lance, par quoi je commence ?

Un hébergement

Pour pouvoir faire tourner un blog Dotclear (ou tout autre site web d'ailleurs), le préalable est de disposer d'un espace de stockage en ligne sur lequel vous mettrez vos pages pour qu'elles soient accessibles sur le web. Les prestataires qui mettent à disposition ces espaces s'appellent des hébergeurs.

Une erreur fréquente lorsqu'on débarque dans cette aventure est de confondre le prestataire qui vous permet de vous connecter à Internet, appelé fournisseur d'accès internet (FAI) et hébergeur. Confusion tout à fait compréhensible puisque beaucoup de FAI proposent également un service d'hébergement. Cependant, rien ne vous contraint à choisir le même pour les deux services. Ce qui devra gouverner votre choix d'hébergeur c'est avant tout qu'il réponde aux prérequis nécessaires au bon fonctionnement de l'application choisie.

Ces prérequis sont listés dans la documentation. Tous les hébergeurs proposent une page d'information sur la mise à disposition de ceci ou cela sur leur hébergement. Consultez cette page, si vous n'y comprenez goutte, envoyez-leur un mail pour le leur demander. Nous testons au fur et à mesure des « retours d'expérience » des utilisateurs les hébergements compatibles avec Dotclear 2.0, vous pouvez choisir votre hébergeur dans cette liste, ce qui vous épargnera le doute :)

Un nom de domaine

Il vous faudra également une « URL » : ce qu'on tapera dans la barre d'adresse du navigateur pour aller chez vous. Votre hébergeur vous en fournira une par défaut en « sous-domaine » de chez lui, qui ressemblera à http://monlogin.hebergeur.fr. Certains, comme Free par exemple, ne vous laisseront d'ailleurs pas d'autre choix : toutes les adresses des sites hébergées par Free sont de cette forme.

Mais la plupart des autres vous proposeront si vous le souhaitez de servir d'intermédiaire à l'achat d'un nom de domaine rien que pour vous. Là encore ne confondez pas les deux services : vous pouvez acheter un nom de domaine chez un prestataire spécifique (le plus connu en France est Gandi) et héberger vos pages ailleurs. Assurez-vous cependant que votre hébergeur accepte cette procédure (c'est presque toujours le cas).

Avoir un nom de domaine n'est pas une obligation, comme je vous le disais ci-dessus tous les hébergeurs mettront à votre disposition une URL en sous-domaine de chez eux. En revanche si j'en parle ici c'est qu'il est beaucoup plus simple si vous en souhaitez un rien-qu'à-vous de vous en occuper avant de lancer votre blog !

Quelques outils

Un client FTP

Vous aurez besoin d'envoyer des fichiers depuis votre disque dur vers l'espace que vous aura fourni votre hébergeur et d'en récupérer depuis cet espace vers votre disque dur (par exemple pour y apporter des modifications). Il faut pour cela un logiciel spécifique qui se charge du transport de l'un à l'autre. Le terme générique est « client FTP ». Au fait, puisqu'on en parle, attention avec « FTP », c'est le pur machin en jargon informatique qui paume car il ne veut pas toujours dire la même chose selon le contexte où il est employé. Il sera ainsi employé pour désigner votre espace web chez l'hébergeur (t'as quoi sur ton ftp ?), un procédé de transfert (tu l'as envoyé en ftp ?) et ce fameux logiciel de transport dont je vous parlais à l'instant (tu utilises quoi comme ftp ?).

Il en existe des gratuits pour toutes les plates-formes. Un consensus semble se faire autour de :

Filezilla (Windows)
gFTP (Linux)
Cyberduck (Mac)

Pour ma part, j'utilise Transmit^[1] (Mac, autour de 25 euros) dont je trouve la prise en main et l'ergonomie très aisées.

Un éditeur

Vous aurez des fichiers à modifier. Je vous recommande fortement de vous munir d'un éditeur de texte qui ne soit NI un traitement de texte NI un éditeur html. L'un comme l'autre ajoutent de leur propre initiative des caractères visibles ou invisibles ou « corrigent » automatiquement les données qui mettront la pagaille dans votre blog. Au pire il vaut mieux utiliser le bloc-notes de Windows ou Text-Edit de Mac.

Là encore il en existe de gratuits et très bien fichus, notamment en coloriant la syntaxe, ce qui en facilite la lecture et la modification. En voici quelques-uns :

Notepad++ ou SciTE (Windows)
Smultron (Mac)

Un bon carnet d'adresses

Quelques adresses à consulter et à garder sous le coude vous seront précieuses :

La documentation de Dotclear est votre premier point de rendez-vous.
Si vous n'y avez pas trouvé vos réponses, le forum d'entraide vous y aidera.
Les informations de sortie de nouvelle version ou de mises à jour à effectuer sont publiées sur le blog de news.

Notes

[1] Je vous fais passer par ce lien qui explique bien ce qu'est le FTP.

dcTips()

Changement d'herbage...

Clearbricks : quelques autres fonctions de dbLayer

La table lecteurs

Le curseur

Insérer un enregistrement avec la fonction insert()

Modifier un enregistrement avec la fonction update()

Effacer un enregistrement avec la fonction execute()

Quelques fonctions supplémentaires pour les recordsets

isEmpty()

count()

Conclusion

Clearbricks : découverte de dbLayer et de sa fonction select()

Introduction à Clearbricks

La base de données

La classe dbLayer

La table lecteurs

Première requête sur un enregistrement et un champ

Une requête sur un champ avec plusieurs enregistrements

Une requête sur plusieurs champs de plusieurs enregistrements

Conclusion

Notes

Fermeture pendant les travaux

Balises : 9. Afficher un billet ou un texte fixe

Notes

Balises : 8. Le fichier _public.php en détail

Balises : 7. Exercice pratique, développer ses propres balises

Notes

Balises : 6. Exercice pratique, se limiter à la première page

Notes

Balises : 5. Exercice pratique, utiliser les attributs des balises

Notes

Balises : 4. Ne pas imbriquer des balises de même nom

Notes

Balises : 3. les deux formes de balises

Notes

Balises : 2. les commentaires invisibles et le PHP dans les thèmes

Notes

Balises : 1. Introduction aux balises de Dotclear 2

Notes

Faire l'inventaire

Ce qu'il vous faut savoir

Le fonctionnement global

Les fichiers de Dotclear

On commence par...

Tout un blog bac à sable...

... ou au moins un nouveau thème

Et en tous les cas, créer un nouveau thème

Bonjour, c'est pour un sondage...

Total Validator

Apportez votre pierre à l'édifice !

Je ne vous laisserai pas vous lancer sans avoir insisté sur deux-trois trucs importants

Les sauvegardes

Soyez toujours capables de revenir en arrière

Du temps, du calme

Un pas après l'autre

Et tout de suite

Aorakits en thèmes paramétrables

Ce dont vous aurez besoin avant de télécharger Dotclear 2.0

Bon allez, je me lance, par quoi je commence ?

Un hébergement

Un nom de domaine

Quelques outils

Un client FTP

Un éditeur

Un bon carnet d'adresses

Notes

Insérer un enregistrement avec la fonction `insert()`

Modifier un enregistrement avec la fonction `update()`

Effacer un enregistrement avec la fonction `execute()`

`isEmpty()`

`count()`