Construire un plugin de Blog
Ce tutoriel 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 inclus blog. Vous pouvez désactiver le plugin de blog inclus 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.
Prérequis :
Créez le répertoire du plugin et le fichier composer
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 de 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, à la racine du plugin, créez le fichier composer du plugin, composer.json.
Voyez Plugins pour plus d’informations sur le fichier composer.
Créez le formulaire pour créer 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 contenu et les tags de l’article de blog my_blog. Il n’est pas nécessaire d’ajouter les balises form du formulaire.
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 saisie, et est utilisée comme raccourci pour afficher des éléments des champs, tels que le label, le texte d’aide et le champ de saisie. Voir Formulaires + Actions.
Vous pouvez voir une liste complète des vues de saisie 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
// set the title
$title = "Create a new my_blog post";
// add the form to the main column
$content = elgg_view_form("my_blog/save");
// optionally, add the content for the sidebar
$sidebar = "";
// draw the page, including the HTML wrapper and basic page layout
echo elgg_view_page($title, [
'content' => $content,
'sidebar' => $sidebar
]);
La fonction elgg_view_form("my_blog/save") affiche le formulaire que vous avez créé dans la 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 = elgg_get_title_input('title');
$body = get_input('body');
$tags = elgg_string_to_array((string) 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->setSubtype('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
// 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->save()) {
return elgg_ok_response('', "Your blog post was saved.", $blog->getURL());
} else {
return elgg_error_response("The blog post could not be saved.");
}
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é une entité « entity ». Les utilisateurs, sites et groupes sont également des sous-classes d’une entité. Le sous-type « subtype » d’une entité permet un contrôle granulaire pour les listes 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, 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 qui soient cohérents avec votre plugin.
Créer le fichier elgg-plugin.php
Le fichier /mod/my_blog/elgg-plugin.php est utilisé pour déclarer diverses fonctionnalités du plugin. Il peut, par exemple, être utilisé pour configurer des entités, des actions, des widgets et des routes.
<?php
return [
'entities' => [
[
'type' => 'object',
'subtype' => 'my_blog',
'capabilities' => [
'searchable' => true,
],
],
],
'actions' => [
'my_blog/save' => [],
],
'routes' => [
'view:object:blog' => [
'path' => '/my_blog/view/{guid}/{title?}',
'resource' => 'my_blog/view',
],
'add:object:blog' => [
'path' => '/my_blog/add/{guid?}',
'resource' => 'my_blog/add',
],
'edit:object:blog' => [
'path' => '/my_blog/edit/{guid}/{revision?}',
'resource' => 'my_blog/edit',
'requirements' => [
'revision' => '\d+',
],
],
],
];
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 également à des visiteurs non identifiés, vous pouvez passer respectivement ['access' => 'admin'] ou ['access' => 'public'] lors de enregistrement de l’action.
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));
echo elgg_view_page($my_blog->getDisplayName(), [
'content' => $content,
]);
Cette page a beaucoup de points communs avec la page add.php. Les principales différences sont que les informations sont extraites 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, vue mobile et d’autres sont divers types de vues valides.)
Tester le plugin
Rendez-vous sur la page d’administration de 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',
));
echo elgg_view_page($titlebar, [
'title' => $pagetitle,
'content' => $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 limiter 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()
));
Ensuite, vous devrez enregistrer votre route pour renvoyer la nouvelle page lorsque l’URL est définie sur /my_blog/all. Configurez la section routes dans elgg-plugin.php pour contenir les éléments suivants :
'routes' => [
'collection:object:my_blog:all' => [
'path' => '/my_blog/all',
'resource' => 'my_blog/all',
],
],
Désormais, si l’URL contient /my_blog/all, l’utilisateur verra une page « Tous les My_Blogs du site ».
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 articles. 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']->getDisplayName(),
'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.
FIN
Il y a tant d’autres choses qui peuvent être faites ! Nous espérons que ceci vous donne une bonne idée de comment démarrer.