Construire un plugin de Blog¶
Ce tutorial va vous apprendre à créer un plugin de blog simple. Les fonctionnalités de base du blog seront de créer des articles, les enregistrer et les afficher. Le plugin duplique des fonctionnalités présentes dans le plugin blog empaqueté. Vous pouvez désactiver le plugin blog empaqueté si vous le souhaitez, mais ce n’est pas nécessaire dans la mesure où les fonctionnalités ne seront pas en conflit les unes avec les autres.
Contents
Prérequis :
Créez le répertoire du plugin et le fichier manifest¶
Tout d’abord, choisissez un nom simple et descriptif pour votre plugin. Dans ce tutoriel, le nom sera my_blog. Puis créez un répertoire pour votre plugin dans le répertoire /mod/ qui se trouve dans le répertoire d’installation d’Elgg. D’autres plugins sont également situés dans /mod/. Dans notre cas, le nom de ce répertoire devrait être /mod/my_blog/. Ce répertoire constitue la racine de votre plugin, et tous les fichiers que vous allez créer pour votre nouveau plugin vont l’être quelque part dans ce répertoire.
Ensuite, créez le fichier manifest.xml à la racine du plugin :
<?xml version="1.0" encoding="UTF-8"?>
<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
<name>My Blog</name>
<id>my_blog</id>
<author>Your Name Here</author>
<version>0.1</version>
<description>Adds blogging capabilities.</description>
<requires>
<type>elgg_release</type>
<version>2.0</version>
</requires>
</plugin_manifest>
Voyez la documentation sur les Plugins pour plus d’informations sur le fichier manifest.
Créez le formulaire pour la création d’un nouvel article de blog¶
Créez un fichier /mod/my_blog/views/default/forms/my_blog/save.php` qui contiendra le corps du formulaire. Le formulaire doit avoir des champs de saisie pour le titre, le corps et les tags de l’article de blog my_blog. Il n’est pas nécessaire d’ajouter les balises <form>.
echo elgg_view_field([
'#type' => 'text',
'#label' => elgg_echo('title'),
'name' => 'title',
'required' => true,
]);
echo elgg_view_field([
'#type' => 'longtext',
'#label' => elgg_echo('body'),
'name' => 'body',
'required' => true,
]);
echo elgg_view_field([
'#type' => 'tags',
'#label' => elgg_echo('tags'),
'#help' => elgg_echo('tags:help'),
'name' => 'tags',
]);
$submit = elgg_view_field(array(
'#type' => 'submit',
'#class' => 'elgg-foot',
'value' => elgg_echo('save'),
));
elgg_set_form_footer($submit);
Notez comment le formulaire appelle elgg_view_field() pour afficher les champs de saisie. Cette fonction d’aide permet de maintenir la cohérence dans les balises des champs de de saisie, et est utilisée comme raccourci pour afficher des éléments des champs, tels que le label, l’aide et le champs de saisie. Voir la Formulaires + Actions.
Vous pouvez voir une liste complète des vues d’entrée dans le répertoire /vendor/elgg/elgg/views/default/input/.
Il est recommandé que vous rendiez votre plugin traduisible en utilisant elgg_echo() à chaque fois qu’une chaîne de texte sera affichée à l’utilisateur. Lisez-en plus sur l”Internationalisation.
Créez une page pour écrire les articles de blog¶
Créez le fichier /mod/my_blog/views/default/resources/my_blog/add.php. Cette page va afficher le formulaire que vous avez créé dans la section précédente.
<?php
// make sure only logged in users can see this page
gatekeeper();
// set the title
$title = "Create a new my_blog post";
// start building the main column of the page
$content = elgg_view_title($title);
// add the form to the main column
$content .= elgg_view_form("my_blog/save");
// optionally, add the content for the sidebar
$sidebar = "";
// layout the page
$body = elgg_view_layout('one_sidebar', array(
'content' => $content,
'sidebar' => $sidebar
));
// draw the page, including the HTML wrapper and basic page layout
echo elgg_view_page($title, $body);
La fonction elgg_view_form("my_blog/save") affiche le formulaire que vous avez créé dans al section précédente. Elle ajoute automatiquement au formulaire la balise <form> avec les attributs nécessaires ainsi que des jetons anti-csrf.
L’action du formulaire sera "<?= elgg_get_site_url() ?>action/my_blog/save".
Créez le fichier d’action pour enregistrer l’article de blog¶
Le fichier d’action va enregistrer l’article de blog my_blog dans la base de données. Créez le fichier /mod/my_blog/actions/my_blog/save.php:
<?php
// get the form inputs
$title = get_input('title');
$body = get_input('body');
$tags = string_to_tag_array(get_input('tags'));
// create a new my_blog object and put the content in it
$blog = new ElggObject();
$blog->title = $title;
$blog->description = $body;
$blog->tags = $tags;
// the object can and should have a subtype
$blog->subtype = 'my_blog';
// for now, make all my_blog posts public
$blog->access_id = ACCESS_PUBLIC;
// owner is logged in user
$blog->owner_guid = elgg_get_logged_in_user_guid();
// save to database and get id of the new my_blog
$blog_guid = $blog->save();
// if the my_blog was saved, we want to display the new post
// otherwise, we want to register an error and forward back to the form
if ($blog_guid) {
system_message("Your blog post was saved.");
forward($blog->getURL());
} else {
register_error("The blog post could not be saved.");
forward(REFERER); // REFERER is a global variable that defines the previous page
}
Comme vous pouvez le voir dans le code ci-dessus, les objets Elgg disposent de plusieurs champs intégrés. Le titre de l’article my_blog est conservé dans le champs title tandis que le contenu est conservé dans le champs description. Il y a également un champs pour des tags, qui sont stockés sous la forme de métadonnées.
Les objets dans Elgg sont une sous-classe de quelque chose appelé « entité » (entity). Les utilisateurs, sites et groupes sont également des sous-classes d’entité. Le sous-type (subtype) d’une entité permet un contrôle granulaire pour les listings et l’affichage, c’est pourquoi chaque entité devrait avoir un sous-type. Dans ce tutoriel, le sous-type « my_blog » permet d’identifier un article my_blog post, mais toute chaîne de caractères alphanumérique peut constituer un sous-type valide. Lorsque vous choisissez des sous-types, veuillez vous assurer d’en choisir un qui soit cohérent avec votre plugin.
La méthode getURL charge l’URL du nouvel article. Il est recommandé de surcharger cette méthode. La surcharge sera faite dans le fichier start.php.
Créez le fichier start.php¶
Le fichier /mod/my_blog/start.php a besoin d’enregistrer l’action d’enregistrement que vous avez créée plus tpot, d’enregistrer un gestionnaire de page, et de surcharger la génération d’URL.
<?php
// register an initializer
elgg_register_event_handler('init', 'system', 'my_blog_init');
function my_blog_init() {
// register the save action
elgg_register_action("my_blog/save", __DIR__ . "/actions/my_blog/save.php");
// register the page handler
elgg_register_page_handler('my_blog', 'my_blog_page_handler');
// register a hook handler to override urls
elgg_register_plugin_hook_handler('entity:url', 'object', 'my_blog_set_url');
}
L’enregistrement de l’action de sauvegarde va la rendre disponible via /action/my_blog/save. Par défaut, toutes les actions ne sont disponibles qu’aux utilisateurs identifiés. Si vous souhaitez rendre une action disponible aux seuls administrateurs ou l’ouvrir y compris à des visiteurs non identifiés, vous pouvez passer respectivement “admin” ou “public” comme troisième paramètre de elgg_register_action.
La fonction de surcharge d’URL va extraire l’ID de l’entité et l’utiliser pour créer une URL simple pour la page qui va afficher cette entité. Dans ce cas l’entité devrait bien sûr être un article my_blog. Ajoutez cette fonction à votre fichier start.php :
function my_blog_set_url($hook, $type, $url, $params) {
$entity = $params['entity'];
if (elgg_instanceof($entity, 'object', 'my_blog')) {
return "my_blog/view/{$entity->guid}";
}
}
Le gestionnaire de page permet de servir la page qui génère le formulaire et la page qui affiche l’article. La prochaine section va montrer comment créer la page qui affiche l’article. Ajoutez cette fonction à votre fichier start.php` :
function my_blog_page_handler($segments) {
if ($segments[0] == 'add') {
echo elgg_view_resource('my_blog/add');
return true;
}
else if ($segments[0] == 'view') {
$resource_vars['guid'] = elgg_extract(1, $segments);
echo elgg_view_resource('my_blog/view', $resource_vars);
return true;
}
return false;
}
La variable $segments contient les différentes parties de l’URL une fois séparées par /.
Les fonctions de gestion de page doivent renvoyer true ou false. true signifie que la page existe et a bien été prise en charge par le gestionnaire de page. false signifie que la page n’existe pas et que l’utilisateur sera redirigé vers la page 404 du site (la page demandée n’existe pas ou n’a pas été trouvée). Dans cet exemple, l’URL doit contenir soit /my_blog/add soit /my_blog/view/id où id est un ID valide d’une entité de sous-type my_blog. Plus d’informations sur la gestion des URL sur Gestionnaire de pages.
Créez une page pour afficher l’article de blog¶
Pour pouvoir afficher un article my_blog sur sa propre page, vous devez créer une page d’affichage. Créez le fichier /mod/my_blog/views/default/resources/my_blog/view.php:
<?php
// get the entity
$guid = elgg_extract('guid', $vars);
$my_blog = get_entity($guid);
// get the content of the post
$content = elgg_view_entity($my_blog, array('full_view' => true));
$params = array(
'title' => $my_blog->title,
'content' => $content,
'filter' => '',
);
$body = elgg_view_layout('content', $params);
echo elgg_view_page($my_blog->title, $body);
Cette page a beaucoup de points communs avec la page add.php. Les principales différences sont que les informations sont extraires depuis l’entité my_blog, et qu’au lieu d’afficher un formulaire, la fonction elgg_view_entity est appelée. Cette fonction donne les informations de l’entité à ce qu’on appelle la vue de l’objet.
Créez la vue de l’objet¶
Quand elgg_view_entity est appelé ou quand des articles my_blogs sont affichés dans une liste par exemple, la vue de l’objet va générer le contenu approprié. Créez le fichier /mod/my_blog/views/default/object/my_blog.php :
<?php
echo elgg_view('output/longtext', array('value' => $vars['entity']->description));
echo elgg_view('output/tags', array('tags' => $vars['entity']->tags));
Comme vous pouvez le voir dans la section précédente, chaque article my_blog est passé à la vue de l’objet sous la forme $vars['entity']. ($vars est un tableau utilisé dans le système de vues pour passer des variables à une vue.)
La dernière ligne prend les tags de l’article my_blog et les affiche automatiquement sous la forme d’une série de liens cliquables. La recherche est gérée automatiquement.
(Si vous vous interrogez sur le « default » dans /views/default/, vous pouvez créer des vues alternatives. RSS, OpenDD, FOAF, mobile et d’autres sont divers types de vues valides.)
Tester le plugin¶
Rendez-vous sur la page d’administration d’Elgg, listez les plugins, et activez le plugin my_blog.
La page pour créer un nouvel article my_blog devrait désormais être accessible via https://elgg.example.com/my_blog/add, et après avoir enregistré l’article, vous devriez le voir affiché sur sa propre page.
Afficher une liste des articles de blog¶
Créons également une page qui liste les entrées my_blog qui ont été créées
Créez /mod/my_blog/views/default/resources/my_blog/all.php :
<?php
$titlebar = "All Site My_Blogs";
$pagetitle = "List of all my_blogs";
$body = elgg_list_entities(array(
'type' => 'object',
'subtype' => 'my_blog',
));
$body = elgg_view_title($pagetitle) . elgg_view_layout('one_column', array('content' => $body));
echo elgg_view_page($titlebar, $body);
La fonction elgg_list_entities prend les derniers articles my_blog et les passe à la vue d’affichage de l’objet. Notez que cette fonction ne retourne que les articles que l’utilisateur a le droit de voir, aussi le contrôle d’accès est géré de manière transparente. La fonction (et ses cousines) gère également de manière transparente la pagination, et crée même un flux RSS pour votre my_blogs si vous avez défini cette vue.
La fonction de liste peut également restreindre les articles my_blog à ceux d’un utilisateur spécifique. Par exemple, la fonction elgg_get_logged_in_user_guid récupère l’identifiant unique (GUID) de l’utilisateur connecté, et en le passant à elgg_list_entities la liste n’affichera que les articles de l’utilisateur connecté :
echo elgg_list_entities(array(
'type' => 'object',
'subtype' => 'my_blog',
'owner_guid' => elgg_get_logged_in_user_guid()
));
Puis vous devez modifier votre gestionnaire de page my_blog pour récupérer la nouvelle page quand l’URL est /my_blog/all. Modifiez la fonction my_blog_page_handler dans start.php pour qu’elle ressemble à ceci :
function my_blog_page_handler($segments) {
switch ($segments[0]) {
case 'add':
echo elgg_view_resource('my_blog/add');
break;
case 'view':
$resource_vars['guid'] = elgg_extract(1, $segments);
echo elgg_view_resource('my_blog/view', $resource_vars);
break;
case 'all':
default:
echo elgg_view_resource('my_blog/all');
break;
}
return true;
}
Maintenant, si l’URL contient /my_blog/all, l’utilisateur verra une page « Tous les My_Blogs du site ». Grâce au cas par défaut, la liste de tous les my_blogs sera également affichée si l’URL n’est pas valide, comme par exemple``/my_blog`` ou /my_blog/xyz.
Vous pouvez aussi choisir de mettre à jour la vue de l’objet pour gérer différents types d’affichage, faute de quoi la liste de tous les my_blogs va également afficher le contenu complet de tous les my_blogs. Modifiez /mod/my_blog/views/default/object/my_blog.php pour qu’il ressemble à ceci :
<?php
$full = elgg_extract('full_view', $vars, FALSE);
// full view
if ($full) {
echo elgg_view('output/longtext', array('value' => $vars['entity']->description));
echo elgg_view('output/tags', array('tags' => $vars['entity']->tags));
// list view or short view
} else {
// make a link out of the post's title
echo elgg_view_title(
elgg_view('output/url', array(
'href' => $vars['entity']->getURL(),
'text' => $vars['entity']->title,
'is_trusted' => true
)));
echo elgg_view('output/tags', array('tags' => $vars['entity']->tags));
}
Désormais, si full_view est à true (tel qu’il avait été préalablement défini dans cette section), la vue de l’objet va afficher le contenu et les tags de l’article (le titre est affiché par view.php). Sinon la vue de l’objet ne va afficher que le titre et les tags de l’article.