Vous pouvez avoir besoin, pour plusieurs raisons, de servir votre contenu autrement que sous la forme d'une page HTML. Par exemple pour créer un page sitemap au format XML et favoriser l'indexation de votre site web auprès des moteurs de recherche. Pour créer un JSON Feed ou que votre contenu soit lisible par une autre application.

Pour créer une representation de votre contenu, c'est relativement simple, il faut d'abord s'assurer qu'elle sera liée à un template existant. Ensuite il faut créer un fichier PHP dans le dossier /site/templates/ et le nomer avec le mot json entre le nom du template qu'il représente et l'extension .php Par exemple, une représentation JSON du template about.php devra être nomé about.json.php

Biensure si vous choissisez de fournir une représentation sous la forme d'un fichier JSON par exemple, le fichier /site/templates/about.json.php doit retouner un document JSON valide. Idem pour une représentation XML ou tout autre format de fichier.

<?php

// /site/templates/about.json.php

$data = [
  'title' => $page->title()->value(),
  'description'  => $page->description()->kirbytext()->value(),
  'biography' => $page->biography()->kirbytext()->value(),
];

echo json_encode($data);

Remarque :

Le content-type qui sera indiqué dans le header de la page par le serveur est automatiquement géré par Kirby qui se base sur l'extension du fichier et/ou le contenu renvoyé.

Si vous avez besoin de renvoyer un content-type spécifique, vous pouvez l'indiquer à l'aide de la methode response()

<?php

$kirby->response()->type('text/plain');

Par défaut, les représentations de contenu sont accessibles sans restriction par tout le monde en indiquant leur URL dans un navigateur.

Ici toutes les pages liées au template "about" peuvent afficher leurs données sous forme d'une représentation JSON en indiquant dans le navigateur l'URL https://monsiteweb.com/about.json

Idem pour les posts, tous les posts liés au template "post" peuvent afficher leurs données sous forme d'une représentation JSON en indiquant dans le navigateur l'URL https://monsiteweb.com/titre-du-post.json

Si pour des raisons de confientialités ou d'exclusivités, vous avez besoin que vos représentations ne soient pas accessibles par tout le monde vous pouvez restreindre cet accès en enregistrant le hook route:before dans votre fichier de configuration. Par exemple voici comment restreindre l'accès aux représentations JSON des posts uniquement aux utilisateurs connectés :

<?php

// /site/config/config.php

return [
    'hooks' => [
        'route:before' => function ($route, $path, $method) {
          if ( fnmatch( 'notes/*.json', $path ) && !kirby()->user() ) {
            go('/');
          }
        }
    ],
];

Ici, avant que la page ne soit chargée, je vérifie si la page correspond au pattern 'notes/*.json' pour savoir si il s'agit d'un post. Je vérifie également si l'utilisateur est connecté. Si il s'agit bien d'un post et que l'utilisateur n'est pas connecté, je le renvoie vers la page d'accueil.

Vous pouvez utiliser des "Controller" dédiés pour chacune de vos représentations. Si vous créez un "Controller" portant le nom /site/controllers/post.json.php, il sera utilisé pour la représentation JSON du template /site/templates/post.php. Si aucun "Controller" de représentation dédié n'existe, le "Controller" standard (default.php ou site.php) sera utilisé à la place (s'il existe).

<?php

// /site/controllers/post.json.php

return function ($page) {
    return [
        'hello' => 'Hello world',
    ];
};

La donnée $hello définie dans ce controller sera utilisable dans la representation /site/template/post.json.php et disponible dans toutes les representations de post.

<?php

// /site/template/post.json.php

$data = [
  'title' => $page->title()->value(),
  'hello'  => $hello,
];

echo json_encode($data);

Les représentations de page sont un moyen simple et rapide de mise à disposition de vos contenus dans des formats divers. Il y a une autre manière d'accéder à vos contenus au format JSON en utilisant l'API de Kirby mais ce sujet fera l'objet d'un article à part entière.

Disponible prochainement ...