Documentation Elgg (master)

Elgg (pronunciation) est un framework open source de développement rapide pour construire des applications web sociales. C’est un excellent choix pour construire tout type d’application où des utilisateurs se connectent et partagent des informations.

Fonctionnalités

• Une API bien documentée qui permet aux développeurs de démarrer leurs nouveaux projets avec une courbe d’apprentissage simple

• Composer est le gestionnaire de paquets qui simplifie grandement l’installation et la maintenance du noyau de Elgg et des plugins

• Un Système flexible d’événements qui permet aux plugins d’étendre et de modifier la plupart des fonctionnalités et le comportement de l’application

• Un système de vues extensible qui permet aux plugins de collaborer sur la couche de présentation des applications et de construire des thèmes personnalisés complexes

• Un système de ressources statiques mises en cache qui permet aux thèmes et aux plugins de servir des images, des feuilles de style, des polices et des scripts sans charger le moteur

• L’authentication des utilisateurs s’appuie sur des modules d’authentification enfichables, ce qui permet aux applications d’implémenter des protocoles d’authentification personnalisés

• La Sécurité est assurée par une validation anti-CSRF native, des filtres XSS stricts, des signatures HMAC, et les dernières approches cryptographiques pour le hachage des mots de passe

• Une API côté client motorisée par des modules JavaScript asynchrones chargés via RequireJS et un service Ajax natif pour une communication aisée avec le serveur

• Un système d’Entités flexible qui permet aux applications de prototyper de nouveaux types de contenus et d’interactions entre utilisateurs

• Un modèle de données très bien conçu avec une couche d’API consolidée qui permet aux développeurs d’interfacer facilement avec la base de données

• Un système de contrôle d’accès qui permet aux applications de construire des politiques d’accès aux contenus granulaires, comme de créer des réseaux privés et des intranets

• Des Groupes - support natif de groupes d’utilisateurs

• Un système de Stockage de fichiers fourni par une API flexible qui permet aux plugins de stocker les fichiers créés par les utilisateurs et de les servir/streamer sans démarrer le moteur

• Un Service de Notifications qui permet aux applications d’abonner des utilisateurs à des notifications sur le site ou par e-mail, et d’implémenter l’intégration avec d’autres services tierce-partie

• Des Services Web RPC qui peuvent être utilisés pour des intégrations complexes avec des applications externes et des clients mobiles

• L”Internationalisation et la localisation des applications Elgg est simple et peut être intégrée avec des services tierce-partie tels que Transifex

• La Communauté Elgg peut aider sur n’importe quelle problématique, et héberge un répertoire de plusieurs milliersde plugins open source

Sous le capot :

• Elgg est un framework modulaire orienté objet (OOP) qui est dirigé par des services DI

• compatible NGINX ou Apache

• Symfony2 HTTP Foundation gère les requêtes et réponses

• RequireJS gère les modules AMD

• Laminas Mail gère les e-mails sortants

• Des Filtres XSS htmLawed

• DBAL

• Migrations de base de donnée avec Phinx

• CSS-Crush pour le pré-traitement CSS

• Imagine pour la manipulation d’image

• Cache persistant avec Memcached et/ou Redis

• Gestion des erreurs avec Monolog

Exemples

Elgg a été utilisé pour construire tous types d’applications sociales:

• réseaux sociaux ouverts (similaires à Facebook)

• thématiques (comme la communauté Elgg)

• intranets privés ou professionnels

• sites de rencontres

• plateformes éducatives

• blog d’entreprise

Ceci constitue la documentation officielle du projet Elgg.

Poursuivre la lecture

Pour démarrer

Découvrez si Elgg est adapté pour votre communauté.

Plugins inclus

Elgg est fourni avec un jeu de plugins. Ils fournissent les fonctionnalités fondamentales pour votre réseau social.

Blog

Un weblog, ou blog, est sans conteste un élément d’ADN fondamental de tous les types de sites de réseautage social. La forme la plus simple de publication personnelle, qui permet de publier des notes textuelles dans un ordre antéchronologique. Les commentaires sont également une part importante des blogs, en transformant un acte de publication personnel en une conversation.

Le blog de Elgg étend ce modèle en fournissant des contrôles d’accès pour chaque entrée et un système de tags transverse aux blogs. Vous pouvez contrôler précisément qui peut voir quel article de blog, et identifier des articles écrits par d’autres personnes sur des sujets similaires. Vous pouvez également voir les entrées écrites par vos contacts (auxquels vous avez accès).

Voir aussi

Blog sur Wikipédia

CKEditor

Avec ce plugin activé, les champs de saisie de texte long disposent d’un éditeur WYSIWYG avec des options de balisage supplémentaires pour votre texte.

Selon la configuration, l’éditeur peut être enrichi de diverses options de balisage de style de texte. Consultez le site web de CKEditor pour un éditeur complet.

Images

Elgg prend également en charge le téléchargement d’images dans l’éditeur. Vous pouvez charger des images à l’aide d’une boîte de dialogue de fichier ou simplement glisser/déposer ou copier/coller l’image dans l’éditeur.

Mentions

Avec le plugin CKEditor, vous activez également les fonctionnalités de mention. Par défaut, vous pouvez mentionner :

• Des utilisateurs : utilisez @ pour lancer l’autocomplétion pour les utilisateurs

• Des groupes : utilisez @ pour lancer l’autocomplétion pour les groupes

• Du contenu indexé : utilisez ` [` pour lancer l’autocomplétion pour du contenu

Lorsque vous sélectionnez quelque chose dans la liste d’autocomplétion, un lien vers l’utilisateur/groupe/contenu sélectionné sera ajouté au contenu. En fonction des préférences des utilisateurs mentionnés, ils seront également informés qu’ils ont été mentionnés.

Configuration de la barre d’outils

Ce plugin fournit une configuration de barre d’outils standard pour l’éditeur par défaut et l’éditeur simple. Les paramètres du plugin vous permettent de configurer une configuration personnalisée de barre d’outils. Presque tous les plugins CKEditor sont disponibles. Des informations sur la façon de configurer une barre d’outils peuvent être trouvées ici : https://ckeditor.com/docs/ckeditor5/latest/features/toolbar/toolbar.html

Tableau de bord

Un tableau de bord Elgg typique

Le tableau de bord est distribué à la fois avec la version complète et avec la version noyau seulement de Elgg. C’est le portail des utilisateurs vers des activités qui leur sont importantes à la fois à l’intérieur du site et depuis des sources externes. En utilisant la puissante API des widgets de Elgg, il est possible de construire des widgets qui extraient du contenu pertinent depuis l’intérieur d’un site Elgg, ou qui récupèrent des informations depuis des sources tierce-partie telles que Twitter ou Flickr (dès lors que ces widgets existent). Le tableau de bord des utilisateurs n’est pas la même chose que leur profil : tandis que le profil est destiné à être consulté par les autres, le tableau de bord est un espace strictement personnel que les utilisateurs utilisent pour leurs propres besoins.

Discussions

Ajoutez un forum pour démarrer une discussion. Cette fonctionnalité est principalement destinée à être utilisée dans les groupes. Les propriétaires de groupe peuvent activer/désactiver cette fonctionnalité pour leur groupe.

Il existe un paramètre de plugin pour permettre des discussions globales (donc hors d’un groupe). Ce paramètre est désactivé par défaut mais peut être activé par un administrateur de site.

Notifications

Afin de favoriser les échanges dans un groupe, tous les membres du groupe recevront des notifications concernant les commentaires sur un sujet de discussion. Cela suivra les préférences de notification définis par chaque membre du groupe, en fonction de ses préférences globales pour les groupes, ou de ses préférences spécifiques pour les nouvelles discussions.

Répertoire de fichiers

Un fichier dans un répertoire de fichiers Elgg

Le répertoire de fichiers permet à des membres de charger n’importe quel type de fichier. Comme avec tout dans un système Elgg, vous pouvez aisément filtrer les fichiers par tags et restreindre l’accès de sorte qu’ils soient visibles seulement par les personnes que vous souhaitez. Chaque fichier peut également avoir des commentaires associés.

Il existe plusieurs types d’usages différents pour cette fonctionnalité

Galerie de photo

Quand un utilisateur charge des photographies ou d’autres images, elles sont automatiquement rassemblées dans une galerie de photos Elgg dans laquelle il est possible de naviguer. Les utilisateurs peuvent aussi voir les photos que leurs contacts ont chargées, ou voir des images attachées à un groupe. Une version plus grande de la photo apparaît en cliquant sur l’un des fichiers.

Podcasts

Un répertoire de fichiers Elgg est doublé automatiquement par un flux RSS, de sorte que vous pouvez vous abonner à du nouveau contenu audio en utilisant des programmes tels que iTunes.

Contenus spéciaux

Il est possible pour d’autres plugins d’ajouter de nouveaux lecteurs et visionneuses pour différents types de contenus. L’auteur d’un plugin peut intégrer de cette manière une visionneuse, par exemple pour des documents Word.

Note pour les développeurs

Pour ajouter un lecteur pour un nouveau type de contenu, créez un plugin avec des vues de la forme file/specialcontent/mime/type. Par exemple, pour créer une visionneuse pour des documents Word, vous pouvez créer une vue nommée file/specialcontent/application/msword, puisque application/msword est le type MIME pour les documents Word. A l’intérieur de cette vue, la version ElggEntity du fichier sera référencée en tant que $vars['entity']. Dès lors, l’URL du fichier téléchargeable est :

echo $vars['entity']->getDownloadURL();

En utilisant cela, il devrait être possible de développer des visionneuses intégrées pour la plupart des types des contenus.

Contacts

En tant que framework de réseau social, Elgg gère les relations entre membres.

Par défaut tout membre peut se mettre en contact avec n’importe quel autre membre : cela revient à suivre l’activité de l’autre membre.

Après avoir activé les demandes de contact en tant que fonctionnalité du plugin Friends, lorsque l’utilisateur A veut être en contact avec l’utilisateur B, l’utilisateur B doit approuver la demande. Lors de l’approbation, l’utilisateur A sera en contact avec l’utilisateur B et l’utilisateur B sera en contact avec l’utilisateur A.

Groupes

Un profil de groupe typique

Une fois que vous avez trouvé d’autres personnes avec des centres d’intérêt similaires - ou peut-être que vous faites partie d’un groupe de recherche ou d’un cours - vous pourriez souhaiter disposer d’un environnement plus structuré pour partager du contenu et discuter d’idées. C’est là qu’interviennent les puissantes fonctionnalités de Elgg en terme de construction de groupes. Vous pouvez créer et modérer autant de groupes que vous le désirez.

• Vous pouvez conserver toute l’activité du groupe privée pour le groupe, ou utiliser l’option “rendre public” pour disséminer ses travaux auprès d’un public plus large.

• Chaque groupe produit des flux RSS granulaires, de sorte qu’il est aisé de suivre les développements des groupes

• Chaque groupe dispose de sa propre URL et page de profil

• Chaque groupe dispose d’un répertoire de fichiers Répertoire de fichiers, d’un forum, de pages et d’un tableau de messages

Likes

Permet aux utilisateurs d’aimer le contenu de votre site. Si le contenu prend en charge le fait d’être liké, un “pouce levé” apparaîtra comme une interaction sociale avec ce contenu. Le fait d’aimer le contenu informera également le propriétaire du contenu du nouveau J’aime. Un compteur s’affichera à côté de l’action, indiquant le nombre de likes du contenu. Cliquer sur le compteur affichera une liste d’utilisateurs qui ont récemment aimé le contenu.

Note

Le plugin likes utilise la capacité d’entité likable. Cette capacité définit si une entité peut être aimée.

Tableau de messages

Un exemple de panneau d’affichage placé sur le profil

Le tableau de messages - similaire au “Mur” de Facebook ou à un mur de commentaires dans d’autres réseaux - est un plugin qui permet aux membres de placer un widget tableau de messages sur leur profil. Les autres membres peuvent alors publier des messages qui vont apparaître sur ce tableau de messages. Vous pouvez ensuite répondre directement à n’importe quel message et voir l’historique entre vous et la personne qui a publié le message.

Messages

Notification des messages

Des messages privés peuvent être envoyés aux membres en cliquant sur leur avatar ou sur le lien vers leur profil. Puis, en utilisant l”éditeur WYSIWYG intégré, il est possible de mettre en forme le message. Chaque membre dispose de sa propre boîte de réception et d’envoi. Il est possible d’être notifié par e-mail des nouveaux messages.

Quand les membres s’identifient, il sont notifiés de tout nouveau message par le mécanisme de notification des messages dans leur barre d’outil supérieure.

Pages

Une page Elgg

Le plugin pages permet d’enregistrer et de conserver d’une manière organisée et hiérarchisée des pages de texte, et d’en restreindre à la fois les accès en lecture et en écriture. Ceci signifie que vous pouvez créer collaborativement un ensemble de documents avec une liste de personnes choisies, participer à un processus d’écriture au sein d’un groupe formalisé, ou simplement utiliser cette fonctionnalité pour créer un document que vous seul pouvez voir, jusqu’à ce que vous choisissiez de le partager une fois terminé. Le menu de navigation simple vous permet de voir la structure de l’ensemble de documents depuis n’importe quelle page. Vous pouvez créer autant de ces structures que vous le souhaitez ; chaque page individuelle dispose de ses propres contrôles d’accès, de sorte que vous pouvez révéler des portions de la structure tout en conservant les autres invisibles. Dans la ligne des autres éléments dans Elgg, vous pouvez aisément ajouter des commentaires sur une page, ou rechercher des pages par tag.

Usage

Les pages expriment vraiment leur potentiel dans deux domaines, d’abord comme moyen pour les utilisateurs de construire des choses telles qu’un CV, un portfolio, une documentation réflexive, et autres constructions de ce type. La seconde est dans le domaine de la collaboration, tout particulièrement dans le cadre d’un groupe. Avec les puissants outils de contrôle d’accès à la fois en lecture et en écriture, ce plugin est idéal pour la création collaborative de documents.

Note

Les développeurs devraient tenir compte du fait qu’il existe en fait 2 types de pages :

1. Pages racine (avec le sous-type page_top)

2. Pages normales (avec le sous-type page)

Profil

Un profil Elgg

Le plugin profile est distribué à la fois avec la version complète et avec la version noyau seulement de Elgg. L’objectif est qu’il puisse être désactivé et remplacé par un autre plugin de profil si vous le souhaitez. Il fournit un certain nombre d’éléments de fonctionnalités que beaucoup considèrent comme fondamentales pour le concept d’un site de réseautage social, et est unique parmi les plugins parce que l’icône de profil qu’il définit est référencée comme un standard à travers l’ensemble du système.

Informations sur l’utilisateur

Cela fournit des informations sur un utilisateur, qui sont configurables avec l’événement fields, user:user. Vous pouvez modifier les champs de profil disponibles à partir du panneau d’administration. Chaque champ de profil a sa propre restriction d’accès, de sorte que les utilisateurs peuvent choisir exactement qui peut voir chaque élément individuel. Certains des champs contiennent des tags (par exemple compétences) qui limitent l’accès à un champ qui limite également qui peut vous trouver via ce tag.

Avatar utilisateur

Le menu contextuel Elgg

L’avatar utilisateur représente un utilisateur (ou un groupe) à travers le site. Par défaut, l’avatar intègre un menu contextuel sensitif qui vous permet d’effectuer des actions sur l’utilisateur dès lors que vous voyez son avatar. Par exemple vous pouvez l’ajouter comme contact, lui envoyer un message privé, et plus. Chaque plugin peut ajouter des entrées à ce menu contextuel, de sorte que son contenu final va beaucoup dépendre des fonctionnalités actives dans le site Elgg actuel.

Notes pour les développeurs

Utiliser une icône de profil différente

Pour remplacer l’icône de profil, ou fournir plus de contenu, étendre la vue icon/user/default.

Ajouter des éléments au menu contextuel

Le menu contextuel peut être étendu en enregistrant un event pour “register” “menu:user_hover”, les sections suivantes ont une signification spécifique :

• default pour les liens non actifs (par ex. pour lire un blog)

• admin pour les liens accessibles seulement par les administrateurs

Dans tous les cas, l’utilisateur en question sera passé en tant que $params['entity'].

Notifications du site

Le plugin Site notifications offre à vos utilisateurs un moyen de se tenir au courant de ce qui se passe dans votre communauté en envoyant une notification directement sur le site.

Fonctionnalités

• Recevez une notification lorsque du contenu est publié

• Les notifications non lues seront automatiquement marquées comme lues quand vous afficherez le contenu auquel elles se rapportent

• Les notifications seront automatiquement supprimées si le contenu auquel elles se rapportent est supprimé

• Les paramètres du plugin permettent de nettoyer automatiquement les notifications lues / non lues

Note pour les développeurs

Le nettoyage via cron des notifications de site (non) lues supprime directement les entités de la base de données. Il n’utilise pas $entity->delete() afin d’améliorer les performances. Cela signifie qu’aucun événement n’est déclenché pour les entités supprimées lors du nettoyage.

Le Fil

Le plugin « The Wire » - Le Fil de Elgg est un plugin de micro-blogging à la manière de Twitter, qui permet aux utilisateurs de publier des notes vers le Fil.

Validation des comptes utilisateur via l’e-mail

Le plugin uservalidationbyemail ajoute une étape au processus d’inscription des utilisateurs. Après que l’utilisateur se soit enregistré sur le site, un e-mail est envoyé à son adresse e-mail afin de valider que cette adresse e-mail appartient bien à l’utilisateur. L’utilisateur ne pourra se connecter qu’après avoir cliqué sur le lien de vérification contenu dans l’e-mail.

Déroulement pour l’utilisateur

1. L’utilisateur crée un compte en se rendant sur la page d’inscription de votre site

2. Une fois le compte créé l’utilisateur arrive sur une page qui indique de vérifier la présence de l’e-mail de validation sa boîte de messagerie

3. Dans l’e-mail de validation, un lien permet de confirmer son adresse e-mail

4. Après avoir cliqué sur le lien, le compte est validé

5. Si possible l’utilisateur est connecté

Si l’utilisateur tente de s’identifier avant d’avoir validé son compte, une erreur indique que l’utilisateur doit d’abord vérifier sa boite mail. De plus, un nouveau mail de validation est envoyé.

Options pour les administrateurs du site

Un administrateur du site peut effectuer certaines actions sur les comptes non validés. Une liste des membres non validés se trouve dans Administration -> Utilisateurs -> Non validés. L’administrateur peut manuellement valider ou supprimer l’utilisateur. Il existe également une option pour renvoyer l’e-mail de validation.

Les plugins suivants sont également distribués avec Elgg, mais ne sont pas (encore) documentés

• activity

• bookmarks

• custom_index

• developers

• externalpages

• friends_collections

• garbagecollector

• invitefriends

• members

• reportedcontent

• search

• system_log

• tagcloud

• theme_sandbox

• web_services

Licence

MIT ou GPLv2

Un package Elgg complet comprenant le framework et un noyau de plugins est disponible sous la version 2 de la licence GNU General Public License (GPLv2). Nous distribuons également le framework (sans les plugins) sous la licence MIT.

FAQ

Les réponses suivantes vous sont proposées à titre informatif ; elles ne constituent pas un conseil légal. Consultez un juriste si vous voulez vous assurer des réponses à ces questions. La Fondation Elgg ne peut pas être tenues pour responsable des décisions que vous prendrez sur la base de ce que vous lisez sur cette page.

Pour les questions qui n’ont pas réponse ici, veuillez vous référer à la FAQ officielle pour GPLv2 : official FAQ for the GPLv2.

Combien coûte Elgg ?

Elgg peut être téléchargé, installé et utilisé gratuitement. Si vous souhaitez faire un don, nous apprécions d’avoir des partenaires financiers financial supporters !

Puis-je enlever les liens / le branding Elgg ?

Oui.

Puis-je modifier le code source ?

Oui, mais en général nous vous recommandons de faire vos modifications sous forme de plugins, de sorte que lorsque une nouvelle version de Elgg est publiée le processus de mise à niveau reste aussi simple que possible.

Puis-je demander des frais d’adhésion à mes utilisateurs ?

Oui.

Si je modifie Elgg, dois-je rendre mes modifications disponibles ?

Non, si vous utilisez Elgg pour fournir un service, vous n’avez pas à rendre les sources disponibles. Si vous distribuez une version modifiée de Elgg, alors vous devez inclure le code sources des modifications.

Si j’utilise Elgg pour héberger un réseau, est-ce que la Fondation Elgg a quelques droits que ce soit sur mon réseau ?

Non.

Quelle est la différence entre la version MIT et la version GPL ?

Les plugins ne sont pas inclus avec la version MIT.

Vous pouvez distribuer un produit commercial construit avec Elgg en utilisant la version MIT sans devoir rendre disponibles vos modifications.

Avec la version sous licence GPL, vous devez rendre vos modifications du framework publiques si vous redistribuez le framework.

Pourquoi est-ce que certains plugins sont absents de la version MIT ?

Les plugins ont été développés sous licence GPL, et ne peuvent donc pas être diffusés sous une licence MIT. De plus, certains plugins font appel à des dépendances externes qui ne sont pas compatibles avec la licence MIT.

Ai-je le droit de distribuer un plugin pour Elgg sous une licence commerciale ?

Nous pensons que vous le pouvez, puisque les plugins ne dépendent habituellement que du noyau du framework ou « core », et que le framework est disponible sous la licence MIT. Ceci dit, nous vous conseillons vraiment de consulter un juriste sur ce point particulier si vous voulez vous en assurez absolument.

Notez que les plugins distribués via le site communautaire doivent être publiés sous une licence compatible GPLv2. Ils n’ont pas à être publiés sous licence GPLv2, seulement sous une licence compatible (comme la MIT).

Pouvons-nous construire notre propre outil utilisant Elgg et vendre cet outil à nos clients ?

Oui, mais dans ce cas vos clients seront libres de redistribuer cet outil sous les termes de la licence GPLv2.

Installation

Ayez votre propre instance de Elgg opérationnelle en un rien de temps.

Pré-requis

• MySQL 5.7+ ou MariaDB 10.3+

• PHP 8.0+ avec les extensions suivantes :

  • GD (pour les opérations graphiques)

  • PDO (pour la connexion à la base de données)

  • JSON (pour les réponses AJAX, etc.)

  • XML (pour les ressources xml et les web services, etc.)

  • Multibyte String support (pour l’internationalisation i18n)

  • (optionnel) intl (pour i18n)

  • La configuration appropriée et la capacité d’envoyer des e-mails via un agent de transport mail « MTA - Mail Transport Agent »

• Un serveur web avec le support de la réécriture d’URL « URL rewriting »

Le support officiel est fourni pour les configurations suivantes :

• Serveur Apache

  • Apache avec le module module rewrite activé

  • PHP exécuté en tant que module Apache

• Serveur Nginx

  • Nginx avec PHP-FPM utilisant FastCGI

Par « support officiel », nous entendons que :

• La plupart des développements et des tests sont effectués avec ces configurations

• Une bonne part de la documentation a été écrite en partant du principe qu’Apache ou Nginx est utilisé

• La priorité sur les rapports de bug est donnée aux utilisateurs d’Apache et Nginx si le bug est propre au serveur web (mais ces cas sont rares).

Note

Si vous utilisez RHEL, CentOS, ou toute distribution avec SELinux activé, vous devrez vous assurer que les contextes et permissions appropriés sont configurés :

• Donnez le contexte httpd_sys_rw_content_t à la racine de votre projet, à votre répertoire des données, et à tous leurs enfants

• Activez les booléens httpd_can_network_connect et httpd_can_network_connect_db

Politique de support des navigateurs

Les branches de fonctionnalités supportent les 2 dernières versions de tous les principaux navigateurs disponibles au moment de la première publication d’une version stable pour cette branche.

Les versions de correction de bugs ne modifient pas le support des navigateurs, même si une nouvelle version du navigateur a été publiée depuis.

Les principaux navigateurs signifie ici les navigateurs suivants, ainsi que leurs homologues mobiles :

• Navigateur Android

• Chrome

• Firefox

• Edge

• Safari

« Support » peut signifier que nous prenons avantage des technologies nouvelles et non implémentées, mais fournissons un polyfill JavaScript pour les navigateurs qui en ont besoin.

Il se peut qu’Elgg fonctionne avec des navigateurs non supportés, cependant la compatibilité peut être perdue à tout moment, y compris lors de la publication d’une correction de bug.

Vue d’ensemble

Téléchargez Elgg

Avec Composer (recommandé si vous êtes à l’aise avec la ligne de commande) :

composer self-update
composer create-project elgg/starter-project:dev-master ./path/to/project/root
cd ./path/to/project/root
composer install
composer install # 2nd call is currently required
vendor/bin/elgg-cli install # follow the questions to provide installation details

A partir du fichier ZIP (recommandé si vous n’êtes pas à l’aise avec la ligne de commande) :

• Télécharger la dernière version de Elgg

• Téléchargez le fichier ZIP avec un client FTP sur votre serveur

• Dézippez les fichiers dans la racine web de votre domaine.

Créez un répertoire pour les données

Elgg a besoin d’un répertoire particulier pour stocker les fichiers chargés, y compris les images du profil et les photos. Vous devez créer ce répertoire.

Attention

Pour des raisons de sécurité, ce dossier DOIT être conservé hors de la racine de vos documents « DocumentRoot ». Si vous l’avez créé dans le dossier /www/ ou /public_html/, ce n’est pas la bonne manière de faire.

Une fois que ce répertoire a été créé, vous devez vous assurer que le serveur web sur lequel tourne Elgg a le droit d’écrire et de créer des répertoires à l’intérieur. Ceci ne devrait pas être un problème sur les serveurs basés sur Windows, mais si votre serveur utilise Linux, Mac OS X ou une variante d’UNIX, vous aurez besoin de définir les droits d’accès du répertoire.

Si vous utilisez un client FTP graphique pour charger les fichiers, vous pouvez habituellement définir les droits en faisant un clic droit sur le dossier et en sélectionnant « propriétés » ou « Informations ».

Note

Les répertoires doivent pouvoir être lus et écrits. Les permissions suggérées dépendent de votre serveur et de la configuration des utilisateurs. Si le répertoire des données a pour propriétaire l’utilisateur du serveur web, les droits d’accès recommandés sont 750.

Avertissement

Définir les droits de votre répertoire des données à 777 va fonctionner, mais c’est dangereux et ce n’est pas recommandé. Si vous hésitez sur la bonne configuration à choisir pour les permissions, contactez votre hébergeur pour plus d’informations.

Créer une base de données MySQL

En utilisant l’outil d’administration de base de données de votre choix (si vous ne savez pas lequel, demandez à votre administrateur système), créez une nouvelle base de données MySQL pour Elgg. Vous pouvez créer une base de données MySQL avec n’importe lequel des outils suivants :

Assurez-vous d’ajouter un utilisateur à la base de données avec tous les privilèges et notez le nom de la base de données, l’identifiant et le mot de passe. Vous aurez besoin de ces informations pour installer Elgg.

Mettre en place le Cron

Elgg utilise des requêtes paramétrées pour effectuer des tâches de fond telles qu’envoyer des notifications ou effectuer des travaux de nettoyage de la base de données. Vous devez configurer le cron pour pouvoir utiliser ce type de fonctionnalités.

Visitez votre site Elgg

Une fois ces étapes terminées, visitez votre site Elgg dans votre navigateur web. A partir de là, Elgg vous guidera à travers le reste du processus d’installation. Le premier compte que vous créerez à la fin de l’installation sera le compte administrateur.

Une note sur settings.php et .htaccess

L’installeur de Elgg va essayer de créer deux fichiers pour vous :

• elgg-config/settings.php, qui contient la configuration de votre environnement local pour votre installation

• .htaccess, qui permet à Elgg de générer des URLs dynamiques

Si ces fichiers ne peuvent pas être générés automatiquement, par exemple parce que le serveur web n’a pas les droits d’accès en écriture dans les répertoires, Elgg vous dira comment les créer. Vous pouvez aussi modifier temporairement les droits d’accès sur la racine du répertoire et le répertoire engine. Définissez les droits d’accès sur ces deux répertoires de sorte que le serveur web puisse écrire dans ces deux répertoires terminez le processus d’installation, et modifiez à nouveau les droits d’accès pour rétablir les droits d’origine. Si, pour quelque raison que ce soit, ceci ne fonctionne pas, vous devrez :

• Depuis elgg-config/, copiez settings.example.php vers settings.php, puis ouvrez-le dans un éditeur de texte et renseignez les informations de la base de données

• Sur un serveur Apache, copiez install/config/htaccess.dist vers .htaccess

• Sur un serveur Nginx copiez install/config/nginx.dist vers /etc/nginx/sites-enabled et ajustez son contenu

Autres configurations

• Cloud9

• Homestead

• EasyPHP

• IIS

• MAMP

• MariaDB

• Nginx

• Ubuntu

• Hôtes virtuels

• XAMPP

Dépannage

Au secours ! J’ai des soucis pour installer Elgg

D’abord :

• Re-vérifiez que votre serveur répond bien aux pré-requis pour Elgg.

• Suivez si besoin les instructions spécifiques à un environnement

• Avez-vous vérifié que mod_rewrite est bien chargé ?

• Est-ce que le module mysql de apache est bien chargé ?

Conservez des notes sur ce que vous faites pour résoudre les problèmes d’installation. Parfois la modification d’un paramètre ou d’un fichier pour essayer de résoudre un problème peut être à l’origine d’un autre problème plus tard. Si vous devez recommencer depuis le début, supprimez simplement tous les fichiers, videz votre base de données, et commencez à nouveau.

Je ne peux pas enregistrer mon fichier de configuration sur une installation (j’ai une erreur 404 lors de l’enregistrement des paramètres)

Elgg dépend de l’extension Apache mod_rewrite pour simuler certaines URLs. Par exemple à chaque fois que vous effectuez une action dans Elgg, or lorsque vous visitez la page de profil d’un utilisateur, l’URL est translatée par le serveur en quelque chose que Elgg comprend en interne. Ceci est fait en utilisant des règles définies dans un fichier .htaccess, qui est le moyen standard d’Apache pour définir des éléments de configuration supplémentaires pour un site.

Cette erreur suggère que les règles de mod_rewrite ne sont pas traitées correctement. Ceci peut arriver pour différentes raisons. Si vous n’êtes pas à l’aise pour mettre en œuvre les solutions indiquées ci-dessous, nous vous recommandons vivement de contacter votre administrateur système ou le support technique et de leur faire suivre cette page.

Le .htaccess, s’il n’est pas créé automatiquement (cela se produit quand vous avez un problème avec mod_rewrite), peut être créé en renommant en .htaccess le fichier install/config/htaccess.dist distribué avec Elgg. Par ailleurs, si vous trouvez un fichier .htaccess dans le répertoire d’installation, mais avez toujours une erreur 404, vérifiez que le contenu du .htaccess est identique à celui de install/config/htaccess.dist.

``mod_rewrite`` n’est pas installé.

Contrôlez votre httpd.conf pour vérifier que ce module est bien chargé par Apache. Vous pouvez avoir besoin de redémarrer Apache pour qu’il tienne compte de tout changement de configuration. Vous pouvez également utiliser PHP info pour contrôler que le module est bien chargé.

Les règles définies dans ``.htaccess`` ne sont pas respectées.

Dans les paramètres de configuration de votre hôte virtuel (qui peut être intégrée dans httpd.conf), modifiez le paramètre AllowOverride pour qu’il ressemble à :

AllowOverride all

Ceci va indiquer à Apache de prendre en compte les règles de mod_rewrite depuis .htaccess.

Elgg n’est pas installé à la racine de votre répertoire web - « Elgg is not installed in the root of your web directory » (par ex.: http://example.org/elgg/ au lieu de http://example.org/)

Le script d’installation me redirige vers « action » alors que cela devrait être vers « actions »

Il s’agit d’un problème avec votre configuration de mod_rewrite.

Attention

NE CHANGEZ PAS, RÉPÉTEZ AVEC NOUS, NE CHANGEZ AUCUN nom de répertoire !

J’ai installé Elgg dans un sous-répertoire et mon action d’installation ne fonctionne pas !

Si vous installez Elgg de sorte qu’il soit accessible avec une adresse comme http://example.org/monsite/ plutôt que http://example.org/, il existe une faible possibilité que les règles de réécriture dans .htaccess ne soient pas traitées correctement. Ceci est généralement lié à l’utilisation d’un alias dans Apache. Vous pouvez avoir besoin d’indiquer à mod_rewrite où se situe votre installation Elgg.

• Ouvrez .htaccess dans un éditeur de texte

• Lorsqu’on vous y invite, ajoutez une ligne comme RewriteBase /chemin/vers/votre/installation/elgg/ (N’oubliez pas le slash final)

• Enregistrez le fichier et rafraîchissez votre navigateur.

Veuillez noter que le chemin que vous utilisez est le chemin web, moins l’hôte.

Par exemple, si votre installation Elgg s’affiche sur http://example.org/elgg/, vous devriez définir la base comme ceci :

RewriteBase /elgg/

Veuillez noter qu’installer dans un sous-répertoire ne nécessite pas d’utiliser RewriteBase. Il y a seulement quelques rares circonstances dans lesquelles c’est imposé par la configuration du serveur.

J’ai tout fait ! mod_rewrite fonctionne correctement, mais j’ai toujours l’erreur 404

Il y a peut-être un problème avec le fichier .htaccess. Parfois le processus d’installation de Elgg n’arrive pas à en créer ce fichier, ni à vous le signaler. Si vous en êtes à ce stade et avez essayé tout ce qui est indiqué ci-dessus :

• vérifiez qu’il s’agit bien du .htaccess créé par Elgg (et pas d’un fichier d’exemple fourni par le fournisseur du serveur)

• s’il ne s’agit pas du fichier htaccess fourni par Elgg, utilisez htaccess_dist (renommez-le en .htaccess)

J’ai un message d’erreur indiquant que le test de réécriture a échoué après la page de vérification des pré-requis

J’ai les messages suivants après l’étape de vérification des pré-requis (étape 2) de l’installation :

Nous pensons que votre serveur utilise un serveur web Apache.

Le test de réécriture a échoué et la cause la plus probable est que AllowOverride n’est pas défini à All pour le répertoire de Elgg. Ceci empêche Apache de traiter le fichier .htaccess qui contient les règles de réécriture.

Une cause moins probable est qu’Apache est configuré avec un alias pour votre répertoire Elgg et que vous deviez définir le RewriteBase dans votre .htaccess. Vous trouverez des instructions complémentaires dans le fichier .htaccess de votre répertoire Elgg.

Après cette erreur, chaque interaction avec l’interface web va produire une erreur 500 (Internal Server Error)

Ceci est probablement causé par le non-chargement du module de filtre en dé-commentant la ligne

#LoadModule filter_module modules/mod_filter.so

ligne dans le fichier « httpd.conf ».

le fichier de journal Apache « error.log » va contenir une entrée similaire à :

… « .htaccess: Invalid command “AddOutputFilterByType”, perhaps misspelled or defined by a module not included in the server configuration », soit Commande “AddOutputFilterByType” invalide, peut-être mal écrite ou définie par un module qui n’est pas inclus dans la configuration du serveur

Il y a une page blanche après que j’ai soumis ma configuration de base de données

Vérifiez que le module d’Apache mysql est installé et est bien chargé.

J’obtiens une erreur 404 avec une URL très longue

Si vous voyez une erreur 404 pendant l’installation ou lors de la création du premier compte utilisateur, avec une URL telle que : http://example.com/homepages/26/d147515119/htdocs/elgg/action/register ceci signifie que l’URL de votre site est incorrecte dans la table sites_entity de votre base de données. Cette valeur a été définie par vous lors de la deuxième étape de l’installation. Elgg essaie de deviner la bonne valeur mais a des difficultés avec les hébergements mutualisés. Utilisez phpMyAdmin pour modifier cette valeur avec la bonne URL de racine du site.

J’ai des difficultés pour définir le chemin vers le répertoire des données

Ceci est fortement spécifique au serveur utilisé aussi il est difficile de donner des conseils spécifiques. Si vous avez créé un répertoire pour les données, vérifiez que votre serveur HTTP arrive bien à y accéder. Le moyen le plus simple (mais le moins sécurisé) d’y parvenir est de lui donner les droits d’accès 777. Il est largement préférable de donner au serveur web la propriété du répertoire et de limiter les droits d’accès.

Avertissement

Définir les permissions du répertoire à 777 permet à L’INTÉGRALITÉ d’Internet de placer des fichiers dans la structure de votre répertoire et ainsi d’infecter votre serveur avec des malwares et autres virus. Définir les permissions à 750 devrait être plus que suffisant.

L’origine la plus probable de ce problème est que PHP est configuré pour interdire l’accès à la plupart des répertoires en utilisant open_basedir. Vous pouvez souhaiter vérifier ce point avec votre fournisseur d’hébergement.

Assurez-vous que le chemin est correct et se termine par un /. Vous pouvez vérifier le chemin dans la table de configuration de votre base de données.

Si vous n’avez qu’un accès FTP à votre serveur et que vous avez créé un répertoire mais n’en connaissez pas le chemin, vous devriez pouvoir le trouver à partir du chemin www défini dans la table de configuration de votre base de données. A ce stade il est recommandé de demander de l’aide à l’équipe support de votre fournisseur d’hébergement.

Je ne peux pas valider mon compte admin car je n’ai pas de serveur d’e-mail !

Bien qu’il soit exact que les comptes utilisateur normaux (à l’exception de ceux créés depuis le panneau d’administration) nécessitent que leur adresse e-mail soit authentifiée avant de pouvoir se connecter, ceci n’est pas nécessaire pour le compte administrateur.

Une fois que vous avez créé votre premier compte utilisateur vous pouvez vous connecter en utilisant les accès que vous avez fourni !

J’ai essayé toutes ces suggestions et je n’arrive toujours pas à installer Elgg

Il est possible que quelque chose d’autre ait été cassé lors du débogage de l’installation. Essayez de faire une nouvelle installation propre :

• supprimez votre base de données Elgg

• supprimez votre répertoire des données

• supprimez les fichiers source de Elgg

• recommencez l’installation

SI cette méthode ne fonctionne pas, demandez de l’aide à la communauté Elgg. Pensez à indiquer quelle version de Elgg vous essayez d’installer, à fournir des détails sur le serveur et la plateforme utilisés, ainsi que tous les messages d’erreur que vous pouvez avoir reçus, y compris ceux du journal d’erreur de votre serveur.

Vue d’ensemble pour les développeurs

Cette page constitue une rapide introduction à Elgg pour les développeurs. Elle couvre les principales approches pour travailler avec Elgg en tant que framework, et mentionne certains des termes et des technologies utilisées.

Voyez Guides de développement pour des tutoriels ou Documentation du design de conception pour une discussion approfondie sur le design.

Base de données et Persistance

Elgg utilise MySQL 5.7 ou supérieur pour la persistance des données et mappe les valeurs de la base de données en entités (une représentation d’une unité atomique d’informations) et en extensions (informations et descriptions supplémentaires sur les entités). Elgg prend en charge des informations supplémentaires telles que les relations entre les entités, les flux d’activité et divers types de paramètres.

Plugins

Les plugins modifient le comportement ou l’apparence de Elgg en remplaçant les vues ou en gérant les événements. Toutes les modifications apportées à un site Elgg doivent être implémentées via des plugins pour garantir une mise à niveau facile du noyau.

Actions

Les actions sont le principal moyen par lequel les utilisateurs interagissent avec un site Elgg. Les actions sont enregistrées par des plugins.

Evénements

Les événements sont utilisés dans les plugins Elgg pour interagir avec le moteur Elgg dans certaines circonstances. Les événements sont déclenchés à des moments stratégiques tout au long du processus de démarrage et d’exécution de Elgg, et permettent aux plugins de modifier ou d’annuler le comportement par défaut.

Vues « Views »

Les vues ou Views sont la première couche de présentation pour Elgg. Les vues peuvent être surchargées ou étendues par les Plugins. Les vues sont des catégories d’un type de vue « Viewtype », qui définit quel type de sortie devrait être généré par la vue.

JavaScript

Elgg utilise un système JavaScript compatible AMD fourni par RequireJs. Les bibliothèques jQuery, jQuery UI, jQuery Form, et jQuery UI Autocomplete sont distribuées avec Elgg.

Les plugins peuvent charger leurs propres bibliothèques JS.

Internationalisation

L’interface de Elgg supporte de multiples langues, et utilise Transifex pour la traduction.

Mise en cache

Elgg utilise deux caches pour améliorer les performances : un cache système et SimpleCache.

Bibliothèques tierce-partie

L’utilisation de bibliothèques tierce-partie dans Elgg est gérée par le gestionnaire de dépendances Composer. jQuery, RequireJs ou Zend mail sont des exemples de bibliothèques tierce-partie.

Pour une liste complète des dépendances de Elgg, consultez la page Packagist pour Elgg.

Génération de données de test ou Ensemencement

Elgg fournit un mécanisme de génération de données - ensemencement de base de données, ou database seeding - pour remplir la base de données avec des entités à des fins de test.

Vous pouvez exécuter les commandes suivantes pour générer des données de test et les supprimer de la base de données.

# seed the database
vendor/bin/elgg-cli database:seed

# unseed the database
vendor/bin/elgg-cli database:unseed

Les plugins peuvent enregistrer leurs propres graines via l’événement 'seeds', 'database'. Le gestionnaire doit renvoyer le nom de classe de la graine, qui doit étendre la classe \Elgg\Database\Seeder\Seed.

Ligne de commande Elgg CLI

elgg-cli outils en ligne de commande

Selon la manière dont vous avez installé Elgg et la configuration de votre serveur vous pouvez accéder aux binaires de l’outil en ligne de commande elgg-cli de l’une des manières suivantes depuis la racine de votre installation Elgg :

php ./elgg-cli list
./elgg-cli list
php ./vendor/bin/elgg-cli list
./vendor/bin/elgg-cli list

Note

Soyez informé que lors de l’utilisation de elgg-cli il peut être nécessaire d’exécuter la commande avec le même utilisateur que le serveur Web pour éviter les problèmes avec les droits des fichiers.

Commandes disponibles

cd /path/to/elgg/

# Get help
vendor/bin/elgg-cli --help

# List all commands
vendor/bin/elgg-cli list

# Install Elgg
# no-plugins: This is an optional argument, it'll prevent the activation of any plugins
# config: (string) Path to php file that returns an array with installation configuration, if not provided the config parameters will be questioned in the console.
vendor/bin/elgg-cli install [--no-plugins] [-c|--config CONFIG]

# Seed the database with fake entities
# limit: (int) number of items to seed (will be asked interactively for each seeder unless the -n/--no-interaction is used or only one type is seeded)
# type: (string) only seed given entity type
# create_since: (string) a compatible PHP date/time string to set the lower bound entity time created (eg, '-5 months')
# create_until: (string) a compatible PHP date/time string to set the upper bound entity time created (eg, 'yesterday')
# image_folder: (string) a folder where the seeder can find images to use as icons, etc.
# create: This is an argument, it'll force the creation of entities instead of building up to the limit
vendor/bin/elgg-cli database:seed [-l|--limit LIMIT] [-t|--type TYPE] [--create_since DATE/TIME] [--create_until DATE/TIME] [--image_folder FOLDER] [create]

# List information about the seeded database content
# this will show the available seeders to be used with the database:seed and database:unseed command and the currently seeded amounts
vendor/bin/elgg-cli database:seeders

# Remove seeded faked entities
# type: (string) only unseed given entity type
vendor/bin/elgg-cli database:unseed [-t|--type TYPE]

# Optimize database tables
# Requires garbagecollector plugin
vendor/bin/elgg-cli database:optimize

# Run cron jobs
vendor/bin/elgg-cli cron [-i|--interval INTERVAL] [-q|--quiet]

# Clear caches
vendor/bin/elgg-cli cache:clear

# Invalidate caches
vendor/bin/elgg-cli cache:invalidate

# Purge caches
vendor/bin/elgg-cli cache:purge

# System upgrade
# -v|-vv|-vvv control verbosity of the command (helpful for debugging upgrade scripts)
vendor/bin/elgg-cli upgrade [-v]

# Upgrade and execute all async upgrades
vendor/bin/elgg-cli upgrade async [-v]

# List all upgrades
vendor/bin/elgg-cli upgrade:list

# Execute a specific upgrade
# <upgrades>: a space separated list of upgrade classes to execute (see the upgrade:list command for a list)
vendor/bin/elgg-cli upgrade:batch <upgrades>

# List all, active or inactive plugins
# STATUS = all | active | inactive
vendor/bin/elgg-cli plugins:list [-s|--status STATUS]

# Activate plugins
# List plugin ids separating them with spaces: vendor/bin/elgg-cli plugins:activate activity blog
# use -f flag to resolve conflicts and dependencies
# you can set a plugin priority by using the format plugin_id:priority (eg. blog:last)
vendor/bin/elgg-cli plugins:activate [<plugins>] [-f|--force]

# Deactivate plugins
# List plugin ids separating them with spaces: vendor/bin/elgg-cli plugins:deactivate activity blog
# use -f flag to also disable dependents
vendor/bin/elgg-cli plugins:deactivate [<plugins>] [-f|--force]

Ajouter des commandes personnalisées

Les plugins peuvent ajouter leurs commandes à l’application CLI, en ajoutant le nom de la classe de commandes via une configuration dans elgg-plugin.php ou via l’événement 'commands','cli'. La classe de la commande doit étendre \Elgg\CLI\Command.

class MyCommand extends \Elgg\Сli\Command {

}

elgg_register_event_handler('commands', 'cli', function(\Elgg\Event $event) {
    $return = $event->getValue();

    $return[] = MyCommand::class;

    return $return;

});

Les commandes personnalisées sont basées sur Symfony Console Commands. Veuillez consulter leur documentation pour plus d’informations.

Guides pour les administrateurs

Bonnes pratiques pour gérer efficacement un site construit avec Elgg.

Prise en main

Vous avez installé Elgg et réglé toutes les potentiels problèmes initiaux. Et maintenant ? Voici quelques suggestions pour vous aider à vous familiariser avec Elgg.

Concentrez-vous d’abord sur les fonctionnalités principales

Quand vous commencez avec Elgg, le mieux est de commencer par explorer les fonctionnalités de base du noyau et des plugins livrés conjointement avant d’installer des plugins tierce-partie. Il est tentant d’installer chaque plugin intéressant du site communautaire, mais explorer les fonctionnalités du noyau vous permet de vous familiariser avec le comportement habituel de Elgg, et évite d’introduire des bugs ou de la confusion dans votre nouveau réseau Elgg.

Elgg s’installe avec un jeu de plugins de réseau social activés : des blogs, des marque-pages partagés, des fichiers, des groupes, des « likes », des messages, des pages de type wiki, des profils utilisateurs, et du microblogging. Pour changer les plugins activés, connectez-vous avec un compte administrateur, puis utilisez le menu supérieur pour accéder à Administration, puis à Plugins dans la barre latérale droite.

Note

L’utilisateur que vous créez pendant l’installation est un utilisateur admin.

Créez des utilisateurs de test

Les utilisateurs peuvent être créés de deux manières dans un Elgg standard :

1. Terminez le processus d’inscription en utilisant une autre adresse e-mail et un autre identifiant. (Déconnectez-vous d’abord ou utilisez un autre navigateur !)

2. Ajoutez un utilisateur dans la section Admin en naviguant vers Administration -> Utilisateurs -> Ajouter un nouvel utilisateur.

Note

Les utilisateurs qui s’inscrivent eux-même doivent valider leur compte avant de pouvoir se connecter. Les utilisateurs qu’un administrateur crée sont déjà validés.

Explorez les fonctionnalités de l’utilisateur

Utilisez vos utilisateurs de test pour créer des articles de blog, ajouter des widgets à votre profil ou à votre tableau de bord, publier sur le Fil (« The Wire », microblogging) et créer des pages (création de pages de type wiki). Examinez les Paramètres - « Settings » - dans la barre de menu supérieure. C’est à cet endroit qu’un utilisateur définit ses préférences et configure ses outils (qui peuvent être vides parce qu’aucun des plugins par défaut n’ajoute de contrôle à cet endroit).

Explorez les fonctionnalités de l’administration

Tous les outils d’administration sont accessibles en cliquant sur Administration dans le menu supérieur. L’administrateur a un tableau de bord avec un widget qui explique les diverses sections. Changez les options dans le menu Configurer pour changer l’apparence et le comportement de Elgg.

Étendre les fonctionnalités de Elgg

Après avoir exploré ce que Elgg peut faire d’emblée, installez quelques thèmes et plugins. Vous pouvez trouver de nombreux plugins et thèmes sur le site de la communauté Elgg qui ont été développés par d’autres personnes. Ces plugins font tout, de la modification de chaînes de traductions à un re-design complet de l’interface de Elgg, en passant par l’ajout d’un chat, etc. Puisque ces plugins ne sont pas officiels, assurez-vous de vérifier les commentaires pour vous assurer que vous installez des plugins bien écrits par des développeurs de qualité.

Installation avec Composer

Le moyen le plus simple pour garder votre site Elgg à jour est d’utiliser Composer. Composer va s’occuper d’installer toutes les dépendances requises pour tous les plugins et pour Elgg, tout en conservant également ces dépendances à jour sans avoir de conflit.

Installer Composer

https://getcomposer.org/download/

Installer Elgg en tant que projet Composer

composer self-update
composer create-project elgg/starter-project:dev-master ./path/to/my/project
cd ./path/to/my/project
composer install

Ceci va créer un fichier composer.json sur la base du projet de démarrage Elgg Elgg starter project qui a les bases pour installer Elgg.

Ouvrez votre navigateur

Allez sur votre navigateur et installez Elgg via l’interface d’installation

Mettre en place un contrôle de version

Cette étape est optionnelle mais vivement recommandée. Elle vous permettra de gérer simplement l’installation du même plugin entre différents environnements (développement/tests/production).

cd ./path/to/my/project
git init
git add .
git commit -a -m 'Initial commit'
git remote add origin <git repository url>
git push -u origin master

Installer les plugins

Installez les plugins sous forme de dépendances Composer. Ceci suppose qu’un plugin a été enregistré sur Packagist

composer require hypejunction/hypefeed
composer require hypejunction/hypeinteractions
# whatever else you need

Commitez

Assurez-vous que composer.lock n’est pas ignoré dans .gitignore

git add .
git commit -a -m 'Add new plugins'
git push origin master

Déployer en production

Déploiement initial

cd ./path/to/www

# you can also use git clone
git init
git remote add origin <git repository url>
git pull origin master

composer install

Déploiements subséquents

cd ./path/to/www
git pull origin master

# never run composer update in production
composer install

Mettre à niveau Elgg

Ce document va vous guider à travers les étapes nécessaires pour mettre à niveau votre installation Elgg vers la dernière version.

Si vous avez écrit des plugins personnalisés, vous devriez également lire les guides de développement pour les informations sur la mise à jour du code des plugins pour la dernière version de Elgg.

Conseil

• Sauvegardez votre base de données, votre répertoire des données et le code source

• Faites attention aux commentaires spécifiques pour certaines versions ci-dessous

• Il est conseillé pour les versions inférieures à 2.0 de n’appliquer qu”une seule mise à niveau mineure à la fois

• Vous pouvez mettre à niveau depuis n’importe quelle version mineure vers n’importe quelle version mineure supérieure au sein de la même version majeure (2.0 -> 2.1 ou 2.0 -> 2.3)

• Vous pouvez mettre à niveau uniquement la dernière version mineure de la version majeure précédente vers n’importe quelle version mineure de la version majeure suivante (2.3 -> 3.0 ou 2.3 -> 3.2, mais pas 2.2 -> 3.x).

• A partir de Elgg 2.3.* vous pouvez mettre à niveau vers n’importe quelle version ultérieure de Elgg sans devoir passer par chacune des versions mineures (par ex. vous pouvez mettre à niveau directement de la 2.3.8 vers la 3.2.5, sans devoir mettre à niveau vers les versions 3.0 et 3.1)

• Essayez la nouvelle version sur un site de test avant d’effectuer une mise à niveau

• Signalez tout problème dans les plugins aux auteurs de plugins

• Si vous êtes auteur de plugins, vous pouvez signaler tout problème de rétro-compatibilité sur GitHub

De 2.3 à 3.0

1. Mettez à niveau composer.json

Si vous avez utilisé le projet de démarrage Elgg pour installer Elgg 2.3, vous pouvez avoir besoin de mettre à niveau votre composer.json :

• modifiez les pré-requis de la plateforme vers PHP >= 7.0

• facultativement, définissez les paramètres d’optimisation de l’autoloader

• facultativement, désactivez le plugin fxp-asset au bénéfice de asset-packagist

Votre composer.json devrait ressembler à quelque chose comme ceci (en fonction des changements que vous avez vous-même introduits) :

{
        "type": "project",
        "name": "elgg/starter-project",
        "require": {
                "elgg/elgg": "3.*"
        },
        "config": {
                "process-timeout": 0,
                "platform": {
                        "php": "7.0"
                },
                "fxp-asset": {
                        "enabled": false
                },
                "optimize-autoloader": true,
                "apcu-autoloader": true
        },
        "repositories": [
                {
                        "type": "composer",
                        "url": "https://asset-packagist.org"
          }
        ]
}

2. Mettez à jour le .htaccess

Trouvez la ligne :

RewriteRule ^(.*)$ index.php?__elgg_uri=$1 [QSA,L]

Et remplacez-la par :

RewriteRule ^(.*)$ index.php [QSA,L]

3a. Mise à niveau via Composer (recommandé)

Si vous aviez installé votre projet 2.3 avec composer, vous pouvez suivre la séquence suivante :

Sauvegardez votre base de données, votre répertoire des données, et le code

composer self-update

cd ./path/to/project/root
composer require elgg/elgg:~3.0.0
composer update
vendor/bin/elgg-cli upgrade async -v

Note

Dans certains cas, la mise à niveau via la ligne de commande échoue car certaines modifications de schéma de base de données doivent d’abord être appliquées. Dans ce cas, vous devez exécuter les migrations Phinx migrations manuellement

3b. Mise à niveau manuelle (approche traditionnelle)

Les mises à niveau manuelles sont une opération pénible pour les administrateurs de sites. Nous vous déconseillons de maintenir un site Elgg en utilisant des archives ZIP. Économisez-vous du temps en apprenant comment utiliser composer et les systèmes de contrôle de version, tels que git. Cette tâche sera également plus complexe si vous utilisez des plugins tierce-partie et/ou si vous avez modifié les fichiers du noyau !

1. Sauvegardez votre base de données, votre répertoire des données, et le code

2. Identifiez-vous sur votre site en tant qu’administrateur

3. Téléchargez la nouvelle version de Elgg depuis http://elgg.org

4. Mettez à jour les fichiers

   • Si vous mettez à niveau vers une version majeure, vous devrez replacer tous les fichiers du noyau et supprimer tous les fichiers qui ont été retirés du noyau de Elgg, car ils peuvent interférer avec le bon fonctionnement de votre site.

   • Si vous mettez à jour vers une version mineure ou un patch, vous devez remplacer tous les fichiers du noyau.

5. Fusionnez tous les nouveaux changements des règles de réécriture « rewrite rules »

   • Pour Apache depuis install/config/htaccess.dist vers .htaccess

   • Pour Nginx depuis install/config/nginx.dist vers la configuration de votre serveur (habituellement dans /etc/nginx/sites-enabled)

6. Visitez http://your-elgg-site.com/upgrade.php

7. Exécutez les mises à niveau asynchrones via http://your-elgg-site.com/admin/upgrades

Note

Toutes les modifications devraient avoir été faites au sein de plugins, de sorte qu’elles ne sont pas perdues lors de l’écrasement des fichiers. Si ce n’est pas le cas, prenez soin de maintenir vos modifications.

Note

Si vous n’arrivez pas à accéder au script upgrade.php et recevez une erreur, ajoutez la ligne $CONFIG->security_protect_upgrade = false; à votre ficher settings.php, puis supprimez-le après avoir terminé toutes les étapes de l’installation.

Note

Si vous rencontrez des soucis avec des plugins lors du processus de mise à niveau, ajoutez un fichier nommé disabled dans votre dossier /mod/. Ceci va désactiver tous les plugins, de sorte que vous puissiez terminer la mise à niveau du noyau. Vous pouvez ensuite gérer les mises à niveau de chacun des plugins l’un après l’autre.

Si vous avez installé Elgg en utilisant une archive d’installation mais souhaitez maintenant basculer vers composer :

• Mettez à niveau votre installation en utilisant la méthode manuelle

• Déplacez votre code vers un emplacement provisoire

• Créez un nouveau projet composer en utilisant le projet Elgg de démarrage en suivant les instructions d’installation dans le répertoire racine de votre installation actuelle

• Copiez les plugins tierce-partie depuis votre ancienne installation vers le répertoire /mod

• Exécutez l’installateur de Elgg en utilisant votre navigateur ou l’outil en ligne de commande elgg-cli

• Quand vous arrivez à l’étape de la base de données, indiquez les mêmes accès que vous avez utilisés pour l’installation manuelle, Elgg va comprendre qu’il y a une installation existante et ne remplacera aucune valeur de la base de données

• Facultativement, commitez votre nouveau projet vers un suivi de version

Application d’un correctif à l’aide de Composer

La définition d’un correctif se trouve dans la documentation Release policy.

Les pré-requis de votre composer.json pour Elgg doivent être ~3.y.0 (où y est la version mineure 0, 1, etc. que vous souhaitez installer). Cela vous permettra d’installer facilement des correctifs sans risque d’installer la prochaine version mineure.

{
        "require": {
                "elgg/elgg": "~3.0.0"
        }
}

Juste pour vous en assurer vous pouvez d’abord vérifier ce qui sera installé / mis à niveau en exécutant la commande suivante

# to get a full list of all packages which can be upgraded
composer update --dry-run

# or if you only wish to check for Elgg
composer update elgg/elgg --dry-run

Pour mettre à niveau Elgg, exécutez simplement

# to upgrade all packages
composer update

# or to only upgrade Elgg
composer update elgg/elgg

Versions précédentes

Vérifiez la documentation Elgg qui correspond à la version Elgg vers laquelle vous souhaitez mettre à niveau, en changeant la version de documentation dans le coin inférieur gauche de Upgrading docs

Plugins

Les plugins peuvent modifier le comportement de Elgg et ajouter de nouvelles fonctionnalités.

Où trouver des plugins

Des plugins peuvent être obtenus depuis :

• La Communauté Elgg

• Github

• Sites tierce-partie (généralement pour un certain prix)

Si aucun plugin existant ne correspond à vos besoins, vous pouvez solliciter un développeur hire a developer ou créer le vôtre create your own.

La Communauté Elgg

Trouver des plugins

Ordre de tri basé sur la popularité

Sur la page des plugins de la communauté, vous pouvez trier par date de mise en ligne (Filtre par date « Newest ») ou par nombre de téléchargements (Filtre par nombre de téléchargement « Most downloads »). Trier par nombre de téléchargement est une bonne idée si vous débutez avec Elgg et voulez voir quels plugins sont fréquemment utilisés par d’autres administrateurs. Ceux-ci sont souvent (mais pas toujours) des plugins de meilleure qualité qui offrent des possibilités significatives.

Utilisez la recherche de plugin par tag

Une boite de recherche se trouve à côté des options de filtrage de la page des plugins. Elle vous permet de rechercher des plugins par tags. Les auteurs des plugins définissent les tags.

Identifiez les auteurs de plugins particuliers

La qualité des plugins varie de manière substantielle. Si vous trouvez un plugin qui fonctionne bien sur votre site, vous pouvez regarder les autres réalisations que l’auteur du plugin a développées en cliquant sur son nom lorsque vous êtes sur la page d’un plugin.

Évaluer les Plugins

Regardez les commentaires et les notations

Avant de télécharger et d’utiliser un plugin, c’est toujours une bonne idée de lire les commentaires que les autres ont laissé. Si vous voyez des personnes qui se plaignent que le plugin ne fonctionne pas ou qu’il rend leur site instable, vous devriez probablement éviter ce plugin. Néanmoins, certains utilisateurs ignorent les instructions d’installation ou installent un plugin de manière incorrecte puis laissent un feedback négatif. De plus, certains auteurs de plugins choisissent de ne pas autoriser les commentaires.

Installer sur une site de test

Si vous essayez un plugin pour la première fois, c’est une mauvaise idée de l’installer sur un site de production. Vous devriez maintenir un site de test séparé pour évaluer les plugins. C’est une bonne idée de mettre en place progressivement les plugins sur votre site de production même après qu’ils aient passé l’évaluation sur un site de test. Ceci vous permet d’isoler les problèmes potentiels introduits par un nouveau plugin.

Types de plugins

Thèmes

Les thèmes sont des plugins qui modifient l’apparence et le comportement de votre site. Ils comprennent généralement des feuilles de styles, des scripts côté client et des vues qui modifient la présentation et le comportement par défaut de Elgg.

Packs de langues

Les packs de langue sont des plugins qui fournissent le support d’autres langues.

Les packs de traduction peuvent étendre et inclure des traductions pour les chaînes de traduction du noyau, des plugins du noyau et/ou de plugins tierces-parties.

Quelques packs de langues sont déjà inclus dans le noyau, et se trouvent dans le dossier languages du répertoire racine de Elgg. Les plugins individuels incluent leurs traductions dans le répertoire languages de la racine du plugin.

Cette structure facilite la création de nouveaux packs de langues qui remplacent les chaînes de traduction existantes ou ajoutent le support de nouvelles langues.

Installation

Tous les plugins sont dans le dossier mod de votre installation Elgg.

Pour installer un nouveau plugin :

• décompresser (unzip) le contenu du package de distribution du plugin

• copier/FTP le dossier extrait dans le répertoire mod de votre installation Elgg

• activez le plugin depuis votre panneau d’administration

Pour activer un plugin :

• Connectez-vous à votre site Elgg avec votre compte administrateur

• Allez dans Administration -> Configurer -> Plugins

• Trouvez votre plugin dans la liste des plugins installés et cliquez sur le bouton “activer”.

Ordre des plugins

Les plugins sont chargés selon l’ordre dans lequel ils sont listés sur la page Plugins. L’ordre initial après une installation est plus ou moins aléatoire. Au fur et à mesure que de nouveaux plugins sont ajoutés par un administrateur, ils sont placés en fin de liste.

Quelques règles générales pour l’ordre des plugins :

• Un plugin de thème devrait être placé en dernier ou au moins proche du bas de la liste

• Un plugin qui modifie le comportement d’un autre plugin devrait être placé plus bas dans la liste des plugins

Performance

Faites que votre site fonctionne sans heurt et de manière aussi réactive que possible.

Est-ce que Elgg peut passer à l’échelle de X millions d’utilisateurs ?

Les gens demandent souvent si Elgg convient pour de grands sites.

Tout d’abord, nous pourrions nous arrêter et demander: « où et comment prévoyez-vous d’obtenir tous ces utilisateurs ? » Sérieusement, c’est un problème très intéressant. Faire évoluer Elgg est avant tout une question d’ingénierie technique. C’est intéressant mais plus ou moins un problème résolu. L’informatique ne fonctionne pas différemment pour Elgg que pour Google, par exemple. Obtenir des millions d’utilisateurs? C’est comme le Saint Graal de toute l’industrie de la technologie.

Deuxièmement, comme pour la plupart des choses dans la vie, la réponse est « ça dépend » :

• Que font vos utilisateurs ?

• Sur quelle machine et avec quelle configuration fonctionne Elgg ?

• Est-ce que vos plugins se comportent bien ?

Améliorer l’efficacité du moteur Elgg est un projet en cours, bien qu’il y ait des limites à la quantité de choses que n’importe quel script peut faire.

Si vous prenez au sérieux le sujet de la scalabilité, vous aurez probablement envie de considérer un certain nombre de choses vous-même.

Mesurez d’abord

Il ne sert à rien de dépenser des ressources sur un problème si vous ne connaissez pas :

• quel est le problème

• de quelles ressources ce problème a besoin

• où ces ressources sont nécessaires

Investissez dans un outil de profilage afin de pouvoir identifier où votre goulot d’étranglement se situe, surtout si vous envisagez de dépenser de l’argent sur ce problème.

Régler MySQL

Elgg fait un usage intensif de la base de données en back-end, faisant, à chaque chargement de page, de nombreux appels et allers et retours entre le serveur web et la base de données. Ceci est parfaitement normal et un serveur de base de données bien configuré sera capable de faire face à des milliers de requêtes par seconde.

Voici quelques astuces de configuration qui pourraient aider :

• Assurez-vous que MySQL utilise un fichier de configuration my.cnf adapté à la taille de votre site web.

• Augmentez la quantité de mémoire disponible pour PHP et de même pour MySQL (vous aurez dans tous les cas à augmenter la quantité de mémoire disponible pour le processus de php)

Activer la mise en cache

En règle générale, si un programme est lent, c’est parce qu’il effectue à plusieurs reprises un calcul ou une opération coûteuse. La mise en cache permet au système d’éviter de faire ce travail encore et encore à chaque requête grâce à la mise en cache des résultats précédents. En utilisant la mémoire pour stocker les résultats, il est alors facile de récupérer en mémoire le résultat de la requête et de le passer aux requêtes suivantes, économisant ainsi à chaque requête tout le travail de calcul. Nous discutons ci-dessous de plusieurs solutions de mise en cache généralement disponibles et pertinentes pour Elgg.

Cache simple - Simplecache

Par défaut, les vues sont mises en cache dans le répertoire des données de Elgg pour une période de temps donnée. Cela supprime la nécessité de régénérer chaque vue à chaque chargement de la page.

Ceci peut être désactivé en définissant $CONFIG->simplecache_enabled = false; Pour de meilleures performances, assurez-vous que cette valeur est bien définie sur true.

Cela conduit à des artefacts pendant le développement/la programmation, si par exemple vous modifiez un thème dans votre plugin, puisque la version mise en cache sera utilisée au lieu de la nouvelle version fournie par votre plugin.

Le cache simple peut être désactivée via le menu d’administration. Il est recommandé de le faire sur votre plate-forme de développement si vous écrivez des plugins Elgg.

Ce cache est automatiquement vidé à chaque fois qu’un plugin est activé, désactivé ou réorganisé, ou quand le script upgrade.php est exécuté.

Pour de meilleures performances, vous pouvez également créer un lien symbolique depuis /cache/ dans votre répertoire racine web vers le répertoire assetroot spécifié dans votre configuration (par défaut il est situé dans /path/to/dataroot/caches/views_simplecache/ :

cd /path/to/wwwroot/
ln -s /path/to/dataroot/caches/views_simplecache/ cache

Si votre serveur web supporte les liens symboliques « symlinks », ceci va servir les fichiers directement depuis le disque sans démarrer PHP à chaque fois.

Pour des raisons de sécurité, quelques serveurs web (par ex. Apache dans la version 2.4) pourraient par défaut ne suivre les liens symboliques que si le propriétaire de la source et de la cible du lien correspondent. Si le lien symbolique du cache ne fonctionne pas sur votre serveur web, vous pouvez changer le propriétaire du lien symbolique du cache lui-même (et non du répertoire /views_simplecache/) avec

cd /path/to/wwwroot/
chown -h wwwrun:www cache

Dans cet exemple on prend l’hypothèse que le répertoire /views_simplecache/ du répertoire des données appartient au compte wwwrun qui fait partie du groupe www. Si ce n’est pas le cas sur votre serveur, vous devez modifier la commande chown en conséquence.

Cache système - System cache

L’emplacement des vues est mis en cache afin de retrouver rapidement les vues (en effet, le profilage a indiqué que le temps de chargement d’une page prend une quantité non-linéaire du temps plus il y a de plugins activés, ceci en raison de la recherche des vues). Elgg met également en cache des informations telles que la cartographie de la langue et de la carte des classes.

Ceci peut être désactivé en définissant $CONFIG->system_cache_enabled = false; Pour de meilleures performances, assurez-vous que cette valeur est bien définie sur true.

Les emplacements des vues sont actuellement stockés dans des fichiers placés dans votre dossier de données (toutefois des versions ultérieures de Elgg peuvent utiliser memcache). Comme avec le cache simple, le cache système est automatiquement vidé chaque fois qu’un plugin est activé, désactivé ou réorganisé, ou quand le script upgrade.php est exécuté.

Le cache du système peut être désactivé via le menu d’administration, et il est recommandé de le faire sur votre plate-forme de développement si vous écrivez des plugins Elgg.

Cache de démarrage

Elgg a la capacité de mettre en cache de nombreuses ressources créées et récupérées pendant le processus de démarrage. Pour configurer la durée de validité de ce cache vous devez définir la valeur du TTL dans votre fichier settings.php : $CONFIG->boot_cache_ttl = 3600;

Cache des requêtes de base de données

Pour la durée de vie de l’exécution d’une page donnée, un cache de toutes les requêtes SELECT est conservé. Cela signifie que pour le chargement d’une page donnée, une requête sélectionnée donnée ne sortira dans la base de données qu’une seule fois, même si elle est exécutée plusieurs fois. Toute écriture dans la base de données videra ce cache. Ce cache sera automatiquement effacé à la fin du chargement d’une page.

Vous pouvez rencontrer des problèmes de mémoire si vous utilisez le framework Elgg comme bibliothèque dans un script PHP CLI. Ceci peut être désactivé en définissant $CONFIG->db_disable_query_cache = true;

Etags et headers Expires

Ces technologies indiquent aux navigateurs de vos utilisateurs de mettre en cache des actifs statiques (CSS, JS, images) localement. Avoir ceci activé réduit fortement la charge du serveur et améliore la performance perçue par les utilisateurs.

Utilisez le plugin Firefox yslow ou les Outils de Développement de Chrome DevTools Audits pour confirmer quelles technologies sont utilisées actuellement sur votre serveur.

Si les actifs statiques ne sont pas mis en cache :

• Vérifiez que vous avez ces extensions et qu’elles sont activées sur votre hébergement

• Mettez à jour votre fichier .htaccess, si vous faites une mise à niveau depuis une version précédente de Elgg

• Activez Simplecache, qui transforme les vues sélectionnées en actifs pouvant être mis en cache par le navigateur

Memcached

Libmemcached a été créé par Brian Aker et a été conçu dès le départ pour offrir la meilleure performance possible aux utilisateurs de Memcached.

Voir aussi

http://libmemcached.org/About.html et https://secure.php.net/manual/en/book.memcached.php

Pré-requis pour l’installation :

• php-memcached

• libmemcached

• memcached

Configuration :

Dé-commentez et renseignez les sections suivantes dans le fichier settings.php

$CONFIG->memcache = true;

$CONFIG->memcache_servers = array (
    array (
        'host' => 'server1',
        'port' => 11211
    ),
    array (
        'host' => 'server2',
        'port' => 11211
    )
);

De manière optionnelle, si vous avez plusieurs installations Elgg mais n’utilisez qu’un seul serveur Memcache, vous pouvez vouloir ajouter un préfixe d’espace de nom. Afin de faire cela, dé-commentez la ligne suivante

$CONFIG->memcache_namespace_prefix = '';

Squid

Nous avons obtenu de bons résultats en utilisant Squid pour mettre en cache les images.

Mise en cache du code exécutable - « bytecode »

Il existe de nombreux caches de code disponibles sur le marché. Ceux-ci accélèrent votre site en mettant en cache le code compilé depuis votre script, ce qui signifie que votre serveur n’a pas à compiler le code PHP à chaque fois qu’il est exécuté.

Servir directement les fichiers

Si votre serveur peut être configuré pour supporter les headers X-Sendfile ou X-Accel, vous pouvez configurer leur utilisation dans settings.php. Ceci permet à votre serveur web de diffuser directement les fichiers au client au lieu d’utiliser la fonction PHP readfile().

Optimisation de l’Autoloader de Composer

Le chargeur automatique Composer est responsable du chargement des classes fournies par les dépendances de Elgg. La façon dont le chargeur automatique fonctionne est qu’il recherche un nom de classe dans les dépendances installées. Bien qu’il s’agisse principalement d’un processus rapide, il peut être optimisé.

Vous pouvez optimiser l’autoloader de 2 façons différentes. La première est via la ligne de commande, l’autre est d’utiliser le fichier composer.json de votre projet.

Si vous souhaitez optimiser le chargeur automatique à l’aide de la ligne de commande, utilisez le drapeau -o. L’inconvénient est que vous devez ajouter le drapeau -o à chaque fois que vous exécutez Composer.

# During the installation
composer install -o

# Or during the upgrade process
composer upgrade -o

La deuxième option consiste à ajouter l’optimisation à votre fichier composer.json, de cette façon vous ne l’oubliez jamais.

{
        "config": {
                "optimize-autoloader": true,
                "apcu-autoloader": true
        }
}

Voir aussi

Consultez la page d’optimisaiton de l’auto-chargement Autoloader Optimization pour plus d’informations sur l’optimisation du chargeur automatique Composer.

Note

À partir de Elgg 3.0 tous les téléchargements de Elgg à partir du site disposent du chargeur automatique optimisé.

Hébergement

N’espérez pas faire tourner un site avec des millions d’utilisateurs sur un hébergement mutualisé à bas prix. Vous aurez besoin de votre propre serveur d’hébergement et d’avoir la main sur la configuration, ainsi que de beaucoup de bande passante et de mémoire disponibles.

Mémoire, CPU et bande passante

De par la nature de la mise en cache, toutes les solutions de mise en cache auront besoin de mémoire. C’est un investissement plutôt économique d’augmenter la mémoire et le CPU.

Au sujet d’un matériel puissant il est probable que la bande passante soit le goulet d’étranglement - « bottleneck » - avant le serveur lui-même. Assurez-vous que votre hébergement peut supporter le trafic que vous attendez.

Configuration

Enfin, jetez un coup d’œil à votre configuration car il y a quelques points d’attention qui peuvent surprendre les gens.

Par exemple, Apache peut d’emblée gérer une charge plutôt élevée. Cependant, la majorité des distributions Linux sont livrées avec mysql configuré pour de petits sites. Ceci peut peut donner lieu à des processus Apache bloqués qui attendent de pouvoir parler à un processus MySQL très surchargé.

Vérifiez les plugins ayant un mauvais comportement

Des plugins peuvent être développés d’une manière très naïve et ceci peut ralentir l’ensemble du site.

Essayez de désactiver quelques plugins pour voir si cela améliore notablement les performances. Une fois que vous avez trouvé un responsable potentiel, rendez-vous sur la page de l’auteur du plugin et signalez vos résultats.

Utilisez du HTML rendu côté client

Nous avons constaté qu’à un certain niveau, une bonne partie du temps passé sur le serveur est simplement le temps de construction du HTML de la page avec le système de vues de Elgg.

Il est très difficile de mettre en cache les sorties templates - des modèles de mise en page - dans la mesure où ils prennent généralement des entrées arbitraires. Au lieu d’essayer de mettre en cache la sortie de certaines pages ou vues, la suggestion est de basculer vers un système de modèles basé sur HTML de sorte que le navigateur de l’utilisateur puisse lui-même mettre en cache les modèles. Puis demandez à l’ordinateur de l’utilisateur de faire le travail de générer le résultat en appliquant des données JSON à ces modèles.

Ceci peut être très efficace, mais présente l’inconvénient de demander un travail de développement supplémentaire significatif. L’équipe de Elgg envisage d’intégrer cette stratégie directement dans Elgg, dans la mesure où c’est aussi efficace, tout particulièrement pour les pages avec du contenu répété ou masqué.

Cron

Qu’est-ce que ça fait ?

Cron est un programme disponible sur les systèmes d’exploitation basés sur Unix qui permet aux utilisateurs d’exécuter des commandes et des scripts à des intervalles définis ou à des heures précises.

Le gestionnaire de cron de Elgg permet aux administrateurs et aux développeurs de plugins de mettre en place des tâches qui ont besoin d’être exécutées à des intervalles définis.

Les exemples les plus courants de tâches cron dans Elgg incluent :

• l’envoi des notifications en file d’attente

• la rotation des journaux système dans la base de données

• le nettoyage des déchets - garbage collector - dans la base de données (compactage de la base de données par la suppression des entrées qui ne sont plus requises)

Les plugins peuvent ajouter des tâches en enregistrant un gestionnaire d’événement pour l’un des intervalles cron suivants :

• minute - Exécuté toutes les minutes

• fiveminute - Exécuté toutes les 5 minutes

• fifteenmin - Exécuté toutes les 15 minutes

• halfhour - Exécuté toutes les 30 minutes

• hourly - Exécuté toutes les heures

• daily - Exécuté tous les jours

• weekly - Exécuté toutes les semaines

• monthly - Exécuté tous les mois

• yearly - Exécuté tous les ans

elgg_register_event_handler('cron', 'hourly', function() {

   $events = my_plugin_get_upcoming_events();

   foreach ($events as $event) {
      $attendees = $event->getAttendees();

      // notify
   }
});

Comment ça marche ?

crontab doit être configuré de manière à activer le gestionnaire cron Elgg toutes les minutes ou à un intervalle spécifique. Une fois que l’entrée cron active la tâche cron, Elgg exécute tous les gestionnaires d’événements attachés à cet intervalle.

Si vous avez un accès SSH à vos serveurs Linux, tapez crontab -e et ajoutez votre configuration crontab.

* * * * * path/to/phpbin path/to/elgg/elgg-cli cron -q

La commande suivante va s’exécuter chaque minute et activer toutes les tâches du cron attendues.

Facultativement, vous pouvez activer les gestionnaire pour un intervalle spécifique :

0 * * * * path/to/phpbin path/to/elgg/elgg-cli cron -i hourly -q

Sauvegarde et Restauration

Introduction

Pourquoi

Les fournisseurs d’hébergements mutualisés ne fournissent généralement pas de moyen automatisé de sauvegarder votre installation Elgg. Cet article propose une méthode permettant d’accomplir cette tâche.

Dans l’IT il existe souvent de nombreuses manières d’accomplir la même chose. Gardez cela à l’esprit. Cet article va expliquer une méthode pour sauvegarder et restaurer votre installation Elgg sur un hébergement mutualisé qui utilise l’application CPanel. Cependant, les idées présentées ici peuvent être ajustées pour d’autres applications également. Ce qui suit sont des situations typiques qui peuvent exiger une procédure telle que celle-ci :

• Récupération après une catastrophe

• Déplacer votre site Elgg vers un nouvel hôte

• Dupliquer une installation

Quoi

Sujets couverts :

• Des backups complets des répertoires de Elgg et des bases de données MySQL sont effectués tous les jours (automatisé)

• Les backups sont envoyés sur autre emplacement hors-site via FTP (automatisé)

• Les backups locaux sont supprimés après un transfert réussi vers le site distant (automatisé)

• Cinq jours de backups seront conservés (automatisé)

• Restauration des données sur le nouvel hôte (manuel)

Ce processus a été composé à partir d’articles d’assistance précédemment publiés dans le wiki de documentation de Elgg.

Hypothèses

Les hypothèses suivantes ont été faites :

• Le répertoire du programme Elgg est /home/userx/public_html

• Le répertoire des données de Elgg est /home/userx/elggdata

• Vous avez créé un répertoire local pour vos backups à /home/userx/sitebackups

• Vous disposez d’un server FTP distant auquel envoyer les fichiers de backup

• Le répertoire dans lequel vous allez enregistrer les backups distants est /home/usery/sitebackups/

• Vous allez restaurer le site chez un deuxième fournisseur d’hébergement mutualisé dans le répertoire /home/usery/public_html

Important

Assurez-vous de remplacer userx, usery, http://mynewdomain.com et tous les mots de passe par des valeurs qui correspondent à votre propre installation !

Créer un backup utilisable - automatiquement

Personnalisez le script de backup - sauvegarde automatique

Le script que vous allez utiliser peut être trouvé ici .

Copiez simplement le script dans un fichier texte et renommez le fichier avec une extension .pl. Vous pouvez utiliser n’importe quel éditeur de texte pour modifier le fichier.

Modifiez les valeurs suivantes pour qu’elles correspondent à votre structure de répertoires :

# ENTER THE PATH TO THE DIRECTORY YOU WANT TO BACKUP, NO TRAILING SLASH
$directory_to_backup = '/home/userx/public_html';
$directory_to_backup2 = '/home/userx/elggdata';
# ENTER THE PATH TO THE DIRECTORY YOU WISH TO SAVE THE BACKUP FILE TO, NO TRAILING SLASH
$backup_dest_dir = '/home/userx/sitebackups';

Modifiez les valeurs suivantes pour qu’elles correspondent à vos paramètres de base de données :

# MYSQL BACKUP PARAMETERS
$dbhost = 'localhost';
$dbuser = 'userx_elgg';
$dbpwd = 'dbpassword';
# ENTER DATABASE NAME
$database_names_elgg = 'userx_elgg';

Modifiez les valeurs suivantes pour qu’elles correspondent aux paramètres de votre serveur FTP distant :

# FTP PARAMETERS
$ftp_host = "FTP HOSTNAME/IP";
$ftp_user = "ftpuser";
$ftp_pwd = "ftppassword";
$ftp_dir = "/";

Enregistrez le fichier avec l’extension .pl (dans le cadre de cet article nous appellerons ce fichier : elgg-ftp-backup-script.pl) et chargez-le dans le répertoire /home/userx/sitebackups

Ayez conscience que vous pouvez désactiver le FTP et modifier un peu le script de sorte qu’il ne supprime pas le fichier de backup local dans le cas où vous ne voulez pas utiliser de stockage distant pour vos backups.

Configurez la tâche périodique cron de backup

Connectez-vous à votre application CPanel et cliquez sur le lien « Cron Jobs ». Dans le menu déroulant Paramètres communs - « Common Settings », choisissez une fois par jour - « Once a day » - et tapez ce qui suit dans le champ de commande /usr/bin/perl /home/userx/sitebackups/elgg-ftp-backup-script.pl

Cliquez sur le bouton d’ajout d’une nouvelle tâche cron « Add New Cron Job ». Des sauvegardes quotidiennes complètes sont désormais planifiées et seront transférées hors du site.

Configurez la tâche périodique Cron de nettoyage

Si vous envoyez vos sauvegardes, via FTP, à un autre hébergeur mutualisé qui utilise l’application CPanel ou si vous avez totalement désactivé FTP, vous pouvez configurer votre conservation des données comme suit.

Connectez-vous à votre application CPanel pour votre site FTP, ou localement si vous n’utilisez pas FTP, et cliquez sur le lien « Cron Jobs ». Dans le menu déroulant Paramètres communs - « Common Settings » choisissez une fois par jour - « Once a day » - et saisissez ce qui suit dans le champ de commande find /home/usery/sitebackups/full_* -mtime +4 -exec rm {} \;

Le paramètre -mtime X va définir le nombre de jours de rétention des sauvegardes. Tous les fichiers plus anciens que le nombre de jour x sera supprimé. Cliquez sur le bouton d’ajout d’une nouvelle tâche cron « Add New Cron Job ». Vous avez maintenant configuré la durée de rétention de vos sauvegardes.

Restauration depuis un backup

Préparez vos fichiers de backup

L’hypothèse est que vous restaurez votre site vers un autre prestataire d’hébergement mutualisé avec CPanel.

Lorsque le script a sauvegardé les fichiers, la structure originelle des répertoires est conservée dans le fichier zip. Nous devons faire un petit nettoyage. Effectuez ce qui suit :

• Téléchargez le fichier de backup à partir duquel vous souhaitez effectuer la restauration

• Décompressez le contenu du fichier de backup

• Naviguez pour trouver la sauvegarde de votre site et la sauvegarde SQL. Extrayez les deux archives. Vous aurez alors :

  • un fichier de dump MySQL avec une extension « .sql »

  • une autre structure de répertoire avec pour contenu :

    • /home/userx/public_html

    • /home/userx/elggdata

• Compressez le contenu du répertoire /home/userx/public_html sous forme de fichier zip de sorte que les fichiers soient à la racine du fichier zip

  • La raison de cette démarche est simple. Il est beaucoup plus efficace de télécharger un seul fichier zip que d’envoyer par FTP sur votre nouvel hôte tout le contenu du répertoire / home/userx/public_html.

• Compressez le contenu du répertoire /home/userx/elggdata sous forme de fichier zip de sorte que les fichiers soient à la racine du fichier zip

Vous devriez maintenant avoir les fichiers suivants :

• le fichier .sql

• le fichier zip avec le contenu de /home/userx/public_html à la racine

• le fichier zip avec le contenu de /home/userx/elggdata` à la racine

Restaurez les fichiers

Ceci est écrit dans l’hypothèse que vous restaurez vers un hébergement différent mais conservez la même structure de répertoires. Faites comme suit :

• Connectez-vous à l’application CPanel de l’hébergement sur lequel vous souhaitez restaurer le site et ouvrez le gestionnaire de fichiers - « File Manager ».

• Naviguez vers /home/usery/public_html

  • Chargez le fichier zip qui contient les fichiers de /home/userx/public_html

  • Décompressez le fichier zip

    Vous devriez maintenant voir tous les fichiers dans /home/usery/public_html

  • Supprimez le fichier zip

• Naviguez vers /home/usery/elggdata

  • Chargez le fichier zip qui contient les fichiers de /home/userx/elggdata

  • Décompressez le fichier zip

    Vous devriez maintenant voir tous les fichiers dans /home/usery/elggdata

  • Supprimez le fichier zip

La restauration des fichiers du programme et des données est terminée

Restaurez la base de données MySQL

Note

A nouveau, l’hypothèse ici est que vous restaurez votre installation Elgg vers un second fournisseur d’hébergement mutualisé. Chaque fournisseur d’hébergement mutualisé préfixe avec le nom du compte du détenteur les bases de données associées à ce compte. Par exemple, l’identifiant de notre premier hébergement est userx de sorte que l’hébergeur va ajouter le préfixe userx_ pour nous donner un nom de base de données de userx_elgg. Quand nous restaurons vers notre second fournisseur d’hébergement mutualisé nous le faisons avec un identfiant de usery de sorte que le nom de notre base de données sera usery_elgg. Les fournisseurs d’hébergement ne vous permettent pas de modifier ce comportement. De sorte que le processus ici n’est pas aussi simple que simplement restaurer la base de données depuis le backup vers le compte usery. Néanmoins, une fois ceci dit, ce n’est pas si difficile non plus.

Modifiez le backup MySQL

Ouvrez le fichier``.sql`` que vous avez extrait de votre backup dans votre éditeur de texte favori. Commentez les lignes suivantes avec un dièse :

#CREATE DATABASE /*!32312 IF NOT EXISTS*/ `userx_elgg` /*!40100 DEFAULT CHARACTER SET latin1 */;
#USE `userx_elgg`;

Enregistrez le fichier.

Créez la nouvelle base de données

Effectuez les actions suivantes :

• Connectez-vous à l’application CPanel du nouvel hôte et cliquez sur l’icône « Bases de données MySQL - « MySQL Databases »

  • Renseignez le nom de la base de données et cliquez sur le bouton créer - « create ». Pour notre exemple, nous allons conserver elgg ce qui nous donne pour nom de base de données usery_elgg

  • Vous pouvez associer un utilisateur existant à la nouvelle base de données, ou pour créer un nouvel utilisateur vous aurez besoin de :

    • Allez dans la section « Ajouter Nouvel utilisateur » de la page « Bases de données MySQL »

    • Saisissez l’identifiant et le mot de passe. Pour notre exemple nous allons rester simples et utiliser à nouveau elgg. Ce qui va nous donner un identifiant usery_elgg

  • Associez le nouvel utilisateur avec la nouvelle base de données

    • Allez dans la section Ajouter un nouvel utilisateur à la base de données - « Add User To Database » - de la page des Bases de données MySQL - « MySQL Databases ». Ajoutez l’utilisateur usery_elgg à la base de données usery_elgg

    • Sélectionnez « Tous les Privilèges » - « All Privileges » - et cliquez sur le bouton « Effectuer les changements » - « Make Changes »

Restaurez la base de données de production

Maintenant il est temps de restaurer le fichier de backup MySQL en l’important dans notre nouvelle base de données nommée « usery_elgg ».

• Connectez-vous à l’application CPanel du nouvel hôte et cliquez sur l“« icône phpMyAdmin

  • Choisissez la base de données usery_elgg dans la colonne de gauche

  • Cliquez sur l’onglet « import » en haut de la page

  • Naviguez jusqu’au backup .sql dans votre arborescence locale et sélectionnez-le

  • Cliquez sur le bouton « Go » en bas à droite de la page

Vous devriez maintenant voir un message indiquant que l’opération a réussi

Combiner le tout

L’installation elgg restaurée ne connaît rien du nom de la nouvelle base de données, de l’identifiant, de la structure des répertoires, etc. C’est ce que nous allons aborder ici.

Modifiez /public_html/elgg-config/settings.php sur le nouvel hébergement pour reproduire les informations de la base de données que vous venez de créer.

// Database username
$CONFIG->dbuser = 'usery_elgg';

// Database password
$CONFIG->dbpass = 'dbpassword';

// Database name
$CONFIG->dbname = 'usery_elgg';

// Database server
// (For most configurations, you can leave this as 'localhost')
$CONFIG->dbhost = 'localhost';

// (For most configurations, you can leave this as 3306)
$CONFIG->dbport = 3306;

$CONFIG->wwwroot = 'http://your.website.com/'

Téléchargez le fichier settings.php vers le nouvel hôte - en remplaçant le fichier existant.

Ouvrez l’outil phpMyAdmin sur le nouvel hôte depuis CPanel. Sélectionnez la base de données usery_elgg sur la gauche, et cliquez sur l’onglet SQL en haut de la page. Exécutez les requêtes SQL suivantes sur la base de données usery_elgg :

Modifiez le chemin d’installation

UPDATE `elgg_config` SET `value` = REPLACE(`value`, "/home/userx/public_html/grid/", "/home/usery/public_html/grid/") WHERE `name` = "path";

Modifiez le répertoire des données

UPDATE `elgg_config` SET `value` = REPLACE(`value`, "/home/userx/elggdata/", "/home/usery/elggdata/") WHERE `name` = "dataroot";

Modifiez le répertoire des données de stockage des fichiers

UPDATE elgg_metadata set value = '/home/usery/elggdata/' WHERE name = 'filestore::dir_root';

Finaliser la nouvelle installation

Exécutez le script de mise à niveau en visitant l’URL suivante : http://mynewdomain.com/upgrade.php . Effectuez cette étape deux fois - depuis le début.

Mettez à jour vos enregistrements DNS de sorte que votre nom d’hôte se résolve toujours vers l’adresse IP du nouvel hôte si c’est un déplacement permanent.

Félicitations !

Si vous avez suivi les étapes soulignées ici vous devriez maintenant avoir une copie totalement fonctionnelle de votre installation Elgg d’origine.

Connexe

Script de backup FTP

Voici un script automatisé pour sauvegarder une installation Elgg.

#!/usr/bin/perl -w

# FTP Backup

use Net::FTP;

# DELETE BACKUP AFTER FTP UPLOAD (0 = no, 1 = yes)
$delete_backup = 1;

# ENTER THE PATH TO THE DIRECTORY YOU WANT TO BACKUP, NO TRAILING SLASH
$directory_to_backup = '/home/userx/public_html';
$directory_to_backup2 = '/home/userx/elggdata';

# ENTER THE PATH TO THE DIRECTORY YOU WISH TO SAVE THE BACKUP FILE TO, NO TRAILING SLASH
$backup_dest_dir = '/home/userx/sitebackups';

# BACKUP FILE NAME OPTIONS
($a,$d,$d,$day,$month,$yearoffset,$r,$u,$o) = localtime();
$year = 1900 + $yearoffset;
$site_backup_file = "$backup_dest_dir/site_backup-$day-$month-$year.tar.gz";
$full_backup_file = "$backup_dest_dir/full_site_backup-$day-$month-$year.tar.gz";

# MYSQL BACKUP PARAMETERS
$dbhost = 'localhost';
$dbuser = 'userx_elgg';
$dbpwd = 'dbpassword';
$mysql_backup_file_elgg = "$backup_dest_dir/mysql_elgg-$day-$month-$year.sql.gz";

# ENTER DATABASE NAME
$database_names_elgg = 'userx_elgg';

# FTP PARAMETERS
$ftp_backup = 1;
$ftp_host = "FTP HOSTNAME/IP";
$ftp_user = "ftpuser";
$ftp_pwd = "ftppassword";
$ftp_dir = "/";

# SYSTEM COMMANDS
$cmd_mysqldump = '/usr/bin/mysqldump';
$cmd_gzip = '/usr/bin/gzip';

# CURRENT DATE / TIME
($a,$d,$d,$day,$month,$yearoffset,$r,$u,$o) = localtime();
$year = 1900 + $yearoffset;

# BACKUP FILES
$syscmd = "tar --exclude $backup_dest_dir" . "/* -czf $site_backup_file $directory_to_backup $directory_to_backup2";

# elgg DATABASE BACKUP
system($syscmd);
$syscmd = "$cmd_mysqldump --host=$dbhost --user=$dbuser --password=$dbpwd --add-drop-table --databases $database_names_elgg -c -l | $cmd_gzip > $mysql_backup_file_elgg";

system($syscmd);

# CREATING FULL SITE BACKUP FILE
$syscmd = "tar -czf $full_backup_file $mysql_backup_file_elgg $site_backup_file";
system($syscmd);

# DELETING SITE AND MYSQL BACKUP FILES
unlink($mysql_backup_file_elgg);
unlink($site_backup_file);

# UPLOADING FULL SITE BACKUP TO REMOTE FTP SERVER
if($ftp_backup == 1)
{
   my $ftp = Net::FTP->new($ftp_host, Debug => 0)
      or die "Cannot connect to server: $@";

   $ftp->login($ftp_user, $ftp_pwd)
      or die "Cannot login ", $ftp->message;

   $ftp->cwd($ftp_dir)
      or die "Can't CWD to remote FTP directory ", $ftp->message;

   $ftp->binary();

   $ftp->put($full_backup_file)
      or warn "Upload failed ", $ftp->message;

   $ftp->quit();
}

# DELETING FULL SITE BACKUP
if($delete_backup = 1)
{
   unlink($full_backup_file);
}

Dupliquer une installation

Introduction

Pourquoi dupliquer une installation Elgg ?

Il existe beaucoup de raisons pour lesquelles vous pouvez vouloir dupliquer une installation Elgg : déplacer le site vers un autre serveur, créer un serveur de test ou de développement, et créer des backups fonctionnels sont les plus habituelles. Pour créer un double fonctionnel d’un site Elgg, 3 choses doivent être copiées :

• Base de données

• Données du répertoire des données

• Code

Il faut modifier au moins 5 éléments d’information pour une installation copiée :

• le fichier elgg-config/settings.php qui peut aussi se trouver à l’emplacement engine/settings.php pour les versions pré-2.0

• le fichier .htaccess (Apache) ou la configuration de Nginx en fonction du serveur utilisé

• l’entrée de la base de donnée pour l’entité de votre site

• l’entrée de la base de donnée pour le chemin d’installation

• l’entrée de la base de donnée pour le chemin du répertoire des données

Ce qui n’est pas traité dans ce tutoriel

Ce tutoriel nécessite une connaissance minimale d’Apache, MySQL, et des commandes Linux. A ce titre, certaines choses ne seront pas couvertes dans ce tutoriel. Ceci comprend :

• Comment faire un backup - sauvegarder et restaurer des bases de données MySQL

• Comment configurer Apache pour fonctionner avec Elgg

• Comment transférer des fichiers vers et depuis votre serveur de production

Avant de commencer

Avant de commencer, assurez-vous que votre installation Elgg est pleinement fonctionnelle. Vous aurez aussi besoin des éléments suivants :

• Un backup de la base de données de votre site Elgg actif

• Un emplacement pour copier la base de données active

• Un serveur qui convienne pour installer le site Elgg dupliqué

  (Qui peut être le même serveur que celui de votre installation Elgg en production)

Les backups de la base de données peuvent être obtenus de diverses manières, y compris via phpMyAdmin, l’interface graphique de MySQL, et la ligne de commande. Contactez votre hébergeur pour des informations sur comment sauvegarder et restaurer des bases de données, ou utilisez un moteur de recherche pour trouver de l’information à ce sujet.

Au cours de ce tutoriel, nous allons faire les hypothèses suivantes à propos du site Elgg en production :

• L’URL est http://www.myelgg.org/

• Le chemin d’installation est /var/www/elgg/

• Le chemin du répertoire des données est /var/data/elgg/

• L’hôte de la base de données est localhost

• Le nom de la base de données est production_elgg

• L’utilisateur de la base de données est db_user

• Le mot de passe de la base de données est db_password

• Le préfixe des tables de la base de données est elgg

A la fin du tutoriel, les renseignements de notre installation Elgg de test seront :

• L’URL est http://test.myelgg.org/

• Le chemin d’installation est /var/www/elgg_test/

• Le répertoire des données est /var/data/elgg_test/

• L’hôte de la base de données est localhost

• Le nom de la base de données est test_elgg

• L’utilisateur de la base de données est db_user

• Le mot de passe de la base de données est db_password

• Le préfixe des tables de la base de données est elgg

Copiez le code de Elgg vers le serveur de test

La toute première étape est de dupliquer le code du site Elgg de production. Dans notre exemple, c’est aussi simple que de copier /var/www/elgg/ vers /var/www/elgg_test/.

cp -a /var/www/elgg/ /var/www/elgg_test/

Copiez les données de Elgg vers le serveur de test

Dans cet exemple, c’est aussi simple que copier /var/data/elgg/ vers /var/data/elgg_test/.

cp -a /var/data/elgg/ /var/data/elgg_test/

Si vous n’avez pas d’accès console - shell - à votre serveur et devez transférer les données par FTP, vous pouvez avoir besoin de modifier le propriétaire et les permissions des fichiers.

Note

Vous devez aussi supprimer les dossiers de cache du disque. Ceux-ci correspondent aux dossiers cacheroot et assetroot dans votre configuration.

Editez settings.php

Le fichier elgg-config/settings.php contient les renseignement de configuration de la base de données. Ceux-ci doivent être ajustés pour votre nouvelle installation Elgg de test. Dans notre exemple, nous allons regarder dans /var/www/elgg_test/elgg-config/settings.php et trouver les lignes qui ressemblent à ceci :

// Database username
$CONFIG->dbuser = 'db_user';

// Database password
$CONFIG->dbpass = 'db_password';

// Database name
$CONFIG->dbname = 'elgg_production';

// Database server
// (For most configurations, you can leave this as 'localhost')
$CONFIG->dbhost = 'localhost';
// (For most configurations, you can leave this as 3306)
$CONFIG->dbport = 3306;

// Database table prefix
// If you're sharing a database with other applications, you will want to use this
// to differentiate Elgg's tables.
$CONFIG->dbprefix = 'elgg';

Nous devons modifier ces lignes pour qu’elles correspondent à notre nouvelle installation :

// Database username
$CONFIG->dbuser = 'db_user';

// Database password
$CONFIG->dbpass = 'db_password';

// Database name
$CONFIG->dbname = 'elgg_test';

// Database server
// (For most configurations, you can leave this as 'localhost')
$CONFIG->dbhost = 'localhost';
// (For most configurations, you can leave this as 3306)
$CONFIG->dbport = 3306;

// Database table prefix
// If you're sharing a database with other applications, you will want to use this
// to differentiate Elgg's tables.
$CONFIG->dbprefix = 'elgg';

$CONFIG->wwwroot = 'http://your.website.com/'

Note

Notez que $CONFIG->dbname a changé pour correspondre à notre nouvelle base de données.

Copier la base de données de Elgg

Maintenant la base de données doit être copiée depuis elgg_production vers elgg_test. Voyez la documentation de votre gestionnaire MySQL préféré pour savoir comment dupliquer une base de données. Vous allez généralement exporter les tables de la base de donnée actuelle vers un fichier, créer la nouvelle base de données, puis importer les tables que vous avez précédemment exportées.

Vous avez deux possibilités pour mettre à jour les valeurs dans la base de données. Vous pourriez changer les valeurs dans le fichier exporté, ou vous pourriez modifier ces valeurs par des requêtes sur la base de données. Un avantage de modifier directement le fichier exporté est que vous pouvez aussi modifier les liens que les utilisateurs ont créé vers du contenu au sein de votre site. Par exemple, si des personnes ont mis en marque-page des pages avec le plugin bookmarks, les marque-pages vont pointer vers l’ancien site tant que vous n’aurez pas mis à jour leurs URLs.

Entrées de la base de données

Nous devons maintenant modifier 4 entrées dans la base de données. Ceci peut être fait aisément en exécutant 4 commandes SQL simples :

Modifiez le chemin d’installation

UPDATE `elgg_config` SET `value` = REPLACE(`value`, "/var/www/elgg_production/", "/var/www/elgg_test/") WHERE `name` = "path";

Modifiez le répertoire des données

UPDATE `elgg_config` SET `value` = REPLACE(`value`, "/var/data/elgg_production/", "/var/data/elgg_test/") WHERE `name` = "dataroot";

Vérifiez le fichier .htaccess

Si vous aviez apporté des modifications au fichier .htaccess qui modifient des chemins, assurez-vous que vous les mettez à jour dans l’installation de test.

Mettez à jour la configuration du serveur web

Pour cet exemple, vous devez modifier la config Apache pour activer un sous-domaine avec pour racine des documents - document root /var/www/elgg_test/. Si vous prévoyez d’installer dans un sous-répertoire de votre racine des documents, cette étape n’est pas nécessaire.

Si vous utilisez Nginx, vous aurez besoin de mettre à jour la configuration du serveur pour correspondre aux nouveaux chemins basés sur install/config/nginx.dist.

Exécutez upgrade.php

Pour régénérer les données mises en cache, assurez-vous d’exécuter http://test.myelgg.org/upgrade.php

Astuces

C’est une bonne idée de garder un serveur de test à portée de main pour expérimenter l’installation de nouveaux plugins et faire du développement. Si vous automatisez les restaurations de la base de données elgg_test, modifier les valeurs de $CONFIG et ajouter les lignes suivantes à la fin du fichier elgg_test/elgg-config/settings.php va permettre de réécrire sans couture les entrées de la base de données MySQL.

$con = mysql_connect($CONFIG->dbhost, $CONFIG->dbuser, $CONFIG->dbpass);
mysql_select_db($CONFIG->dbname, $con);

$sql = "UPDATE {$CONFIG->dbprefix}config
   SET value = REPLACE(`value`, "/var/www/elgg_production/", "/var/www/elgg_test/")
   WHERE name = 'path'";
mysql_query($sql);
print mysql_error();

$sql = "UPDATE {$CONFIG->dbprefix}config
   SET value = REPLACE(`value`, "/var/data/elgg_production/", "/var/data/elgg_test/")
   WHERE name = 'dataroot'";
mysql_query($sql);
print mysql_error();

Connexe

Voir aussi

Sauvegarde et Restauration

Trouver de l’aide

Vous avez un problème avec Elgg ? Le meilleur moyen d’obtenir de l’aide est de demander sur le Site de la Communité. Ce site communautaire est animé par un grand nombre de volontaires. Voici quelques astuces pour vous aider à trouver l’aide dont vous avez besoin.

Trouver de l’aide

Ne soyez pas un Help Vampire

Nous avons tous été des débutants à un moment, mais nous pouvons tous apprendre. Le fait de ne pas montrer que vous faites des tentatives pour apprendre par vous-même ou faites vos propres recherches est décourageant pour ceux qui aident. De plus, il est quasiment impossible de répondre à des questions très génériques comme « Comment je construis un forum ? ».

Faites d’abord des recherches

Assurez-vous de faire des recherches dans la documentation (ce site), sur le Site de la Communauté, et dans un moteur de recherche avant de poser une question. Les nouveaux utilisateurs de Elgg se posent souvent les mêmes questions, aussi merci de faire des recherches. Les membres sont moins enclins à répondre à une demande à laquelle il a déjà été répondu maintes fois ou à laquelle on peut facilement trouver une réponse via un moteur de recherche.

Demandez une seule fois

Poser les mêmes questions à plusieurs endroits rend plus difficile le fait de vous répondre. Posez votre questions à un seul endroit. Les questions dupliquées peuvent être modérées.

Indiquez la version de Elgg

Les différentes versions de Elgg ont différentes fonctionnalités (et différents bugs). Préciser la version de Elgg que vous utilisez va aider les personnes qui aident.

Ayez un profil raisonnable

Les profils qui ressemblent à du spam ou ont des noms loufoques seront souvent ignorés. La jovialité est bienvenue, mais les membres ont plus de chance d’aider Michael que 1337elggHax0r.

Publiez dans le forum approprié

Assurez-vous de publier dans le bon forum. Si vous avez une question sur comment créer un plugin, n’écrivez pas dans le forum « Elgg Feedback ». Si vous avez besoin d’aide pour installer Elgg, écrivez dans le groupe de support technique « Technical Support » et pas dans le groupe des thèmes « Theming ».

Utilisez un titre de sujet descriptif

De bons titres de sujets décrivent de manière concise votre problème ou question. De mauvais titres sont vagues, ne contiennent que les lettres capitales, et une ponctuation excessive.

Bon titre : « Écran blanc après la mise à niveau vers 1.7.4 »

Mauvais titre : « URGENT!!!! site cassé ;-( je perds de l’argent à l’aide!!!!!!!!!! »

Donnez des détails

Ajoutez autant de détails que possible à propos de votre problème. Si vous avez un site en ligne, incluez un lien. Soyez accueillant si des membres de la communauté vous demandent plus d’informations. Nous ne pouvons pas vous aider si vous ne donnez pas de détails !

Gardez cela public

C’est un forum public pour le bien du projet Elgg. Gardez les messages publics. Il n’y a aucune raison pour qui que ce soit de vous envoyer des messages privés ou des e-mails. De même, il n’y a aucune raison de demander à qui que ce soit de vous envoyer un e-mail privé. Publiez en public.

Recommandations

En plus des mentions légales et des conditions d’utilisation du site, suivre ces recommandations aide à garder notre site communautaire utile et sûr pour tout le monde.

Contenu

Tous les contenus doivent être tous publics : « PG » ou Parental Guidance - classification des contenus adultes aux USA et au Royaume-Uni. Si votre site Elgg a du contenu adulte et qu’on vous a demandé de publier un lien, veuillez le marquer « NSFW » (Not Safe For Work) de sorte que les personnes le sachent.

L’utilisation excessive de jurons dans n’importe quelle langue ne sera pas tolérée.

Humeur

Travailler avec des problèmes techniques peut être frustrant. Veuillez laisser le site de la communauté libre de frustration. Si vous ressentez de l’anxiété, passez le cap et faites autre chose. Menacer ou attaquer des membres de la communauté, des développeurs du noyau, ou des développeurs de plugins n’aidera pas à résoudre votre problème et risque très probablement de vous faire bannir.

Publicité

Les annonces publicitaires ne sont pas autorisées. La publication de tout type d’annonce sera modérée.

Demander de l’argent / Offrir de payer

Ne demandez pas d’argent sur le site de la communauté. De même, ne proposez pas de payer pour des réponses. Si vous recherchez des développements sur mesure, publiez dans le groupe des services professionnels « Professional Services ». Les publications qui demandent de l’argent ou recommandent un plugin commercial peuvent être modérées.

Liens

Si vous avez un problème avec un site en ligne, merci de fournir un lien vers ce site.

Ceci dit, la communauté n’est pas un service de backlinks ni un outil SEO. Un excès de liens sera modéré et votre compte peut être banni.

Signatures

Il y a une raison pour laquelle Elgg n’a pas d’option pour les signatures : elles causent du désordre et détournent l’attention de la conversation. Il est recommandé aux utilisateurs de ne pas utiliser de signature sur le site communautaire, et les signatures avec des liens ou de la publicité seront retirées.

Relancer, +1, moi aussi

Ne faites pas cela. Si votre question n’a pas reçu de réponse, voyez le début de ce document pour des astuces. Ces types de réponses n’ajoutent rien à la conversation et peuvent être modérées.

Publier du Code

De longs extraits de code rendent la lecture confuse dans le cadre d’un forum. Veuillez utiliser http://elgg.pastebin.com pour publier de longs extraits de code et donnez le lien PasteBin au lieu de publier directement le code.

Bonnes idées

Pas de règles strictes, mais des bonnes idées.

Dites merci

Est-ce que quelqu’un vous a aidé ? Assurez-vous de remercier cette personne : le site de la communauté est animé par des volontaires. Personne n’a la devoir de vous aider avec votre problème. Assurez-vous de montrer votre reconnaissance !

Donnez en retour

Vous avez une astuce pour Elgg ? Vous voyez quelqu’un qui a le même problème que vous aviez eu ? Vous êtes passé par là et pouvez les aider, alors donnez-leur un coup de main !

Sécurité

A partir de Elgg 3.0 plusieurs paramètres de sécurisation ont été ajoutés à Elgg. Vous pouvez activer/désactiver ces paramètres comme vous le souhaitez.

Protection des mises à niveau

L’URL de mise à niveau http://your-elgg-site.com/upgrade.php peut être protégée par un jeton unique. Ceci évite que des utilisateurs aléatoires aient la possibilité d’exécuter ce fichier. Le jeton n’est pas nécessaire pour les administrateurs du site connectés.

Protection du Cron

Les URLs du cron peuvent être protégées par un jeton unique. Ceci évite que des utilisateurs aléatoires puissent exécuter le cron. Le jeton n’est pas nécessaire quand le cron est lancé depuis la ligne de commande du serveur.

Désactiver l’autocomplétion du mot de passe

Les données saisies dans ces champs seront mises en cache par le navigateur. Un attaquant qui a accès au navigateur de la victime pourrait subtiliser ces informations. Ceci est particulièrement important si l’application est utilisée habituellement depuis des ordinateurs partagés tels que des cybercafés ou des terminaux d’aéroports. Si vous désactivez ceci, les outils de gestion des mots de passe ne pourront plus renseigner automatiquement ces champs. Le support pour l’attribut « autocomplete » peut dépendre des navigateurs.

Le changement d’adresse e-mail requiert le mot de passe

Quand un utilisateur souhaite changer l’adresse e-mail associée à son compte, il doit également donner son mot de passe actuel.

Le changement d’adresse e-mail nécessite une confirmation

Lorsqu’un utilisateur souhaite modifier l’adresse e-mail associée à son compte, il doit confirmer la nouvelle adresse e-mail. Cela se fait en envoyant un e-mail à la nouvelle adresse avec un lien de validation. Après avoir cliqué sur ce lien, la nouvelle adresse e-mail sera utilisée.

Icônes liées à la session

Les icônes d’entité peuvent être liées par défaut à une session. Cela signifie que les URL générées contiennent également des informations sur la session en cours. Le fait d’avoir des icônes liées à la session rend les URLs des icônes non partageables entre les sessions. L’effet secondaire est que la mise en cache de ces URL ne bénéficiera qu’à la session active.

Notification aux administrateurs du site

Quand un nouvel administrateur de site est ajouté ou quand un administrateur du site est retiré tous les administrateurs du site reçoivent une notification à ce sujet.

Notifications à l’utilisateur

Administrateur du site

Quand le rôle d’administrateur du site est ajouté ou retiré à un compte, envoie une notification à l’utilisateur dont le compte est concerné.

Bannir (ou réintégrer)

Quand le compte d’un utilisateur est banni ou réintégré, permet à l’utilisateur concerné d’être informé de cette action.

Longueur minimale de l’identifiant

Vous pouvez configurer la longueur minimale de l’identifiant lors de l’inscription d’un utilisateur.

Exigences minimales en matière de mot de passe

Vous pouvez configurer plusieurs exigences pour les nouveaux mots de passe des utilisateurs

• longueur : le mot de passe doit comporter au moins x caractères

• minuscule : nombre minimal de caractères minuscules (a-z) dans le mot de passe

• majuscule : nombre minimal de caractères majuscules (A-Z) dans le mot de passe

• nombres : nombre minimal de nombres (0-9) dans le mot de passe

• specials : nombre minimal de caractères spéciaux (comme !@#$%^&*(), etc.) dans le mot de passe

Sécurisation de l’accès aux fichiers via .htaccess

Dans le fichier .htaccess, un ensemble de règles de durcissement de l’accès aux fichiers a été ajouté pour empêcher l’accès direct aux fichiers dans certains dossiers. L’activation de ces règles ne devrait pas causer des problèmes lorsque tous les plugins que vous utilisez suivent les directives de codage Elgg.

Voici quelques exemples de règles :

• le dossier vendor. Ce dossier contient uniquement des bibliothèques que Elgg utilise et il n’est pas nécessaire d’accéder directement à ce dossier. Toutes les dépendances requises sont chargées depuis Elgg

• le dossier languages. Ce dossier contient les principaux fichiers linguistiques de Elgg. Ces fichiers sont chargés à partir de Elgg

Validation des utilisateurs

Les plugins peuvent influencer la manière dont les utilisateurs sont validés avant de pouvoir utiliser le site.

Liste des utilisateurs non validés

Dans la section Admin du site vous trouverez une liste des utilisateurs non validés. Plusieurs actions peuvent être effectuées sur les utilisateurs, telles que les supprimer du système ou les valider.

Les plugins ont la possibilité d’ajouter de nouvelles fonctionnalités à cette liste.

Voir aussi

Un exemple de ceci est le plugin Validation des comptes utilisateur via l’e-mail qui ne permet pas aux utilisateurs de se connecter sur le site tant que leur adresse e-mail n’est pas validée.

Exiger la validation de l’administrateur

Dans les paramètres du site sous la section Utilisateurs, il existe un paramètre qui peut être activé pour exiger la validation par l’administrateur d’un nouveau compte utilisateur avant que celui-ci puisse utiliser son compte. Après l’inscription, l’utilisateur est informé que son compte est en attente de validation par un administrateur.

Les administrateurs de site peuvent recevoir une notification par e-mail indiquant qu’il y a des utilisateurs en attente de validation.

Après validation, l’utilisateur est notifié qu’il peut utiliser son compte.

Spam

Gardez le spam sous contrôle.

Le spam est un problème très commun que les administrateurs doivent traiter et que nous visons à améliorer dans le noyau, mais il existe quelques mesures que les administrateurs de site peuvent prendre pour atténuer le problème.

Installez un plugin anti-spam

Il y en a plusieurs disponibles dans la communauté

http://community.elgg.org/plugins/search?f[c][]=spam&sb=Search

Modifier l’url d’inscription

Certaines personnes ont dit avoir obtenu de bons résultats en changeant l’URL d’inscription, puisque les spammeurs sont des bots naïfs qui ne peuvent plus trouver où créer les faux comptes.

Désactiver l’inscription libre

Si le flux d’inscriptions est assez faible, vous pouvez vérifier tous les utilisateurs qui s’inscrivent pour conserver une qualité d’interaction élevée.

Contribuer aux mesures anti-spam dans le noyau

https://github.com/Elgg/Elgg/issues?labels=spam&state=open

Guides de développement

Personnalisez le comportement de Elgg avec des plugins.

Ne modifiez pas le cœur

Avertissement

De manière générale, vous ne devriez pas modifier de fichier autre que ceux de configuration fournis avec des logiciels tiers comme Elgg.

Le meilleur moyen de personnaliser le comportement de Elgg est d” installer Elgg en tant que dépendance composer et d’utiliser un plugin pour conserver les modifications spécifiques de votre application, et modifier le comportement à travers la riche API plugin de Elgg.

Si vous souhaitez partager des personnalisations entre les sites ou même publier vos modifications en tant que package réutilisable pour la communauté, créez un plugin qui utilise la même API de plugin et la même structure de fichiers.

Cela rend difficile d’obtenir de l’aide

Lorsque vous ne partagez pas la même base de code que tout le monde, il est impossible pour les autres de savoir ce qui se passe dans votre système et si vos modifications sont à blâmer. Cela peut frustrer ceux qui offrent de l’aide parce que cela complique considérablement le processus de soutien.

Cela rend la mise à niveau délicate et potentiellement désastreuse

Vous voudrez certainement ou aurez besoin de mettre à niveau Elgg pour profiter de

• patchs de sécurité

• nouvelles fonctionnalités

• nouvelles APIs de plugin

• nouvelles améliorations de la stabilité

• amélioration des performances

Si vous avez modifié des fichiers du noyau, alors vous devez être très prudent lors de la mise à niveau afin que vos modifications ne soient pas remplacées et qu’elles soient compatibles avec le nouveau code de Elgg. Si vos modifications sont perdues ou incompatibles, la mise à niveau peut supprimer les fonctionnalités que vous avez ajoutées et même casser complètement votre site.

Cela peut également être une pente glissante. Beaucoup de modifications peuvent vous conduire à un processus de mise à niveau si complexe qu’il en devient pratiquement impossible. Il existe beaucoup de sites coincés avec d’anciennes versions du logiciel à cause du choix de cette voie.

Cela peut casser des plugins

Vous pourriez ne réaliser que beaucoup plus tard que votre « solution rapide » a cassé des fonctionnalités apparemment sans rapport dont les plugins dépendaient.

Résumé

• Résistez à la tentation

  L’édition des fichiers existants est rapide et facile, mais cela compromet fortement la maintenance, la sécurité et la stabilité de votre site.

• Lorsque vous recevez des conseils, considérez si la personne qui vous dit de modifier le noyau sera là pour vous sauver si vous rencontrez des ennuis plus tard !

• Appliquez ces principes aux logiciels en général.

  Si vous pouvez l’éviter, ne modifiez pas non plus les plugins tiers, pour les mêmes raisons : les auteurs de plugin publient également de nouvelles versions, et vous voudrez pouvoir utiliser ces mises à jour.

Listes de Contrôle d’Accès

Une Liste de Contrôle d’Accès (ACL - Access Control Lists) permet d’octroyer à un ou plusieurs utilisateurs l’accès à une entité ou à une annotation dans la base de données.

Voir aussi

Database Access Control

Créer une ACL

Une collection d’accès peut être créée en utilisant la fonction elgg_create_access_collection().

$owner_guid = elgg_get_logged_in_user_guid();

$acl = elgg_create_access_collection("Sample name", $owner_guid, 'collection_subtype');

Sous-types d’ACL

Les ACLs peuvent avoir un sous-type, ceci permet de différencier différents usages de l’ACL. Il est fortement recommandé de définir un sous-type pour une ACL.

Le noyau de Elgg a trois exemples d’usage de sous-types

• group_acl une ACL qui appartient à un ElggGroup qui donne aux membres du groupe l’accès aux contenus partagés dans le groupe

• friends une ACL détenue par un ElggUser qui donne aux contacts de l’utilisateur l’accès aux contenus partagés avec les contacts

• friends_collection une ACL qui appartient à un ElggUser qui donne à des contacts spécifiques l’accès aux contenus partagés avec cette ACL

Ajouter des membres à une ACL

Si vous avez une ACL vous devez encore lui ajouter des utilisateurs pour donner accès à ces utilisateurs au contenu avec l”access_id de l’ACL id.

// creating an ACL
$owner_guid = elgg_get_logged_in_user_guid();

/* @var $acl ElggAccessCollection */
$acl = elgg_create_access_collection("Sample name", $owner_guid, 'collection_subtype');

// add user
$acl->addMember($some_other_user_guid);

Retirer des membres d’une ACL

Si vous souhaitez ne plus donner l’accès à un utilisateur donné dans une ACL, vous pouvez facilement retirer cet utilisateur de la liste.

// remove a user from an ACL
/* @var $acl ElggAccessCollection */
$acl = elgg_get_access_collection($acl_id);

$acl->removeMember(user_guid_to_be_removed);

Récupérer une ACL

Afin de gérer une ACL, ou ajouter l’ID d’une ACL à une liste d’accès il existe plusieurs fonctions disponibles pour récupérer une ACL depuis la base de données.

// get ACL based on known id
$acl = elgg_get_access_collection($acl_id);

// get all ACLs of an owner (procedural style)
$acls = elgg_get_access_collections([
        'owner_guid' => $some_owner_guid,
]);

// get all ACLs of an owner (object oriented style)
$acls = $some_owner_entity->getOwnedAccessCollections();

// add a filter for ACL subtype
// get all ACLs of an owner (procedural style)
$acls = elgg_get_access_collections([
        'owner_guid' => $some_owner_guid,
        'subtype' => 'some_subtype',
]);

// get all ACLs of an owner (object oriented style)
$acls = $some_owner_entity->getOwnedAccessCollections([
        'subtype' => 'some_subtype',
]);

// get one ACL of an owner (object oriented style)
// for example the group_acl of an ElggGroup
// Returns the first ACL owned by the entity with a given subtype
$acl = $group_entity->getOwnedAccessCollection('group_acl');

Accès en lecture

Le système d’accès de Elgg ajoute automatiquement toutes les ACL dont un utilisateur est membre aux contrôles d’accès. Par exemple, si un utilisateur est membre d’un groupe et est en contact avec 3 autres utilisateurs, toutes les ACL correspondantes sont ajoutées afin de vérifier l’accès aux entités lors de leur récupération (par exemple, la liste de tous les articles de blog).

Ignorer l’accès

Si dans certains cas vous avez besoin d’entités récupérées en ignorant les règles d’accès, vous pouvez envelopper votre code dans elgg_call. Il existe différents drapeaux que vous pouvez utiliser.

• ELGG_IGNORE_ACCESS : aucune règle d’accès n’est appliquée

• ELGG_ENFORCE_ACCESS : les règles d’accès sont forcées à être appliquées

• ELGG_SHOW_DISABLED_ENTITIES : récupérera les entités désactivées

• ELGG_HIDE_DISABLED_ENTITIES : ne récupérera jamais les entités désactivées

$options = [
        'type' => 'user'
];

$entities = elgg_call(ELGG_IGNORE_ACCESS, function() use ($options) {
        return elgg_get_entities($options);
});

Vous pouvez également combiner des drapeaux.

$entities = elgg_call(ELGG_IGNORE_ACCESS | ELGG_SHOW_DISABLED_ENTITIES, function() {
        return elgg_get_entities([
                'type' => 'user'
        ]);
});

Accessibilité

Cette page a pour but d’énumérer et de documenter les règles d’accessibilité et les meilleures pratiques pour aider les développeur du noyau et des plugins à faire de Elgg le meilleur framework applicatif de moteur social dont tout le monde rêve.

Note

Il s’agit d’un travail en cours, veuillez contribuer sur Github si vous avez des compétences dans ce domaine !

Ressources + références

• Aperçu des guides d’accessibilité officiels WCAG

• Guides d’accessibilité officiels WCAG

• Ressources pour planifier et implémenter l’accessibilité

• Astuces pratiques du W3C pour améliorer l’accessibilité

• Tests et vérifications préliminaires pour évaluer l’accessibilité d’un site

• Outils pour vérifier l’accessibilité des sites web

• Liste de techniques pratiques pour implémenter l’accessibilité (Ce serait génial si quelqu’un pouvait les examiner et filtrer celles qui sont pertinentes pour Elgg)

Astuces pour implémenter l’accessibilité

• Tous les tickets relatifs à l’accessibilité devraient être tagués avec « a11y », raccourci pour accessibilité - « accessibility »

• Utilisez les vues du noyau telles que output/*, et input/* pour générer le balisage, dans la mesure où nous pouvons intégrer les règles d’accessibilité dans ces vues

• Toutes les images doivent avoir un attribut descriptif alt. Les graphiques d’espacement ou purement décoratifs doivent avoir un attribut alt vide

• Toutes les balises <a> doivent avoir du texte ou une image accessible à l’intérieur. Sinon, les lecteurs d’écran devront lire l’URL, ce qui est une mauvaise expérience. Les balises <a> devraient contenir du texte descriptif, si possible, par opposition a un texte générique comme « Cliquez ici »

• Le balisage devrait être valide

• Les thèmes de doivent pas réinitialiser « outline » à rien. :focus mérite un traitement visuel spécial afin que les utilisateurs handicapés puissent savoir où ils se trouvent

Astuces pour tester l’accessibilité

• Utilisez les outils disponibles à partir de la section ressources. Exemple de rapport pour community.elgg.org du 16 juin 2012

• Essayez différentes configurations de taille de police et de zoom dans votre navigateur pour être sûr que votre thème reste utilisable

• Désactivez css pour vous assurer que l’ordre séquentiel de la page est logique

Objectifs et principes de la documentation

• Principales règles d’accessibilité

• collecter et documenter les bonnes pratiques

• Fournir des exemples de code

• Conserver le document simple et utilisable

• Le rendre utilisable à la fois pour les développeurs débutants et les experts (des changements les plus courants et les plus faciles aux techniques élaborées)

Formulaires + Actions

Créer, mettre à jour, ou supprimer du contenu.

Les formulaires Elgg sont envoyés aux actions. Les actions définissent le comportement pour l’envoi des formulaires.

Ce guide suppose une familiarité de base avec :

• Plugins

• Vues

• Internationalisation

Enregistrer des actions

Les actions doivent être enregistrées avant de pouvoir être utilisées.

Il existe deux manières d’enregistrer des actions :

Utiliser elgg_register_action()

elgg_register_action("example", __DIR__ . "/actions/example.php");

Le fichier de script mod/example/actions/example.php sera maintenant utilisé à chaque fois qu’un formulaire est envoyé vers http://localhost/elgg/action/example.

Utilisez elgg-plugin.php

return [
   'actions' => [
      // defaults to using an action file in /actions/myplugin/action_a.php
      'myplugin/action_a' => [
         'access' => 'public',
      ],

      // define custom action path
      'myplugin/action_b' => [
         'access' => 'admin',
         'filename' => __DIR__ . '/actions/action.php'
      ],

      // define a controller
      'myplugin/action_c' => [
         'controller' => \MyPlugin\Actions\ActionC::class,
      ],
   ],
];

Avertissement

Un point d’achoppement pour de nombreux nouveaux développeurs est l’URL pour les actions. L’URL utilise toujours /action/ (singulier) et jamais /actions/ (pluriel). Toutefois, les fichiers de script d’action sont généralement enregistrés dans le répertoire /actions/ (pluriel) et ont toujours une extension. Utilisez elgg_generate_action_url() pour éviter toute confusion.

Enregistrement des actions en utilisant le fichier de configuration du plugin

Vous pouvez également enregistrer des actions via le fichier de configuration elgg-plugin. Pour cela vous devez fournir une section action dans le fichier de configuration. L’emplacement des fichiers d’action est situé dans le dossier /actions du plugin.

<?php

return [
        'actions' => [
            'blog/save' => [], // all defaults
            'blog/delete' => [ // all custom
                  'access' => 'admin',
                  'filename' => __DIR__ . 'actions/blog/remove.php',
            ],
        ],
];

Permissions

Par défaut, les actions ne sont accessibles qu’aux utilisateurs connectés.

Pour qu’une action soit disponible pour des utilisateurs non identifiés, passez "public" comme troisième argument :

elgg_register_action("example", $filepath, "public");

Pour restreindre l’action aux seuls administrateurs, passez "admin" en dernier paramètre :

elgg_register_action("example", $filepath, "admin");

Pour restreindre une action aux seuls utilisateurs non-connectés, passez "logged_out" en dernier paramètre :

elgg_register_action("example", $filepath, "logged_out");

Écrire des fichiers d’action

Utilisez la fonction get_input() pour accéder aux paramètres de la requête :

$field = get_input('input_field_name', 'default_value');

Vous pouvez ensuite utiliser l’api de la Base de données pour charger des entités et effectuer des actions dessus.

Pour indiquer une action réussie, utilisez elgg_ok_response(). Cette fonction accepte comme paramètre les données que vous souhaitez mettre à la disposition du client pour les appels XHR (ces données seront ignorées pour les appels non XHR)

$user = get_entity($guid);
// do something

$action_data = [
   'entity' => $user,
   'stats' => [
       'friends_count' => $user->getEntitiesFromRelationship([
           'type' => 'user',
           'relationship' => 'friend',
           'count' => true,
       ]);
   ],
];

return elgg_ok_response($action_data, 'Action was successful', 'url/to/forward/to');

Pour indiquer une erreur utilisez elgg_error_response()

$user = elgg_get_logged_in_user_entity();
if (!$user) {
   // show an error and forward the user to the referring page
   // send 404 error code on AJAX calls
   return elgg_error_response('User not found', REFERRER, ELGG_HTTP_NOT_FOUND);
}

if (!$user->canEdit()) {
   // show an error and forward to user's profile
   // send 403 error code on AJAX calls
   return elgg_error_response('You are not allowed to perform this action', $user->getURL(), ELGG_HTTP_FORBIDDEN);
}

Personnaliser des actions

Avant d’exécuter chaque action, Elgg déclenche un événement :

$result = elgg_trigger_event_results('action:validate', $action, [], true);

Où $action est l’action appelée. Si l’événement renvoie false alors l’action ne sera pas exécutée. Ne renvoyez rien si votre validation réussit.

Exemple : Captcha

Le module captcha utilise ceci pour intercepter les actions register et user/requestnewpassword et les rediriger vers une fonction qui vérifie le code captcha. Cette vérification renvoie false si la validation captcha échoue (ce qui bloque l’exécution de l’action associée).

Ceci est fait comme suit :

elgg_register_event_handler("action:validate", "register", "captcha_verify_action_event");
elgg_register_event_handler("action:validate", "user/requestnewpassword", "captcha_verify_action_event");

...

function captcha_verify_action_event(\Elgg\Event $event) {
  $token = get_input('captcha_token');
  $input = get_input('captcha_input');

  if (($token) && (captcha_verify_captcha($input, $token))) {
    return;
  }

  elgg_register_error_message(elgg_echo('captcha:captchafail'));

  return false;
}

Cela permet à un plugin d’étendre une action existante sans qu’il soit nécessaire de remplacer l’ensemble de l’action. Dans le cas du plugin captcha, cela permet de proposer un support captcha couplé de façon souple.

Actions disponibles dans le noyau

entity/delete

Si votre plugin n’implémente aucune logique personnalisée lors de la suppression d’une entité, vous pouvez utiliser l’action de suppression intégrée

$guid = 123;
// You can provide optional forward path as a URL query parameter
$forward_url = 'path/to/forward/to';
echo elgg_view('output/url', array(
   'text' => elgg_echo('delete'),
   'href' => elgg_generate_action_url('entity/delete', [
     'guid' => $guid,
     'forward_url' => $forward_url,
   ]),
   'confirm' => true,
));

Vous pouvez personnaliser les clefs du message de succès pour votre type d’entité et votre sous-type, en utilisant les clefs `"entity:delete:$type:$subtype:success" et "entity:delete:$type:success".

// to add a custom message when a blog post or file is deleted
// add the translations keys in your language files
return [
   'entity:delete:object:blog:success' => 'Blog post has been deleted,
   'entity:delete:object:file:success' => 'File titled %s has been deleted',
];

Formulaires

Pour afficher un formulaire, utilisez la fonction elgg_view_form comme ceci :

echo elgg_view_form('example');

Faire ceci génère quelque chose comme le balisage suivant :

<form action="http://localhost/elgg/action/example">
  <fieldset>
    <input type="hidden" name="__elgg_ts" value="1234567890" />
    <input type="hidden" name="__elgg_token" value="3874acfc283d90e34" />
  </fieldset>
</form>

Elgg fait automatiquement plusieurs choses pour vous quand vous générez un formulaire de cette manière :

1. Il définit l’action vers l’URL appropriée, sur la base du nom de l’action que vous lui avez passé

2. Il ajoute des jetons anti-csrf (__elgg_ts et __elgg_token) pour aider à garder vos actions sûres

3. Il recherche automatiquement le corps du formulaire dans la vue forms/example.

Ajoutez le contenu de votre formulaire dans la vue forms/example de votre plugin :

// /mod/example/views/default/forms/example.php
echo elgg_view('input/text', array('name' => 'example'));

// defer form footer rendering
// this will allow other plugins to extend forms/example view
elgg_set_form_footer(elgg_view('input/submit'));

Désormais quand vous appelez elgg_view_form('example'), Elgg va produire :

<form action="http://localhost/elgg/action/example">
  <fieldset>
    <input type="hidden" name="__elgg_ts" value="...">
    <input type="hidden" name="__elgg_token" value="...">

    <input type="text" class="elgg-input-text" name="example">
    <div class="elgg-foot elgg-form-footer">
        <input type="submit" class="elgg-button elgg-button-submit" value="Submit">
    </div>
  </fieldset>
</form>

Entrées

Pour rendre une entrée de formulaire, utilisez l’une des vues d’entrée intégrées, qui couvrent tous les éléments d’entrée HTML standard. Voyez les fichiers individuels des vues pour une liste complète des paramètres acceptés.

echo elgg_view('input/select', array(
   'required' => true,
   'name' => 'status',
   'options_values' => [
      'draft' => elgg_echo('status:draft'),
      'published' => elgg_echo('status:published'),
   ],
   // most input views will render additional parameters passed to the view
   // as tag attributes
   'data-rel' => 'blog',
));

L’exemple ci-dessus va afficher une liste déroulante :

<select required="required" name="status" data-rel="blog" class="elgg-input-select">
   <option value="draft">Draft</option>
   <option value="published">Published</option>
</select>

Pour assurer la cohérence du balisage du champ, utilisez elgg_view_field(), qui accepte tous les paramètres de l’entrée à afficher, ainsi que les paramètres #label et #help (qui sont tous deux facultatifs et acceptent du HTML ou du texte).

echo elgg_view_field([
   '#type' => 'select',
   '#label' => elgg_echo('blog:status:label'),
   '#help' => elgg_view_icon('help') . elgg_echo('blog:status:help'),
   'required' => true,
   'name' => 'status',
   'options_values' => [
      'draft' => elgg_echo('status:draft'),
      'published' => elgg_echo('status:published'),
   ],
   'data-rel' => 'blog',
]);

Ce qui précède générera le balisage suivant :

<div class="elgg-field elgg-field-required">
   <label for="elgg-field-1" class="elgg-field-label">Blog status<span title="Required" class="elgg-required-indicator">*</span></label>
   <div class="elgg-field-input">
      <select required="required" name="status" data-rel="blog" id="elgg-field-1" class="elgg-input-select">
         <option value="draft">Draft</option>
         <option value="published">Published</option>
      </select>
   </div>
   <div class="elgg-field-help elgg-text-help">
      <span class="elgg-icon-help elgg-icon"></span>This indicates whether or not the blog is visible in the feed
   </div>
</div>

Types d’entrées

Une liste des types/vues de saisie inclus :

• input/text - afficher une entrée texte <input type="text">

• input/plaintext - affiche une zone de texte brut <textarea></textarea>

• input/longtext - affiche une zone de texte riche - avec éditeur WYSIWYG

• input/url - affiche une entrée d’adresse web - URL <input type="url">

• input/email - affiche un champ de saisie de type e-mail <input type="email">

• input/checkbox - affiche une case à cocher <input type="checkbox">

• input/checkboxes - affiche un jeu de cases à cocher portant le même nom

• input/radio - affiche un ou plusieurs bouton radio <input type="radio">

• input/submit - affiche un bouton d’envoi <button type="submit">

• input/button - affiche un bouton <button></button>

• input/file - affiche un sélecteur de fichier <input type="file">

• input/select - affiche une liste déroulante <select></select>

• input/hidden - affiche une entrée invisible <input type="hidden">

• input/password - affiche une entrée de type mot de passe <input type="password">

• input/number - affiche une entrée de type nombre <input type="number">

• input/date - affiche un sélecteur de date jQuery

Elgg offre quelques types de saisies facilitées

• input/access - affiche une liste de niveaux d’accès Elgg

• input/tags - affiche une entrée de type tags

• input/autocomplete - affiche un sélecteur d’entités Elgg

• input/captcha - vue destinée à être étendue par des plugins

• input/friendspicker - affiche un sélecteur de contact Elgg par autocomplétion

• input/userpicker - affiche un sélecteur d’utilisateur Elgg avec autocomplétion

• input/grouppicker - affiche un sélecteur de groupe Elgg par autocomplétion

• input/objectpicker - affiche un sélecteur d’objet Elgg par autocomplétion

• input/location affiche une entrée de type adresse

Fichiers et images

Utilisez la vue input/file dans la vue du contenu de votre formulaire.

// /mod/example/views/default/forms/example.php
echo elgg_view('input/file', ['name' => 'icon']);

Si vous souhaitez télécharger une icône pour l’entité, vous pouvez utiliser la vue entity/edit/icon. Cette vue affiche une entrée de fichier pour le téléchargement d’une nouvelle icône pour l’entité, une miniature de l’icône actuelle et l’option de supprimer l’icône actuelle.

La vue prend en charge quelques variables pour contrôler la sortie

• entity - l’entité pour laquelle ajouter ou supprimer l’icône. Si elle est fournie, la miniature et l’option de suppression s’affichent en fonction de cette entité

• entity_type - le type d’entité pour lequel l’icône sera téléchargée. Des plugins pourraient trouver cela utile, peut-être pour valider les dimensions d’icônes

• entity_subtype - le sous-type d’entité pour lequel l’icône sera téléchargée. Des plugins pourraient trouver cela utile, peut-être pour valider les dimensions d’icônes

• icon_type - le type de l’icône (par défaut : icon)

• name - le nom du champ input/file (par défaut : icon)

• remove_name - nom de la bascule de suppression de l’icône (par défaut : $vars[“name”] . “_remove”)

• required - est-ce que le téléchargement d’une icône est requis (par défaut : false)

• cropper_enabled - le recadrage des icônes est-il autorisé (par défaut : true)

• show_remove - affiche l’option pour supprimer l’icône (par défaut : true)

• show_thumb - afficher la miniature de l’entité si elle est disponible (par défaut : true)

• thumb_size - la taille de l’icône à utiliser pour la miniature (par défaut : medium)

Si vous utilisez la vue, vous pouvez utiliser le code suivant dans votre action pour enregistrer l’icône dans l’entité ou supprimer l’icône actuelle.

if (get_input('icon_remove')) {
   $entity->deleteIcon();
} else {
   $entity->saveIconFromUploadedFile('icon');
}

Définissez le type d’encodage du formulaire sur multipart/form-data :

echo elgg_view_form('example', array(
  'enctype' => 'multipart/form-data'
));

Note

Le type d’encodage enctype de tous les formulaires qui utilisent la méthode POST est par défaut multipart/form-data.

Dans votre fichier d’action, utilisez elgg_get_uploaded_file('nom-de-votre-input') pour accéder au fichier téléchargé :

$icon = elgg_get_uploaded_file('icon');

Formulaires persistants

Les formulaires persistants sont des formulaires qui conservent les entrées de l’utilisateur en cas d’échec de l’enregistrement. Ils sont « persistants » parce que les données de l’utilisateur « persistent » dans le formulaire après soumission, bien qu’elles n’aient jamais été enregistrées dans la base de données. Cela améliore considérablement l’expérience utilisateur en minimisant la perte de données. Elgg inclut des fonctions d’assistance afin que vous puissiez rendre n’importe quel formulaire persistant.

Fonctions d’assistance

Les formulaires persistants sont implémentés dans Elgg par les fonctions suivantes :

• elgg_make_sticky_form($name) - Indique au moteur de persister les valeurs de toutes les entrées d’un formulaire.

• elgg_clear_sticky_form($name) - Indique au moteur de supprimer toutes les valeurs d’un formulaire.

• elgg_is_sticky_form($name) - Vérifie si $name est un formulaire persistant valide.

• elgg_get_sticky_values($name) - Renvoie toutes les valeurs persistantes enregistrées pour $name par elgg_make_sticky_form($name).

Aperçu

Le déroulement de l’utilisation des formulaires persistants est :

1. Appelez elgg_make_sticky_form($name) au début des actions des formulaires que vous voulez rendre persistants.

2. Utilisez elgg_is_sticky_form($name) et elgg_get_sticky_values($name) pour obtenir des valeurs persistantes lors du rendu d’une vue de formulaire.

3. Appelez elgg_clear_sticky_form($name) une fois l’action terminée avec succès ou après que les données ont été chargées par elgg_get_sticky_values($name).

Note

Depuis Elgg 5.0, les formulaires rendus avec elgg_view_form() peuvent définir l’indicateur $form_vars['sticky_enabled'] = true pour obtenir automatiquement la prise en charge des formulaires persistants. Les valeurs soumises à l’action seront automatiquement renseignées dans $body_vars lorsqu’une erreur survient dans l’action.

elgg_view_form() prend en charge les $form_vars suivants pour faciliter la prise en charge des formulaires persistants :

• sticky_enabled : un bool pour activer la prise en charge automatique de formulaire persistant

• sticky_form_name : une string facultative pour définir l’endroit où les valeurs du formulaire collant sont enregistrées. La valeur par défaut est $action_name et ne doit être modifiée que si $action_name est différent de l’action réelle

• sticky_ignored_fields: an array with the names fo the form fields that should be saved. For example password fields

Exemple : Inscription d’un utilisateur

Les formulaires persistants simples nécessitent peu de logique pour déterminer les valeurs d’entrée du formulaire. Cette logique est placée en haut de la vue du corps de formulaire.

L’affichage du formulaire d’inscription définit d’abord les valeurs par défaut pour les entrées, puis vérifie s’il y a des valeurs persistantes. Si c’est le cas, il charge les valeurs persistantes avant de supprimer le formulaire persistant :

// views/default/forms/register.php
$password = $password2 = '';
$username = get_input('u');
$email = get_input('e');
$name = get_input('n');

if (elgg_is_sticky_form('register')) {
   extract(elgg_get_sticky_values('register'));
   elgg_clear_sticky_form('register');
}

Les ensembles d’action d’inscription créent le formulaire persistant et l’effacent une fois l’action terminée :

// actions/register.php
elgg_make_sticky_form('register', ['password', 'password2']);

elgg_register_user([
   'username' => $username,
   'password' => $password,
   'name' => $name,
   'email' => $email,
]);

elgg_clear_sticky_form('register');

Astuce

La fonction elgg_make_sticky_form() supporte un second argument optionnel $ignored_field_names. Cela doit être un array des noms de champs que vous ne souhaitez pas rendre persistants. Ceci est utile pour les champs qui contiennent des données sensibles, comme les mots de passe.

Exemple : Signets - Bookmarks

Le formulaire et l’action d’enregistrement du plugin « Bookmarks » inclus est un exemple de formulaire persistant complexe.

La vue du formulaire pour l’action d’enregistrement d’un signet utilise elgg_extract() pour extraire des valeurs du tableau $vars :

// mod/bookmarks/views/default/forms/bookmarks/save.php
$title = elgg_extract('title', $vars, '');
$desc = elgg_extract('description', $vars, '');
$address = elgg_extract('address', $vars, '');
$tags = elgg_extract('tags', $vars, '');
$access_id = elgg_extract('access_id', $vars, ACCESS_DEFAULT);
$container_guid = elgg_extract('container_guid', $vars);
$guid = elgg_extract('guid', $vars, null);
$shares = elgg_extract('shares', $vars, array());

Les scripts du gestionnaire de page activent le support des formulaires persistants en passant les valeurs correctes à elgg_view_form() :

// mod/bookmarks/pages/add.php
$content = elgg_view_form('bookmarks/save', ['sticky_enabled' => true]);

De même, mod/bookmarks/pages/edit.php utilise le même support persistant, mais transmet l’entité qui est en cours d’édition :

$bookmark_guid = get_input('guid');
$bookmark = get_entity($bookmark_guid);

...

$content = elgg_view_form('bookmarks/save', ['sticky_enabled' => true], ['entity' => $bookmark]);

Le plugin a un écouteur d’événement sur l’événement 'form:prepare:fields', 'bookmarks/save' et le gestionnaire fait 2 choses :

1. Définit les noms et les valeurs par défaut pour les champs de formulaire.

2. Extrait les valeurs d’un objet bookmark s’il est passé.

// mod/bookmarks/classes/Elgg/Bookmarks/Forms/PrepareFields.php
/**
      * Prepare the fields for the bookmarks/save form
      *
      * @since 5.0
      */
     class PrepareFields {

             /**
              * Prepare fields
              *
              * @param \Elgg\Event $event 'form:prepare:fields', 'bookmarks/save'
              *
              * @return array|null
              */
             public function __invoke(\Elgg\Event $event): ?array {
                     $vars = $event->getValue();

                     // input names => defaults
                     $values = [
                             'title' => get_input('title', ''), // bookmarklet support
                             'address' => get_input('address', ''),
                             'description' => '',
                             'access_id' => ACCESS_DEFAULT,
                             'tags' => '',
                             'container_guid' => elgg_get_page_owner_guid(),
                             'guid' => null,
                     ];

                     $bookmark = elgg_extract('entity', $vars);
                     if ($bookmark instanceof \ElggBookmark) {
                             // load current bookmark values
                             foreach (array_keys($values) as $field) {
                                     if (isset($bookmark->$field)) {
                                             $values[$field] = $bookmark->$field;
                                     }
                             }
                     }

                     return array_merge($vars, $values);
             }
     }

L’action de sauvegarde n’a pas besoin de faire quoi que ce soit avec la prise en charge des formulaires persistants car tout est géré par le système.

Ajax

Voir le guide Ajax pour savoir comment appeler les actions depuis JavaScript.

Sécurité

Pour une sécurité renforcée, toutes les actions nécessitent un jeton CSRF. Les appels aux URLs d’action qui n’incluent pas les jetons de sécurité seront ignorés et un avertissement sera généré.

Quelques vues et fonctions génèrent automatiquement des jetons de sécurité :

elgg_view('output/url', array('is_action' => true));
elgg_view('input/securitytoken');
$url = elgg_add_action_tokens_to_url("http://localhost/elgg/action/example");
$url = elgg_generate_action_url('myplugin/myaction');

Dans de rares cas, vous devrez peut-être générer des jetons manuellement :

$__elgg_ts = elgg()->csrf->getCurrentTime()->getTimestamp();
$__elgg_token = elgg()->csrf->generateActionToken($__elgg_ts);

Vous pouvez aussi accéder aux jetons depuis JavaScript :

elgg.security.token.__elgg_ts;
elgg.security.token.__elgg_token;

Ces jetonsci sont rafraîchis périodiquement aussi ils devraient être à jour.

Jetons de sécurité

À l’occasion, nous devons transmettre des données par l’intermédiaire d’une tierce partie non digne de confiance ou générer un jeton impossible à deviner basé sur certaines données. L’algorithme HMAC est le bon outil pour cela. Il nous permet de vérifier que les données reçues ont été générées par notre site, et n’ont pas été trafiquées. Notez que même les fonctions de hachage fortes comme SHA-2 ne devraient pas être utilisés sans HMAC pour ces tâches.

Elgg fournit elgg_build_hmac() pour générer et valider des codes d’authentification des messages HMAC qui ne puissent pas être devinés sans la clé privée du site.

// generate a querystring such that $a and $b can't be altered
$a = 1234;
$b = "hello";
$query = http_build_query([
    'a' => $a,
    'b' => $b,
    'mac' => elgg_build_hmac([$a, $b])->getToken(),
]);
$url = "action/foo?$query";

// validate the querystring
$a = (int) get_input('a', '', false);
$b = (string) get_input('b', '', false);
$mac = get_input('mac', '', false);

if (elgg_build_hmac([$a, $b])->matchesToken($mac)) {
    // $a and $b have not been altered
}

Remarque : si vous utilisez une non-chaîne comme données HMAC, vous devez utiliser les types de manière cohérente. Considérez ce qui suit :

$mac = elgg_build_hmac([123, 456])->getToken();

// type of first array element differs
elgg_build_hmac(["123", 456])->matchesToken($mac); // false

// types identical to original
elgg_build_hmac([123, 456])->matchesToken($mac); // true

URLs signées

Les URL signées offrent un niveau de sécurité limité pour les situations où les jetons d’action ne conviennent pas, par exemple lors de l’envoi d’un lien de confirmation par e-mail. Les signatures de l’URL vérifient que l’URL a été générée par votre installation Elgg (en utilisant le secret du site) et que les éléments de l’URL de requête n’ont pas été trafiqués.

URLs signées avec une clef SHA-256 HMAC impossible à deviner. Pour plus de détails, consultez Jetons de Sécurité .

$url = elgg_http_add_url_query_element(elgg_normalize_url('confirm'), [
   'user_guid' => $user_guid,
]);

$url = elgg_http_get_signed_url($url);

notify_user($user_guid, $site->guid, 'Confirm', "Please confirm by clicking this link: $url");

Avertissement

Les URL signées n’offrent pas de protection CSRF et ne doivent pas être utilisées à la place des jetons d’action.

Ajax

Le module AMD elgg/Ajax (introduit dans Elgg 2.1) fournit un ensemble de méthodes pour communiquer avec le serveur d’une manière concise et uniforme, ce qui permet aux plugins de collaborer sur les données de requête, la réponse du serveur et les données renvoyées côté client.

Aperçu

Toutes les méthodes ajax effectuent ce qui suit :

1. Côté client, l’option data (si elle est donnée en tant qu’objet) est filtrée par le hook ajax_request_data.

2. La requête est faite au serveur, que ce soit en affichant une vue ou un formulaire, en appelant une action, ou en chargeant un chemin d’accès.

3. La méthode renvoie un objet jqXHR, qui peut être utilisé comme promesse - Promise.

4. Le contenu généré par le serveur est transformé en objet de réponse (Elgg\Services\AjaxResponse) contenant une chaîne (ou une valeur parsée en JSON).

5. L’objet de réponse est filtré par l’événement ajax_response.

6. L’objet de réponse est utilisé pour créer la réponse HTTP.

7. Côté client, les données de réponse sont filtrées par le hook ajax_response_data.

8. La promesse - promise - jqXHR est résolue et toutes les fonctions de rappel success sont appelées.

Plus de notes :

• Tous les hooks ont un type en fonction de la méthode et du premier argument. Voyez ci-dessous.

• Par défaut, le module elgg/spinner est automatiquement utilisé lors des requêtes.

• Les messages utilisateur générés par elgg_register_success_message() et elgg_register_error_message() sont collectés et affichés sur le client.

• Elgg intègre un gestionnaire d’erreurs par défaut qui affiche un message générique en cas d’échec de la sortie.

• Les exceptions PHP ou les codes d’erreur HTTP d’accès refusé, ce qui entraîne l’utilisation du gestionnaire d’erreurs côté client.

• La méthode HTTP par défaut est POST pour les actions, sinon GET. Vous pouvez changer cela via options.method.

• Si une valeur options.data non vide est donnée, la méthode par défaut est toujours POST.

• Pour la mise en cache côté client, définissez la méthode options.method sur GET et options.data.elgg_response_ttl sur l’âge maximal que vous souhaitez en secondes.

• Pour enregistrer des messages système pour le chargement de la page suivante, définissez options.data.elgg_fetch_messages = 0. Vous pourriez vouloir faire cela si vous avez l’intention de rediriger l’utilisateur en fonction de la réponse.

• Pour empêcher l’API côté client d’exiger des modules AMD requis côté serveur avec elgg_require_js(), définissez options.data.elgg_fetch_deps = 0.

• Toutes les méthodes acceptent une chaîne de requête comme premier argument. Cette chaîne est transmise à l’URL de récupération, mais n’apparaît pas dans les types de hooks.

Effectuer des actions

Considérez cette action :

// in myplugin/actions/do_math.php

elgg_ajax_gatekeeper();

$arg1 = (int)get_input('arg1');
$arg2 = (int)get_input('arg2');

// will be rendered client-side
elgg_register_success_message('We did it!');

echo json_encode([
    'sum' => $arg1 + $arg2,
    'product' => $arg1 * $arg2,
]);

Pour l’exécuter, utilisez ajax.action('<action_name>', options) :

var Ajax = require('elgg/Ajax');
var ajax = new Ajax();

ajax.action('do_math', {
    data: {
        arg1: 1,
        arg2: 2
    },
}).done(function (output, statusText, jqXHR) {
    alert(output.sum);
    alert(output.product);
});

Notes pour les actions :

• Tous les hooks ont le type action:<action_name>. Donc, dans ce cas, trois hooks seront déclenchés :

  • côté client "ajax_request_data", "action:do_math" pour filtrer les données de la requête (avant qu’elle soit envoyée)

  • côté serveur "ajax_response", "action:do_math" pour filtrer la réponse (après que l’action a été exécutée)

  • côté client "ajax_response_data", "action:do_math" pour filtrer les données de la réponse (avant que le code appelant ne les reçoive)

• Les jetons CSRF sont ajoutés aux données de la requête.

• La méthode par défaut est POST.

• Une URL d’action absolue peut être donnée à la place du nom d’action.

Note

Lorsque vous définissez data, utilisez ajax.objectify($form) au lieu de $form.serialize(). Cela permet au hook de plugin ajax_request_data d’être déclenché, et à d’autres plugins de modifier / réagir à la requête.

Récupérer des données

Considérez ce script PHP qui s’exécute à http://example.org/myplugin_time.

// in myplugin/elgg-plugin.php
return [
    'routes' => [
        'default:myplugin:time' => [
            'path' => '/myplugin_time',
            'resource' => 'myplugin/time',
        ],
    ],
];

// in myplugin/views/default/resources/myplugin/time.php
elgg_ajax_gatekeeper();

echo json_encode([
    'rfc2822' => date(DATE_RFC2822),
    'day' => date('l'),
]);

return true;

Pour récupérer sa sortie, utilisez ajax.path('<url_path>', options).

var Ajax = require('elgg/Ajax');
var ajax = new Ajax();

ajax.path('myplugin_time').done(function (output, statusText, jqXHR) {
    alert(output.rfc2822);
    alert(output.day);
});

Notes pour les chemins :

• Les 3 hooks (voyez les Actions ci-dessus) auront le type path:<url_path>. Dans ce cas, « path:myplugin_time ».

• Si le gestionnaire de page renvoie une page Web normale, output sera une chaîne contenant le HTML de la page.

• Une URL absolue peut être donnée à la place du nom du chemin.

Récupérer des vues

Considérez cette vue :

// in myplugin/views/default/myplugin/get_link.php

if (empty($vars['entity']) || !$vars['entity'] instanceof ElggObject) {
    return;
}

$object = $vars['entity'];
/* @var ElggObject $object */

echo elgg_view('output/url', [
    'text' => $object->getDisplayName(),
    'href' => $object->getUrl(),
    'is_trusted' => true,
]);

Comme il s’agit d’un fichier PHP, nous devons d’abord l’enregistrer pour Ajax :

// in myplugin_init()
elgg_register_ajax_view('myplugin/get_link');

Pour récupérer la vue, utilisez ajax.view('<view_name>', options) :

var Ajax = require('elgg/Ajax');
var ajax = new Ajax();

ajax.view('myplugin/get_link', {
    data: {
        guid: 123 // querystring
    },
}).done(function (output, statusText, jqXHR) {
    $('.myplugin-link').html(output);
});

Notes pour les vues :

• Les 3 hooks (voyez les Actions ci-dessus) auront le type view:<view_name>. Dans ce cas, « view:myplugin/get_link ».

• output sera une chaîne avec le contenu de la vue générée.

• Les données de la requête sont injectées dans la vue à l’intérieur de $vars.

• Si les données de la requête contiennent guid, le système définit $vars['entity'] à l’entité correspondante ou à false si elle ne peut pas être chargée.

Avertissement

Dans les vues et les formulaires ajax, notez que $vars peut être peuplé par les saisies du client. Les données sont filtrées comme avec get_input(), mais peuvent ne pas avoir le type que vous attendez ou peuvent avoir des clefs inattendues.

Récupérer des formulaires

Considérez que nous avons une vue de formulaire. Nous l’enregistrons pour Ajax :

// in myplugin_init()
elgg_register_ajax_view('forms/myplugin/add');

Pour récupérer ceci utilisez ajax.form('<action_name>', options).

var Ajax = require('elgg/Ajax');
var ajax = new Ajax();

ajax.form('myplugin/add').done(function (output, statusText, jqXHR) {
    $('.myplugin-form-container').html(output);
});

Notes pour les formulaires :

• Les 3 hooks (voir Actions ci-dessus) auront le type form:<action_name>. Dans ce cas, « form:myplugin/add ».

• output sera une chaîne avec le contenu de la vue générée.

• Les données de la requête sont injectées dans $vars dans la vue de votre formulaire.

• Si les données de la requête contiennent guid, le système définit $vars['entity'] à l’entité correspondante ou à false si elle ne peut pas être chargée.

Note

Seules les données de la requête sont transmises à la vue du formulaire demandé (c’est-à-dire en tant que troisième paramètre accepté par elgg_view_form()). Si vous devez transmettre des attributs ou des paramètres de l’élément de formulaire rendus par la vue input/form (c’est-à-dire normalement passés comme deuxième paramètre à elgg_view_form()), utilisez l’événement côté serveur view_vars , input/form.

Avertissement

Dans les vues et les formulaires ajax, notez que $vars peut être peuplé par les saisies du client. Les données sont filtrées comme avec get_input(), mais peuvent ne pas avoir le type que vous attendez ou peuvent avoir des clefs inattendues.

Envoyer des formulaires

Pour envoyer un formulaire avec Ajax, il suffit de passer le paramètre ajax avec des variables de formulaire :

echo elgg_view_form('login', ['ajax' => true]);

Redirections

Utilisez ajax.forward() pour démarrer une animation d’attente - spinner - et rediriger l’utilisateur vers une nouvelle destination.

var Ajax = require('elgg/Ajax');
var ajax = new Ajax();
ajax.forward('/activity');

Réagir - « piggybacking » - lors d’une requête Ajax

Le hook ajax_request_data côté client peut être utilisé pour ajouter ou filtrer les données envoyées par une demande elgg/Ajax.

Supposons que lorsque la vue foo est récupérée, nous voulons également envoyer au serveur quelques données :

// in your boot module
var Ajax = require('elgg/Ajax');
var hooks = require('elgg/hooks');

var ajax = new Ajax();

hooks.register(Ajax.REQUEST_DATA_HOOK, 'view:foo', function (name, type, params, data) {
    // send some data back
    data.bar = 1;
    return data;
});

Ces données peuvent être lues côté serveur via get_input('bar');.

Note

Si les données ont été fournies sous forme de chaîne (par ex. $form.serialize()), les hooks de requête ne sont pas déclenchés.

Note

Le formulaire sera transformé en objet nommé FormData, et le type de contenu de la requête sera déterminé en conséquence.

Réagir à une réponse Ajax

L’événement ajax_response côté serveur peut être utilisé pour ajouter ou filtrer les données de réponse (ou métadonnées).

Disons que lorsque la vue foo est récupérée, nous voulons également envoyer au client quelques données supplémentaires :

use Elgg\Services\AjaxResponse;

function myplugin_append_ajax(\Elgg\Event $event) {

    /* @var $response AjaxResponse */
    $response = $event->getValue();

    // alter the value being returned
    $response->getData()->value .= " hello";

    // send some metadata back. Only client-side "ajax_response" hooks can see this!
    $response->getData()->myplugin_alert = 'Listen to me!';

    return $response;
}

// in myplugin_init()
elgg_register_event_handler(AjaxResponse::RESPONSE_EVENT, 'view:foo', 'myplugin_append_ajax');

Pour capturer les métadonnées renvoyées au client, nous utilisons le hook ajax_response_data côté client :

// in your boot module
var Ajax = require('elgg/Ajax');
var hooks = require('elgg/hooks');

hooks.register(Ajax.RESPONSE_DATA_HOOK, 'view:foo', function (name, type, params, data) {

    // the return value is data.value

    // the rest is metadata

    alert(data.myplugin_alert);

    return data;
});

Note

Seule la valeur data.value est renvoyée à la fonction success, ou disponible via l’interface Deferred.

Note

Elgg utilise ces mêmes hooks pour diffuser des messages système via les réponses elgg/Ajax .

Gérer les erreurs

Les réponses correspondent à l’une de ces trois catégories :

1. Succès HTTP (200) avec un statut 0. Aucun appel elgg_register_error_message() n’a été fait sur le serveur.

2. Succès HTTP (200) avec le statut -1. elgg_register_error_message() a été appelé.

3. Erreur HTTP (4xx/5xx). Par ex. appeler une action avec des jetons expirés, ou une exception sur le serveur. Dans ce cas les fonctions de callback done ne sont pas appelées.

Le premier et le troisième cas sont les plus courants dans le système. Utilisez les callbacks done et fail pour différencier le comportement en cas de succès et d’erreur.

ajax.action('entity/delete?guid=123').done(function (value, statusText, jqXHR) {
    // remove element from the page
}).fail(function() {
    // handle error condition if needed
});

Requérir des modules AMD

Chaque réponse d’un service Ajax contiendra une liste de modules AMD requis côté serveur avec elgg_require_js(). Lorsque les données de réponse sont déballées, ces modules seront chargés de façon asynchrone - les plugins ne doivent pas s’attendre à ce que ces modules soient chargés dans leurs gestionnaires $.done() et $.then() et doivent utiliser require() pour tous les modules dont ils dépendent. En outre, les modules AMD ne doivent pas s’attendre à ce que le DOM ait été modifié par une demande Ajax lorsqu’ils sont chargés - les événements DOM doivent être délégués et les manipulations sur les éléments DOM doivent être retardées jusqu’à ce que toutes les requêtes Ajax aient été résolues.

Authentification

Elgg fournit d’emblée tout ce qui est nécessaire pour authentifier les utilisateurs via le nom d’utilisateur/l’e-mail et le mot de passe, y compris :

• cookie permanent pour une connexion persistante

• logique de réinitialisation de mot de passe

• stockage sécurisé des mots de passe

• déconnexion

• Interfaces utilisateurs - UI - pour accomplir tout ce qui précède

Il ne vous reste plus en tant que développeur qu’à utiliser les fonctions d’authentification intégrées pour sécuriser vos pages et vos actions.

Travailler avec l’utilisateur connecté

Vérifiez si l’utilisateur actuel est connecté avec elgg_is_logged_in() :

if (elgg_is_logged_in()) {
  // do something just for logged-in users
}

Vérifiez si l’utilisateur actuel est un administrateur avec elgg_is_admin_logged_in() :

if (elgg_is_admin_logged_in()) {
  // do something just for admins
}

Récupérez l’utilisateur actuellement connecté avec elgg_get_logged_in_user_entity() :

$user = elgg_get_logged_in_user_entity();

L’objet retourné est un ElggUser de sorte que vous pouvez utiliser toutes les méthodes et propriétés de cette classe pour accéder à des informations sur l’utilisateur. Si l’utilisateur n’est pas connecté, cela vous renvoie null, aussi assurez-vous de vérifier cela en premier.

Gestionnaires d’accès - gatekeepers

Les fonctions de gestion d’accès « gatekeeper » vous permettent de gérer l’exécution du code en appliquant des règles de contrôle d’accès.

Redirigez vers la page d’accueil un utilisateur qui n’est pas connecté avec elgg_gatekeeper() :

elgg_gatekeeper();

echo "Information for logged-in users only";

Redirigez vers la page d’accueil un utilisateur, sauf s’il s’agit d’un administrateur avec elgg_admin_gatekeeper() :

elgg_admin_gatekeeper();

echo "Information for admins only";

Modules d’authentification enfichables - Pluggable Authentication Modules

Elgg est compatible avec des modules d’authentification enfichables (PAM = Pluggable Authentication Modules), qui vous permettent d’écrire vos propres gestionnaires d’authentification. A chaque fois qu’une requête a besoin d’être authentifiée, le système va appeler elgg_pam_authenticate() qui va vérifier tous les gestionnaires de PAM enregistrés jusqu’à-ce que l’un d’entre eux renvoie un succès.

L’approche privilégiée est de créer un plugin Elgg séparé qui aura une tâche simple : traiter une demande d’authentification. Il s’agit de configurer un gestionnaire d’authentification dans la classe Bootstrap, et de l’enregistrer auprès du module PAM pour traité chaque fois que le système doit authentifier une requête.

Le gestionnaire d’authentification est une fonction qui prend un seul paramètre. L’enregistrement du gestionnaire se fait par elgg_register_pam_handler() qui prend le nom du gestionnaire d’authentification, l’importance et la politique de validité comme paramètres. Il est conseillé d’enregistrer le gestionnaire dans la fonction d’initialisation du plugin, par exemple :

// classes/Your/Plugin/Bootstrap.php

function init() {
   // Register the authentication handler
   elgg_register_pam_handler('your_plugin_auth_handler');
}

// your_plugin/lib/functions.php

function your_plugin_auth_handler($credentials) {
   // do things ...
}

Importance

Par défaut, un module d’authentification est enregistré avec une importance suffisante.

Dans une liste de modules d’authentification ; si n’importe lequel des modules marqués sufficient renvoie true, elgg_pam_authenticate() renverra également true. L’exception à cela est lorsqu’un module d’authentification est enregistré avec une importance marquée required. Tous ces modules requis doivent renvoyer true pour que elgg_pam_authenticate() renvoie true, indépendamment du fait que les modules suffisants renvoient true.

Informations d’identification transmises

Le format des informations d’identification transmises au gestionnaire peut varier en fonction de la demande d’origine. Par exemple, une connexion classique via le formulaire de connexion créera un tableau indexé, avec les clefs username et password. Si une demande a été faite par exemple via XML-RPC, les informations d’identification seront définies dans l’entête HTTP, de sorte que dans ce cas rien ne sera transmis au gestionnaire d’authentification, et que le gestionnaire devra effectuer ses propres étapes pour authentifier la demande.

Valeur de retour

Le gestionnaire d’authentification doit renvoyer un booléen, indiquant si la demande peut être authentifiée ou non. Une mise en garde est que dans le cas d’une connexion utilisateur classique où les informations d’identification sont disponibles sous la forme d’un nom d’utilisateur et d’un mot de passe, l’utilisateur sera connecté. Dans le cas de l’exemple XML-RPC, le gestionnaire d’authentification devra effectuer cette étape lui-même puisque le reste du système n’aura aucune idée des formats possibles des informations d’authentification passées ni de leur contenu. La connexion d’un utilisateur est assez simple et se fait par login(), qui s’attend à recevoir un objet ElggUser.

Capacités

Capacités des entités

Définition des capacités

Il n’est pas nécessaire de définir ou d’enregistrer explicitement une nouvelle capacité dans le système. Par exemple, le plugin search utilise la capacité searchable.

Enregistrement des capacités

Si une entité prend en charge une certaine capacité (ou fonctionnalité), celle-ci doit être enregistrée dans le système. Cela peut être fait en enregistrant la capacité dans la section entities du elgg-plugin.php du plugin.

'entities' => [
        [
                'type' => 'object',
                'subtype' => 'blog',
                'capabilities' => [
                        'searchable' => true,
                ],
        ],
],

Il existe également une option pour activer (ou désactiver) une capacité pour un certain type/sous-type d’entité à l’aide de l’une des fonctions suivantes :

• elgg_entity_enable_capability($type, $subtype, $capability) utilisez ceci pour activer une certaine capacité

• elgg_entity_disable_capability($type, $subtype, $capability) utilisez ceci pour désactiver une certaine capacité

Vérification des capacités

Il existe plusieurs fonctions d’aide pour vérifier si une certaine capacité est prise en charge dans le système. Vous pouvez vérifier si une entité prend en charge une certaine capacité en utilisant la fonction $entity->hasCapability($capability). Alternativement, si vous n’avez pas d’entité à votre disposition, vous pouvez utiliser elgg_entity_has_capability($type, $subtype, $capability).

Il existe également une fonction pour obtenir un tableau de tous les types/sous-types du système prenant en charge une certaine capacité.

$types_subtypes = elgg_entity_types_with_capability('searchable');

// output
[
        'object' => [
                'blog',
                'page',
        ],
        'group' => [
                'group',
        ],
]

Contexte

Avertissement

Le contenu de cette page est obsolète. Bien que la fonctionnalité soit toujours en place, l’utilisation du contexte global pour déterminer votre logique de fonctionnement est une mauvaise pratique, et rendra votre code moins testable et plus sujet aux bogues.

Au sein du framework Elgg, le contexte peut être utilisé par les fonctions de votre plugin pour déterminer s’ils doivent s’exécuter ou non. Vous allez enregistrer des fonctions de rappel à exécuter lorsque des événements sont déclenchés. Parfois, les événements sont génériques et vous souhaitez uniquement exécuter votre fonction de rappel quand votre plugin est à l’origine du déclenchement de l’événement. Dans ce cas, vous pouvez utiliser le contexte de la page.

Vous pouvez définir explicitement le contexte avec set_context(). Le contexte est une chaîne de caractères, et généralement vous la définissez au nom de votre plugin. Vous pouvez récupérer le contexte avec la fonction get_context(). Il est toutefois préférable d’utiliser elgg_push_context($string) pour ajouter un contexte à la pile. Vous pouvez vérifier si le contexte que vous souhaitez ajouter est déjà dans la pile actuelle en appelant elgg_in_context($context). N’oubliez pas de dépiler (avec elgg_pop_context()) le contexte après l’avoir empilé, si vous n’en avez plus besoin.

Si vous ne le définissez pas, Elgg essaie de deviner le contexte. Si la page a été appelée via le routeur, le contexte est défini sur le premier segment de la route actuelle, par exemple profile dans profile/username.

Parfois, une vue va renvoyer un code HTML différent selon le contexte. Un plugin peut en profiter en définissant le contexte avant d’appeler elgg_view() sur la vue, puis en rétablissant le contexte d’origine. Cela se fait fréquemment avec le contexte de recherche - search.

Cron

Si vous configurez correctement cron comme décrit dans Cron, des événements spéciaux seront déclenchés afin que vous puissiez vous inscrire à ces événements à partir de votre propre code.

L’exemple ci-dessous enregistre une fonction pour le cron quotidien.

function my_plugin_init() {
    elgg_register_event_handler('cron', 'daily', 'my_plugin_cron_handler');
}

Si le timing est important dans votre événement cron, sachez que les fonctions sont exécutées par ordre d’enregistrement. Cela pourrait signifier que votre fonction pourrait démarrer (beaucoup) plus tard que prévu. Cependant, les paramètres fournis dans l’événement contiennent l’heure de début d’origine du cron, vous pouvez donc toujours utiliser cette information.

function my_plugin_cron_handler(\Elgg\Event $event) {
    $start_time = $event->getParam('time');
}

Intervalles personnalisés

Les développeurs de plugins peuvent configurer leurs propres intervalles personnalisés.

Avertissement

Il n’est PAS recommandé de faire cela, car les utilisateurs de votre plugin pourraient aussi avoir besoin de configurer votre intervalle personnalisé. Essayez de travailler avec les intervalles par défaut. Si vous avez seulement à effectuer une certaine tâche à 16:30, vous pouvez utiliser l’intervalle d’une demi-heure halfhour et vérifier que date('G', $start_time) == 16 et date('i', $start_time) == 30

elgg_register_event_handler('cron:intervals', 'system', 'my_custom_cron_interval');

function my_custom_cron_interval(\Elgg\Event $event) {
        $cron_intervals = $event->getValue();

        // add custom interval
        $cron_intervals['my_custom_interval'] = '30 16 * * *'; // every day at 16:30 hours

        return $cron_intervals;
}

Voir aussi

• Événements donne plus d’informations sur les événements

• Pour plus d’informations sur la définition des intervalles de cron pris en charge, voir la documentation PHP Scheduler

Base de données

Persistez le contenu et les paramètres générés par l’utilisateur avec l’API de stockage générique de Elgg.

Entités

Création d’un objet

Pour créer un objet dans votre code, vous devez instancier un ElggObject. La définition des données est simplement une question d’ajout de variables ou de propriétés d’instance. Les propriétés intégrées sont :

• ``guid`` Le GUID de l’entité ; défini automatiquement

• ``owner_guid`` Le GUID de l’utilisateur propriétaire

• ``subtype`` Une chaîne arbitraire en un seul mot qui définit de quel type d’objet il s’agit, par exemple blog`

• ``access_id`` Un entier qui représente le niveau d’accès de l’objet

• ``title`` Le titre de l’objet

• ``description`` La description de l’objet

Le sous-type d’objet est une propriété spéciale. Il s’agit d’une chaîne arbitraire qui décrit ce qu’est l’objet. Par exemple, si vous écriviez un plugin de blog, votre chaîne de sous-type pourrait être blog. C’est une bonne idée de faire en sorte que cette chaîne soit unique, de sorte que d’autres plugins n’essaient et n’utilisent pas accidentellement le même sous-type. Pour les besoins de ce document, supposons que nous construisons un forum simple. Par conséquent, le sous-type sera forum :

$object = new ElggObject();
$object->setSubtype('forum');
$object->access_id = 2;
$object->save();

access_id est une autre propriété importante. Si vous ne la définissez pas, votre objet sera privé, et seul l’utilisateur qui l’a créé sera en mesure de le voir. Elgg définit des constantes pour les valeurs spéciales de access_id :

• ACCESS_PRIVATE Seul son propriétaire peut le voir

• ACCESS_LOGGED_IN Tout utilisateur connecté peut le voir

• ACCESS_PUBLIC Même les visiteurs non connectés peuvent le voir

L’enregistrement de l’objet remplira automatiquement la propriété $object->guid en cas de succès. Si vous modifiez d’autres propriétés de base, vous pouvez appeler à nouveau $object->save(), ce qui va mettre à jour la base de données pour vous.

Vous pouvez définir des métadonnées sur un objet comme une propriété standard. Disons que nous voulons définir le SKU - référence unique pour les stocks - d’un produit :

$object->SKU = 62784;

Si vous affectez un tableau, toutes les valeurs seront définies pour ces métadonnées. C’est ainsi que, par exemple, vous définissez des balises.

Les métadonnées ne peuvent pas être conservées dans la base de données tant que l’entité n’a pas été enregistrée, mais pour plus de commodité, ElggEntity peut la mettre en cache en interne et l’enregistrer lors de l’enregistrement de l’entité.

Charger un objet

Par GUID

$entity = get_entity($guid);
if (!$entity) {
    // The entity does not exist or you're not allowed to access it.
}

Mais que faire si vous ne connaissez pas le GUID ? Il y a plusieurs options.

Par utilisateur, sous-type ou site

Si vous connaissez l’ID de l’utilisateur pour lequel vous souhaitez obtenir des objets, ou leur sous-type, vous disposez de plusieurs options. Le plus simple est probablement d’appeler la fonction procédurale elgg_get_entities :

$entities = elgg_get_entities(array(
    'type' => $entity_type,
    'subtype' => $subtype,
    'owner_guid' => $owner_guid,
));

Celle-ci renvoie un tableau d’objets ElggEntity que vous pouvez parcourir. elgg_get_entities dispose d’une pagination par défaut, avec une limite de 10, et un décalage - offset - de 0.

Vous pouvez laisser de côté owner_guid pour obtenir tous les objets, et laisser de côté le sous-type ou le type pour obtenir des objets de tous types/sous-types.

Si vous avez déjà un ElggUser – par exemple via elgg_get_logged_in_user_entity, qui renvoie toujours l’objet de l’utilisateur actuel lorsque vous êtes connecté – vous pouvez simplement utiliser :

$objects = $user->getObjects($subtype, $limit, $offset)

Mais comment fait-on pour obtenir des objets avec une valeur de métadonnée particulière ?

Par propriétés

Vous pouvez récupérer des entités par leurs propriétés en utilisant elgg_get_entities. En utilisant des paramètres spécifiques passés au tableau $options, vous pouvez récupérer des entités par leurs attributs, métadonnées, annotations et relations.

Affichage des entités

Pour que les entités s’affichent dans les fonctions de liste, vous devez fournir une vue pour l’entité dans le système de vues.

Pour afficher une entité, créez une vue EntityType/subtype où EntityType a l’une des valeurs suivantes :

object : pour les entités dérivées de ElggObject, user : pour les entités dérivées de ElggUser, site : pour les entités dérivées de ElggSite, group : pour les entités dérivées de ElggGroup

Une vue par défaut pour toutes les entités a déjà été créée, elle s’appelle EntityType/default.

Icônes des entités

Les icônes d’entité peuvent être enregistrées à partir de fichiers téléchargés, de fichiers locaux existants, ou d’objets ElggFile existants. Ces méthodes enregistrent la taille master de l’icône définie dans le système. Les autres tailles définies seront générées sur demande.

$object = new ElggObject();
$object->title = 'Example entity';
$object->description = 'An example object with an icon.';

// from an uploaded file
$object->saveIconFromUploadedFile('file_upload_input');

// from a local file
$object->saveIconFromLocalFile('/var/data/generic_icon.png');

// from a saved ElggFile object
$file = get_entity(123);
if ($file instanceof ElggFile) {
        $object->saveIconFromElggFile($file);
}

$object->save();

Les tailles d’images suivantes existent par défaut :

• master - 10240px dans la plus grande longueur (sans agrandissement)

• large - 200px dans la plus grande dimension (sans agrandissement)

• medium - carré de 100px de côté

• small - carré de 40px de côté

• tiny - carré de 25px de côté

• topbar - carré de 16px de côté

Utilisez elgg_get_icon_sizes() pour obtenir toutes les tailles d’icône possibles pour un type et un subtype d’entité spécifiques. La fonction déclenche l’événement entity:icon:sizes event.

Pour vérifier si une icône est définie, utilisez $object->hasIcon($size).

Vous pouvez récupérer l’URL de l’icône générée avec la méthode ElggEntity::getIconURL($params). Cette méthode accepte un argument $params comme tableau qui spécifie la taille, le type et fournit un contexte supplémentaire pour l’événement afin de déterminer l’icône à servir. La méthode déclenche l’événement entity:icon:url event.

Utilisez elgg_view_entity_icon($entity, $size, $vars) pour afficher une icône. Cela analysera les emplacements suivants pour trouver une vue et inclura la première qui correspond.

1. views/$viewtype/icon/$type/$subtype.php

2. views/$viewtype/icon/$type/default.php

3. views/$viewtype/icon/default.php

Où

$viewtype

Type de vue, par ex. 'default' ou 'json'.

$type

Type d’entité, par ex. 'group' ou 'user'.

$subtype

Sous-type d’entité, par ex. 'blog' ou 'page'.

Vous n’êtes pas obligé de renvoyer une icône de secours du gestionnaire d’événements. Si aucune icône téléchargée n’est trouvée, le système de visualisation analysera les vues (dans cet ordre spécifique) :

1. views/$viewtype/$icon_type/$entity_type/$entity_subtype.svg

2. views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.gif

3. views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.png

4. views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.jpg

Où

$viewtype

Type de vue, par ex. 'default' ou 'json'.

$icon_type

Type d’icône, par ex. 'icon' ou 'cover_image'.

$entity_type

Type d’entité, par ex. 'group' ou 'user'.

$entity_subtype

Sous-type d’entité, par ex. 'blog' ou 'page' (ou 'default' si l’entité n’a pas de sous-type).

$size

Taille de l’icône (notez que nous n’utilisons pas la taille avec les icônes svg)

Les méthodes des icônes permettent de passer un type d’icône si une entité possède plus d’une icône. Par exemple, un utilisateur peut avoir un avatar et une icône de photo de couverture. Vous passeriez 'cover_photo' comme type d’icône :

$object->saveIconFromUploadedFile('uploaded_photo', 'cover_photo');

$object->getIconUrl([
        'size' => 'medium',
        'type' => 'cover_photo'
]);

Note

Les types d’icônes personnalisées (par ex. les photos de couverture) n’ont qu’un préréglage pour la taille master, pour ajouter des tailles personnalisées, utilisez l”événement entity::url pour les configurer.

Par défaut, les icônes seront stockées dans /icons/<icon_type>/<size>.jpg par rapport au répertoire de l’entité sur le répertoire de fichiers. Pour fournir un autre emplacement, utilisez l”événement entity:<icon_type>:file.

Ajout, lecture et suppression des annotations

Les annotations peuvent être utilisées, par exemple, pour suivre les évolutions des notes. Pour annoter une entité, vous pouvez utiliser la méthode annotate() de l’objet. Par exemple, pour donner à un article de blog une note de 5, vous pouvez utiliser :

$blog_post->annotate('rating', 5);

Pour récupérer les notes sur l’article de blog, utilisez $blogpost->getAnnotations('rating') et si vous souhaitez supprimer une annotation, vous pouvez opérer sur la classe ElggAnnotation, par ex. $annotation->delete().

La récupération d’une seule annotation peut être faite avec get_annotation() si vous avez l’ID de l’annotation. Si vous supprimez une ElggEntity de quelque nature que ce soit, toutes ses métadonnées, annotations et relations seront également supprimées automatiquement.

Étendre ElggEntity

Si vous dérivez de l’une des classes du noyau Elgg, vous devrez dire à Elgg comment instancier correctement le nouveau type d’objet afin que get_entity() et assimilés renvoient la classe PHP appropriée. Par exemple, si je personnalise ElggGroup dans une classe appelée Committee, je dois faire connaître à Elgg le nouveau mappage. Voici un exemple d’extension de classe :

// Class source
class Committee extends ElggGroup {

    protected function initializeAttributes() {
        parent::initializeAttributes();
        $this->attributes['subtype'] = 'committee';
    }

    // more customizations here
}

Dans votre fichier elgg-plugin.php ajoutez la section entities.

<?php // mod/example/elgg-plugin.php
return [
    // entities registration
    'entities' => [
                    [
                            'type' => 'group',
                            'subtype' => 'committee',
                            'class' => 'Committee',
                            'capabilities' => [
                                    'searchable' => true,
                            ],
                    ],
            ],
];

Les entités seront enregistrées lors de l’activation du plugin.

Maintenant, si vous invoquez get_entity() avec le GUID d’un objet de comité, vous récupérerez un objet de type Comité - Committee.

Fonctionnalités avancées

URLs des entités

Les URLs d’entité sont fournies par l’interface getURL() et fournissent au framework Elgg un moyen commun de diriger les utilisateurs vers le gestionnaire d’affichage approprié pour n’importe quel objet donné.

Par exemple, une page de profil dans le cas des utilisateurs.

L’URL est définie à l’aide de la fonction elgg\_register\_entity\_url\_handler(). La fonction que vous enregistrez doit renvoyer l’URL appropriée pour le type donné - qui peut elle-même être une adresse configurée par un gestionnaire de page.

Le gestionnaire par défaut doit utiliser l’interface d’export par défaut.

Performance de chargement des entités

elgg_get_entities dispose de quelques options qui peuvent être utiles pour améliorer les performances.

• preload_owners : Si les entités récupérées sont affichées dans une liste avec des informations sur le propriétaire, vous pouvez définir cette option sur true pour charger efficacement les utilisateurs propriétaires des entités récupérées.

• preload_containers : Si les entités récupérées sont affichées dans une liste avec des informations sur leurs conteneurs, vous pouvez définir cette option sur true pour les charger efficacement.

• distinct : Quand Elgg récupère des entités à l’aide d’une requête SQL, Elgg doit être sûr que chaque ligne d’entité n’apparaît qu’une seule fois dans le jeu de résultats. Par défaut, il inclut un modificateur DISTINCT sur la colonne GUID pour l’appliquer, mais certaines requêtes renvoient naturellement des entités uniques. La définition de l’option distinct sur false supprime ce modificateur et s’appuie sur la requête pour s’assurer de l’unicité des résultats.

Le fonctionnement interne des requêtes d’entités Elgg est un sujet complexe et il est recommandé de demander de l’aide sur le site de la communauté Elgg avant d’utiliser l’option distinct.

Fonctionnalité de base de données personnalisée

Il est fortement recommandé d’utiliser des entités dans la mesure du possible. Toutefois, Elgg prend en charge les requêtes SQL personnalisées à l’aide de l’API de base de données.

Systemlog

Note

Cette section requiert une certaine attention et risque de contenir des informations obsolètes

Le journal système de Elgg par défaut est un moyen simple d’enregistrer ce qui se passe dans un système Elgg. Il est visible et consultable directement à partir du panneau d’administration.

Conservation du journal système

Une ligne de journal système est stockée chaque fois qu’un événement concernant un objet dont la classe implémente l’interface Loggable est déclenché. ElggEntity et ElggExtender implémentent Loggable, de sorte qu’une ligne de journal système est créée chaque fois qu’un événement est effectué sur tous les objets, utilisateurs, groupes, sites, métadonnées et annotations.

Les événements courants comprennent :

• create

• update

• delete

• login

Création de votre propre journal système

Il y a quelques raisons pour lesquelles vous pouvez vouloir créer votre propre journal système. Par exemple, vous pourriez avoir besoin de stocker une copie complète des entités lorsqu’elles sont mises à jour ou supprimées, à des fins d’audit. Vous pourriez aussi avoir besoin d’aviser un administrateur lorsque certains types d’événements se produisent.

Pour ce faire, vous pouvez créer une fonction qui écoute tous les événements pour tous les types d’objets :

register_elgg_event_handler('all','all','your_function_name');

Votre fonction peut alors être définie comme :

function your_function_name($object, $event) {
   if ($object instanceof Loggable) {
      ...
   }
}

Vous pouvez ensuite utiliser les méthodes supplémentaires définies par Loggable pour extraire les informations dont vous avez besoin.

E-mail

Elgg a la capacité d’envoyer des e-mails. Cela peut être fait directement en utilisant des fonctions comme elgg_send_email() et notify_user() ou indirectement via le système de notifications. Voici un aperçu des fonctionnalités du système de messagerie.

Courrier HTML

En tant qu’administrateur, vous pouvez configurer votre site pour que tous les e-mails sortants soient des e-mails HTML ou simplement des e-mails en texte brut. Les e-mails HTML sont activés par défaut. Lorsqu’il est activé, le contenu de l’e-mail sera enveloppé dans des éléments HTML et du CSS sera appliqué. Cela permet aux développeurs de thèmes de styliser les e-mails.

Les vues appropriées pour formater et styliser les e-mails peuvent être trouvées dans views/default/email.

Le CSS sera automatiquement intégré afin qu’il fonctionne dans la plupart des clients de messagerie. Si votre e-mail contient des images, ces images peuvent être converties en images encodées en base64 (par défaut) ou en pièces jointes. Les images converties sont le meilleur moyen d’afficher les images de manière cohérente dans divers clients.

Au lieu de convertir automatiquement le message en HTML, vous pouvez également fournir votre propre html_message dans les params d’une notification. Le message_html peut être un Elgg\Email\HtmlPart ou une string. S’il s’agit d’une string, Elgg essaiera automatiquement d’insérer le CSS fourni présent dans le paramètre css. Si vous ne voulez pas insérer de CSS, vous devrez définir le paramètre convert_css sur false. Ci-dessous un exemple de partie HTML personnalisée.

elgg_send_email(\Elgg\Email::factory([
        'from' => 'from@elgg.org',
        'to' => 'to@elgg.org',
        'subject' => 'Test Email',
        'body' => 'Welcome to the site',
        'params' => [
                'html_message' => '
                        <p>Welcome to the site</p>
                        <img src="site_logo.png"/>
                ',
                'convert_css' => true,
                'css' => 'p { padding: 10px;}'
        ],
]));

Pièces jointes

notify_user() ou les notifications mises en file d’attente prennent en charge les pièces jointes pour les notifications par e-mail si elles sont fournies dans $params. Pour ajouter une ou plusieurs pièces jointes, ajoutez une clef attachments dans $params, avec pour valeur un tableau des pièces jointes. Une pièce jointe doit être dans l’un des formats suivants :

• Un ElggFile qui pointe vers un fichier existant

• Un tableau avec le contenu du fichier

• Un tableau avec le chemin

// this example is for notify_user()
$params['attachments'] = [];

// Example of an ElggFile attachment
$file = new \ElggFile();
$file->owner_guid = <some owner_guid>;
$file->setFilename('<some filename>');

$params['attachments'][] = $file;

// Example of array with content
$params['attachments'][] = [
        'content' => 'The file content',
        'filename' => 'test_file.txt',
        'type' => 'text/plain',
];

// Example of array with filepath
// 'filename' can be provided, if not basename() of filepath will be used
// 'type' can be provided, if not will try a best guess
$params['attachments'][] = [
        'filepath' => '<path to a valid file>',
];

notify_user($to_guid, $from_guid, $subject, $body, $params);

Formatage des adresses e-mail

Elgg dispose d’une classe d’aide pour récupérer des adresses e-mail formatées : \Elgg\Email\Address.

// the constructor takes two variables
// first is the email address, this is REQUIRED
// second is the name, this is optional
$address = new \Elgg\Email\Address('example@elgg.org', 'Example');

// this will result in 'Example <example@elgg.org>'
echo $address->toString();

// to change the name use:
$address->setName('New Example');

// to change the e-mail address use:
$address->setEmail('example2@elgg.org');

Il existe plusieurs fonctions d’aide disponibles

• \Elgg\Email\Address::fromString($string) Va retourner une classe \Elgg\Email\Address avec le nom et l’e-mail définis, à partir d’une chaîne formatée (par ex. Exemple <example@elgg.org>)

• \Elgg\Email\Address::fromEntity($entity) Va renvoyer une classe \Elgg\Email\Address avec l’e-mail et le nom définis en fonction de l’entité

• \Elgg\Email\Address::getFormattedEmailAddress($email, $name) Va retourner une chaîne formatée à partir d’une adresse e-mail, et d’un nom optionnel

Gestion des erreurs

Sous le capot, Elgg utilise Monolog pour enregistrer les erreurs dans le journal d’erreur du serveur (et stdout pour les commandes CLI).

Monolog est livré avec un certain nombre d’outils qui peuvent aider les administrateurs à suivre les erreurs et le débogage des informations.

Vous pouvez ajouter des gestionnaires personnalisés (voir la documentation de Monolog pour une liste complète des gestionnaires) :

// Add a new handler to notify a given email about a critical error
elgg()->logger->pushHandler(
        new \Monolog\Handler\NativeMailerHandler(
                'admin@example.com',
                'Critical error',
                'no-reply@mysite.com',
                \Monolog\Logger::CRITICAL
        )
);

Liste des événements dans le noyau

Pour plus d’informations sur le fonctionnement des événements, visitez Événements.

Note

Certains événements sont marqués avec cela signifie que ces événements ont également un événement :before et :after Voir aussi Séquence d’événements

Certains événements sont marqués avec cela signifie que ces événements permettent de modifier la sortie d’un événement

Événements système

activate, plugin

Renvoyez false pour empêcher l’activation du plugin.

cache:clear, system

Efface les caches internes et externes, par défaut, y compris system_cache, simplecache et memcache. Il est possible de l’utiliser pour réinitialiser d’autres caches comme APC, OPCache ou WinCache.

cache:generate, <view>

Filtre la sortie de la vue pour une URL /cache quand simplecache est désactivé. Notez que cela sera déclenché pour chaque requête à /cache – aucun entête Expires n’est utilisé quand simplecache est désactivé.

cache:invalidate, system

Invalide les caches internes et externes.

cache:purge, system

Purge les caches internes et externes. Il s’agit de supprimer le contenu ancien/obsolète des caches.

commands, cli

Permet aux plugins d’enregistrer leurs propres commandes exécutables via le binaire elgg-cli. Les gestionnaires doivent renvoyer un tableau de noms de classes de commande. Les commandes doivent étendre \Elgg\Cli\Command pour être exécutables.

cron, <period>

Déclenché par le cron pour chaque période.

Le tableau $params va contenir :

• time - l’horodatage du lancement de la commande cron

• dt - l’objet \DateTime du moment où la commande cron a été lancée

• logger - instance de \Elgg\Logger\Cron pour enregistrer toute information dans le journal cron

cron:intervals, system

Permet la configuration d’intervalles de cron personnalisés

deactivate, plugin

Renvoyez false pour éviter la désactivation du plugin.

diagnostics:report, system

Filtre la sortie pour le téléchargement du rapport de diagnostic.

elgg.data, page

Filtre les données de configuration non mises en cache et spécifiques à la page à transmettre au client. Plus d’informations

elgg.data, site

Filtre les données de configuration mises en cache pour les transmettre au client. Plus d’informations

format, friendly:title

Formate un titre « sympathique » pour les chaînes de caractères. Ceci est utilisé pour générer des URLs.

format, friendly:time

Formate une date « sympathique » pour le timestamp $params['time'].

format, strip_tags

Filtre une chaîne pour supprimer les balises. La chaîne d’origine est passée par $params['original_string'] et un ensemble facultatif de balises autorisées est passé par $params['allowed_tags'].

gc, system

Autorise les plugins à exécuter la collecte des déchets - « garbage collection » - pour $params['period'].

generate, password

Permet aux plugins de générer de nouveaux mots de passe textuels aléatoires.

init:cookie, <name>

Renvoyez false pour remplacer la définition d’un cookie.

init, system

Les plugins ont tendance à utiliser cet événement pour l’initialisation (extension des vues, enregistrement des rappels, etc.)

languages, translations

Permet aux plugins d’ajouter/supprimer des langues des langues configurables du système.

log, systemlog

Appelé pour tous les événements déclenchés par le plugin system_log. Utilisé en interne par Elgg\SystemLog\Logger::log() pour remplir la table system_log.

login_url, site

Filtre l’URL de connexion du site. Le tableau $params contient un tableau d’éléments de requête ajoutés à l’URL de connexion par le script appelant. L’événement doit renvoyer une URL absolue de la page de connexion.

output:before, page

Dans elgg_view_page(), ceci filtre $vars avant qu’il soit transmis à la vue de la coquille de la page (page/<page_shell>). Pour arrêter d’envoyer l’entête X-Frame-Options, désenregistrez le gestionnaire Elgg\Page\SetXFrameOptionsHeaderHandler::class de cet événement.

output, page

Dans elgg_view_page(), ceci filtre la valeur de retour renvoyée.

parameters, menu:<menu_name>

Déclenché par elgg_view_menu(). Utilisé pour modifier les variables de menu (comme l’ordre de tri) avant le rendu.

Le tableau $params va contenir :

• name - nom du menu

• sort_by - paramètre de tri préféré

• d’autres paramètres passés à elgg_view_menu()

plugins_load, system

Déclenché avant que les plugins ne soient chargés. Rarement utilisé. init, system est utilisé à la place. Peut être utilisé pour charger des bibliothèques supplémentaires.

plugins_boot, system

Déclenché juste après le chargement des plugins. Rarement utilisé. init, system est utilisé à la place.

prepare, html

Déclenché par elgg_format_html() et utilisé pour préparer du HTML non sûr.

La valeur $return est un tableau :

• html - La chaîne de caractères HTML en train d’être préparée

• options - Options de préparation

prepare, menu:<menu_name>

Filtre le tableau des sections de menu avant leur affichage. Chaque section est une touche de chaîne mappée à une zone d’éléments de menu. Il s’agit d’un bon événement pour trier, ajouter, supprimer et modifier des éléments de menu. Déclenché par elgg_view_menu() et elgg()->menus->prepareMenu().

Le tableau $params va contenir :

• selected_item - ElggMenuItem sélectionné dans le menu, le cas échéant

La valeur de retour est une instance de \Elgg\Menu\PreparedMenu. Le menu préparé est une collection d’objets \Elgg\Menu\MenuSection, qui sont à leur tour des collections d’objets \ElggMenuItem.

prepare, menu:<menu_name>:<type>:<subtype>

Version plus granulaire de l’événement de menu déclenché avant l’événement prepare, menu:<menu_name>.

Uniquement appliqué si les paramètres de menu contiennent - params[“entity”] avec un \ElggEntity (<type> est \ElggEntity::type et <subtype> est \ElggEntity::subtype` `) ou - params['annotation'] avec un ``\ElggAnnotation (<type> est \ElggAnnotation::getType() et <subtype> est \ElggAnnotation::getSubtype() ``) ou - params['relationship'] avec un ``\ElggRelationship (<type> est \ElggRelationship::getType() et <subtype> est \ElggRelationship::getSubtype( ))

ready, system

Déclenché après l’événement init, system. Tous les plugins sont entièrement chargés et le moteur est prêt à servir les pages.

regenerate_site_secret:before, system

Renvoyez false pour annuler la régénération du secret du site. Vous devez également fournir un message à l’utilisateur.

regenerate_site_secret:after, system

Déclenché après que le secret du site a été régénéré.

register, menu:<menu_name>

Filtre la liste initiale des éléments de menu issus de la configuration, avant que le menu n’ait été divisé en sections. Déclenché par elgg_view_menu() et elgg()->menus->getMenu().

Le tableau $params contiendra les paramètres renvoyés par l’événement parameters, menu:<menu_name>.

La valeur de retour est une instance de \Elgg\Menu\MenuItems contenant des objets \ElggMenuItem.

Les gestionnaires d’événements peuvent ajouter/supprimer des éléments à la collection à l’aide de l’API collection, ainsi que des opérations d’accès au tableau.

register, menu:<menu_name>:<type>:<subtype>

Version plus granulaire de l’événement de menu déclenché avant l’événement prepare, menu:<menu_name>.

Uniquement appliqué si les paramètres de menu contiennent - params[“entity”] avec un \ElggEntity (<type> est \ElggEntity::type et <subtype> est \ElggEntity::subtype` `) ou - params['annotation'] avec un ``\ElggAnnotation (<type> est \ElggAnnotation::getType() et <subtype> est \ElggAnnotation::getSubtype() ``) ou - params['relationship'] avec un ``\ElggRelationship (<type> est \ElggRelationship::getType() et <subtype> est \ElggRelationship::getSubtype( ))

register, menu:filter:<filter_id>

Permet aux plugins de modifier les onglets de filtre de mise en page sur les mises en page qui spécifient le paramètre <filter_id>. Les paramètres et les valeurs de retour sont les mêmes que dans l’événement register, menu:<menu_name>

Si filter_id vaut filter (valeur par défaut), alors les onglets all, mine et friends seront générés sur la base d’informations fournies, ou seront testés pour des routes similaires à la route actuelle.

• params[“all_link”] sera utilisé pour l’onglet all

• params[“mine_link”] sera utilisé pour l’onglet mine

• params[“friends_link”] sera utilisé pour l’onglet friend

Si ce qui précède n’est pas fourni, une route sera essayée en fonction de params['entity_type'] et params['entity_subtype']. S’il n’est pas fourni, entity_type et entity_subtype seront basés sur la détection de la route actuelle. Par exemple, si la route actuelle est collection:object:blog:all entity_type sera object et entity_subtype sera blog. - L’onglet all sera basé sur la route collection:<entity_type>:<entity_subtype>:all - L’onglet mine sera basé sur la route collection:<entity_type>:<entity_subtype>:owner - L’onglet `` friend`` sera basé sur la route collection:<entity_type>:<entity_subtype>:friends

Si les routes ne sont pas enregistrés, les onglets n’apparaîtront pas.

registration_url, site

Filtre l’URL d’inscription du site. Peut être utilisé par les plugins pour attacher des codes d’invitation, des codes de référence, etc. à l’URL d’inscription. Le tableau $params contient un tableau d’éléments de requête ajoutés à l’URL d’enregistrement par le script appelant. L’événement doit renvoyer une URL absolue vers la page d’inscription.

reload:after, translations

Déclenché après que les traductions ont été (re)chargées.

sanitize, input

Filtre l’entrée GET et POST. Ceci est utilisé par get_input() pour assainir les entrées utilisateur.

seeds, database

Permet aux plugins d’enregistrer leurs propres semences de base de données. Les graines remplissent la base de données avec de fausses entités à des fins de test. Les graines doivent étendre la classe \Elgg\Database\Seeds\Seed pour qu’elle soit exécutable via elgg-cli database:seed.

send:before, http_response

Déclenché avant l’envoi d’une réponse HTTP. Les gestionnaires recevront une instance de la réponse SymfonyComponentHttpFoundationResponse qui doit être envoyée au demandeur. Les gestionnaires peuvent mettre fin à l’événement et empêcher l’envoi de la réponse en renvoyant false.

send:after, http_response

Déclenché après l’envoi d’une réponse HTTP. Les gestionnaires recevront une instance de la réponse SymfonyComponentHttpFoundationResponse qui a été envoyée au demandeur.

shutdown, system

Déclenché après l’envoi de la page à l’utilisateur. Des opérations coûteuses pourraient être faites ici sans que cela fasse attendre l’utilisateur.

Note

Selon la configuration de votre serveur, la sortie PHP peut ne pas être affichée avant la fin du processus. Cela signifie que tous les processus longs retarderont toujours le chargement de la page.

Note

Cet événement est préféré à l’utilisation de register_shutdown_function car vous n’avez peut-être pas accès à tous les services Elgg (par ex. la base de données) dans la fonction d’arrêt, alors que vous l’aurez dans l’événement.

Note

La session Elgg est déjà terminée avant cet événement. La manipulation de la session n’est plus possible.

simplecache:generate, <view>

Filtre la sortie de la vue pour une URL /cache quand simplecache est activé.

upgrade, system

Déclenché une fois la mise à niveau du système terminée. Tous les scripts de mise à niveau sont exécutés, mais les caches ne sont pas effacés.

upgrade:execute, system

Déclenché lors de l’exécution d’un ElggUpgrade. L’objet $object de l’événement est le ElggUpgrade.

Événements utilisateur

ban, user

Déclenché avant qu’un utilisateur ne soit banni. Retournez false pour l’éviter.

change:email, user

Déclenché avant la modification de l’adresse email de l’utilisateur. Permet aux plugins d’implémenter une logique supplémentaire requise pour modifier l’email, par ex. validation supplémentaire par email. Le gestionnaire d’événements doit renvoyer false pour empêcher que l’e-mail soit modifié immédiatement.

Le tableau $params va contenir :

• user - \ElggUser, dont les paramètres ont été sauvegardés

• email - Adresse e-mail qui passe les vérifications sanitaires

• request - \Elgg\Request vers le contrôleur de l’action

invalidate:after, user

Déclenché lorsque la validation du compte de l’utilisateur a été révoquée.

login:after, user

Déclenché après que l’utilisateur se soit identifié.

login:before, user

Déclenché lors de la connexion. Renvoyer false empêche l’utilisateur de se connecter

login:forward, user

Filtre l’URL vers laquelle l’utilisateur sera redirigé après la connexion.

login:first, user

Déclenché après une connexion réussie. Uniquement s’il n’y a pas de connexion précédente.

logout:after, user

Déclenché après que l’utilisateur se soit déconnecté.

logout:before, user

Déclenché pendant la déconnexion. Renvoyer false empêche l’utilisateur de se déconnecter.

make_admin, user

Déclenché avant qu’un utilisateur ne soit promu administrateur. Retournez false pour l’éviter.

profileiconupdate, user

L’utilisateur a modifié son icône de profil

profileupdate, user

L’utilisateur a modifié son profil

register, user

Déclenché par l’action register après l’enregistrement de l’utilisateur. Renvoyez false pour supprimer l’utilisateur. Notez que la fonction register_user ne déclenche pas cet événement. Les gestionnaires d’événements peuvent lancer \Elgg\Exceptions\Configuration\RegistrationException avec un message d’erreur à afficher à l’utilisateur.

Le tableau $params va contenir :

• user - L’entité utilisateur nouvellement enregistrée

• Tous les paramètres envoyés avec la requête à l’action (comprend password, friend_guid, invitecode, etc.)

registeruser:validate:email, all

Renvoie un booléen si la chaîne dans $params['email'] est une adresse email valide. Le gestionnaire d’événements peut lancer \Elgg\Exceptions\Configuration\RegistrationException avec un message d’erreur à afficher à l’utilisateur.

registeruser:validate:password, all

Renvoie un booléen si la chaîne dans $params['password'] est un mot de passe valide. Le gestionnaire d’événements peut lancer une \Elgg\Exceptions\Configuration\RegistrationException avec un message d’erreur à afficher à l’utilisateur.

registeruser:validate:username, all

Renvoie un booléen si la chaîne dans $params['username'] est un nom d’utilisateur valide. Le gestionnaire d’événements peut lancer une \Elgg\Exceptions\Configuration\RegistrationException avec un message d’erreur à afficher à l’utilisateur.

remove_admin, user

Déclenché avant que le rôle d’administrateur ne soit retiré à un utilisateur. Retournez false pour l’éviter.

unban, user

Déclenché avant qu’un utilisateur ne soit réintégré. Retournez false pour l’éviter.

username:character_blacklist, user

Filtre la chaîne et supprime les caractères interdits pour valider le nom d’utilisateur lors de l’inscription. La valeur de retour doit être une chaîne composée des caractères refusés. La chaîne par défaut se trouve dans $params['blacklist'].

usersettings:save, user

Déclenché dans l’action globale pour enregistrer les paramètres utilisateur. Le gestionnaire d’événements doit retourner false pour empêcher que les formulaires persistants ne soient effacés (c’est-à-dire pour indiquer que certaines valeurs n’ont pas été enregistrées). Ne renvoyez pas true depuis votre gestionnaire d’événements, car vous écraseriez la sortie des autres événements, mais renvoyez plutôt null pour indiquer une opération réussie.

Le tableau $params va contenir :

• user - \ElggUser, dont les paramètres ont été sauvegardés

• request - \Elgg\Request vers le contrôleur de l’action

validate, user

Lorsqu’un utilisateur s’inscrit, le compte de l’utilisateur est désactivé. Cet événement est déclenché pour permettre à un plugin de déterminer comment l’utilisateur doit être validé (par exemple, par le biais d’un e-mail avec un lien de validation).

validate:after, user

Déclenché lorsque le compte utilisateur a été validé.

Événements des relations

create, relationship

Déclenché après la création d’une relation. Renvoyez false pour supprimer la relation qui vient d’être créée.

delete, relationship

Déclenché avant la suppression d’une relation. Renvoyez false pour éviter qu’elle soit supprimée.

join, group

Déclenché après que l’utilisateur $params['user'] a rejoint le groupe $params['group'].

leave, group

Déclenché avant que l’utilisateur $params['user'] n’ait quitté le groupe $params['group'].

Événements des entités

comments, <entity_type>

Déclenché dans elgg_view_comments(). S’il renvoie du contenu, celui-ci remplace la vue page/elements/comments.

comments:count, <entity_type>

Renvoie le nombre de commentaires sur $params['entity'].

create, <entity type>

Déclenché pour les entités user, group, object et site après leur création. Déclenché juste avant l’événement create:after, principalement pour des raisons de rétrocompatibilité. L’utilisation de l’événement create:after est préférable.

create:after, <entity type>

Déclenché pour les entités user, group, object et site après la création.

create:before, <entity type>

Déclenché pour les entités user, group, object et site avant la création. Renvoyez false pour empêcher la création de l’entité.

delete, <entity type>

Déclenché avant la suppression d’une entité.

delete:after, <entity type>

Déclenché après la suppression d’une entité.

delete:before, <entity type>

Déclenché avant la suppression d’une entité. Retournez false pour éviter la suppression.

disable, <entity type>

Déclenché avant qu’une entité soit désactivée. Retournez false pour éviter la désactivation.

disable:after, <entity type>

Déclenché après qu’une entité a été désactivée.

enable, <entity type>

Retournez false pour éviter l’activation.

enable:after, <entity type>

Déclenché après qu’une entité a été activée.

likes:count, <entity_type>

Renvoie le nombre de mentions J’aime pour $params['entity'].

update, <entity type>

Déclenché avant une mise à jour pour les entités user, group, object et site. Renvoyez false pour empêcher la mise à jour. La méthode d’entité getOriginalAttributes() peut être utilisée pour identifier les attributs qui ont changé depuis la dernière fois que l’entité a été enregistrée.

update:after, <entity type>

Déclenché après une mise à jour pour les entités user, group, object et site. La méthode d’entité getOriginalAttributes() peut être utilisée pour identifier les attributs qui ont changé depuis la dernière fois que l’entité a été enregistrée.

Événements des métadonnées

create, metadata

Appelé après qu’une métadonnée a été créée. Retournez false pour supprimer la métadonnée qui vient d’être créée.

delete, metadata

Appelé avant que métadonnée soit supprimée. Retournez false pour éviter la suppression.

update, metadata

Appelé après qu’une métadonnée a été modifiée. Retournez false pour supprimer la métadonnée.

Événements des annotations

annotate, <entity type>

Appelé avant que l’annotation soit créée. Retournez false pour éviter l’annotation de cette entité.

create, annotation

Appelé après que l’annotation a été créée. Retournez false pour supprimer l’annotation.

delete, annotation

Appelé avant que l’annotation soit supprimée. Retournez false pour éviter la suppression.

disable, annotations

Appelé lors de la désactivation d’annotations. Retournez false pour éviter la désactivation.

enable, annotation

Appelé lors de l’activation d’annotations. Retournez false pour éviter l’activation.

update, annotation

Appelé après qu’une annotation a été modifiée. Retournez false pour supprimer l’annotation.

Événements de la rivière

create:after, river

Appelé après qu’un élément de la rivière a été créé.

create:before, river

Appelé avant que l’élément river ne soit enregistré dans la base de données. Renvoie false pour empêcher la création de l’élément.

delete:after, river

Déclenché après qu’un élément de la rivière a été supprimé.

delete:before, river

Déclenché avant qu’un élément de la rivière soit supprimé. Renvoyer false annule la suppression.

Événements des accès

access_collection:url, access_collection

Peut être utilisé pour filtrer l’URL de la collection d’accès.

Le tableau $params va contenir :

• access_collection - ElggAccessCollection

access_collection:name, access_collection

Peut être utilisé pour filtrer le nom affiché (niveau d’accès lisible) de la collection d’accès.

Le tableau $params va contenir :

• access_collection - ElggAccessCollection

access:collections:read, user

Filtre le tableau des IDs d’accès que l’utilisateur $params['user_id'] peut voir.

Avertissement

Le gestionnaire doit soit ne pas utiliser les parties de l’API qui utilisent le système d’accès (déclenchant à nouveau l’événement), soit ignorer le deuxième appel. Sinon, une boucle infinie sera créée.

access:collections:write, user

Filtre un tableau d’IDs d’accès sur lesquels l’utilisateur $params['user_id'] peut écrire. Dans elgg_get_write_access_array(), cet événement filtre la valeur de retour, afin qu’il puisse être utilisé pour modifier les options disponibles dans la vue input/access. Pour les plugins principaux, la valeur « input_params » a les clés « entity » (ElggEntity|false), « entity_type » (string), « entity_subtype » (string), « container_guid » (int) fournies. Une valeur d’entité vide signifie généralement que le formulaire doit créer un nouvel objet.

Avertissement

Le gestionnaire doit soit ne pas utiliser les parties de l’API qui utilisent le système d’accès (déclenchant à nouveau l’événement), soit ignorer le deuxième appel. Sinon, une boucle infinie sera créée.

access:collections:write:subtypes, user

Renvoie un tableau de sous-types de collection d’accès à utiliser lors de la récupération des collections d’accès appartenant à un utilisateur, dans le cadre de la fonction elgg_get_write_access_array().

access:collections:add_user, collection

Déclenché avant d’ajouter l’utilisateur $params['user_id'] à la collection $params['collection_id']. Retournez false pour éviter l’ajout.

access:collections:remove_user, collection

Déclenché avant de supprimer l’utilisateur $params[’user_id'] de la collection $params['collection_id']. Renvoyez false pour éviter la suppression.

create, access_collection

Déclenché durant la création d’une ElggAccessCollection.

delete, access_collection

Déclenché durant la suppression d’une ElggAccessCollection.

get_sql, access

Filtre les clauses SQL limitant/autorisant l’accès aux entités et aux annotations.

Note

L’événement est déclenché même si l’accès est ignoré. Les gestionnaires devront peut-être vérifier si l’accès est ignoré et retourner une réponse plus tôt, si les clauses ajoutées ne doivent s’appliquer qu’à des contextes à accès contrôlé.

La valeur $return est un tableau imbriqué de ands et de ors.

$params comprend :

• table_alias - alias de la table principale utilisée dans la clause de sélection

• ignore_access - selon que les accès sont ignorés ou activés

• use_enabled_clause - selon que les entités désactivées sont affichées/cachées

• access_column - colonne de la table principale contenant l’ID de la collection d’accès

• owner_guid_column - colonne de la table principale faisant référence au GUID du propriétaire

• guid_column - colonne de la table principale faisant référence au GUID de l’entité

• enabled_column - colonne de la table principale faisant référence à l’état activé de l’entité

• query_builder - une instance de QueryBuilder

update, access_collection

Déclenché durant la mise à jour d’une ElggAccessCollection.

Événements des permissions

container_logic_check, <entity_type>

Déclenché par ElggEntity:canWriteToContainer() avant de déclencher les événements permissions_check et container_permissions_check. Contrairement aux événements des permissions, la vérification logique peut être utilisée pour empêcher certains types d’entités d’être contenus par d’autres types d’entités, par ex. les réponses aux discussions ne doivent être contenues que par les discussions. Cet événement peut également être utilisé pour appliquer une logique d’état, par ex. pour interdire les nouvelles réponses pour les discussions fermées.

Le gestionnaire devrait renvoyer false pour empêcher une entité de contenir une autre entité. La valeur par défaut transmise à l’événement est null, donc le gestionnaire peut vérifier si un autre événement a modifié la valeur en vérifiant si la valeur de retour est définie. Si cet événement renvoie false, les événements container_permissions_check et permissions_check ne seront pas déclenchés.

Le tableau $params va contenir :

• container - Une entité qui sera utilisée comme conteneur

• user - L’utilisateur qui sera propriétaire de l’entité à écrire dans le conteneur

• subtype - Subtype de l’entité à écrire dans le conteneur (le type d’entité est déduit à partir du type d’événement)

container_permissions_check, <entity_type>

Renvoie un booléen pour indiquer si l’utilisateur $params['user'] peut utiliser l’entité $params['container'] comme conteneur pour une entité <entity_type> et le sous-type $params['subtype'].

Dans les rares cas où une entité est créée sans le container_guid ni le owner_guid correspondant à l’utilisateur connecté, cet événement est appelé deux fois, et lors du premier appel $params['container '] sera le propriétaire, et pas le véritable conteneur de l’entité.

Le tableau $params va contenir :

• container - Une entité qui sera utilisée comme conteneur

• user - L’utilisateur qui sera propriétaire de l’entité à écrire dans le conteneur

• subtype - Subtype de l’entité à écrire dans le conteneur (le type d’entité est déduit à partir du type d’événement)

permissions_check, <entity_type>

Renvoie un booléen pour indiquer si l’utilisateur $params['user'] peut modifier l’entité $params['entity'].

permissions_check:delete, <entity_type>

Renvoie un booléen pour indiquer si l’utilisateur $params['user'] peut supprimer l’entité $params['entity']. Vaut par défaut $entity->canEdit().

permissions_check:delete, river

Renvoyez un booléen pour indiquer si l’utilisateur $params['user'] peut supprimer l’élément de la rivière $params['item']. Par défaut à true pour les administrateurs et false pour les autres utilisateurs.

permissions_check:download, file

Renvoie un booléen pour indiquer si l’utilisateur $params['user'] peut télécharger le fichier dans $params['entity'].

Le tableau $params va contenir :

• entity - Instance de ElggFile

• user - Utilisateur qui va télécharger le fichier

permissions_check, widget_layout

Renvoie un booléen pour indiquer si $params['user'] peut modifier les widgets dans le contexte passé par $params['context'] et avec le propriétaire de page $params['page_owner'].

permissions_check:comment, <entity_type>

Renvoie un booléen pour indiquer si l’utilisateur $params['user'] peut commenter l’entité $params['entity'].

permissions_check:annotate:<annotation_name>, <entity_type>

Renvoie un booléen pour indiquer si l’utilisateur $params['user'] peut créer une annotation <annotation_name> sur l’entité $params['entity']. Si l’utilisateur est connecté, la valeur par défaut est true.

Note

Ceci est appelé avant l’événement plus général permissions_check:annotate, et sa valeur de retour est la valeur initiale de cet événement.

permissions_check:annotate, <entity_type>

Renvoie un booléen pour indiquer si l’utilisateur $params['user'] peut créer une annotation $params['annotation_name'] sur l’entité $params['entity']. Si l’utilisateur est connecté, la valeur par défaut est true.

api_key, use

Déclenché dans la classe \Elgg\WebServices\PAM\API\APIKey. Renvoyer false empêche l’authentification de la clef.

gatekeeper, <entity_type>:<entity_subtype>

Filtre le résultat de elgg_entity_gatekeeper() pour bloquer ou autoriser l’accès à une entité à laquelle l’utilisateur aurait ou n’aurait pas accès autrement. Un gestionnaire peut renvoyer false ou une instance de \Elgg\Exceptions\HttpException pour empêcher l’accès à une entité. Un gestionnaire peut retourner true pour remplacer le résultat du gatekeeper. Important l’entité reçue par cet événement est récupérée en ignorant les accès, et en incluant les entités désactivées, vous devez donc faire attention à ne pas contourner le système d’accès.

le tableau $params comprend :

• entity - Entité à laquelle on accède

• user - L’utilisateur qui accède à l’entité (null implique l’utilisateur connecté)

Événements des notifications

dequeue, notifications

Appelé lorsqu’un objet ElggData est supprimé de la file d’attente des notifications pour être traité

enqueue, notifications

Appelé lorsqu’un objet ElggData est en train d’être ajouté à la file d’attente des notifications

Les événements suivants sont répertoriés chronologiquement au cours de la durée de vie de l’événement de notification. Notez que tous les événements ne s’appliquent pas aux notifications instantanées.

enqueue, notification

Peut être utilisé pour empêcher un événement de notification d’envoyer des notifications subscription. Le gestionnaire d’événements doit renvoyer false pour empêcher qu’un événement de notification d’abonnement ne soit mis en file d’attente.

le tableau $params comprend :

• object - objet de l’événement de notification

• action - action qui a déclenché l’événement de notification. Par exemple, correspond à publish quand elgg_trigger_event('publish', 'object', $object) est appelé

get, subscriptions

Filtre les abonnés de l’événement de notification. S’applique aux notifications d’abonnement subscriptions et instantanées instant. Lors d’un événement d’abonnement, par défaut, la liste des abonnés se compose des utilisateurs abonnés à l’entité conteneur de l’objet de l’événement. En cas d’événement de notification instantanée, la liste des abonnés se compose des utilisateurs précédemment passés en tant que destinataires à notify_user()

IMPORTANT Validez toujours les types d’événement, d’objet et/ou d’action de notification avant d’ajouter de nouveaux destinataires pour vous assurer que vous n’envoyez pas accidentellement des notifications à des destinataires inattendus. Prenons une situation dans laquelle un plugin de mentions envoie une notification instantanée à un utilisateur mentionné - tout événement agissant sur un sujet ou un objet sans valider un événement ou un type d’action (par exemple inclure un propriétaire du fil de discussion d’origine) pourrait finir par envoyer des notifications aux mauvais utilisateurs.

le tableau $params comprend :

• event - instance de \Elgg\Notifications\NotificationEvent qui décrit l’événement de notification

• origin - subscriptions_service ou instant_notifications

• methods_override - préférence de méthode de remise pour les notifications instantanées

Les gestionnaires doivent renvoyer un tableau de la forme :

array(
        <user guid> => array('sms'),
        <user_guid2> => array('email', 'sms', 'ajax')
);

send:before, notifications

Déclenché avant le traitement de la file d’attente des événements de notification. Peut être utilisé pour mettre fin à l’événement de notification. S’applique aux notifications d’abonnement subscriptions et instantanées instant.

le tableau $params comprend :

• event - instance de \Elgg\Notifications\NotificationEvent qui décrit l’événement de notification

• subscriptions - une liste d’abonnements. Voir l’événement 'get', 'subscriptions' pour plus de détails

prepare, notification

Un événement de haut niveau qui peut être utilisé pour modifier une instance de \Elgg\Notifications\Notification avant qu’elle ne soit envoyée à l’utilisateur. S’applique aux abonnements et aux notifications instantanées. Cet événement est déclenché avant une 'prepare', 'notification:<action>:<entity_type>:<entity_subtype>' plus granulaire et après 'send:before', 'notifications. Le gestionnaire d’événements doit renvoyer un objet de notification modifié.

$params peut varier en fonction du type de notification et peut comprendre :

• event - instance de \Elgg\Notifications\NotificationEvent qui décrit l’événement de notification

• object - objet de la notification event. Peut être null pour les notifications instantanées

• action - action qui a déclenché la notification event. Peut avoir pour valeur par défaut notify_user pour les notifications instantanées

• method - méthode d’envoi (par ex. email, site)

• sender - expéditeur

• recipient - destinataire

• language - langue de la notification (langue du destinataire)

• origin - subscriptions_service ou instant_notifications

prepare, notification:<action>:<entity_type>:<entity_type>

Un événement granulaire qui peut être utilisé pour filtrer une notification \Elgg\Notifications\Notification avant qu’elle ne soit envoyée à l’utilisateur. S’applique aux subscriptions et aux notifications instant. En cas de notifications instantanées qui n’ont pas reçu d’objet, l’événement sera appelé 'prepare', 'notification:<action>'. Dans le cas de notifications instantanées qui n’ont pas reçu de nom d’action, il sera par défaut notify_user.

$params comprend :

• event - instance de \Elgg\Notifications\NotificationEvent qui décrit l’événement de notification

• object - objet de la notification event. Peut être null pour les notifications instantanées

• action - action qui a déclenché la notification event. Peut avoir pour valeur par défaut notify_user pour les notifications instantanées

• method - méthode d’envoi (par ex. email, site)

• sender - expéditeur

• recipient - destinataire

• language - langue de la notification (langue du destinataire)

• origin - subscriptions_service ou instant_notifications

format, notification:<method>

Cet événement peut être utilisé pour formater une notification avant qu’elle soit transmise à l’événement 'send', 'notification:<method>'. S’applique aux notifications subscriptions et instant. Le gestionnaire d’événement doit renvoyer une instance de \Elgg\Notifications\Notification. L’événement ne reçoit aucun $params. Quelques cas d’utilisation :

• Supprime les balises du titre et du corps de la notification pour les notifications par e-mail en texte brut

• Styles HTML en ligne pour les e-mails de notification HTML

• Envelopper la notification dans un modèle, ajouter une signature, etc.

send, notification:<method>

Délivre une notification. S’applique aux notifications d’abonnement subscriptions et instantanées instant. Le gestionnaire doit retourner true ou false pour indiquer le résultat de la remise.

le tableau $params comprend :

• notification - un objet de notification \Elgg\Notifications\Notification

send:after, notifications

Déclenché après que toutes les notifications dans la file d’attente pour l’événement notifications ont été traitées. S’applique aux notifications d’abonnement subscriptions et instantanées instant.

le tableau $params comprend :

• event - instance de \Elgg\Notifications\NotificationEvent qui décrit l’événement de notification

• subscriptions - une liste d’abonnements. Voir l’événement 'get', 'subscriptions' pour plus de détails

• deliveries - une matrice des statuts de remise par utilisateur pour chaque méthode de livraison

E-mails

prepare, system:email

Déclenché par elgg_send_email(). S’applique à tous les emails système et de notification sortants. Cet événement vous permet de modifier une instance de \Elgg\Email avant qu’elle soit transmise à l’agent de transport de courrier électronique. Cet événement peut être utilisé pour modifier l’expéditeur, le destinataire, l’objet, le corps et/ou les entêtes de l’email.

$params est vide. La valeur de retour $return est une instance de \Elgg\Email.

transport, system:email

Déclenché par elgg_send_email(). S’applique à tous les emails système et de notification sortants. Cet événement vous permet d’implémenter un transport de courrier électronique personnalisé, par ex. envoyer des emails via un service proxy tiers tel que SendGrid ou Mailgun. Le gestionnaire doit retourner true pour indiquer que l’email a bien été transporté.

$params contient :

• email - Une instance de \Elgg\Email

validate, system:email

Déclenché par elgg_send_email(). S’applique à tous les emails système et de notification sortants. Cet événement vous permet de supprimer ou de mettre sur liste blanche les emails sortants, par ex. lorsque le site est en mode développement. Le gestionnaire doit retourner false pour supprimer l’envoi du courrier électronique.

$params contient :

• email - Une instance de \Elgg\Email

zend:message, system:email

Déclenché par le gestionnaire de transport de courrier électronique par défaut (Elgg utilise laminas/laminas-mail). S’applique à tous les emails système et de notification sortants qui n’ont pas été transportés à l’aide de l’événement transport, system:email. Cet événement vous permet de modifier une instance de \Laminas\Mail\Message avant qu’elle soit transmise au transport de courrier électronique Laminas.

$params contient :

• email - Une instance de \Elgg\Email

Événements des fichiers

download:url, file

Permet aux plugins de filtrer l’URL de téléchargement du fichier.

Par défaut, l’URL de téléchargement est générée par le service de fichiers.

le tableau $params comprend :

• entity - instance de ElggFile

• use_cookie - utiliser ou non un cookie pour sécuriser le lien de téléchargement

• expires - une représentation sous forme de chaîne indiquant quand le lien de téléchargement doit expirer

inline:url, file

Permet aux plugins de filtrer l’URL en ligne du fichier image.

Par défaut, l’URL en ligne - inline - est générée par le service de fichiers.

le tableau $params comprend :

• entity - instance de ElggFile

• use_cookie - utiliser ou non un cookie pour sécuriser le lien de téléchargement

• expires - une représentation sous forme de chaîne indiquant quand le lien de téléchargement doit expirer

mime_type, file

Renvoie le type MIME pour le nom de fichier $params['filename'] avec le nom de fichier original $params['original_filename'] et avec le type MIME détecté par défaut de $params['default'].

simple_type, file

L’événement fournit $params['mime_type'] (par exemple application/pdf ou image/jpeg) et détermine une catégorie globale comme document ou image. Le plugin file fourni et les autres plugins tiers stockent généralement les métadonnées simpletype sur les entités de fichiers et les utilisent lors du service d’icônes et de la construction de filtres et de menus ege*.

upload, file

Permet aux plugins d’implémenter une logique personnalisée pour déplacer un fichier téléchargé dans une instance de ElggFile. Le gestionnaire doit renvoyer true pour indiquer que le fichier téléchargé a été déplacé. Le gestionnaire doit renvoyer false pour indiquer que le fichier téléchargé n’a pas pu être déplacé. D’autres valeurs de retour indiqueront que ElggFile::acceptUploadedFile devrait poursuivre la logique de téléchargement par défaut.

le tableau $params comprend :

• file - instance de ElggFile dans laquelle écrire

• upload - instance de UploadedFile de Symfony

upload:after, file

Appelé après qu’un fichier téléchargé a été écrit dans le répertoire de fichiers. Reçoit une instance du ElggFile dans lequel le fichier téléchargé a été écrit. Le ElggFile peut ou non être une entité avec un GUID.

Événements des actions

action:validate, <action>

Déclenchement avant l’exécution du script d’action/du contrôleur. Cet événement doit être utilisé pour valider/modifier la saisie de l’utilisateur, avant de poursuivre l’action. Le gestionnaire d’événements peut lancer une instance de \Elgg\Exceptions\Http\ValidationException ou renvoyer false pour interrompre l’exécution.

le tableau $params comprend :

• request - instance de \Elgg\Request

action_gatekeeper:permissions:check, all

Déclenché après la validation d’un jeton CSRF. Renvoyez false pour empêcher la validation.

forward, <reason>

Filtre l’URL pour rediriger un utilisateur lorsque forward($url, $reason) est appelé. Dans certains cas, le tableau params va contenir une instance de \Elgg\Exceptions\HttpException qui a déclenché l’erreur.

response, action:<action>

Filtrez une instance de \Elgg\Http\ResponseBuilder avant qu’elle ne soit envoyée au client. Cet événement peut être utilisé pour modifier le contenu de la réponse, le code d’état, l’URL de transfert ou définir des en-têtes de réponse supplémentaires. Notez que la valeur <action> est analysée à partir de l’URL de la requête, vous ne pourrez donc peut-être pas filtrer les réponses des appels action() si elles sont imbriquées dans un autre fichier de script d’action.

Ajax

ajax_response, *

Lorsque le module AMD elgg/Ajax est utilisé, cet événement donne accès à l’objet de réponse (\Elgg\Services\AjaxResponse) afin qu’il puisse être modifié/étendu. Le type d’événement dépend de l’appel de méthode :

méthode elgg/Ajax	type d’événement
action()	action:<action_name>
path()	path:<url_path>
view()	view:<view_name>
form()	form:<action_name>

ajax_response, action:<action_name>

Filtre les réponses action/ avant qu’elles soient renvoyées au module elgg/Ajax.

ajax_response, path:<path>

Filtre les réponses ajax avant qu’elles soient renvoyées au module elgg/Ajax. Ce type d’événement ne sera utilisé que si le chemin ne commence pas par « action/ » ou « ajax/ ».

ajax_response, view:<view>

Filtre les réponses ajax/view/ avant qu’elles soient renvoyées au module elgg/Ajax.

ajax_response, form:<action_name>

Filtre les réponses ajax/form/ avant qu’elles soient renvoyées au module elgg/Ajax.

Routage

response, path:<path>

Filtre une instance de \Elgg\Http\ResponseBuilder avant qu’elle ne soit envoyée au client. Ce type d’événement ne sera utilisé que si le chemin ne commence pas par « action/ » ou « ajax/ ». Cet événement peut être utilisé pour modifier le contenu de la réponse, le code d’état, l’URL de transfert ou définir des entêtes de réponse supplémentaires. Notez que la valeur <path> est analysée à partir de l’URL de la requête, donc les plugins utilisant l’événement route doivent utiliser le <path> d’origine pour filtrer la réponse, ou passer à l’utilisation de route:rewrite événement.

route:config, <route_name>

Permet de modifier la configuration de la route avant son enregistrement. Cet événement peut être utilisé pour modifier le chemin, les valeurs par défaut, les pré-requis, ainsi que pour définir/supprimer un middleware. Veuillez noter que le gestionnaire de cet événement doit être enregistré en dehors du gestionnaire d’événement init, car les routes principales sont enregistrées lors de l’événement plugins_boot.

route:rewrite, <identifier>

Permet de modifier le chemin de l’URL relative au site pour une demande entrante. Voir Routage pour plus de détails. Veuillez noter que le gestionnaire de cet événement doit être enregistré en dehors du gestionnaire d’événement init, car les réécritures de route ont lieu après la fin de l’événement plugins_boot.

Vues

attributes, htmlawed

Permet de modifier des attributs individuels.

allowed_styles, htmlawed

Configure les styles autorisés pour HTMLawed.

config, htmlawed

Filtre le tableau HTMLawed $config.

form:prepare:fields, <form_name>

Préparez les valeurs des champs à utiliser dans le formulaire. Par ex. lors de la modification d’un blog, remplissez-le avec les valeurs actuelles du blog. Les valeurs du formulaire collant seront automatiquement ajoutées aux valeurs des champs (si disponibles).

head, page

Dans elgg_view_page(), filtre la valeur de retour de $vars['head'], qui contient un tableau avec les clefs title, metas et links, où metas est un tableau d’éléments à formater sous la forme de balises d’entête <meta>, et links est un tableau d’éléments à formater sous la forme de baslises d’entête <link>. Chaque élément meta et link contient un ensemble de paires de clés/valeurs qui sont formatées en attributs de balise html, par ex.

return [
   'title' => 'Current page title',
   'metas' => [
      'viewport' => [
         'name' => 'viewport',
         'content' => 'width=device-width',
      ]
   ],
   'links' => [
      'rss' => [
         'rel' => 'alternative',
         'type' => 'application/rss+xml',
         'title' => 'RSS',
         'href' => elgg_format_url($url),
      ],
      'icon-16' => [
         'rel' => 'icon',
         'sizes' => '16x16',
         'type' => 'image/png',
         'href' => elgg_get_simplecache_url('graphics/favicon-16.png'),
      ],
   ],
];

layout, page

Dans elgg_view_layout(), filtre le nom de la disposition. Le tableau $params comprend :

• identifier - identifiant de la page en cours de rendu

• segments - Segments d’URL de la page en cours de rendu

• autres $vars reçues par elgg_view_layout()

response, form:<form_name>

Filtrez une instance de \Elgg\Http\ResponseBuilder avant qu’elle ne soit envoyée au client. S’applique à la demande adressée à /ajax/form/<form_name>. Cet événement peut être utilisé pour modifier le contenu de la réponse, le code d’état, l’URL de transfert ou définir des entêtes de réponse supplémentaires.

response, view:<view_name>

Filtrez une instance de \Elgg\Http\ResponseBuilder avant qu’elle soit envoyée au client. S’applique à la requête adressée à /ajax/view/. Cet événement peut être utilisé pour modifier le contenu de la réponse, le code d’état, l’URL de transfert ou définir des entêtes de réponse supplémentaires.

shell, page

Dans elgg_view_page(), filtre le nom de la coquille - page shell - de la page

spec, htmlawed

Filtre la chaîne HTMLawed $spec (vide par défaut).

table_columns:call, <name>

Lorsque la méthode elgg()->table_columns->$name() est appelée, cet événement est appelé pour permettre aux plugins de remplacer ou de fournir une implémentation. Les gestionnaires reçoivent les arguments de la méthode via $params['arguments'] et doivent renvoyer une instance de Elgg\Views\TableColumn s’ils souhaitent spécifier la colonne directement.

vars:compiler, css

Permet aux plugins de modifier les variables CSS transmises à CssCrush pendant la compilation. Voyez les variables CSS <_guides/theming#css-vars>.

view, <view_name>

Filtre le contenu renvoyé par la vue

view_vars, <view_name>

Filtre le tableau $vars passé à la vue

Recherche

search:config, search_types

Implémenté dans le plugin search. Filtre un tableau de types de recherche personnalisés. Cela permet aux plugins d’ajouter des types de recherche personnalisés (par ex. une recherche par mots-clefs ou par localisation géographique). L’ajout d’un type de recherche personnalisé permettra d’étendre l’interface utilisateur du plugin de recherche avec des liens et des listes appropriés.

search:config, type_subtype_pairs

Implémenté dans le plugin search. Filtre les paires de types/sous-types d’entités avant l’exécution de la recherche d’entité. Permet aux plugins de supprimer certains types/sous-types d’entités des résultats de recherche, de regrouper plusieurs sous-types, ou de réorganiser des sections de recherche.

search:fields, <entity_type>

Déclenché par elgg_search(). Filtre les champs de recherche avant que les clauses de recherche ne soient préparées. La valeur $return contient un tableau avec les noms de chaque type de propriété d’entité, qui devrait être comparé à la requête de recherche. Le tableau $params contient un tableau de paramètres de recherche transmis et filtrés par elgg_search().

return [
    'attributes' => [],
    'metadata' => ['title', 'description'],
    'annotations' => ['revision'],
];

search:fields, <entity_type>:<entity_subtype>

Voyez search:fields, <entity_type>

search:fields, <search_type>

Voyez search:fields, <entity_type>

search:format, entity

Implémenté dans le plugin search. Permet aux plugins de renseigner les données volatiles de l’entité avant qu’elles ne soient transmises à la vue de recherche. Ceci est utilisé pour mettre en surbrillance les correspondances de la recherche, extraire les sous-chaînes pertinentes dans les champs de texte long, etc.

search:options, <entity_type>

Déclenché par elgg_search(). Prépare les clauses de recherche (options) à transmettre à elgg_get_entities().

search:options, <entity_type>:<entity_subtype>

Voyez search:options, <entity_type>

search:options, <search_type>

Voyez search:options, <entity_type>

search:params, <search_type>

Déclenché par elgg_search(). Filtre les paramètres de recherche (requête, tri, champs de recherche, etc.) avant que les clauses de recherche ne soient préparées pour un type de recherche donné. Le noyau de Elgg ne prend en charge que le type de recherche entities.

search:results, <search_type>

Déclenché par elgg_search(). Reçoit les options normalisées adaptées à l’appel elgg_get_entities() et doit renvoyer un tableau d’entités correspondant aux options de recherche. Cet événement est conçu pour être utilisé par des plugins intégrant des services d’indexation tiers, tels que Solr et Elasticsearch.

Autres

config, comments_per_page

Filtre le nombre de commentaires affichés par page. La valeur par défaut est 25. $params['entity'] contiendra l’entité contenant ou null si elle n’est pas fournie. Utilisez elgg_comments_per_page() pour obtenir la valeur.

config, comments_latest_first

Filtre l’ordre des commentaires. Vaut true par défaut pour le plus récent en premier. $params['entity'] indique l’entité contenante, ou null si elle n’est pas fournie.

default, access

Dans elgg_get_default_access(), cet événement filtre la valeur de retour, afin de pouvoir l’utiliser pour modifier la valeur par défaut dans la vue input/access. Pour les plugins principaux, la valeur « input_params » fournit les clés « entity » (ElggEntity|false), « entity_type » (string), « entity_subtype » (string), « container_guid » (int). Une valeur d’entité vide signifie généralement que le formulaire doit créer un nouvel objet.

classes, icon

Peut être utilisé pour filtrer les classes CSS appliquées aux glyphes d’icônes. Par défaut, Elgg utilise FontAwesome. Les plugins peuvent utiliser cet événement pour passer à une autre famille de polices et remapper les classes d’icônes.

config, amd

Filtre la configuration AMD pour la bibliothèque requirejs.

entity:icon:sizes, <entity_type>

Déclenché par elgg_get_icon_sizes(), définit le type d’entité/le sous-type de tailles d’icônes spécifiques. entity_subtype sera transmis dans le tableau $params à la fonction de rappel.

entity:<icon_type>:sizes, <entity_type>

Permet de filtrer les tailles pour les types d’icônes personnalisés, voir entity:icon:sizes, <entity_type>.

L’événement doit renvoyer un tableau associatif où les clés sont les noms des tailles d’icônes (par ex. « large ») et les valeurs sont des tableaux avec les clés suivantes :

• w - Largeur de l’image en pixels

• h - Hauteur de l’image en pixels

• square - Le ratio devrait-il être carré (true/false)

• upscale - L’image doit-elle être agrandie si elle est plus petite que la largeur et la hauteur indiquées (true/false)

• crop - Est-ce que le recadrage est autorisé sur cette taille d’image (true/false, par défaut : true)

  Si le tableau de configuration d’une taille d’image est vide, l’image sera enregistrée en tant que copie exacte de la source sans redimensionnement ni recadrage.

  Exemple :

return [
        'small' => [
                'w' => 60,
                'h' => 60,
                'square' => true,
                'upscale' => true,
        ],
        'large' => [
                'w' => 600,
                'h' => 600,
                'upscale' => false,
        ],
        'original' => [],
];

entity:icon:url, <entity_type>

Déclenché lorsque l’URL de l’icône de l’entité est demandée, voir les icônes des entités. La fonction de rappel doit renvoyer l’URL de l’icône de dimension $params['size'] pour l’entité $params['entity']. Les paramètres suivants sont disponibles via le tableau $params :

entity

Entité pour laquelle l’url de l’icône est demandée.

viewtype

Le type de vue, par exemple 'default' ou 'json'.

size

Dimension demandée, voir les icônes des entités pour les valeurs possibles.

Exemple sur comment mettre en place une icône par défaut Gravatar pour les utilisateurs qui n’ont pas encore téléchargé un avatar :

// Priority 600 so that handler is triggered after avatar handler
elgg_register_event_handler('entity:icon:url', 'user', 'gravatar_icon_handler', 600);

/**
 * Default to icon from gravatar for users without avatar.
 *
 * @param \Elgg\Event $event 'entity:icon:url', 'user'
 *
 * @return string
 */
function gravatar_icon_handler(\Elgg\Event $event) {
        $entity = $event->getEntityParam();

        // Allow users to upload avatars
        if ($entity->icontime) {
                return $url;
        }

        // Generate gravatar hash for user email
        $hash = md5(strtolower(trim($entity->email)));

        // Default icon size
        $size = '150x150';

        // Use configured size if possible
        $config = elgg_get_icon_sizes('user');
        $key = $event->getParam('size');
        if (isset($config[$key])) {
                $size = $config[$key]['w'] . 'x' . $config[$key]['h'];
        }

        // Produce URL used to retrieve icon
        return "http://www.gravatar.com/avatar/$hash?s=$size";
}

entity:<icon_type>:url, <entity_type>

Permet de filtrer les URLs pour les types d’icônes personnalisés, voir entity:icon:url, <entity_type>

entity:icon:file, <entity_type>

Déclenché par ElggEntity::getIcon(), et permet aux plugins de fournir un objet alternatif ElggIcon qui pointe vers un emplacement personnalisé de l’icône dans le répertoire de fichiers. Le gestionnaire doit renvoyer une instance de ElggIcon ou une exception sera lancée.

entity:<icon_type>:file, <entity_type>

Permet de filtrer l’objet du fichier d’icône pour les types d’icônes personnalisés ; voyez entity:icon:file, <entity_type>

entity:<icon_type>:prepare, <entity_type>

Déclenché par les méthodes ElggEntity::saveIcon*() et peut être utilisé pour préparer une image à partir d’un fichier téléchargé ou lié. Cet événement peut être utilisé par ex. pour faire pivoter l’image avant qu’elle ne soit redimensionnée/recadrée, ou peut être utilisé pour extraire une image si le fichier téléchargé est une vidéo. Le gestionnaire doit renvoyer une instance de ElggFile avec un simpletype qui se résout en image. La valeur $return transmise à l’événement est une instance de ElggFile qui pointe vers une copie temporaire du fichier téléchargé ou lié.

Le tableau $params contient :

• entity - entité propriétaire des icônes

• file - fichier d’entrée original avant qu’il ne soit modifié par d’autres événements

entity:<icon_type>:save, <entity_type>

Déclenché par les méthodes ElggEntity:::saveIcon*(), et qui peut être utilisé pour appliquer une logique de manipulation d’image personnalisée pour redimensionner/recadrer les icônes. Le gestionnaire doit renvoyer true pour empêcher les API du noyau de redimensionner/rogner les icônes. Le tableau $params contient :

• entity - entité propriétaire des icônes

• file - objet ElggFile qui pointe vers le fichier image à utiliser comme source pour les icônes

• x1, y1, x2, y2 - coordonnées de découpe

entity:<icon_type>:saved, <entity_type>

Déclenché par les méthodes ElggEntity::saveIcon*() une fois les icônes créées. Cet événement peut être utilisé par les plugins pour créer des éléments dans la rivière, mettre à jour les coordonnées de recadrage pour les types d’icônes personnalisés, etc. Le gestionnaire peut accéder aux icônes créées en utilisant ElggEntity::getIcon(). Le tableau $params contient :

• entity - entité propriétaire des icônes

• x1, y1, x2, y2 - coordonnées de découpe

entity:<icon_type>:delete, <entity_type>

Déclenché par la méthode ElggEntity::deleteIcon() et peut être utilisé pour les opérations de nettoyage. Cet événement est déclenché avant la suppression des icônes. Le gestionnaire peut renvoyer false pour empêcher la suppression des icônes. Le tableau $params contient :

• entity - entité propriétaire des icônes

entity:url, <entity_type>

Renvoie l’URL de l’entité $params['entity']. Remarque : Généralement, il est préférable de remplacer la méthode getUrl() d’ElggEntity. Cet événement doit être utilisé lorsqu’il n’est pas possible de sous-classer (comme si vous souhaitez étendre un plugin fourni sans remplacer de nombreuses vues).

extender:url, <annotation|metadata>

Renvoie l’URL de l’annotation ou les métadonnées $params['extender'].

fields, <entity_type>:<entity_subtype>

Renvoie un tableau de champs utilisable par elgg_view_field(). Le résultat doit être renvoyé sous la forme d’un tableau de champs. Il est nécessaire de fournir name et #type pour chaque champ.

$result = [];

$result[] = [
        '#type' => 'longtext',
        'name' => 'description',
];

return $result;

get_list, default_widgets

Filtre une liste de widgets par défaut à ajouter pour les utilisateurs nouvellement enregistrés. La liste est un tableau de tableaux dans le format :

array(
        'name' => elgg_echo('name'),
        'widget_columns' => 3,
        'widget_context' => $widget_context,

        'event_name' => $event_name,
        'event_type' => $event_type,

        'entity_type' => $entity_type,
        'entity_subtype' => $entity_subtype,
)

handlers, widgets

Déclenché lorsqu’une liste de widgets disponibles est nécessaire. Les plugins peuvent ajouter ou supprimer des widgets de cette liste de manière conditionnelle, ou modifier des attributs de widgets existants comme context ou multiple.

maintenance:allow, url

Retourne un booléen si l’URL $params['current_url'] et le chemin $params['current_path']

sont autorisés pendant le mode de maintenance.

plugin_setting, <entity type>

Peut être utilisé pour modifier la valeur du paramètre en cours d’enregistrement

Params contient : - entity - L”ElggEntity où le paramètre du plugin est enregistré - plugin_id - L’ID du plugin pour lequel le paramètre est enregistré - name - Le nom du paramètre en cours d’enregistrement - valeur - La valeur d’origine du paramètre en cours d’enregistrement

La valeur de retour doit être un scalaire afin de pouvoir l’enregistrer dans la base de données. Une erreur sera journalisée si ce n’est pas le cas.

public_pages, walled_garden

Filtre une liste d’URLs (chemins) qui peuvent être vues par les utilisateurs déconnectés en mode jardin clos - walled garden. Les gestionnaires doivent renvoyer un tableau de chaînes regex qui autoriseront l’accès si elles correspondent. Veuillez noter que les routes publiques du système sont transmises comme valeur par défaut à l’événement et que les plugins doivent veiller à ne pas remplacer accidentellement ces valeurs.

Le tableau $params contient :

• url - URL de la page testée pour l’accessibilité publique

relationship:url, <relationship_name>

Filtre l’URL pour l’objet de la relation $params['relationship'].

robots.txt, site

Filtre les valeurs de robots.txt pour $params['site'].

setting, plugin

Filtre les paramètres du plugin. $params contient :

• plugin - Une instance de ElggPlugin

• plugin_id - L’ID du plugin

• name - Le nom du paramètre

• value - La valeur à définir

to:object, <entity_type|metadata|annotation|relationship|river_item>

Convertit l’entité $params['entity'] en objet StdClass. Ceci est utilisé principalement pour exporter des propriétés d’entité vers des formats de données portables comme JSON et XML.

Plugins

Groupes

tool_options, group

Filtre une collection d’outils disponibles au sein d’un groupe spécifique :

Le retour $return est \Elgg\Collections\Collection<\Elgg\Groups\Tool>, une collection d’outils de groupe.

Le tableau $params contient :

• entity - \ElggGroup

Web Services

register, api_methods``

Déclenché lors de la construction de l’ApiRegistrationService, ce qui permet d’ajouter/supprimer/modifier des configurations de webservice

rest, init

Déclenché par le gestionnaire de webservices rest. Les plugins peuvent configurer leurs propres gestionnaires d’authentification, puis renvoyer true pour empêcher les gestionnaires par défaut d’être enregistrés.

rest:output, <method_name>

Filtrer le résultat (et par la suite la sortie) de la méthode API

Système de fichier

Répertoire de fichiers

Emplacement

Le répertoire de fichiers de Elgg est situé dans le dataroot du site, configuré pendant l’installation, et qui peut être modifié via les paramètres du site dans l’interface Admin.

Structure du répertoire

La structure du répertoire de fichiers est liée à la propriété des fichiers par les entités Elgg. Chaque fois que le premier fichier appartenant à une entité est écrit dans le répertoire de fichiers, un répertoire correspondant au GUID de l’entité sera créé dans le répertoire bucket parent (les buckets sont de 5000 guids). Par exemple, les fichiers appartenant à l’utilisateur avec le guid 7777 seront situés dans 5000/7777/.

Lorsque des fichiers sont créés, les noms de fichiers peuvent contenir des noms de sous-répertoires (souvent appelés $prefix dans le code). Par exemple, les avatars de l’utilisateur ci-dessus, peuvent être trouvés dans 5000/7777/profile/.

Objets Fichier - File

Écrire des fichiers

Pour écrire un fichier dans le répertoire de fichiers, vous utiliseriez une instance de ElggFile. Même si ElggFile étend ElggObject et peut être stocké comme une entité Elgg réelle, ce n’est pas toujours nécessaire (par exemple pour la création des miniatures d’une image).

$file = new ElggFile();
$file->owner_guid = 7777;
$file->setFilename('portfolio/files/sample.txt');
$file->open('write');
$file->write('Contents of the file');
$file->close();

// to uprade this file to an entity
$file->save();

Lire des fichiers

Vous pouvez lire le contenu du fichier en utilisant une instance de ElggFile.

// from an Elgg entity
$file = get_entity($file_guid);
readfile($file->getFilenameOnFilestore());

// arbitrary file on the filestore
$file = new ElggFile();
$file->owner_guid = 7777;
$file->setFilename('portfolio/files/sample.txt');

// option 1
$file->open('read');
$contents = $file->grabFile();
$file->close();

// option 2
$contents = file_get_contents($file->getFilenameOnFilestore());

Servir des fichiers

Vous pouvez servir des fichiers depuis le répertoire de fichiers en utilisant elgg_get_inline_url() et elgg_get_download_url(). Les deux fonctions acceptent 3 arguments :

• ``file`` Une instance de ElggFile à servir

• ``use_cookie`` Si défini à true, la validité de l’URL sera limitée à la session actuelle

• ``expires`` Temps d’expiration de l’URL

Vous pouvez utiliser les arguments use_cookie et expires comme moyen de contrôle d’accès. Par exemple, dans la plupart des cas, les avatars des utilisateurs ont un long délai d’expiration et n’ont pas besoin d’être limités à la session en cours - ce qui permettra aux navigateurs de mettre en cache les images. Le service de fichiers enverra les en-têtes Not Modified appropriés aux requêtes suivantes.

Le comportement par défaut de use_cookie peut être contrôlé sur la page des paramètres de sécurité de l’administrateur.

Pour les entités qui utilisent le contrôle d’accès de Elgg, vous pouvez utiliser des cookies pour vous assurer que les paramètres d’accès sont respectés et que les utilisateurs ne partagent pas les URLs de téléchargement avec d’autres personnes.

Vous pouvez également invalider toutes les URLs précédemment générées en mettant à jour l’heure de modification du fichier, par exemple à l’aide de touch().

Intégrer des fichiers

Veuillez noter qu’en raison de leur nature, les URLs en ligne - inline - et de téléchargement ne sont pas adaptées à l’intégration - embed. Les URLs d’intégration doivent être permanentes, tandis que les URLs en ligne et de téléchargement sont volatiles (liées à la session utilisateur et à l’heure de modification des fichiers).

Pour intégrer une icône d’entité, utilisez elgg_get_embed_url().

Gérer l’envoi de fichiers

Pour implémenter une action qui enregistre un unique fichier envoyé par un utilisateur, vous pouvez utiliser l’approche suivante :

// in your form
echo elgg_view('input/file', [
        'name' => 'upload',
        'label' => 'Select an image to upload',
        'help' => 'Only jpeg, gif and png images are supported',
]);

// in your action
$uploaded_file = elgg_get_uploaded_file('upload');
if (!$uploaded_file) {
        return elgg_error_response("No file was uploaded");
}

$supported_mimes = [
        'image/jpeg',
        'image/png',
        'image/gif',
];

$mime_type = elgg()->mimetype->getMimeType($uploaded_file->getPathname());
if (!in_array($mime_type, $supported_mimes)) {
        return elgg_error_response("{$mime_type} is not supported");
}

$file = new ElggFile();
$file->owner_guid = elgg_get_logged_in_user_guid();
if ($file->acceptUploadedFile($uploaded_file)) {
        $file->save();
}

Si votre champ de saisie de fichiers supporte plusieurs fichiers, vous pouvez les parcourir dans votre action :

// in your form
echo elgg_view('input/file', [
        'name' => 'upload[]',
        'multiple' => true,
        'label' => 'Select images to upload',
]);

// in your action
foreach (elgg_get_uploaded_files('upload') as $upload) {
        $file = new ElggFile();
        $file->owner_guid = elgg_get_logged_in_user_guid();
        if ($file->acceptUploadedFile($upload)) {
                $file->save();
        }
}

Note

Si des images sont chargées une tentative est faite pour corriger automatiquement l’orientation de l’image.

Fichiers temporaires

Si jamais vous avez besoin d’un fichier temporaire vous pouvez utiliser elgg_get_temp_file(). Vous obtiendrez une instance de ElggTempFile qui a toutes les fonctions de ElggFile, mais écrit ses données dans le répertoire temporaire du système.

Avertissement

Il n’est pas possible d’enregistrer ElggTempFile dans la base de données. Vous obtiendrez une Elgg\Exceptions\Filesystem\IOException si vous essayez.

Outils du groupe

Les groupes Elgg permettent aux administrateurs de groupe d’activer/désactiver divers outils disponibles au sein d’un groupe. Ces outils sont fournis par d’autres plugins tels que blog ou file.

Les plugins peuvent accéder au registre des outils du groupe via elgg()->group_tools.

elgg()->group_tools->register('my-tool', [
        'default_on' => false, // default is true
        'label' => elgg_echo('my-tool:checkbox:label'),
        'priority' => 300, // display this earlier than other modules/tools
]);

Un outil enregistré aura la possibilité d’être activé sur le formulaire d’édition d’un groupe, et peut avoir un module d’affichage de profil qui lui est associé. Pour ajouter un module de profil, il suffit d’ajouter une vue correspondante groups/profile/module/<tool_name>. Cette vue ne sera appelée que si l’outil est activé.

Si vous souhaitez simplement lister certains contenus dans le groupe, vous pouvez utiliser la vue groups/profile/module avec quelques paramètres supplémentaires.

• entity_type : en combinaison avec le entity_subtype, il peut générer tout ce dont le module a besoin

• entity_subtype : en combinaison avec le entity_type, il peut générer tout ce dont le module a besoin

• no_results : texte personnalisé si aucun résultat n’est trouvé

Les éléments suivants seront générés automatiquement :

• title : basé sur la clef de traduction collection:<entity_type>:<entity_subtype>:group

• content : elgg_list_entities() basé sur un type/sous-type donné

• all_link : basé sur le nom de route collection:<entity_type>:<entity_subtype>:group

• add_link : basé sur le nom de route add:<entity_type>:<entity_subtype>:group et avec une vérification des autorisations pour un type/sous-type donné

// file: groups/profile/module/my-tool.php

// if you wish to list some content (eg. files) in the group
// you can use the following
$params = [
        'entity_type' => 'object',
        'entity_subtype' => 'file',
        'no_results' => elgg_echo('file:none'),
];
$params = $params + $vars;

echo elgg_view('groups/profile/module', $params);

Vous pouvez également générer votre propre titre et contenu

// file: groups/profile/module/my-tool.php

echo elgg_view('groups/profile/module', [
        'title' => elgg_echo('my-tool'),
        'content' => 'Hello, world!',
]);

Vous pouvez activer et désactiver des outils de manière programmatique pour un groupe donné :

$group = get_entity($group_guid);

// enables the file tool for the group
$group->enableTool('file');

// disables the file tool for the group
$group->disableTool('file');

Si vous voulez autoriser une certaine fonctionnalité dans un groupe seulement si l’option du groupe pour cet outil est activée, vous pouvez vérifier en utilisant \ElggGroup::isToolEnabled($tool_option).

Il est également possible d’utiliser une fonction gardienne - gatekeeper - pour éviter l’accès à une page d’un groupe sur la base d’un outil activé.

elgg_group_tool_gatekeeper('file', $group);

Voir aussi

Lisez-en plus sur les gardiens - gatekeepers - ici : Gestionnaires d’accès - gatekeepers

Si vous avez besoin des options d’un outil de groupe configurées pour un groupe spécifique, vous pouvez utiliser la fonction elgg()->group_tools->group($group).

Recommandations pour le développement de plugins

En plus des Standards de Développement Elgg - Elgg Coding Standards -, voici des recommandations pour créer des plugins. Les plugins du noyau sont mis à jour vers ce format et tous les auteurs de plugins devraient suivre ces recommandations pour leurs propres plugins.

Voir aussi

Assurez-vous de suivre Squelette du plugin pour la structure de votre plugin.

Avertissement

Ne modifiez pas le cœur

Utilisez le routage standardisé avec vos gestionnaires de pages

• Exemple : plugin des signets - Bookmarks

• Les gestionnaires de pages devraient accepter le standard d’URLs suivant :

  Objectif	URL
  Tout	page_handler/all
  Utilisateur	page_handler/owner/<username>
  Contacts du membre	page_handler/friends/<username>
  Entité unique	page_handler/view/<guid>/<title>
  Ajout	page_handler/add/<container_guid>
  Modification	page_handler/edit/<guid>
  Liste du groupe	page_handler/group/<guid>/owner

• Incluez les scripts du gestionnaire de page à partir du gestionnaire de page. Presque tous les gestionnaires de page doivent avoir un script de gestionnaire de page. (Exemple : bookmarks/all => mod/bookmarks/views/default/resources/bookmarks/all.php)

• Passez des arguments tels que des guids d’entités à la vue de la ressource via $vars dans elgg_view_resource().

• Appelez elgg_gatekeeper() et elgg_admin_gatekeeper() dans la fonction du gestionnaire de page si nécessaire.

• L’URL d’un groupe doit utiliser des vues telles que resources/groups/*.php pour afficher des pages.

• Les gestionnaires de pages ne devraient pas contenir de HTML.

Utilisez les gestionnaires de pages standardisés et les scripts

• Exemple : plugin des signets - Bookmarks

• Enregistrez les fonctionnalités des pages dans mod/<plugin>/views/default/resources/<page_handler>/<page_name>.php

• Utilisez elgg_view_resource('<page_handler>/<page_name>') pour les afficher.

• Utilisez la disposition de page par défaut dans les scripts du gestionnaire de pages : $content = elgg_view_layout('default', $options);

• Les scripts de gestionnaires de pages ne devraient pas contenir de HTML

• Appelle elgg_push_entity_breadcrumbs() ou elgg_push_collection_breadcrumbs() dans les scripts du gestionnaire de page.

• Nul besoin de s’inquiéter de définir le propriétaire de la page si les URLs sont dans le format standardisé

• Pour le contenu du groupe, vérifiez le conteneur container_guid en utilisant elgg_get_page_owner_entity()

La vue object/<subtype>

• Exemple : plugin des signets - Bookmarks

• Assurez-vous qu’il existe bien des vues pour $vars['full_view'] == true et $vars['full_view'] == false

• Recherchez l’objet dans $vars['entity'] . Utilisez elgg_instance_of() pour vous assurer qu’il s’agit du type d’entité que vous souhaitez. Renvoyez true pour court-circuiter la vue si l’entité est manquante ou erronée.

• Utilisez les nouvelles vues de liste du corps et de liste des métadonnées pour aider au formatage. Vous devriez n’utiliser quasiment aucun balisage dans ces vues.

• Mettez à jour la structure pour les actions - Exemple : le plugin Bookmarks.

• Fichiers d’action et noms d’action de l’espace de noms (exemple : mod/blog/actions/blog/save.php => action/blog/save)

• Utilisez les URLs d’action suivantes :

  Objectif	URL
  Ajout	action/plugin/save
  Modification	action/plugin/save
  Suppression	action/plugin/delete

• Faites que l’action de suppression accepte action/<handler>/delete?guid=<guid> de sorte que le menu des métadonnées de l’entité ait la bonne URL par défaut

Actions

Les actions sont des états transitoires pour effectuer une action telle que la mise à jour de la base de données ou l’envoi d’une notification à un utilisateur. Utilisées correctement, les actions fournissent un niveau de contrôle d’accès et de prévention contre les attaques CSRF.

Les actions nécessitent que les jetons d’action (CSRF) soient soumis via GET/POST, mais ceux-ci sont ajoutés automatiquement par elgg_view_form(), et à l’aide de l’argument is_action de la vue output/url.

Bonnes pratiques pour les actions

Les fichiers d’action sont inclus dans le système d’action de Elgg ; comme les vues, ce ne sont pas des scripts classiques exécutables par les utilisateurs. Ne démarrez pas le noyau de Elgg dans votre fichier et ne renvoyez pas les utilisateurs directement vers ce fichier.

Parce que les actions sont sensibles au temps, elles ne conviennent pas aux liens dans les e-mails ou autres notifications retardées. Un exemple de cela serait des invitations à rejoindre un groupe. Une manière propre de créer un lien d’invitation est de créer un gestionnaire de page pour les invitations et les e-mails qui serait lié à l’utilisateur. Il incombe alors au gestionnaire de page de créer les liens d’action pour qu’un utilisateur accepte ou ignore la demande d’invitation.

Considérez que les actions peuvent être soumises par le biais de requêtes XHR, pas seulement par des liens ou des envois de formulaires.

Appeler directement un fichier

C’est très simple : Ne le faites pas. À l’exception de l’intégration d’applications tierces, il n’y a pas de raison d’appeler directement un fichier dans le répertoire des plugins.

Recommandé

Ces points sont de bonnes idées, mais ne sont pas encore dans les recommandations officielles. Suivre ces suggestions aidera à garder votre plugin compatible avec le noyau de Elgg.

• Mettez à jour les vues du widget (voir les widgets des plugins blog ou file)

• Mettez à jour le “widget” du profil de groupe en utilisant des plugins de blog ou de fichiers comme exemple

• Mettre à jour les formulaires

  • Déplacez les corps de formulaire vers la vue forms/<handler>/<action> pour utiliser le nouveau elgg_view_form() d’Evan

  • Utilisez les vues de saisie dans le corps des formulaires, plutôt que du html

  • Ajoutez une fonction qui prépare le formulaire (voyez mod/file/lib/file.php pour un exemple)

  • Rendez vos formulaires persistants (voyez l’action de téléchargement du plugin file et la fonction de préparation du formulaire)

• Nettoyez le CSS/HTML

  • Devrait être en mesure de supprimer presque tous les CSS (recherchez des motifs qui peuvent être déplacés dans le noyau si vous avez besoin de CSS)

• Utilisez les traits- d’union plutôt que les traits de soulignement - underscores - dans les classes/ids

• N’utilisez pas la catégorie bundled avec vos plugins. Elle est réservée aux plugins distribués avec Elgg

• N’utilisez pas register_shutdown_function car vous pourriez ne plus avoir accès à certaines parties de Elgg (par ex. la base de données). Utilisez plutôt l’événement shutdown system

Fonctions d’assistance

Entrées et sorties

• get_input($name) Récupère des informations depuis un champ de formulaire (ou toute variable passée en utilisant GET ou POST). Se charge également d’assainir l’entrée, en retirant le Javascript, etc.

• set_input($name, $value) Force une valeur pour une variable particulière destinée à être récupérée par la suite par get_input()

Méthode des entités

• $entity->getURL() Renvoie l’URL de n’importe quelle entité dans le système

• $entity->getGUID() Renvoie le GUID de n’importe quelle entité dans le système

• $entity->canEdit() Indique si l’utilisateur courant est autorisé ou non à modifier l’entité

• $entity->getOwnerEntity() Retourne le propriétaire ElggUser d’une entité particulière

Récupération de l’entité et du contexte

• elgg_get_logged_in_user_entity() Retourne le ElggUser de l’utilisateur courant

• elgg_get_logged_in_user_guid() Retourne le GUID de l’utilisateur courant

• elgg_is_logged_in() Est-ce que le visiteur est identifié

• elgg_is_admin_logged_in() Est-ce que le visiteur est un admin identifié

• elgg_gatekeeper() Raccourci pour vérifier si un utilisateur est identifié. Redirige sur la page d’accueil du site si ce n’est pas le cas

• elgg_admin_gatekeeper() Raccourci pour vérifier si un utilisateur est identifié et est admin. Redirige sur la page d’accueil du site si ce n’est pas le cas

• get_user($user_guid) A partir d’un GUID, retourne l’entité ElggUser complète

• elgg_get_page_owner_guid() Retourne le GUID du propriétaire actuel, s’il y en a un

• elgg_get_page_owner_entity() Comme elgg_get_page_owner_guid() mais retourne l’entité complète

• elgg_get_context() Retourne le contexte courant de la page - par ex. « blog » pour le plugin blog, « thewire » pour le Fil, etc. Retourne « main » comme valeur par défaut

• elgg_set_context($context) Force le contexte pour une valeur particulière

• elgg_push_context($context) Ajoute un contexte à la pile de contextes

• elgg_pop_context() Retire le dernier contexte de la pile

• elgg_in_context($context) Vérifie si vous êtes dans un contexte (ceci vérifie la pile complète, par ex. “widget” dans “groups”)

Plugins

• elgg_is_active_plugin($plugin_id) Vérifie si un plugin est installé et activé

Interface et annotations

• elgg_view_image_block($icon, $info) Retourne le résultat dans un élément de liste formaté

• elgg_view_comments($entity) Retourne tous les commentaires associés à une entité donnée

• elgg_get_friendly_time($unix_timestamp) Retourne une date formatée de manière relative - « il y a 18 minutes », « il y a 2 jours », etc.

Messages

• elgg_register_success_message($message) Enregistre un message de succès

• elgg_register_error_message($message) Enregistre un message d’erreur

• elgg_view_message($type, $message) Affiche un message

Internationalisation

Rendre votre interface utilisateur traduisible dans de nombreuses langues différentes.

Si vous souhaitez contribuer à des traductions pour Elgg, consultez le guide des contributeurs.

La langue par défaut est en pour l’anglais. Elgg utilise un système de secours pour les langues :

1. La langue de l’utilisateur

2. La langue du site

3. Anglais

Aperçu

Les traductions sont stockées dans des fichiers PHP dans le répertoire /languages de votre plugin. Chaque fichier correspond à une langue. Le format est /languages/{language-code}.php où {language-code} est le code court ISO 639-1 pour la langue. Par exemple :

<?php // mod/example/languages/en.php

return [
        'example:text' => 'Some example text',
];

Pour remplacer une traduction existante, incluez-la dans le fichier de traduction de votre plugin et assurez-vous que votre plugin est situé après sur la page Admin > Plugins :

<?php // mod/better_example/languages/en.php

return [
        'example:text' => 'Some better text!',
];

Note

A moins que vous ne remplaciez les chaînes de traduction du noyau ou d’un autre plugin, c’est une bonne pratique pour les clefs de traduction de commencer par le nom de votre plugin. Par exemple : yourplugin:success, yourplugin:title, etc. Cela aide à éviter les conflits avec d’autres clefs de traduction.

API côté serveur

elgg_echo($key, $args, $language)

Génère et renvoie la traduction de la clef dans la langue actuelle.

Exemple :

echo elgg_echo('example:text');

Elle prend également en charge le remplacement des variables à l’aide de la syntaxe `` vsprintf`` :

// 'welcome' => 'Welcome to %s, %s!'
echo elgg_echo('welcome', [
        elgg_get_config('sitename'),
        elgg_get_logged_in_user_entity()->getDisplayName(),
]);

Pour forcer la langue qui doit être utilisée pour la traduction, définissez le troisième paramètre :

echo elgg_echo('welcome', [], $user->language);

Pour tester d’abord si elgg_echo() peut trouver une traduction :

$key = 'key:that:might:not:exist';
if (!elgg_language_key_exists($key)) {
        $key = 'fallback:key';
}

echo elgg_echo($key);

Note

Certaines API permettent de créer des traductions pour de nouvelles clefs. Les traducteurs doivent toujours inclure une traduction anglaise comme solution de repli. Ceci fait de elgg_language_key_exists($key) un moyen fiable de prédire si elgg_echo($key) va réussir.

API Javascript

i18n.echo(key, args)

Cette fonction est équivalente à elgg_echo en PHP.

Les traductions côté client sont chargées de façon asynchrone. Assurez-vous que les traductions sont disponibles en exigeant le module AMD elgg :

define(['elgg/i18n'], function(i18n) {
        alert(i18n.echo('my_key'));
});

Les traductions sont également disponibles après l’événement JavaScript init, system.

JavaScript

AMD

Les développeurs doivent utiliser le standard AMD (« Asynchronous Module Definition » ou Définition du module asynchrone) pour écrire du code JavaScript dans Elgg.

Ici, nous allons décrire la création et l’exécution de modules AMD. La documentation RequireJS pour définir des modules peut également être utile.

Exécuter un module dans la page en cours

Il est aisé d’indiquer à Elgg de charger un module existant dans la page en cours :

<?php
elgg_require_js("myplugin/say_hello");

Du côté client, cela chargera le module de manière asynchrone, chargera toutes les dépendances, et exécutera la fonction de définition du module, s’il en dispose d’une.

Définir le Module

Ici, nous définissons un module de base qui modifie la page, en passant une « fonction de définition » à define() :

// in views/default/myplugin/say_hello.js

define(['jquery', 'elgg/i18n'], function($, i18n) {
    $('body').append(i18n.echo('hello_world'));
});

Le nom du module est déterminé par le nom de vue, qui est ici myplugin/say_hello.js. Nous retirons l’extension .js, pour conserver myplugin/say_hello.

Avertissement

La fonction de définition doit avoir un argument nommé require.

Rendre les modules dépendants d’autres modules

Ci-dessous nous factorisons un peu de sorte que le module dépende d’un nouveau module monplugin/hello pour fournir la salutation :

// in views/default/myplugin/hello.js

define(['elgg/i18n'], function(i18n) {
    return i18n.echo('hello_world');
});

// in views/default/myplugin/say_hello.js

define(['jquery', 'myplugin/hello'], function($, hello) {
    $('body').append(hello);
});

Passer des paramètres aux modules

Les événements elgg.data

Le module elgg fournit un objet elgg.data qui est renseigné à partir de deux événements côté serveur :

• elgg.data, site : Ceci filtre un tableau associatif de données spécifiques au site, transmises au client et mises en cache.

• elgg.data, page : Ceci filtre un tableau associatif de données non mises en cache, et spécifiques à la page transmise au client.

Passons quelques données au module :

<?php

function myplugin_config_site(\Elgg\Event $event) {
    $value = $event->getValue();

    // this will be cached client-side
    $value['myplugin']['api'] = elgg_get_site_url() . 'myplugin-api';
    $value['myplugin']['key'] = 'none';

    return $value;
}

function myplugin_config_page(\Elgg\Event $event) {
    $user = elgg_get_logged_in_user_entity();
    if (!$user) {
            return;
    }

    $value = $event->getValue();

    $value['myplugin']['key'] = $user->myplugin_api_key;

    return $value;
}

elgg_register_event_handler('elgg.data', 'site', 'myplugin_config_site');
elgg_register_event_handler('elgg.data', 'page', 'myplugin_config_page');

define(['elgg'], function(elgg) {
    var api = elgg.data.myplugin.api;
    var key = elgg.data.myplugin.key; // "none" or a user's key

    // ...
});

Note

Dans elgg.data les données de la page remplacent les données du site. Notez également que json_encode() est utilisé pour copier les données côté client, de sorte que les données doivent être encodables en JSON.

Créer un module de configuration

Vous pouvez utiliser un module PHP pour transmettre des valeurs à partir du serveur. Pour créer le module myplugin/settings, créez le fichier de la vue views/default/myplugin/settings.js.php (notez la double extension .js.php).

<?php

// this will be cached client-side
$settings = [
    'api' => elgg_get_site_url() . 'myplugin-api',
    'key' => null,
];
?>
define(<?php echo json_encode($settings); ?>);

Vous devez également enregistrer manuellement la vue en tant que ressource externe :

<?php
// note the view name does not include ".php"
elgg_register_simplecache_view('myplugin/settings.js');

Note

La vue PHP est mise en cache, vous devez donc traiter la sortie comme statique (la même pour tous les utilisateurs) et éviter toute logique spécifique à la session.

Définir l’URL d’un module

Vous pouvez avoir un script AMD en dehors de vos vues que vous souhaitez mettre à disposition en tant que module.

La meilleure façon d’y parvenir est de configurer le chemin d’accès au fichier à l’aide de la section views du fichier elgg-plugin.php dans la racine de votre plugin :

<?php // elgg-plugin.php
return [
    'views' => [
            'default' => [
                'underscore.js' => 'vendor/npm-asset/underscore/underscore.min.js',
            ],
    ],
];

Si vous avez copié le script directement dans votre plugin au lieu de le gérer avec Composer, vous pouvez utiliser quelque chose comme ceci à la place :

<?php // elgg-plugin.php
return [
    'views' => [
            'default' => [
                'underscore.js' => __DIR__ . '/node_modules/underscore/underscore.min.js',
            ],
    ],
];

Voilà ! Elgg chargera maintenant ce fichier chaque fois que le module « underscore » est requis.

Utiliser des bibliothèques JS traditionnelles comme modules

Il est possible de prendre en charge les bibliothèques JavaScript qui ne se déclarent pas comme modules AMD (c’est-à-dire qu’elles déclarent plutôt des variables globales) si vous les intégrez via des shims en définissant exports et deps dans elgg_define_js :

// set the path, define its dependencies, and what value it returns
elgg_define_js('jquery.form', [
    'deps' => ['jquery'],
    'exports' => 'jQuery.fn.ajaxForm',
]);

Lorsque cela est demandé côté client :

1. Le module jQuery est chargé, car il est marqué comme une dépendance.

2. https://elgg.example.org/cache/125235034/views/default/jquery.form.js est chargé et exécuté.

3. La valeur de window.jQuery.fn.ajaxForm est renvoyée par le module.

Avertissement

Les appels à elgg_define_js() doivent être faits dans un gestionnaire d’événement init, system.

Quelques points à noter

1. Renvoie la valeur du module au lieu de l’ajouter à une variable globale.

2. Les fichiers statiques (.js, .css, etc.) sont automatiquement minifiés et mis en cache par le système simplecache de Elgg.

3. La configuration est également mise en cache dans le simplecache, et ne doit pas s’appuyer sur des valeurs spécifiques à l’utilisateur comme get_current_language().

Modules fournis avec Elgg

Module elgg

elgg.normalize_url()

Normalise une URL par rapport à la racine de elgg :

// "http://localhost/elgg/blog"
elgg.normalize_url('/blog');

elgg.forward()

Redirige vers une nouvelle page.

elgg.forward('/blog');

Cette fonction normalise automatiquement l’URL.

elgg.parse_url()

Analyse et découpe une URL en ses composants :

// returns {
//   fragment: "fragment",
//   host: "community.elgg.org",
//   path: "/file.php",
//   query: "arg=val"
// }
elgg.parse_url('http://community.elgg.org/file.php?arg=val#fragment');

elgg.get_logged_in_user_guid()

Renvoie le GUID de l’utilisateur connecté.

elgg.is_logged_in()

Vrai si l’utilisateur est connecté.

elgg.is_admin_logged_in()

Vrai si l’utilisateur est connecté et est administrateur.

Un certain nombre de valeurs de configuration sont définies dans l’objet elgg :

// The root of the website.
elgg.config.wwwroot;
// The default site language.
elgg.config.language;
// The Elgg release (X.Y.Z).
elgg.config.release;

Module elgg/Ajax

Voir la page Ajax pour plus de détails.

Module elgg/hooks

Le module elgg/hooks peut être utilisé pour faire interagir les plugins entre eux.

Traduisez le texte de l’interface

define(['elgg/hooks'], function (hooks) {
    hooks.register('my_plugin:filter', 'value', handler, priority);

    var result = hooks.trigger('my_plugin:filter', 'value', {}, 'default');

Module elgg/i18n

Le module elgg/i18n peut être utilisé pour utiliser les traductions.

Traduisez le texte de l’interface

define(['elgg/i18n'], function (i18n) {
    i18n.echo('example:text', ['arg1']);
});

Module elgg/system_messages

Le module elgg/system_messages peut être utilisé pour afficher les messages système à l’utilisateur.

define(['elgg/system_messages'], function (system_messages) {
    system_messages.success('Your success message');

    system_messages.error('Your error message');

    system_messages.clear();
});

Module elgg/security

Le module elgg/security peut être utilisés pour ajouter un jeton de sécurité à un objet, une URL, ou une chaîne de requête :

     define(['elgg/security'], function (security) {
    // returns {
        //   __elgg_token: "1468dc44c5b437f34423e2d55acfdd87",
        //   __elgg_ts: 1328143779,
        //   other: "data"
        // }
        security.addToken({'other': 'data'});

        // returns: "action/add?__elgg_ts=1328144079&__elgg_token=55fd9c2d7f5075d11e722358afd5fde2"
        security.addToken("action/add");

        // returns "?arg=val&__elgg_ts=1328144079&__elgg_token=55fd9c2d7f5075d11e722358afd5fde2"
        security.addToken("?arg=val");
});

Module elgg/spinner

Le module elgg/spinner peut être utilisé pour créer un indicateur de chargement fixé en haut de la fenêtre. Cela peut être utilisé pour indiquer aux utilisateurs que le système exécute une tâche plus longue. L’utilisation des fonctionnalités ajax de elgg/Ajax le fait par défaut. Vous pouvez également l’utiliser dans votre propre code.

define(['elgg/spinner'], function (spinner) {
    spinner.start();
    // your code
    spinner.stop();
});

Module elgg/popup

Le module elgg/popup peut être utilisé pour afficher une superposition - overlay - placée relativement à son ancre (déclencheur - trigger).

Le module elgg/popup est automatiquement chargé pour le contenu dessiné en utilisant output/url avec l’attribut class='elgg-popup' et en définissant le module cible avec un attribut href (ou data-href). Le positionnement du module contextuel peut être défini avec l’attribut data-position de l’élément déclencheur.

echo elgg_format_element('div', [
   'class' => 'elgg-module-popup hidden',
   'id' => 'popup-module',
], 'Popup module content');

// Simple anchor
echo elgg_view('output/url', [
   'href' => '#popup-module',
   'text' => 'Show popup',
   'class' => 'elgg-popup',
]);

// Button with custom positioning of the popup
elgg_require_js('elgg/popup');
echo elgg_format_element('button', [
   'class' => 'elgg-button elgg-button-submit elgg-popup',
   'text' => 'Show popup',
   'data-href' => '#popup-module',
   'data-position' => json_encode([
      'my' => 'center bottom',
      'at' => 'center top',
   ]),
]);

Le module elgg/popup vous permet de créer des éléments d’interface utilisateur/UX plus complexes. Vous pouvez ouvrir et fermer les modules contextuels via le code :

define(['jquery', 'elgg/popup'], function($, popup) {
   $(document).on('click', '.elgg-button-popup', function(e) {

      e.preventDefault();

      var $trigger = $(this);
      var $target = $('#my-target');
      var $close = $target.find('.close');

      popup.open($trigger, $target, {
         'collision': 'fit none'
      });

      $close.on('click', popup.close);
   });
});

Vous pouvez utiliser le hook plugin getOptions, ui.popup pour manipuler la position du popup avant qu’il soit ouvert. Vous pouvez utiliser les événements jQuery open et close pour manipuler le module popup après son ouverture ou sa fermeture.

define(['jquery', 'elgg/Ajax'], function($, Ajax) {

   $('#my-target').on('open', function() {
      var $module = $(this);
      var $trigger = $module.data('trigger');
      var ajax = new Ajax();

      ajax.view('my_module', {
         beforeSend: function() {
            $trigger.hide();
            $module.html('').addClass('elgg-ajax-loader');
         },
         success: function(output) {
            $module.removeClass('elgg-ajax-loader').html(output);
         }
      });
   }).on('close', function() {
      var $trigger = $(this).data('trigger');
      $trigger.show();
   });
});

Les modules popups ouverts contiennent toujours les données suivantes auxquelles il est possible d’accéder via $.data() :

• trigger - élément jQuery utilisé pour déclencher l’ouverture du module popup

• position - Un objet définissant la position du module popup qui a été passé à $.position()

Par défaut, l’élément target sera ajouté à $('body'), modifiant ainsi la hiérarchie DOM. Si vous devez conserver la position DOM du module popup, vous pouvez ajouter la classe .elgg-popup-inline à votre déclencheur.

Module elgg/widgets

Des plugins qui chargent une mise en page widget via Ajax devraient s’initialiser via ce module :

require(['elgg/widgets'], function (widgets) {
    widgets.init();
});

Module elgg/lightbox

Elgg est distribué avec la bibliothèque jQuery Colorbox. Veuillez consulter https://www.jacklmoore.com/colorbox/ pour plus d’informations sur les options de cette lightbox.

Utilisez les classes suivantes pour lier vos éléments d’ancrage à des boîtes surgissantes lightbox :

• elgg-lightbox - charge une ressource HTML

• elgg-lightbox-photo - charge une ressource de type image (devrait être utilisé pour éviter d’afficher les octets d’image bruts au lieu de la balise img)

• elgg-lightbox-inline - affiche un élément HTML en ligne dans une boîte surgissante - lightbox

• elgg-lightbox-iframe - charge une ressource dans une iframe

Vous pouvez appliquer des options de colorbox à un élément individuel elgg-lightbox en définissant l’attribut data-colorbox-opts avec un objet de paramètres JSON.

echo elgg_view('output/url', [
   'text' => 'Open lightbox',
   'href' => 'ajax/view/my_view',
   'class' => 'elgg-lightbox',
   'data-colorbox-opts' => json_encode([
      'width' => '300px',
   ])
]);

Utilisez le hook plugin "getOptions", "ui.lightbox" pour filtrer les options passées à $.colorbox() chaque fois qu’une lightbox est ouverte.

Le module AMD elgg/lightbox devrait être utilisé pour ouvrir et fermer la lightbox de manière programmatique :

define(['elgg/lightbox', 'elgg/spinner'], function(lightbox, spinner) {
   lightbox.open({
      html: '<p>Hello world!</p>',
      onClosed: function() {
         lightbox.open({
            onLoad: spinner.start,
            onComplete: spinner.stop,
            photo: true,
            href: 'https://elgg.org/cache/1457904417/default/community_theme/graphics/logo.png',
         });
      }
   });
});

Pour prendre en charge des ensembles de galerie (via l’attribut rel), vous devez lier colorbox directement à un sélecteur spécifique (notez que cela ignorera data-colorbox-opts sur tous les éléments d’un ensemble) :

require(['elgg/lightbox'], function(lightbox) {
   var options = {
      photo: true,
      width: 500
   };
   lightbox.bind('a[rel="my-gallery"]', options, false); // 3rd attribute ensures binding is done without proxies
});

Vous pouvez également redimensionner la lightbox via le code si nécessaire :

define(['elgg/lightbox'], function(lightbox) {
   lightbox.resize({
      width: '300px'
   });
});

Si vous souhaitez que votre contenu soit chargé par le module AMD elgg/Ajax, qui charge automatiquement les dépendances JS, vous pouvez passer l’option ajaxLoadWithDependencies

define(['elgg/lightbox'], function(lightbox) {
   lightbox.open({
      href: 'some/view/with/js/dependencies',
      ajaxLoadWithDependencies: true
   });
});

Module elgg/ckeditor

Ce module peut être utilisé pour ajouter un éditeur WYSIWYG à un textarea (nécessite que le plugin ckeditor soit activé). Notez que le WYSIWYG sera automatiquement attaché à toutes les instances de .elgg-input-longtext.

require(['elgg/ckeditor'], function (elggCKEditor) {
   elggCKEditor.bind('#my-text-area');

   // Toggle CKEditor
   elggCKEditor.toggle('#my-text-area');

   // Focus on CKEditor input
   elggCKEditor.focus('#my-text-area');
   // or
   $('#my-text-area').trigger('focus');

   // Reset CKEditor input
   elggCKEditor.reset('#my-text-area');
   // or
   $('#my-text-area').trigger('reset');

});

Composant d’onglets en ligne

Le composant d’onglets en ligne déclenche un événement open chaque fois qu’un onglet est ouvert et, en cas d’onglets ajax, une fois le chargement terminé :

// Add custom animation to tab content
require(['jquery'], function($) {
        $(document).on('open', '.theme-sandbox-tab-callback', function() {
                $(this).find('a').text('Clicked!');
                $(this).data('target').hide().show('slide', {
                        duration: 2000,
                        direction: 'right',
                        complete: function() {
                                alert('Thank you for clicking. We hope you enjoyed the show!');
                                $(this).css('display', ''); // .show() adds display property
                        }
                });
        });
});

Scripts traditionnels

Bien que nous recommandons fortement d’utiliser les modules AMD et qu’il n’y ait pas d’API Elgg pour charger les scripts, vous pouvez enregistrer des scripts dans un gestionnaire d’événements pour ajouter des éléments aux liens principaux ;

elgg_register_event_handler('head', 'page', $callback);

Hooks

Le moteur JS dispose d’un système de hooks similaire aux événements du moteur PHP : les hooks sont déclenchés et les plugins peuvent enregistrer des fonctions pour réagir ou modifier des informations.

Enregistrer des gestionnaires de hook

Les fonctions du gestionnaire sont enregistrées en utilisant hooks.register(). Plusieurs gestionnaires peuvent être enregistrés pour le même hook.

define(['elgg/hooks'], function(hooks) {
    hooks.register('name', 'type', {handler}, {priority});
});

La fonction gestionnaire - handler

Le gestionnaire va recevoir 4 arguments :

• hook - Le nom du hook

• type - Le type de hook

• params - Un objet ou un ensemble de paramètres propres au hook

• value - La valeur actuelle

La valeur value passera par chaque hook. Selon le hook, les fonctions de rappel peuvent simplement réagir, ou modifier les données.

Déclencher des hooks personnalisés

Les plugins peuvent déclencher leurs propres hooks :

define(['elgg/hooks'], function(hooks) {
    hooks.trigger('name', 'type', {params}, "value");
});

Hooks disponibles

init, system

Les plugins devraient enregistrer leurs fonctions d’initialisation via ce hook. Il est déclenché après que les JS de Elgg sont chargés, et une fois que tous les modules de démarrage - boot - des plugins sont initialisés.

getOptions, ui.popup

Ce hook est déclenché pour les affichages surgissants - popups ("rel"="popup") et permet des options de positionnement personnalisées.

getOptions, ui.lightbox

Ce hook peut être utilisé pour filtrer les options transmises à $.colorbox()

config, ckeditor

Cela filtre l’objet de configuration CKEditor. Enregistrez un gestionnaire pour ce hook dans le module de démarrage du plugin. Les valeurs par défaut sont visibles dans le module elgg/ckeditor/config.

prepare, ckeditor

Ce hook peut être utilisé pour modifier globalement CKEDITOR. Vous pouvez utiliser ce hook pour enregistrer de nouveaux plugins CKEditor et ajouter des liaisons d’événements - event bindings.

ajax_request_data, *

Ceci filtre les demandes de données envoyées par le module elgg/Ajax. Voir Ajax pour plus de détails. Le hook doit vérifier si les données sont un objet simple ou une instance de FormData pour récupérer les valeurs à l’aide de la bonne API.

ajax_response_data, *

Ceci filtre les données de réponse retournées aux utilisateurs par le module elgg/Ajax. Voir Ajax pour plus de détails.

Actifs tierce-partie - assets

Nous vous recommandons de gérer des scripts et des styles tiers avec Composer. Le composer.json de Elgg est configuré pour installer des dépendances à partir des référentiels de packages NPM ou Yarn à l’aide de l’outil de ligne de commande Composer. La configuration de base installe les actifs à partir de Asset Packagist (un référentiel géré par la communauté Yii).

Alternativement, vous pouvez installer fxp/composer-asset-plugin globalement pour obtenir les mêmes résultats, mais l’installation et la mise à jour prennent beaucoup plus de temps.

Par exemple, pour inclure jQuery, vous pouvez exécuter les commandes composer suivantes :

composer require npm-asset/jquery:~2.0

Si vous utilisez un projet de démarrage - starter-project - ou que vous utilisez Elgg sous forme de dépendance d’un projet composer personnalisé, mettez à jour votre composer.json avec la configuration suivante :

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://asset-packagist.org"
        }
    ],
        "config": {
        "fxp-asset": {
            "enabled": false
        }
    },
}

Vous pouvez trouver des informations supplémentaires sur le site de Asset Packagist.

Menus

Elgg propose des fonctions d’aide pour créer des menus sur tout le site.

Chaque menu nécessite un nom, tout comme chaque élément de menu. Ceux-ci sont nécessaires pour permettre un remplacement et une manipulation faciles, ainsi que pour fournir des événements pour les thèmes.

Utilisation simple

Les fonctionnalités de base peuvent être réalisées grâce à ces deux fonctions :

• elgg_register_menu_item() pour ajouter un élément à un menu

• elgg_unregister_menu_item() pour supprimer un élément d’un menu

Vous voudrez normalement les appeler à partir de la fonction d’initialisation de votre plugin.

Exemples

// Add a new menu item to the site main menu
elgg_register_menu_item('site', array(
        'name' => 'itemname',
        'text' => 'This is text of the item',
        'href' => '/item/url',
));

// Remove the "Elgg" logo from the topbar menu
elgg_unregister_menu_item('topbar', 'elgg_logo');

Menu admin

Vous pouvez également enregistrer des éléments du menu page dans le menu de l’interface d’administration. Lorsque vous enregistrez des éléments pour le menu d’administration, vous pouvez définir le contexte des éléments de menu sur admin afin que les éléments du menu ne s’affichent que dans le contexte admin. Il existe 3 sections par défaut auxquelles ajouter vos éléments de menu.

• administer pour les tâches quotidiennes, la gestion des utilisateurs et d’autres tâches pratiques

• configure pour des paramètres, des éléments de configuration et des utilitaires qui configurent diverses choses

• information pour des statistiques, une vue d’ensemble d’informations ou de statuts

Utilisation avancée

Entêtes

Pour des raisons d’accessibilité, chaque menu recevra un aria-label qui par défaut est le nom du menu, mais peut être traduit en s’assurant que la clef de traduction menu:<menu name>:header est disponible.

Il est également possible d’afficher les entêtes des sections de menu en définissant show_section_headers sur true dans elgg_view_menu()

echo elgg_view_menu('my_menu', [
        'show_section_headers' => true,
]);

Les entêtes utilisent une clé de langage magique disponible menu:<menu name>:header:<section name> afin de pouvoir traduire les entêtes.

Événements

Vous pouvez obtenir plus de contrôle sur les menus en utilisant events et les méthodes publiques fournies par la classe ElggMenuItem.

Trois événements peuvent être utilisés pour modifier un menu :

• 'parameters', 'menu:' pour ajouter ou modifier les paramètres utilisés pour construire le menu (par exemple l’ordre de tri)

• 'register', 'menu:' pour ajouter ou modifier des éléments (en particulier dans les menus dynamiques)

• 'prepare', 'menu:' pour modifier la structure du menu avant qu’il soit affiché

Lorsque vous enregistrez un gestionnaire d’événements, remplacez la partie <menu name> par le nom interne du menu.

Le troisième paramètre passé au gestionnaire de menu contient tous les éléments de menu qui ont été enregistrés jusqu’à présent par le noyau de Elgg et d’autres plugins activés. Dans le gestionnaire, nous pouvons faire une boucle à travers les éléments de menu et utiliser les méthodes de classe pour interagir avec les propriétés de l’élément de menu.

Dans certains cas, une version plus granulaire des événements de menu register et prepare existe avec menu:<menu name>:<type>:<subtype>, cela s’applique lorsque le menu reçoit un \ElggEntity dans `` $params[“entity”]`` ou un \ElggAnnotation dans $params['annotation'] ou un \ElggRelationship dans $params['relationship'].

Exemples

Exemple 1 : Modifier l’URL de l’élément de menu appelé « albums » dans le menu owner_block :

/**
 * Initialize the plugin
 */
function my_plugin_init() {
        // Register an event handler for the owner_block menu
        elgg_register_event_handler('register', 'menu:owner_block', 'my_owner_block_menu_handler');
}

/**
 * Change the URL of the "Albums" menu item in the owner_block menu
 */
function my_owner_block_menu_handler(\Elgg\Event $event) {
        $owner = $event->getEntityParam();

        // Owner can be either user or a group, so we
        // need to take both URLs into consideration:
        switch ($owner->getType()) {
                case 'user':
                        $url = "album/owner/{$owner->guid}";
                        break;
                case 'group':
                        $url = "album/group/{$owner->guid}";
                        break;
        }

        $items = $event->getValue();
        if ($items->has('albums')) {
                $items->get('albums')->setURL($url);
        }

        return $items;
}

Exemple 2 : Modifier le menu entity pour les objets ElggBlog

• Supprimer l’icône du pouce

• Modifier le texte « Modifier » en une icône personnalisée

/**
 * Initialize the plugin
 */
function my_plugin_init() {
        // Register an event handler for the entity menu
        elgg_register_event_handler('register', 'menu:entity', 'my_entity_menu_handler');
}

/**
 * Customize the entity menu for ElggBlog objects
 */
function my_entity_menu_handler(\Elgg\Event $event) {
        // The entity can be found from the $params parameter
        $entity = $event->getEntityParam();

        // We want to modify only the ElggBlog objects, so we
        // return immediately if the entity is something else
        if (!$entity instanceof ElggBlog) {
                return;
        }

        $items = $event->getValue();

        $items->remove('likes');

        if ($items->has('edit')) {
                $items->get('edit')->setText('Modify');
                $items->get('edit')->icon = 'pencil';
        }

        return $items;
}

Créer un nouveau menu

Elgg fournit plusieurs menus différents par défaut. Vous pouvez cependant avoir besoin de certains éléments de menu qui ne figurent pas dans l’un des menus existants. Si tel est le cas, vous pouvez créer votre propre menu avec la fonction elgg_view_menu(). Vous devez appeler la fonction à partir de la vue dans laquelle vous souhaitez afficher le menu.

Exemple: Afficher un menu appelé « my_menu » qui affiche ses éléments de menu dans l’ordre alphabétique :

// in a resource view
echo elgg_view_menu('my_menu', array('sort_by' => 'text'));

Vous pouvez maintenant ajouter de nouveaux éléments au menu comme ceci :

// in plugin init
elgg_register_menu_item('my_menu', array(
        'name' => 'my_page',
        'href' => 'path/to/my_page',
        'text' => elgg_echo('my_plugin:my_page'),
));

De plus il est désormais possible de modifier le menu à l’aide des événements 'register', 'menu:my_menu' et 'prepare', 'menu:my_menu'.

Sous-menus déroulants

Les sous-menus peuvent être configurés à l’aide de l’option child_menu de l’élément parent.

Le tableau d’options child_menu accepte le paramètre display, qui peut être utilisé pour définir que le menu enfant s’ouvre sous forme de liste déroulante dropdown, ou être affiché via une bascule toggle. Toutes les autres paires de clefs/valeurs seront transmises en tant qu’attributs à l’élément ul.

// Register a parent menu item that has a dropdown submenu
elgg_register_menu_item('my_menu', array(
        'name' => 'parent_item',
        'href' => '#',
        'text' => 'Show dropdown menu',
        'child_menu' => [
                'display' => 'dropdown',
                'class' => 'elgg-additional-child-menu-class',
                'data-position' => json_encode([
                        'at' => 'right bottom',
                        'my' => 'right top',
                        'collision' => 'fit fit',
                ]),
                'data-foo' => 'bar',
                'id' => 'dropdown-menu-id',
        ],
));

// Register a parent menu item that has a hidden submenu toggled when item is clicked
elgg_register_menu_item('my_menu', array(
        'name' => 'parent_item',
        'href' => '#',
        'text' => 'Show submenu',
        'child_menu' => [
                'display' => 'dropdown',
                'class' => 'elgg-additional-submenu-class',
                'data-toggle-duration' => 'medium',
                'data-foo' => 'bar2',
                'id' => 'submenu-id',
        ],
));

Création de thèmes

Le nom du menu, les noms de sections et les noms des éléments sont tous intégrés dans le HTML sous forme de classes CSS (normalisées pour ne contenir que des traits d’union, plutôt que des soulignements ou des points). Cela augmente légèrement la taille du balisage, mais procure aux intégrateurs un haut degré de contrôle et de flexibilité lors de la mise en forme du site.

Exemple : Voici la sortie du menu foo avec les sections alt et default contenant respectivement les éléments baz et bar.

<ul class="elgg-menu elgg-menu-foo elgg-menu-foo-alt">
        <li class="elgg-menu-item elgg-menu-item-baz"></li>
</ul>
<ul class="elgg-menu elgg-menu-foo elgg-menu-foo-default">
        <li class="elgg-menu-item elgg-menu-item-bar"></li>
</ul>

Basculer des éléments de menu

Il y a des situations où vous souhaitez basculer entre des éléments de menu qui sont des actions contraires l’une de l’autre, et les ajaxifier. Par exemple ajouter/retirer un contact, bannir/réintégrer, etc. Elgg dispose d’une prise en charge intégrée pour ce genre d’actions. Lorsque vous enregistrez un élément de menu, vous pouvez fournir le nom de l’élément de menu (dans le même menu) qui doit être basculé. Un appel ajax sera fait en utilisant le href de l’élément de menu.

elgg_register_menu_item('my_menu', [
        'name' => 'like',
        'data-toggle' => 'unlike',
        'href' => 'action/like',
        'text' => elgg_echo('like'),
]);

elgg_register_menu_item('my_menu', [
        'name' => 'unlike',
        'data-toggle' => 'like',
        'href' => 'action/unlike',
        'text' => elgg_echo('unlike'),
]);

Note

Les éléments de menu sont basculés de manière optimiste. Cela signifie que les éléments de menu sont basculés avant la fin des actions. Si les actions échouent, les éléments de menu seront rétablis.

JavaScript

Il est courant que les éléments de menu s’appuient sur JavaScript. Vous pouvez lier les événements côté client aux éléments du menu en plaçant votre JavaScript dans le module AMD et en définissant ses exigences lors de son enregistrement.

elgg_register_menu_item('my_menu', array(
        'name' => 'hide_on_click',
        'href' => '#',
        'text' => elgg_echo('hide:on:click'),
        'item_class' => '.hide-on-click',
        'deps' => ['navigation/menu/item/hide_on_click'],
));

// in navigation/menu/item/hide_on_click.js
define(function(require) {
    var $ = require('jquery');

    $(document).on('click', '.hide-on-click', function(e) {
        e.preventDefault();
        $(this).hide();
    });
});

Notifications

Il existe deux manières d’envoyer des notifications dans Elgg :

• Notifications instantanées

• Les notifications basées sur les événements sont envoyées à l’aide d’une file d’attente de notifications

Notifications instantanées

La méthode générique pour envoyer une notification à un utilisateur utilise la fonction notify_user(). Celle-ci devrait être principalement utilisée lorsque nous voulons notifier un seul utilisateur. Une notification comme celle-ci peut, par exemple, informer que quelqu’un a aimé ou commenté la publication de l’utilisateur.

La fonction est habituellement appelée dans un fichier d”action.

Exemple :

Dans cet exemple, un utilisateur ($user) déclenche une action pour noter une publication créée par un autre utilisateur ($owner). Après avoir enregistré la note (ElggAnnotation $rating) dans la base de données, nous pourrions utiliser le code suivant pour envoyer une notification concernant cette nouvelle note au propriétaire.

// Subject of the notification
$subject = elgg_echo('ratings:notification:subject', array(), $owner->language);

// Summary of the notification
$summary = elgg_echo('ratings:notification:summary', array($user->getDisplayName()), $owner->language);

// Body of the notification message
$body = elgg_echo('ratings:notification:body', array(
        $user->getDisplayName(),
        $owner->getDisplayName(),
        $rating->getValue() // A value between 1-5
), $owner->language);

$params = array(
        'object' => $rating,
        'action' => 'create',
        'summary' => $summary
);

// Send the notification
notify_user($owner->guid, $user->guid, $subject, $body, $params);

Note

La langue utilisée par le destinataire n’est pas nécessairement la même que celle de la personne qui déclenche la notification. Par conséquent, vous devez toujours penser à transmettre la langue du destinataire en tant que troisième paramètre à elgg_echo().

Note

Le paramètre 'summary' est destiné aux plugins de notification qui ne souhaitent afficher qu’un message court au lieu du sujet et du corps de message. Par conséquent, le résumé doit être laconique, mais toujours contenir toutes les informations nécessaires.

Notifications en file d’attente

Sur les grands sites, il peut y avoir de nombreux utilisateurs qui se sont abonnés pour recevoir des notifications lors d’un événement particulier. L’envoi immédiat de notifications lorsqu’un utilisateur déclenche un tel événement peut ralentir considérablement la vitesse de chargement des pages. C’est pourquoi l’envoi de ces notifications devrait être mis dans la file d’attente de notification de Elgg.

De nouveaux événements de notification peuvent être enregistrés avec la fonction elgg_register_notification_event() ou dans la configuration de elgg-plugin. Des notifications sur les événements enregistrés seront envoyées automatiquement à tous les utilisateurs abonnés.

Voici le workflow du système de notifications :

1. Quelqu’un effectue une action qui déclenche un événement au sein de Elgg

   • L’action peut être create, update ou delete

   • La cible de l’action peut être n’importe quelle instance de la classe ElggEntity (par exemple un article de blog)

2. Le système de notifications enregistre cet événement dans une file d’attente de notifications dans la base de données

3. Lorsque le gestionnaire d’événements pour l’intervalle d’une minute est déclenché, l’événement est retiré de la file d’attente et traité.

4. Les abonnements sont récupérés pour l’utilisateur qui a déclenché l’événement

   • Par défaut, ceci comprend tous les utilisateurs qui ont activé au moins une méthode de notification pour les utilisateurs via www.site.com/notifications/personal/<username>

5. Les plugins sont autorisés à modifier les abonnements en utilisant l’événement [get, souscriptions]

6. Les plugins sont autorisés à interrompre le traitement de la file d’attente des notifications avec l’événement [send:before, notifications]

7. Les plugins sont autorisés à modifier les paramètres de notification avec l’événement [send:before, notifications]

8. Les plugins sont autorisés à modifier le subject/message/summary de la notification avec l’événement [prepare, notification:<action>:<type>:<subtype>]

9. Les plugins sont autorisés à formater le sujet/message/résumé de notification pour des méthodes de livraison individuelles avec l’événement [format, notification:<method>]

10. Les notifications sont envoyées à chaque abonné en utilisant les méthodes qu’il a choisies

    • Les plugins peuvent remplacer ou empêcher l’envoi de chaque notification individuelle avec l’événement [send, notification:<method>]

11. L’événement [send:after, notifications] est déclenché pour l’événement après que toutes les notifications ont été envoyées

Exemple d’enregistrement d’un événement de notification

Indiquez à Elgg d’envoyer des notifications lorsqu’un nouvel objet de sous-type photo est créé :

/**
 * Initialize the photos plugin
 */
function photos_init() {
        elgg_register_notification_event('object', 'photo', array('create'));
}

Ou dans elgg-plugin.php

'notifications' => [
        'object' => [
                'photo' => [
                        'create' => true,
                ],
        ],
],

Note

Pour envoyer les notifications lors des événements, vous devez configurer l’intervalle CRON d’une minute.

Le contenu du message de notification peut être défini avec l’événement 'prepare', 'notification:[action]:[type]:[subtype]'.

Exemple d’enregistrement d’un événement de notification personnalisé

Indiquer à Elgg d’envoyer des notifications lorsqu’un nouvel objet de sous-type album est créé :

// in the elgg-plugin.php
'notifications' => [
        'object' => [
                'photo' => [
                        'create' => PhotoAlbumCreateNotificationHandler::class, // this needs to be an extension of the \Elgg\Notifications\NotificationEventHandler class
                ],
        ],
],

//PhotoAlbumCreateNotificationHandler.php

class PhotoAlbumCreateNotificationHandler extends \Elgg\Notifications\NotificationEventHandler {

        /**
         * Overrule this function if you wish to modify the subscribers of this notification
         *
         * This will influence which subscribers are available in the 'get', 'subscribers' event
         */
        public function getSubscriptions(): array {
        }

        /**
         * Overrule this function if you wish to modify the subject of the notification
         *
         * A magic language key is checked for a default notification:
         * 'notification:<action>:<type>:<subtype>:subject'
         */
        protected function getNotificationSubject(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you wish to modify the body of the notification
         *
         * A magic language key is checked for a default notification:
         * 'notification:<action>:<type>:<subtype>:body'
         */
        protected function getNotificationBody(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you wish to modify the summary of the notification
         *
         * default: ''
         */
        protected function getNotificationSummary(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you wish to modify the target url of the notification
         *
         * default: $event->object->getURL()
         */
        protected function getNotificationURL(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you don't wish to allow the notification event to be configurable on the user notification settings page
         *
         * default: true
         */
        public static function isConfigurableByUser(): bool {
        }
}

Note

Assurez-vous que la notification sera dans la bonne langue en passant la langue du destinataire à la fonction elgg_echo().

Exemple de contenu de notification personnalisé

Indique à Elgg d’utiliser la fonction photos_prepare_notification() pour formater le contenu de la notification quand un nouvel objet de sous-type “photo” est créé :

/**
 * Initialize the photos plugin
 */
function photos_init() {
    elgg_register_notification_event('object', 'photo', array('create'));
    elgg_register_event_handler('prepare', 'notification:create:object:photo', 'photos_prepare_notification');
}

/**
 * Prepare a notification message about a new photo
 *
 * @param \Elgg\Event $event 'prepare', 'notification:create:object:photo'

 * @return \Elgg\Notification\Notification
 */
function photos_prepare_notification(\Elgg\Event $event) {
    $notification_event = $event->getParam('event');

    $entity = $notification_event->getObject();
    $owner = $notification_event->getActor();
    $recipient = $event->getParam('recipient');
    $language = $event->getParam('language');
    $method = $event->getParam('method');

    /* @var $notification \Elgg\Notification\Notification */
    $notification = $event->getValue();

    // Title for the notification
    $notification->subject = elgg_echo('photos:notify:subject', [$entity->getDisplayName()], $language);

    // Message body for the notification
    $notification->body = elgg_echo('photos:notify:body', array(
        $owner->getDisplayName(),
        $entity->getDisplayName(),
        $entity->getExcerpt(),
        $entity->getURL()
    ), $language);

    // Short summary about the notification
    $notification->summary = elgg_echo('photos:notify:summary', [$entity->getDisplayName()], $language);

    return $notification;
}

Note

Assurez-vous que la notification sera dans la bonne langue en passant la langue du destinataire dans la fonction elgg_echo().

Salutation et signature de la notification

Elgg ajoutera par défaut une formule de salutation au corps du message des notifications sortantes. Une signature sera également annexée. Cela signifie que vous n’aurez pas besoin d’ajouter du texte comme Bonjour Administrateur ou Cordialement, votre sympathique administrateur de site dans le corps de vos notifications. Si pour une raison quelconque vous n’avez pas besoin que cette magie se produise, vous pouvez l’empêcher en définissant le paramètre de notification add_salutation à false. Vous pouvez le faire dans le cadre des paramètres de notify_user() ou de l’événement prepare, notifications. Vous pouvez modifier les textes de salutation et de signature dans les traductions.

Vous pouvez également personnaliser la salutation en remplaçant la vue notifications/elements/salutation. La signature peut être personnalisée en remplaçant la vue notifications/elements/sign-off.

Méthodes de notification

Par défaut, Elgg propose trois méthodes de notification : email, delayed_email et le plugin site_notifications fourni avec Elgg.

E-mail

Enverra une notification par e-mail au destinataire.

E-mail différé

Enregistre les notifications pour les envoyer dans un e-mail groupé à l’intervalle configuré par le destinataire (quotidien ou hebdomadaire).

La disponibilité de cette méthode d’envoi peut être configurée par l’administrateur du site dans la section Paramètres du site.

La mise en page de l’e-mail groupé peut être personnalisée en remplaçant la vue email/delayed_email/plain_text pour la partie en texte brut de l’e-mail et email/delayed_email/html pour la partie HTML de l’e-mail.

Notification sur le site

Affichera la notification sur le site.

Enregistrement d’une nouvelle méthode de notification

Vous pouvez enregistrer une nouvelle méthode de notification avec la fonction elgg_register_notification_method().

Exemple :

Enregistrez un gestionnaire qui enverra les notifications par SMS.

/**
 * Initialize the plugin
 */
function sms_notifications_init() {
        elgg_register_notification_method('sms');
}

Après avoir enregistré la nouvelle méthode, celle-ci apparaîtra sur la page des paramètres de notification à l’adresse www.example.com/notifications/personal/[username].

Envoyer des notifications avec votre propre méthode

Outre l’enregistrement de la méthode de notification, vous devez également enregistrer un gestionnaire qui se charge d’envoyer réellement les notifications SMS. Cela se produit avec l’événement 'send', 'notification:[method]'.

Exemple :

/**
 * Initialize the plugin
 */
function sms_notifications_init () {
        elgg_register_notification_method('sms');
        elgg_register_event_handler('send', 'notification:sms', 'sms_notifications_send');
}

/**
 * Send an SMS notification
 *
 * @param \Elgg\Event $event 'send', 'notification:sms'
 *
 * @return bool
 * @internal
 */
function sms_notifications_send(\Elgg\Event $event) {
        /* @var \Elgg\Notifications\Notification $message */
        $message = $event->getParam('notification');

        $recipient = $message->getRecipient();

        if (!$recipient || !$recipient->mobile) {
                return false;
        }

        // (A pseudo SMS API class)
        $sms = new SmsApi();

        return $sms->send($recipient->mobile, $message->body);
}

Abonnements

Dans la plupart des cas, le noyau de Elgg s’occupe de la gestion des abonnements, de sorte que les plugins de notification n’ont généralement pas besoin de les modifier.

Les abonnements peuvent toutefois être :

• Ajoutés à l’aide de la fonction \ElggEntity::addSubscription()

• Supprimés à l’aide de la fonction \ElggEntity::removeSubscription()

Il est possible de modifier dynamiquement les destinataires d’une notification avec l’événement 'get', 'subscriptions'.

Exemple :

/**
 * Initialize the plugin
 */
function discussion_init() {
        elgg_register_event_handler('get', 'subscriptions', 'discussion_get_subscriptions');
}

/**
 * Get subscriptions for group notifications
 *
 * @param \Elgg\Event $event 'get', 'subscriptions'
 *
 * @return void|array
 */
function discussion_get_subscriptions(\Elgg\Event $event) {
        $reply = $event->getParam('event')->getObject();

        if (!$reply instanceof \ElggDiscussionReply) {
                return;
        }

        $subscriptions = $event->getValue();

        $group_guid = $reply->getContainerEntity()->container_guid;
        $group_subscribers = elgg_get_subscriptions_for_container($group_guid);

        return ($subscriptions + $group_subscribers);
}

Notifications en sourdine

Les notifications peuvent être désactivées afin de ne plus recevoir de notifications, par exemple pour ne plus recevoir de notifications concernant de nouveaux commentaires sur une discussion.

Afin de désactiver les notifications, appelez \ElggEntity::muteNotifications($user_guid) le $user_guid est par défaut l’utilisateur actuellement connecté. Cela entraînera la suppression de tous les abonnements sur l’entité et un indicateur spécial sera défini pour savoir que les notifications sont désactivées.

Les règles de désactivation sont appliquées après que les abonnés d’un événement de notification ont été demandées et appliquées pour les entités suivantes de l’événement de notification : - l’acteur de l’événement \Elgg\Notifications\NotificationEvent::getActor() - l’entité objet de l’événement \Elgg\Notifications\NotificationEvent::getObject() - l’entité conteneur de l’objet de l’événement \Elgg\Notifications\NotificationEvent::getObject()::getContainerEntity() - l’entité propriétaire de l’objet de l’événement \ Elgg\Notifications\NotificationEvent::getObject()::getOwnerEntity()

Pour réactiver les notifications, appelez \ElggEntity::unmuteNotifications($user_guid) le $user_guid est par défaut l’utilisateur actuellement connecté.

Pour vérifier si un utilisateur a les notifications désactivées, appelez \ElggEntity::hasMutedNotifications($user_guid) le $user_guid est par défaut l’utilisateur actuellement connecté.

Page d’aide

Une page d’aide a été ajoutée qui peut être liée (par exemple dans un pied de page d’e-mail) pour gérer la désactivation d’une notification particulière.

La page doit être obligatoirement signée et utiliser la route notifications:mute qui nécessite : - entity_guid l’entité sur laquelle porte la notification - recipient_guid le destinataire de la notification

Désactiver temporairement les notifications

Les utilisateurs peuvent désactiver temporairement toutes les notifications en accédant aux paramètres de notification et en définissant une date de début et de fin pour la période pour laquelle ils ne souhaitent pas recevoir de notifications.

Paramètres de notification

Vous pouvez stocker et récupérer les paramètres de notification des utilisateurs avec \ElggUser::setNotificationSetting() et \ElggUser::getNotificationSettings().

// Setting a notification preference
// notification method: mail
// notification is enabled
// for the purpose 'group_join' (when omitted this is 'default')
$user->setNotificationSetting('mail', true, 'group_join');

// retrieving the preference
$settings = $user->getNotificationSettings('group_join');
// this wil result in an array with all the current notification methods and their state like:
// [
//      'mail' => true,
//      'site' => false,
//      'sms' => false,
// ]

Lorsqu’un utilisateur n’a pas encore de paramètre distinct de celui par défaut, le système revient au paramètre de notification “default”.

Gestion des notifications

Un gestionnaire d’événements de menu générique est fourni pour gérer l’abonnement aux notifications et la mise en sourdine. Si vous souhaitez permettre aux utilisateurs de s’abonner facilement à vos entités, enregistrez un événement de menu sur register menu:<menu name>:<entity type>:<entity subtype> avec le callback Elgg\Notifications\RegisterSubscriptionMenuItemsHandler assurez-vous de fournir un \ ElggEntity dans $params['entity']. Cela fonctionnera pour la plupart des appels elgg_view_menu().

Propriété de la page

Une tâche récurrente de tout plugin sera de déterminer qui est propriétaire de la page afin de décider quelles actions sont autorisées ou non. Elgg dispose de plusieurs fonctions liées à la propriété de la page et offre également aux développeurs de plugin une flexibilité en laissant le plugin gérer également les demandes de propriété de page. La détermination du propriétaire d’une page peut être déterminée avec elgg_get_page_owner_guid(), qui renverra le GUID du propriétaire. Alternativement, elgg_get_page_owner_entity() récupérera l’entité complète du propriétaire de la page. Si la page sait déjà qui est le propriétaire de la page, mais pas le système, la page peut définir le propriétaire de la page en passant son GUID à elgg_set_page_owner_guid($guid).

Note

L’entité propriétaire de la page peut être n’importe quelle ElggEntity. Si vous souhaitez appliquer des paramètres particuliers selon que c’est un utilisateur ou un groupe, assurez-vous de vérifier que vous avez l’entité correcte.

Détection du propriétaire de la page

Sur la base de la définition de la route :

• Si le nom commence par view ou edit les paramètres username et guid sont vérifiés

• Si le nom commence par add ou collection les paramètres username, guid et container_guid sont vérifiés

• Si dans la définition de la route la valeur detect_page_owner est définie sur true les paramètres username, guid et container_guid sont vérifiés

Vérification des permissions

Avertissement

Comme indiqué dans la page, cette méthode fonctionne seulement pour accorder le droit d’accès en écriture sur les entités. Vous ne pouvez pas utiliser cette méthode pour récupérer ou afficher des entités pour lesquelles l’utilisateur n’a pas d’accès en lecture.

Elgg fournit un mécanisme permettant de remplacer la vérification des autorisations d’écriture via l’événement permissions_check . Ceci est utile pour permettre l’écriture du plugin sur toutes les entités accessibles, quels que soient les paramètres d’accès. Cependant, les entités masquées ne seront toujours pas disponibles pour le plugin.

Étendre permissions_check

Dans votre plugin, vous devez enregistrer l’événement pour permissions_check.

elgg_register_event_handler('permissions_check', 'all', 'myplugin_permissions_check');

La fonction de substitution

Créez maintenant la fonction qui sera appelée par l’événement de vérification des autorisations. Dans cette fonction, nous déterminons si l’entité (dans les paramètres) a un accès en écriture. Puisqu’il est important de garantir la sécurité d’Elgg, l’accès en écriture ne doit être accordé qu’après avoir vérifié diverses situations, notamment le contexte de la page, l’utilisateur connecté, etc. Notez que cette fonction peut renvoyer 3 valeurs : true si l’entité a un accès en écriture, false si l’entité ne l’a pas, et null si ce plugin ne s’en préoccupe pas et que le système de sécurité devrait consulter d’autres plugins.

function myplugin_permissions_check(\Elgg\Event $event) {
   $has_access = determine_access_somehow();

   if ($has_access === true) {
      return true;
   } else if ($has_access === false) {
      return false;
   }

   return null;
}

Exemple complet

Voici un exemple complet utilisant le contexte pour déterminer si l’entité dispose d’un accès en écriture.

<?php

function myaccess_init() {
   // override permissions for the myaccess context
   elgg_register_event_handler('permissions_check', 'all', 'myaccess_permissions_check');

   // Register cron event
   elgg_register_event_handler('cron', elgg_get_plugin_setting('period', 'myaccess', 'fiveminute'), 'myaccess_cron');
}

/**
 * Event for cron event.
 */
function myaccess_cron(\Elgg\Event $event) {

   elgg_push_context('myaccess_cron');

   // returns all entities regardless of access permissions.
   // will NOT return hidden entities.
   $entities = get_entities();

   elgg_pop_context();
}

/**
 * Overrides default permissions for the myaccess context
 */
function myaccess_permissions_check(\Elgg\Event $event) {
   if (elgg_in_context('myaccess_cron')) {
      return true;
   }

   return null;
}

// Initialise plugin
register_elgg_event_handler('init', 'system', 'myaccess_init');

Plugins

Les plugins doivent fournir un fichier composer.json situé dans la racine du plugin afin d’être reconnus par Elgg.

elgg-plugin.php

elgg-plugin.php est un fichier statique de configuration du plugin. Il est lu par Elgg pour configurer différents services, et doit retourner un tableau s’il est présent. Il ne doit pas être inclus par les plugins et n’est pas destiné à être exécuté. A l’exception des constantes magiques comme __DIR__, sa valeur de retour ne doit pas changer. Les sections actuellement prises en charge sont :

• plugin - définit les informations et les dépendances du plugin

• bootstrap - définit une classe utilisée pour initialiser le plugin

• entities - définit les types et les classes d’entités du plugin, et les enregistre éventuellement pour la recherche

• actions - élimine la nécessité d’appeler elgg_register_action()

• routes - élimine la nécessité d’appeler elgg_register_route()

• settings - élimine la nécessité de définir des valeurs par défaut sur chaque appel à elgg_get_plugin_setting()

• user_settings - élimine la nécessité de définir des valeurs par défaut sur chaque appel à elgg_get_plugin_user_setting()

• views - permet aux plugins de créer des alias des actifs vers un chemin d’accès dans le système de vue de Elgg

• widgets - élimine la nécessité d’appeler elgg_register_widget_type()

• events - élimine la nécessité d’appeler elgg_register_event_handler()

• cli_commands - un tableau de classes Elgg/Cli/Command pour étendre les fonctionnalités de elgg-cli

• view_extensions - élimine la nécessité d’appeler elgg_extend_view() ou elgg_unextend_view()

• thème - un tableau de variables pour les thèmes

• group_tools - un tableau d’options des outils de groupe disponibles

• view_options - un tableau de vues avec des options supplémentaires

• notifications - un tableau d’événements de notification

• web_services - un tableau de webservices exposés (utilisés par le plugin Web Services)

return [
        'plugin' => [
                'name' => 'Plugin Name', // readable plugin name
                'activate_on_install' => true, // only used on a fresh install
                'version' => '1.3.1', // version of the plugin
                'dependencies' => [
                        // optional list op plugin dependencies
                        'blog' => [],
                        'activity' => [
                                'position' => 'after',
                                'must_be_active' => false,
                        ],
                        'file' => [
                                'position' => 'before',
                                'version' => '>2', // composer notation of required version constraint
                        ],
                ],
        ],

        // Bootstrap must implement \Elgg\PluginBootstrapInterface
        'bootstrap' => MyPluginBootstrap::class,

        'entities' => [
                [
                        // Register a new object subtype and tell Elgg to use a specific class to instantiate it
                        'type' => 'object',
                        'subtype' => 'my_object_subtype',
                        'class' => MyObjectClass::class,

                        'capabilities' => [
                                // Register this subtype for search
                                'searchable' => true,

                                'likable' => true,
                        ],
                ],
        ],

        'actions' => [
                // Registers an action
                // By default, action is registered with 'logged_in' access
                // By default, Elgg will look for file in plugin's actions/ directory: actions/my_plugin/action.php
                'my_plugin/action/default' => [],

                'my_plugin/action/custom_access' => [
                        'access' => 'public', // supports 'public', 'logged_in', 'logged_out', 'admin'
                ],

                // you can use action controllers instead of action files by setting the controller parameters
                // controller must be a callable that receives \Elgg\Request as the first and only argument
                // in example below, MyActionController::__invoke(\Elgg\Request $request) will be called
                'my_plugin/action/controller' => [
                        'controller' => MyActionController::class,
                ],
        ],

        'routes' => [
                // routes can be associated with resource views or controllers
                'collection:object:my_object_subtype:all' => [
                        'path' => '/my_stuff/all',
                        'resource' => 'my_stuff/all', // view file is in resources/my_stuff/all
                ],

                // similar to actions, routes can be associated with a callable controller that receives an instance of \Elgg\Request
                'collection:object:my_object_subtype:json' => [
                        'path' => '/my_stuff/json',
                        'controller' => JsonDumpController::class,
                ],

                // route definitions support other parameters, such as 'middleware', 'requirements', 'defaults'
                // see elgg_register_route() for all options
        ],

        'widgets' => [
                // register a new widget
                // corresponds to a view in widgets/my_stuff/content
                'my_stuff' => [
                        'description' => elgg_echo('widgets:my_stuff'),
                        'context' => ['profile', 'dashboard'],
                ],
        ],

        'settings' => [
                'plugin_setting_name' => 'plugin_setting_value',
        ],

        'user_settings' => [
                'user_setting_name' => 'user_setting_value',
        ],

        'views' => [
                'default' => [
                        'cool_lib/' => __DIR__ . '/vendors/cool_lib/dist/',
                ],
        ],

        'events' => [
                'delete' => [
                        'object' => [
                                'file_handle_object_delete' => [
                                        'priority' => 999,
                                ],
                        ],
                ],
                'create' => [
                        'relationship' => [
                                '_elgg_send_friend_notification' => [],
                        ],
                ],
                'log' => [
                        'systemlog' => [
                                'Elgg\SystemLog\Logger::log' => ['unregister' => true],
                        ],
                ],
                'register' => [
                        'menu:owner_block' => [
                                'blog_owner_block_menu' => [
                                        'priority' => 700,
                                ],
                        ],
                ],
                'usersettings:save' => [
                        'user' => [
                                '_elgg_save_notification_user_settings' => ['unregister' => true],
                        ],
                ],
        ],

        'cli_commands' => [
                \My\Plugin\CliCommand::class,
                '\My\Plugin\OtherCliCommand',
        ],

        'view_extensions' => [
                'elgg.js' => [
                        'bookmarks.js' => [],
                ],
                'page/components/list' => [
                        'list/extension' => [
                                'priority' => 600,
                        ],
                ],
                'forms/usersettings/save' => [
                        'core/settings/account/password' => [
                                'unextend' => true,
                        ],
                ],
        ],

        'theme' => [
                'body-background-color' => '#000',
        ],

        'group_tools' => [
                'activity' => [], // just use default behaviour
                'blog' => [
                        'default_on' => false,
                ],
                'forum' => [
                        'unregister' => true, // unregisters the group tool option
                ],
        ],

        'view_options' => [
                'likes/popup' => [
                        'ajax' => true, // registers the view available via ajax
                ],
                'likes/popup' => [
                        'ajax' => false, // unregisters the view available via ajax
                ],
                'manifest.json' => [
                        'simplecache' => true, // register view as usable in the simplecache
                ],
        ],
        'notifications' => [
                'object' => [
                        'blog' => [
                                'publish' => true, // registers the event to be notified
                        ],
                        'thewire' => [
                                'create' => false, // unregisters the event to be notified
                        ],
                        'page' => [
                                'create' => MyPluginPageCreateEventHandler::class, // a custom event handler, needs to be an extension of a NotificationEventHandler
                        ],
                ],
        ],
        'web_services' => [
                'test.echo' => [
                        'GET' => [ // the HTTP call method (GET|POST)
                                'callback' => 'my_echo', // required
                                'description' => 'A testing method which echos back a string', // optional, the description of the API method, a magic translation key is tried if not provided 'web_services:api_methods:<method>:<http call method>:description'
                                'params' => [ // optional, input parameters for the API method
                                        'string' => [
                                                'type' => 'string', // type of the parameter (int|integer|bool|string|float|array)
                                                'default' => 'some value', // default value if not provided in the request
                                                'required' => true|false, // required in the request
                                        ],
                                ],
                                'require_api_auth' => false, // optional, requires API authentication (default: false)
                                'require_user_auth' => false, // optional, requires User authentication (default: false)
                                'associative' => false, // optional, provide the input params as an array to the callback function (default: false)
                        ],
                ],
        ],
];

Classe d’initialisation - Bootstrap

À partir de Elgg 3.0, la manière recommandée pour initialiser votre plugin est d’utiliser une classe bootstrap. Cette classe doit implémenter l’interface \Elgg\PluginBootstrapInterface. Vous pouvez inscrire votre classe bootstrap dans elgg-plugin.php.

L’interface d’initialisation - bootstrap - définit plusieurs fonctions à implémenter qui sont appelées lors de différents événements dans le processus de démarrage du système.

Voir aussi

Pour plus d’informations sur les différentes fonctions définies dans \Elgg\PluginBootstrapInterface veuillez lire Initialisation - bootstrap - d’un plugin

elgg-services.php

Les plugins peuvent attacher leurs services au conteneur public DI de Elgg en fournissant des définitions PHP-DI dans elgg-services.php, situé à la racine du répertoire du plugin.

Ce fichier doit renvoyer un tableau de définitions PHP-DI. Les services seront disponibles via elgg().

return [
   PluginService::class => \DI\object()->constructor(\DI\get(DependencyService::class)),
];

Les plugins peuvent ensuite utiliser l’API PHP-DI pour s’auto-câbler et appeler le service :

$service = elgg()->get(PluginService::class);

Voyez la documentation PHP-DI pour une liste complète des possibilités de définition et d’invocation.

composer.json

Depuis que Elgg prend en charge l’installation en tant que dépendance Composer , le fait que vos plugins prennent également en charge Composer facilite l’installation par des administrateurs de site. Afin de rendre votre plugin compatible avec Composer, vous devez au moins avoir un fichier composer.json dans la racine de votre plugin.

Voici un exemple de fichier composer.json :

{
        "name": "company/example_plugin",
        "description": "Some description of the plugin",
        "type": "elgg-plugin",
        "keywords": ["elgg", "plugin"],
        "license": "GPL-2.0-only",
        "support": {
                "source": "URL to your code repository",
                "issues": "URL to your issue tracker"
        },
        "conflict": {
                "elgg/elgg": "<3.0"
        }
}

Apprenez-en plus sur le format de composer.json sur le site de Composer.

Les parties importantes du fichier composer.json sont :

• name : le nom de votre plugin, utilisez le même que le nom de dossier de votre plugin pour assurer une installation correcte

• type : indique à Composer où installer votre plugin, laissez TOUJOURS ceci sur elgg-plugin

À titre de suggestion, incluez une règle conflict avec toute version d’Elgg inférieure à votre version minimale requise, cela aidera à empêcher l’installation accidentelle de votre plugin sur une version d’Elgg incompatible.

Après avoir ajouté un fichier composer.json à votre projet de plugin, vous devez enregistrer votre projet sur Packagist afin que d’autres personnes puissent installer votre plugin.

Tests

Il est recommandé de créer des tests PHPUnit pour votre plugin. Tous les tests devraient être situés dans tests/phpunit/unit pour les tests unitaires et tests/phpunit/integration pour les tests d’intégration.

Les tests unitaires devraient étendre la classe Elgg\UnitTestCase. Les tests d’intégration devraient étendre Elgg\Plugins\IntegrationTestCase.

Il existe un ensemble de tests d’intégration de plugins globaux qui s’exécutent sur tous les plugins actifs. Ces tests sont :

• Elgg\Plugins\ActionRegistrationIntegrationTest testera toutes les actions enregistrées du plugin sans fournir de données

• Elgg\Plugins\ComposerIntegrationTest va tester si composer.json est considéré comme valide

• Elgg\Plugins\StaticConfigIntegrationTest testera les sections de elgg-plugin.php et vérifiera que le format est correct

• Elgg\Plugins\TranslationsIntegrationTest testera tous les fichiers de langue pour le format et l’encodage corrects

• Elgg\Plugins\ViewStackIntegrationTest testera toutes les vues du plugin s’il y a des erreurs d’analyse PHP

Voir aussi

Écrire des tests

Connexe

Squelette du plugin

Ce qui suit est le standard pour la structure d’un plugin dans Elgg à partir de Elgg 2.0.

Exemple de structure

Voici un exemple de plugin avec un structure standard. Pour plus d’explications sur cette structure, voyez les informations dans les sections suivantes. Votre plugin peut ne pas avoir besoin de tous les fichiers listés

Les fichiers suivants pour le plugin example iraient dans /mod/example/

actions/
    example/
        action.php
        other_action.php
classes/
    VendorNamespace/
        PluginNamespace/
            ExampleClass.php
languages/
    en.php
vendors/
    example_3rd_party_lib/
views/
    default/
        example/
          component.css
          component.js
          component.png
        forms/
            example/
                action.php
                other_action.php
        object/
            example.php
            example/
                context1.php
                context2.php
        plugins/
            example/
                settings.php
                usersettings.php
        resources/
            example/
                all.css
                all.js
                all.php
                owner.css
                owner.js
                owner.php
        widgets/
            example_widget/
                content.php
                edit.php
elgg-plugin.php
CHANGES.txt
COPYRIGHT.txt
INSTALL.txt
LICENSE.txt
README.txt
composer.json

Fichiers requis

Les plugins doivent fournir un fichier composer.json dans la racine du plugin afin d’être reconnus par Elgg.

De ce fait, voici la structure conforme minimale :

mod/example/
    composer.json

Actions

Les plugins devraient placer les scripts pour les actions dans un dossier actions/, et devraient en outre utiliser le nom de l’action pour déterminer l’emplacement dans ce dossier.

Par exemple, l’action my/example/action irait dans my_plugin/actions/my/example/action.php. Ceci permet de rendre évident quel script est associé avec quelle action.

De même, le corps du formulaire qui est soumis à cette action doit être situé dans forms/my/example/action.php. Non seulement cela rend évident le lien entre le gestionnaire d’action, le code du formulaire, et le nom de l’action, mais cela vous permet aussi d’utiliser facilement la fonction elgg_view_form().

Fichiers texte

Les plugins peuvent fournir divers fichiers *.txt comme documentation supplémentaire pour le plugin. Ces fichiers doivent utiliser la syntaxe Markdown et vont générer des liens vers les sections de gestion du plugins.

README.txt

devrait fournir des informations supplémentaires de toute nature sur le plugin

COPYRIGHT.txt

Si inclus, doit fournir une description du droit d’auteur du plugin.

LICENSE.txt

Si inclus, doit fournir le texte de la licence sous laquelle le plugin est publié.

INSTALL.txt

Si inclus, doit fournir des instructions supplémentaires pour l’installation du plugin si le processus est suffisamment compliqué (par exemple, s’il nécessite l’installation de bibliothèques tierces sur l’hôte, ou nécessite l’acquisition d’une clef API provenant d’un tiers).

CHANGES.txt

Si inclus, doit fournir une liste de modifications pour le plugin, regroupées par numéro de version, avec la version la plus récente au début.

Les plugins peuvent inclure des fichiers supplémentaires *.txt en plus de ceux-ci, mais aucune interface n’est fournie pour les lire.

Pages

Pour afficher des pages complètes, les plugins doivent utiliser les vues de ressources (qui ont des noms commençant par resources/). Cela permet à d’autres plugins de remplacer facilement certaines fonctionnalités via le système de vue.

Note

La raison pour laquelle nous encourageons cette structure est

• Pour former une relation logique entre URLs et scripts, de sorte que les personnes qui examinent le code puissent avoir une idée de ce qu’il fait rien qu’en examinant la structure du code.

• Pour nettoyer le répertoire racine des plugins, qui avait historiquement été rapidement encombré avec les scripts de gestion des pages.

Classes

Elgg fournit un autochargement PSR-0 de toutes les classes du répertoire classes/ des plugins actifs.

Vous êtes encouragés à suivre les standards PHP-FIG quand vous écrivez vos classes.

Note

Les fichiers avec une extension « .class.php » ne seront pas reconnus par Elgg.

Lors de l’organisation de vos classes, Elgg n’impose pas une structure spécifique. Utilisez ce qui fonctionne le mieux pour votre plugin, mais gardez à l’esprit qu’il devrait être facile à lire, et que ses fonctionnalités devraient être faciles à trouver, et qu’avoir des fonctions séparées dans différentes classes permettra d’améliorer la maintenabilité et la testabilité.

Fournisseurs - vendors

Les bibliothèques tierce-partie de tout type devraient être placées dans le dossier vendors/ de la racine du plugin. Quoique ce dossier n’ait pas de signification particulière pour le moteur de Elgg, il a été historiquement l’emplacement où le noyau de Elgg conservait ses bibliothèques tierces-parties, aussi nous encourageons le même format au nom de la cohérence et de la familiarité.

Vues

Afin de surcharger des vues du noyau, les vues d’un plugin peuvent être placées dans views/, ou un fichier de configuration elgg-plugin.php peut être utilisé pour un mappage fichier/chemin plus détaillé. Voyez Vues.

Javascript et CSS seront hébergés dans le système de vues. Voyez JavaScript.

Dépendances du plugin

Dans Elgg, le système de dépendances de plugin est présent pour empêcher les plugins d’être utilisés sur des systèmes incompatibles.

Aperçu

Le système de dépendances est contrôlé par le fichier `elgg-plugin.php file ou composer.json d’un plugin. Les auteurs de plugins peuvent spécifier qu’un plugin :

• Nécessite certains plugins Elgg, une version de PHP ou des extensions PHP.

• Est en conflit avec certains plugins ou versions de Elgg.

Version de PHP ou extension

Ajoutez une section dans votre composer.json comme décrit dans la Documentation de référence Composer JSON

{
        "require": {
                "php": ">8.0",
                "ext-json": "*"
        }
}

Nécessite un plugin Elgg

Ajoutez une section à elgg-plugin.php, voyez aussi Plugins

return [
        'plugin' => [
                'dependencies' => [
                        // optional list op plugin dependencies
                        'blog' => [], // blog needs to be active
                        'activity' => [
                                'position' => 'after', // in the plugin order this plugin must be after the activity plugin
                                'must_be_active' => false, // but the plugin isn't required to be active, but if active order will be checked
                        ],
                        'file' => [
                                'position' => 'before', // file must be active and this plugin needs to be before the file plugin in the plugin order
                                'version' => '>2', // composer notation of required version constraint
                        ],
                ],
        ],
];

Est en conflit avec

Ajoutez une section dans votre composer.json comme décrit dans la Documentation de référence Composer JSON

{
        "conflict": {
                "elgg/elgg": "<4.0",
                "elgg/dataviews": "<1.0 || >= 1.5"
        }
}

Initialisation - bootstrap - d’un plugin

Afin d’initialiser votre plugin à partir de Elgg 3.0, vous pouvez utiliser une classe bootstrap. Cette classe doit implémenter l’interface abstraite \Elgg\PluginBootstrapInterface, mais il est recommandé d’étendre la classe abstraite \Elgg\PluginBootstrap, car certaines préparations ont déjà été faites.

Si vous n’avez besoin que d’un sous-ensemble limité des fonctions d’initialisation, votre classe peut également étendre la classe \Elgg\DefaultPluginBootstrap, cette classe a déjà implémenté toutes les fonctions de \Elgg\PluginBootstrapInterface. Ainsi, vous pouvez surcharger uniquement les fonctions dont vous avez besoin.

Enregistrement de la classe « bootstrap » d’initialisation

Vous devez enregistrer votre classe d’initialisation dans le fichier elgg-plugin.php.

return [
        // Bootstrap must implement \Elgg\PluginBootstrapInterface
        'bootstrap' => MyPluginBootstrap::class,
];

Fonctions disponibles

->load()

Exécuté lors de l’événement plugins_load, system

Permet au plugin de requérir des fichiers supplémentaires, ainsi que de configurer des services avant le démarrage du plugin.

->boot()

Exécuté lors de l’événement plugins_boot:before, system

Permet au plugin d’enregistrer des gestionnaires pour les événements plugins_boot, system et init, system, ainsi que de mettre en œuvre la logique de démarrage.

->init()

Exécuté lors de l’événement init, system

Permet au plugin d’implémenter la logique métier et d’enregistrer tous les autres gestionnaires.

->ready()

Exécuté lors de l’événement ready, system

Permet au plugin d’implémenter sa logique après que tous les plugins ont été initialisés.

->shutdown()

Exécuté lors de l’événement shutdown, system

Permet au plugin d’implémenter sa logique pendant l’arrêt.

->activate()

Exécuté lorsque le plugin est activé, après l’événement activate, plugin.

->deactivate()

Exécuté lorsque le plugin est désactivé, après l’événement deactivate, plugin.

->upgrade()

Enregistré en tant que gestionnaire pour l’événement upgrade, system

Permet au plugin d’implémenter sa logique pendant la mise à niveau du système.

Fonctions d’assistance disponibles

Ceci suppose que votre classe bootstrap étend la classe abstraite \Elgg\PluginBootstrap ou la classe \Elgg\DefaultPluginBootstrap.

->elgg()

Renvoie le conteneur DI public de Elgg. Cela peut être utile si vous souhaitez enregistrer des écouteurs d’événements.

$events = $this->elgg()->events;
$events->registerHandler('create:after', 'object', MyCustomObjectHandler::class);

->plugin()

Renvoie l’entité du plugin à laquelle cette initialisation est liée. Il est ainsi plus facile d’obtenir des paramètres de plugin.

$plugin = $this->plugin();
$my_setting = $plugin->getSetting('my_setting');

Rivière - Flux d’activité

Elgg supporte nativement la « rivière » - river -, un flux d’activité qui contient des descriptions des activités effectuées par les membres du site. Cette page donne un aperçu de comment un plugin Elgg ajoute des événements à la rivière.

Pousser des éléments vers la rivière

Des éléments sont poussés vers la rivière d’activité à travers l’appel à une fonction, que vous devez inclure dans vos plugins pour que ces éléments apparaissent.

Ici nous ajoutons un élément à la rivière, qui indique qu’un utilisateur a créé un nouvel article de blog :

<?php

elgg_create_river_item([
        'view' => 'river/object/blog/create',
        'action_type' => 'create',
        'subject_guid' => $blog->owner_guid,
        'object_guid' => $blog->getGUID(),
]);

Tous les paramètres disponibles :

• view => STR La vue qui va gérer l’élément de la rivière (doit exister)

• action_type => STR Une chaîne arbitraire pour définir l’action (par ex. “create”, “update”, “vote”, “review”, etc.)

• subject_guid => INT Le GUID de l’entité qui effectue l’action (par défaut : le guid de l’utilisateur connecté)

• object_guid => INT Le GUID de l’entité sur laquelle est effectuée l’action

• target_guid => INT Le GUID du conteneur de l’entité de l’objet (optionnel)

• access_id => INT L’ID d’accès de l’élément de la rivière (par défaut : identique à celui de l’objet)

• posted => INT Le timestamp UNIX de l’élément de la rivière (par défaut : maintenant)

• annotation_id => INT L’ID de l’annotation ID associée avec cette entrée de la rivière (optionnel)

Quand un élément est supprimé ou modifié, l’élément de la rivière sera mis à jour automatiquement.

Vues de la rivière

A partir de Elgg 3.0 le paramètre view n’est plus requis. Une logique de rechange a été créée pour vérifier une série de vues pour vous :

1. /river/{$type}/{$subtype}/{$action_type} : par ex. river/object/blog/create seule l’action create parviendra à cette vue

2. river/{$type}/{$subtype}/default : par ex. river/object/blog/default toute l’activité de la rivière pour object blog arrivera ici

3. river/{$type}/{$action_type} : par ex. river/object/create toutes les actions create pour object arriveront ici

4. river/{$type}/default : par ex. river/object/default toutes les actions pour tous les object arriveront ici

5. river/elements/layout : solution de rechange en dernier recours, qui devrait toujours être appelée dans n’importe laquelle des vues de la rivière afin de créer une mise en page cohérente

A la fois type et subtype sont basés sur le type et le subtype de l”object_guid pour lequel l’élément de la rivière a été créé.

Résumé

Si aucun paramètre summary n’est fourni à river/elements/layout la vue va tenter de le créer pour vous. Le résultat de base sera un texte avec le texte Untel a fait quelque chose sur Ceci, où Untel est basé sur subject_guid et Ceci est basé sur object_guid. Des liens seront créés pour Untel et Ceci. Ces liens sont transmis à une série de clefs de traduction afin que vous puissiez générer un résumé informatif.

Les clefs de traduction sont :

1. river:{$type}:{$subtype}:{$action_type}: par ex. river:object:blog:create

2. river:{$type}:{$subtype}:default: par ex. river:object:blog:default

3. river:{$type}:{$action_type}: par ex. river:object:create

4. river:{$type}:default: par ex. river:object:default

Vue personnalisée de la rivière

Si vous souhaitez ajouter plus d’informations à la vue de la rivière, comme par ex. une pièce jointe (une image, une vidéo YouTube embarquée, etc.), vous devez spécifier la vue lors de la création de l’élément de la rivière. Cette vue DOIT exister.

Nous recommandons /river/{type}/{subtype}/{action}, où :

• {type} est le type d’entité du contenu qui nous intéresse (object pour les objets, user pour les utilisateurs, etc.)

• {subtype} est le sous-type d’entité du contenu qui nous intéresse (blog pour les articles de blog, photo_album pour les albums photo, etc.)

• {action} est l’action qui a eu lieu (create, update, etc.)

Les informations relatives à un élément de la rivière seront transmises dans un objet appelé $vars['item'], qui contient les paramètres importants suivants :

• ''$vars['item']->subject_guid Le GUID de l’utilisateur qui effectue l’action

• $vars['item']->object_guid Le GUID de l’entité sur laquelle l’action est effectuée

Les horodatages, etc. seront générés pour vous.

Par exemple, le plugin blog utilise le code suivant pour sa vue dans la rivière :

$item = elgg_extract('item', $vars);
if (!$item instanceof ElggRiverItem) {
        return;
}

$blog = $item->getObjectEntity();
if (!$blog instanceof ElggBlog) {
        return;
}

$vars['message'] = $blog->getExcerpt();

echo elgg_view('river/elements/layout', $vars);

Routage

Elgg dispose de deux mécanismes pour répondre aux requêtes HTTP qui ne passent pas déjà par les systèmes des Actions et du Simplecache - Cache simple.

Identifiant d’URL et segments

Après avoir retiré l’URL du site, Elgg découpe le chemin de l’URL par / dans un tableau. Le premier élément, l’identificateur, est mis de côté, et les éléments restants sont appelés les segments. Par exemple, si l’URL du site est http://example.com/elgg/, l’URL http://example.com/elgg/blog/owner/jane?foo=123 produit :

Identificateur : 'blog'. Segments : ['owner', 'jane']. (les paramètres de la chaîne de requête sont disponibles via get_input())

L’URL du site (page d’accueil) est un cas spécial qui produit un identificateur de chaîne vide et un tableau de segments vide.

Avertissement

Les identificateurs/segments d’URL doivent être considérés comme des entrées utilisateur potentiellement dangereuses. Elgg utilise dessus htmlspecialchars pour échapper les entités HTML.

Gestion des pages

Elgg offre des outils pour gérer les pages de votre plugin via des routes personnalisées, permettant des URLs comme http://yoursite/my_plugin/section. Vous pouvez enregistrer une nouvelle route en utilisant elgg_register_route() ou via la configuration routes dans elgg-plugin.php. Les routes assurent la correspondance avec les vues de ressources, où vous pouvez générer le contenu de la page.

// in your 'init', 'system' handler
elgg_register_route('my_plugin:section' [
        'path' => '/my_plugin/section/{guid}/{subsection?}',
        'resource' => 'my_plugin/section',
        'requirements' => [
                'guid' => '\d+',
                'subsection' => '\w+',
        ],
]);

// in my_plugin/views/default/resources/my_plugin/section.php
$guid = elgg_extract('guid', $vars);
$subsection = elgg_extract('subsection', $vars);

// render content

Dans l’exemple ci-dessus, nous avons enregistré une nouvelle route qui est accessible via http://yoursite/my_plugin/section/<guid>/<subsection>. Chaque fois que cette route est accédée avec le segment requis guid et un segment facultatif subsection, le routeur va afficher la vue de la ressource spécifiée my_plugin/section et transmettre les paramètres extraits de l’URL à votre vue de ressource via $vars.

Noms des routes

Les noms de routes peuvent ensuite être utilisés pour générer une URL :

$url = elgg_generate_url('my_plugin:section', [
        'guid' => $entity->guid,
        'subsection' => 'assets',
]);

Les noms d’itinéraires sont uniques pour l’ensemble des plugins et pour le noyau, de sorte qu’un autre plugin peut surcharger une route en enregistrant d’autres paramètres sur le même nom de route.

Les noms des routes respectent un certain formalisme et seront, dans certains cas, utilisés pour résoudre automatiquement les URLs, par exemple pour afficher une entité.

Les conventions suivantes sont utilisées dans le noyau et recommandées pour les plugins :

view :<entity_type>:<entity_subtype>

Correspond à la page de profil de l’entité, par exemple view:user:user ou view:object:blog. Le chemin d’accès doit contenir un guid, ou un username pour les utilisateurs

edit:<entity_type>:<entity_subtype>

Correspond au formulaire pour modifier l’entité, par exemple edit:user:user ou edit:object:blog. Le chemin d’accès doit contenir un guid, ou un username pour les utilisateurs. Si vous avez besoin d’ajouter des sous-ressources, utilisez des suffixes, par exemple edit:object:blog:images, en gardant au moins une sous-ressource sans suffixe par défaut.

add:<entity_type>:<entity_subtype>

Correspond au formulaire pour ajouter une nouvelle entité d’un type donné, par exemple add:object:blog. Le chemin d’accès, en règle générale, contient le paramètre container_guid

collection:<entity_type>:<entity_subtype>:<collection_type>

Correspond aux pages de listes. Les noms de routes couramment utilisés dans le noyau sont les suivants :

• collection:object:blog:all : liste tous les articles de blog

• collection:object:blog:owner : liste les articles de blog appartenant à un utilisateur avec un identifiant donné

• collection:object:blog:friends : liste les articles de blog appartenant à des contacts de l’utilisateur connecté (ou d’un utilisateur avec un identifiant donné)

• collection:object:blog:group : liste les articles de blog dans un groupe

default:<entity_type>:<entity_subtype>

Fait correspondre à la page par défaut pour une ressource, par exemple pour le chemin d’accès /blog. Elgg utilise la collection « all » pour ces routes.

• default:object:blog : gère le chemin générique /blog.

<entity_subtype> peut être omis des noms de routes pour enregistrer des routes globales applicables à toutes les entités d’un type donné. Le générateur d’URL va d’abord essayer de générer une URL à l’aide du sous-type, puis se replie sur un nom de route sans sous-type. Par exemple, les profils utilisateur sont acheminés vers la même vue de ressource quel que soit le sous-type utilisateur.

elgg_register_route('view:object:attachments', [
        'path' => '/attachments/{guid}',
        'resource' => 'attachments',
]);

elgg_register_route('view:object:blog:attachments', [
        'path' => '/blog/view/{guid}/attachments',
        'resource' => 'blog/attachments',
]);

$blog = get_entity($blog_guid);
$url = elgg_generate_entity_url($blog, 'view', 'attachments'); // /blog/view/$blog_guid/attachments

$other = get_entity($other_guid);
$url = elgg_generate_entity_url($other, 'view', 'attachments'); // /attachments/$other_guid

Configuration du routage

Les segments peuvent être définis à l’aide de jokers, par exemple profile/{username}, qui correspond à toutes les URL qui contiennent profile/ suivies d’un nom d’utilisateur arbitraire.

Pour rendre un segment facultatif, vous pouvez ajouter un ? (point d’interrogation) au nom du joker, par exemple profile/{username}/{section?}. Dans ce cas, l’URL va correspondre même si le segment section n’est pas fourni.

Vous pouvez contraindre davantage les segments en utilisant les exigences regex :

// elgg-plugin.php
return [
        'routes' => [
                'profile' => [
                        'path' => '/profile/{username}/{section?}',
                        'resource' => 'profile',
                        'requirements' => [
                                'username' => '[\p{L}\p{Nd}._-]+', // only allow valid usernames
                                'section' => '\w+', // can only contain alphanumeric characters
                        ],
                        'defaults' => [
                                'section' => 'index',
                        ],
                ],
        ]
];

Par défaut, Elgg va définir les exigences suivantes pour les segments d’URL nommés :

$patterns = [
        'guid' => '\d+', // only digits
        'group_guid' => '\d+', // only digits
        'container_guid' => '\d+', // only digits
        'owner_guid' => '\d+', // only digits
        'username' => '[\p{L}\p{Nd}._-]+', // letters, digits, underscores, dashes
];

Routes dépendant d’un plugin

Si une route a besoin qu’un plugin spécifique soit actif, cela peut être configuré dans la configuration de la route.

// elgg-plugin.php
return [
        'routes' => [
                'collection:object:blog:friends' => [
                        'path' => '/blog/friends/{username?}/{lower?}/{upper?}',
                        'resource' => 'blog/friends',
                        'required_plugins' => [
                                'friends', // route only allowed when friends plugin is active
                        ],
                ],
        ]
];

Middleware de routage

Les middlewares de gestion du routage peuvent être utilisés pour empêcher l’accès à une certaine route, ou pour exécuter une certaine logique avant que la route ne soit rendue. Un middleware peut être utilisé, par exemple pour implémenter un système d’inscription payante, ou pour définir des métadonnées open graph.

Le noyau de Elgg implémente plusieurs gestionnaires de middleware. Le middleware suivant se trouve dans l’espace de noms \Elgg\Router\Middleware :

Gatekeeper

Ce gestionnaire d’accès empêchera l’accès des utilisateurs non authentifiés.

AdminGatekeeper

Ce gestionnaire d’accès empêchera l’accès des utilisateurs non-administrateurs.

LoggedOutGatekeeper

Ce gestionnaire d’accès empêchera l’accès à tout utilisateur authentifié.

AjaxGatekeeper

Ce gestionnaire d’accès empêchera l’accès à toute demande non-XHR.

PageOwnerGatekeeper

Ce contrôleur d’accès empêchera l’accès s’il n’y a pas d’entité propriétaire de la page.

GroupPageOwnerGatekeeper

Ce contrôleur d’accès étend PageOwnerGatekeeper et requiert également que le propriétaire de la page soit une entité ElggGroup.

UserPageOwnerGatekeeper

Ce contrôleur d’accès étend le PageOwnerGatekeeper et requiert également que le propriétaire de la page soit une entité ElggUser.

PageOwnerCanEditGatekeeper

Ce contrôleur d’accès bloquera l’accès si aucun propriétaire de page n’est détecté et que le propriétaire de la page ne peut pas être modifié.

GroupPageOwnerCanEditGatekeeper

Ce gestionnaire d’accès étend PageOwnerCanEditGatekeeper mais exige également que le propriétaire de la page soit une entité ElggGroup.

UserPageOwnerCanEditGatekeeper

Ce gestionnaire d’accès étend PageOwnerCanEditGatekeeper mais exige également que le propriétaire soit une entité ElggUser.

CsrfFirewall

Ce middleware empêchera l’accès sans les jetons CSRF corrects. Ce middleware sera automatiquement appliqué aux actions.

ActionMiddleware

Ce middleware fournira une logique liée à l’action. Ce middleware sera automatiquement appliqué aux actions.

SignedRequestGatekeeper

Ce gestionnaire d’accès empêchera l’accès si l’URL a été trafiquée. Une URL sécurisée peut être générée à l’aide de la fonction elgg_http_get_signed_url.

UpgradeGatekeeper

Ce gestionnaire d’accès empêchera l’accès si l’URL de mise à niveau est sécurisée et que l’URL n’est pas valide.

WalledGarden

Ce middleware empêchera l’accès à une route si le site est configuré uniquement pour les utilisateurs authentifiés et qu’aucun utilisateur authentifié n’est connecté. Ce middleware est automatiquement activé pour toutes les routes. Vous pouvez désactiver le gardien du walled garden avec une option de configuration de route.

Middleware personnalisé

Les gestionnaires de middleware peuvent être définis par n’importe quelle fonction appellable qui reçoit une instance de \Elgg\Request : le gestionnaire devrait lancer une instance de \Elgg\Exceptions\HttpException pour empêcher l’accès à la route. Le gestionnaire peut renvoyer une instance de \Elgg\Http\ResponseBuilder pour empêcher la poursuite de la mise en œuvre de la séquence de routage (une réponse de redirection peut être renvoyée pour réacheminer la requête).

class MyMiddleware {

        public function __invoke(\Elgg\Request $request) {
                $entity = $request->getEntityParam();
                if ($entity) {
                        // do stuff
                } else {
                        throw new EntityNotFoundException();
                }
        }
}

elgg_register_route('myroute', [
        'path' => '/myroute/{guid?}',
        'resource' => 'myroute',
        'middleware' => [
                \Elgg\Router\Middleware\Gatekeeper::class,
                MyMiddleware::class,
        ]
]);

Contrôleurs de routage

Dans certains cas, l’utilisation des vues de ressources n’est pas appropriée. Dans ces cas, vous pouvez utiliser un contrôleur - toute fonction appelable qui reçoit une instance de \Elgg\Request :

class MyController {

        public function handleFoo(\Elgg\Request $request) {
                elgg_set_http_header('Content-Type: application/json');
                $data = [
                        'entity' => $request->getEntityParam(),
                ];
                return elgg_ok_response($data);
        }

}

elgg_register_route('myroute', [
        'path' => '/myroute/{guid?}',
        'controller' => [MyController::class, 'handleFoo'],
]);

L’événement route:rewrite

Pour la réécriture d’URL, l’événement route:rewrite (avec des arguments similaires à route) est déclenché très tôt, et permet de modifier le chemin de l’URL de la requête (par rapport au site Elgg).

Ici, nous réécrivons les requêtes de news/* vers blog/* :

function myplugin_rewrite_handler(\Elgg\Event $event) {
    $value = $event->getValue();

    $value['identifier'] = 'blog';

    return $value;
}

elgg_register_event_handler('route:rewrite', 'news', 'myplugin_rewrite_handler');

Avertissement

L’événement doit être enregistré directement dans la fonction boot du Bootstrap de votre plugin. La fonction init arrive trop tard.

Aperçu du routage

Pour les pages standard, le flux de programme de Elgg est quelque chose comme ceci :

1. Un utilisateur demande http://example.com/news/owner/jane.

2. Les plugins sont initialisés.

3. Elgg analyse l’URL pour l’identificateur news et les segments ['owner', 'jane'].

4. Elgg déclenche l’événement route:rewrite, news (voir ci-dessus).

5. Elgg trouve une route enregistrée qui correspond au chemin d’accès final de la route, et affiche la vue de ressource qui lui est associée, en appellant elgg_view_resource('blog/owner', $vars), où $vars contient le nom d’utilisateur.

6. La vue resources/blog/owner obtient le nom d’utilisateur via $vars['username'] et utilise de nombreuses autres vues et fonctions de mise en forme telles que elgg_view_layout() et elgg_view_page() pour créer la page HTML complète.

7. PHP invoque la séquence d’arrêt de Elgg.

8. L’utilisateur reçoit une page complète.

Les normes de codage de Elgg suggèrent une disposition d’URL particulière, mais il n’y a pas de syntaxe obligatoire.

Recherche

Recherche d’entité

Le noyau de Elgg fournit des elgg_search() flexibles, qui préparent des clauses de recherche personnalisées et utilisent elgg_get_entities() pour récupérer les résultats.

Outre tous les paramètres acceptés par elgg_get_entities(), elgg_search() accepte les paramètres suivants :

• query Requête - Termes de la recherche

• fields Un tableau de noms par type de propriété à rechercher (voir l’exemple ci-dessous)

• sort_by Un tableau contenant des options de tri, comprenant property, property_type et direction

• type Type d’entité à rechercher

• subtype Sous-type d’entité à rechercher - facultatif

• search_type Type de recherche personnalisé (requis si aucun type n’est fourni)

• partial_match Autorise les correspondances partielles

  Par défaut, les correspondances partielles sont autorisées, ce qui signifie que elgg sera trouvé lors de la recherche de el. Les correspondances exactes peuvent être utiles lorsque vous souhaitez trouver les correspondances pour une métadonnée précise, par exemple lorsque vous voulez trouver tous les objets dont la couleur est red et non darkred

• tokenize Décomposer la requête de recherche en jetons

  Par défaut, les requêtes de recherche utilisent des jetons - sont tokenisées, ce qui signifie que nous allons trouver elgg a été publié lors d’une recherche sur elgg publié

// List all users who list United States as their address or mention it in their description
$options = [
    'type' => 'user',
    'query' => 'us',
    'fields' => [
        'metadata' => ['description'],
        'annotations' => ['location'],
    ],
    'sort_by' => [
        'property' => 'zipcode',
        'property_type' => 'annotation',
        'direction' => 'asc',
    ],
];

echo elgg_list_entities($options, 'elgg_search');

Champs de recherche

Vous pouvez personnaliser les champs de recherche pour chaque type/sous-type d’entité, en utilisant l’événement search:fields :

// Let's remove search in location and add address field instead
elgg_register_event_handler('search:fields', 'user', 'my_plugin_search_user_fields');

function my_plugin_search_user_fields(\Elgg\Event $event) {
    $fields = $event->getValue();
    $location_key = array_search('location', $fields['annotations']);
    if ($location_key) {
        unset($fields[$location_key]['annotations']);
    }

    $fields['metadata'][] = 'address';

    return $fields;
}

Entités pouvant être recherchées

Pour enregistrer un type d’entité pour la recherche, utilisez elgg_entity_enable_capability($type, $subtype, 'searchable'), ou faites-le lors de la définition du type d’entité dans elgg-plugin.php.

Note

Le plugin de recherche utilise la capacité d’entité searchable. Cette capacité définit si une entité peut être recherchée.

Pour combiner les résultats de recherche ou filtrer la façon dont les résultats de recherche sont présentés dans le plugin de recherche, utilisez l’événement 'search:config', 'type_subtype_pairs'.

// Let's add places and place reviews as public facing entities
elgg_entity_enable_capability('object', 'place', 'searchable');
elgg_entity_enable_capability('object', 'place_review', 'searchable');

// Now let's include place reviews in the search results for places
elgg_register_event_handler('search:options', 'object:place', 'my_plugin_place_search_options');
elgg_register_event_handler('search:config', 'type_subtype_pairs', 'my_plugin_place_search_config');

// Add place review to search options as a subtype
function my_plugin_place_search_options(\Elgg\Event $event) {

    $params = $event->getParams();
    if (isset($params['subtypes'])) {
        $subtypes = (array) $params['subtypes'];
    } else {
        $subtypes = (array) elgg_extract('subtype', $params);
    }

    if (!in_array('place', $subtypes)) {
        return;
    }

    unset($params["subtype"]);

    $subtypes[] = 'place_review';
    $params['subtypes'] = $subtypes;

    return $params;
}

// Remove place reviews as a separate entry in search sections
function my_plugin_place_search_config(\Elgg\Event $event) {

    $types = $event->getValue();

    if (empty($types['object'])) {
        return;
    }

    foreach ($types['object'] as $key => $subtype) {
        if ($subtype == 'place_review') {
            unset($types['object'][$key]);
        }
    }

    return $types;
}

Types de recherches personnalisés

Le noyau de Elgg prend en charge uniquement la recherche d’entités. Vous pouvez implémenter des recherches personnalisées, par exemple en utilisant une requête de recherche comme un emplacement pour lister les entités à proximité de cet emplacement.

// Let's added proximity search type
elgg_register_event_handler('search:config', 'search_types', function (\Elgg\Event $event) {
    $search_types = $event->getValue();
    $search_types[] = 'promimity';

    return $search_types;
});

// Let's add search options that will look for entities that have geo coordinates and order them by proximity to the query location
elgg_register_event_handler('search:options', 'proximity', function (\Elgg\Event $event) {

    $query = $event->getParam('query');
    $options = $event->getValue();

    // Let's presume we have a geocoding API
    $coords = geocode($query);

    // We are not using standard 'selects' options here, because counting queries do not use custom selects
    $options['wheres']['proximity'] = function (QueryBuilder $qb, $alias) use ($lat, $long) {
        $dblat = $qb->joinMetadataTable($alias, 'guid', 'geo:lat');
        $dblong = $qb->joinMetadataTable($alias, 'guid', 'geo:long');

        $qb->addSelect("(((acos(sin(($lat*pi()/180))
                    *sin(($dblat.value*pi()/180)) + cos(($lat*pi()/180))
                    *cos(($dblat.value*pi()/180))
                    *cos((($long-$dblong.value)*pi()/180)))))*180/pi())
                    *60*1.1515*1.60934
                    AS proximity");

        $qb->orderBy('proximity', 'asc');

        return $qb->merge([
            $qb->compare("$dblat.value", 'is not null'),
            $qb->compare("$dblong.value", 'is not null'),
        ]);
    };

    return $options;
});

Points de terminaison pour l’autocomplétion et la recherche en direct

Le coeur de Elgg fournit un point de terminaison JSON pour rechercher des utilisateurs et des groupes. Ces points de terminaison sont utilisés par les vues input/autocomplete et input/entitypicker.

// Get JSON results of a group search for 'class'
$json = file_get_contents('http://example.com/livesearch/groups?view=json&q=class');

Vous pouvez ajouter des types de recherche personnalisés en ajoutant une vue de ressource correspondante :

// Let's add an endpoint that will search for users that are not members of a group
// and render a userpicker for our invite form
echo elgg_view('input/userpicker', [
    'handler' => 'livesearch/non_members',
    'options' => [
        // this will be sent as URL query elements
        'group_guid' => $group_guid,
    ],
]);

// To enable /livesearch/non_members endpoint, we need to add a view
// in /views/json/resources/livesearch/non_members.php

$limit = get_input('limit', elgg_get_config('default_limit'));
$query = get_input('term', get_input('q'));
$input_name = get_input('name');

// We have passed this value to our input view, and we want to make sure
// external scripts are not using it to mine data on group members
// so let's validate the HMAC that was generated by the userpicker input
$group_guid = (int) get_input('group_guid');

$data = [
    'group_guid' => $group_guid,
];

// let's sort by key, in case we have more elements
ksort($data);

$hmac = elgg_build_hmac($data);
if (!$hmac->matchesToken(get_input('mac'))) {
     // request does not originate from our input view
     throw new \Elgg\Exceptions\Http\EntityPermissionsException();
}

elgg_set_http_header("Content-Type: application/json;charset=utf-8");

$options = [
    'query' => $query,
    'type' => 'user',
    'limit' => $limit,
    'sort' => 'name',
    'order' => 'ASC',
    'fields' => [
        'metadata' => ['name', 'username'],
    ],
    'item_view' => 'search/entity',
    'input_name' => $input_name,
    'wheres' => function (QueryBuilder $qb) use ($group_guid) {
        $subquery = $qb->subquery('entity_relationships', 'er');
        $subquery->select('1')
            ->where($qb->compare('er.guid_one', '=', 'e.guid'))
            ->andWhere($qb->compare('er.relationship', '=', 'member', ELGG_VALUE_STRING))
            ->andWhere($qb->compare('er.guid_two', '=', $group_guid, ELGG_VALUE_INTEGER));

        return "NOT EXISTS ({$subquery->getSQL()})";
    }
];

echo elgg_list_entities($options, 'elgg_search');

Services

Elgg utilise la classe Elgg\Application pour charger et initialiser Elgg. Dans les versions futures cette classe offrira un ensemble d’objets de service à l’usage des plugins.

Note

Si vous avez une idée utile, vous pouvez ajouter un nouveau service !

Menus

elgg()->menus fournit des méthodes de bas niveau pour la construction de menus. En général, les menus doivent être transmis à elgg_view_menu pour le rendu, plutôt qu’un rendu manuel.

Paramètres de plugin

Vous devez effectuer quelques étapes supplémentaires si votre plugin a besoin de paramètres qui doivent être enregistrés et contrôlés via le panneau d’administration :

• Créez un fichier dans le dossier des vues par défaut de votre plugin appelé plugins/your_plugin/settings.php, où your_plugin est le nom du répertoire de votre plugin dans la hiérarchie mod

• Remplissez ce fichier avec les éléments de formulaire que vous souhaitez afficher avec les traductions des étiquettes de texte

• Définissez l’attribut name dans vos composants de formulaire sur params[`varname`] où varname est le nom de la variable. Ceux-ci seront enregistrés sous forme de métadonnées attachées à une entité de plugin. Ainsi, si votre variable s’appelle params[myparameter], votre plugin (qui est également passé à cette vue sous le nom $vars['entity']) s’appellera $vars['entity'] ->myparameter

Un exemple de settings.php ressemblerait à :

echo elgg_view_field([
        '#type' => 'select',
        '#label' => elgg_echo('myplugin:settings:limit'),
        'name' => 'params[limit]',
        'value' => $vars['entity']->limit,
        'options' => [5,8,12,15],
]);

Note

Vous n’avez pas besoin d’ajouter de bouton d’enregistrement ni le formulaire, cela sera géré par le framework.

Note

Vous ne pouvez pas utiliser des composants de formulaire qui n’envoient aucune valeur lorsqu’ils sont « off ». Il s’agit notamment des entrées radio et des cases à cocher.

Si vos paramètres de plugin ont besoin d’un vidage des caches, vous pouvez ajouter une entrée (cachée) sur le formulaire avec le nom “flush_cache” et la valeur “1”

elgg_view_field([
        '#type' => 'hidden',
        'name' => 'flush_cache',
        'value' => 1,
]);

Paramètres de l’utilisateur

Votre plugin peut également avoir besoin de stocker des paramètres pour chaque utilisateur, et vous voudrez voir les options de votre plugin apparaître dans la page des paramètres de l’utilisateur. Ceci est également facile à faire et suit le même modèle que la configuration globale du plugin expliquée plus tôt. La seule différence est qu’au lieu d’utiliser un fichier settings, vous utiliserez usersettings. Ainsi, le chemin d’accès à la vue de modification des paramètres utilisateur de votre plugin serait plugins/<your_plugin>/usersettings.php.

Note

Le titre du formulaire des paramètres utilisateur sera par défaut le nom du plugin. Si vous souhaitez modifier cela, ajoutez une traduction pour <plugin_id>:usersettings:title.

Paramètres du groupe

Si votre plugin a besoin de paramètres pour chaque groupe, vous pouvez étendre la vue groups/edit/settings pour afficher vos paramètres. Les paramètres sont affichés lors de la création et de la modification du groupe. Pour que les paramètres soient enregistrés correctement, ils ont besoin d’un nom au format settings[<plugin id>][<setting name>].

Récupérer des paramètres dans votre code

Pour récupérer les paramètres depuis votre code utilisez :

$setting = elgg_get_plugin_setting($name, $plugin_id);

ou pour les paramètres utilisateur :

$user_setting = elgg_get_plugin_user_setting($name, $user_guid, $plugin_id);

// or
$user = get_user($user_guid);
$user_setting = $user->getPluginSetting($plugin_id, $name);

où :

• $name Est la valeur que vous souhaitez récupérer

• $user_guid Est l’utilisateur pour lequel vous souhaitez récupérer ces valeurs (par défaut l’utilisateur actuellement connecté)

• $plugin_name Est le nom du plugin (détecté s’il s’exécute à partir d’un plugin)

ou pour les paramètres du groupe :

$group = get_entity($group_guid);
$value = $group->getPluginSetting('<plugin id>', '<setting name>');

Définir des valeurs via le code

Les valeurs peuvent également être définies à partir du code de votre plugin, pour cela utilisez l’une des fonctions suivantes :

$plugin = elgg_get_plugin_from_id($plugin_id);
$plugin->setSetting($name, $value);

ou pour les paramètres utilisateur :

$user = elgg_get_logged_in_user_entity();
$user->setPluginSetting($plugin_id, $name, $value);

ou pour les paramètres du groupe :

$group = get_entity($group_guid);
$group->setPluginSetting($plugin_id, $name, $value);

Avertissement

Le $plugin_id doit être fourni lors de la définition des paramètres du plugin (ou de l’utilisateur).

Paramètres par défaut (groupe|utilisateur) du plugin

Si un plugin ou un utilisateur n’a pas de paramètre stocké dans la base de données, vous avez parfois besoin d’une certaine valeur par défaut. Vous pouvez passer cela lors de l’utilisation des fonctions de récupération - getter.

$user_setting = elgg_get_plugin_user_setting($name, $user_guid, $plugin_id, $default);

$plugin_setting = elgg_get_plugin_setting($name, $plugin_id, $default);

$group_setting = $group->getPluginSetting($plugin_id, $name, $default);

Vous pouvez également fournir des paramètres par défaut du plugin et de l’utilisateur dans le fichier elgg-plugin.php.

<?php

return [
        'settings' => [
            'key' => 'value',
        ],
        'user_settings' => [
            'key' => 'value',
        ],
];

Note

Les paramètres de groupe n’ont pas de valeur par défaut disponible dans le fichier elgg-plugin.php.

Thèmes

Personnaliser l’apparence et le comportement de Elgg.

Un thème est un type de plugin qui surcharge des aspects d’affichage de Elgg.

Ce guide suppose que vous connaissez :

• Plugins

• Vues

Principes de création d’un thème et Bonnes Pratiques

Pas de framework CSS tierce-partie

Elgg n’utilise pas de framework CSS, car ces frameworks enferment les utilisateurs dans un balisage HTML spécifique, ce qui rend finalement beaucoup plus difficile pour les plugins de collaborer sur l’apparence. Ce qui est is-primary dans un thème pourrait être quelque chose d’autre dans un autre. L’absence de framework permet aux plugins de modifier l’apparence à l’aide de css pur, sans avoir à remplacer des vues ni devoir ajouter aux éléments de balisage HTML des sélecteurs spécifiques à un framework particulier.

/* BAD */
<div class="box has-shadow is-inline">
        This is bad, because if the plugin wants to change the styling, it will have to either write really specific css
        clearing all the attached styles, or replace the view entirely just to modify the markup
</div>

/* GOOD */
<div class="box-role">
        This is good, because a plugin can just simply add .box-role rule
</div>
<style>
        .box-role {
         padding: 1rem;
         display: inline-block;
         box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
        }
</style>

système de grille à 8 points

Elgg utilise un système de grille à 8 points <https://builttoadapt.io/intro-to-the-8-point-grid-system-d2573cde8632>, aussi les dimensions des éléments, leurs marges internes et externes, etc se font par incréments et fractions de 8px. Étant donné que notre taille de police par défaut est 16px, nous utilisons des fractions de rem, de sorte que 0.5rem = 8px. Le système de grille à 8 points permet aux développeurs de collaborer beaucoup plus facilement sur des éléments de style : cela évite de se demander si la marge interne doit être de 5px ou de 6px.

/* BAD */
.menu > li {
        margin: 2px 2px 2px 0;
}

.menu > li > a {
        padding: 3px 5px;
}

/* GOOD */
.menu > li > a {
        padding: 0.25rem 0.5rem;
}

Mobile first - Conçu d’abord pour les mobiles

Nous écrivons un CSS mobile-first. Nous utilisons deux points de rupture : 50rem et 80rem (800px et 1280px à 16px/rem).

/* BAD: mobile defined in media blocks, different display types */

.menu > li {
        display: inline-block;
}
@media screen and (max-width: 820px) {
        .menu > li {
                display: block;
                width: 100%;
        }
}

/* GOOD: mobile by default. Media blocks style larger viewports. */

.menu {
        display: flex;
        flex-direction: column;
}
@media screen and (min-width: 50rem) {
        .menu {
                flex-direction: row;
        }
}

piloté par Flexbox

Flexbox offre une simplicité d’empilement d’éléments dans des grilles. Flexbox est utilisé pour tout, des menus aux éléments de mise en page.

/* BAD */
.heading:after {
        visibility: hidden;
        height: 0;
        clear: both;
        content: " ";
}
.heading > h2 {
        float: left;
}
.heading > .controls {
        float: right;
}

/* GOOD */
.heading {
        display: flex;
        justify-content: flex-end;
}
.heading > h2 {
        order: 1;
        margin-right: auto;
}
.heading > .controls {
        order: 2;
}

Symétrique

Nous maintenons la symétrie.

/* BAD */
.row .column:first-child {
        margin-right: 10px;
}

/* GOOD */
.row {
        margin: 0 -0.5rem;
}
.row .column {
        margin: 0.5rem;
}

Des transitions de couleur simples

Nous maintenons 4 ensembles de couleurs pour le texte, les arrière-plans et les bordures : soft - doux, mild - modéré, strong - fort et highlight - en exergue. Lors de la transition vers l’état hover ou active, nous montons d’un niveau, par exemple de soft à mild, ou utilisons highlight. Lorsque nous passons à un état inactif ou désactivé, nous descendons d’un niveau.

Augmentez la zone de clic

En travaillant avec des ancres imbriquées, nous augmentons la zone de clic de l’ancre, plutôt que le parent

/* BAD */
.menu > li {
        margin: 5px;
        padding: 5px 10px;
}

/* GOOD */
.menu > li {
        margin: 0.5rem;
}
.menu > li > a {
        padding: 0.5rem 1rem;
}

Pas de z-index 999999

les z-index sont incrémentés par pas de 1.

Envelopper les parents HTML

Nous nous assurons qu’il n’y a pas de chaîne orpheline au sein d’un parent et que les frères et sœurs sont enveloppés d’une manière qui permet de les cibler par CSS.

/* BAD */
<label>
        Orphan
        <span>Sibling</span>
</label>

/* GOOD */
<label>
        <span>Sibling</span>
        <span>Sibling</span>
</label>

/* BAD */
<div>
        <h3>Title</h3>
        <p>Subtitle</p>
        <div class="right">This goes to the right</div>
</div>

/* GOOD */
<div>
        <div class="left">
         <h3>Title</h3>
         <p>Subtitle</p>
        </div>
        <div class="right">This goes to the right</div>
</div>

Créez votre plugin

Créez votre plugin tel que décrit dans le guide de développement.

• Créez un nouveau dossier dans mod/

• Créer un nouveau fichier elgg-plugin.php

• Créez un fichier composer.json décrivant votre thème.

Personnalisez les CSS

Le css est découpé en plusieurs fichiers en fonction des aspects du site que vous êtes en train de styler. Cela vous permet de les aborder un à la fois, vous donnant une chance de faire de réelles améliorations sans être submergé.

Voici la liste des vues CSS existantes :

• elements/buttons.css : fournit un moyen de styler tous les différents types de boutons que votre site utilise. Il existe 5 types de boutons que les plugins s’attendent à trouver disponibles : action, cancel - annuler, delete - supprimer, submit - envoyer, et special.

• elements/chrome.css : ce fichier comporte diverses classes de présentation.

• elements/components.css : ce fichier contient de nombreux “objets css” qui sont utilisés sur tout le site : media block - bloc multimédia, list, gallery, table - tableau, owner block - propriétaire, system, messages, river, tags, photo et comments.

• elements/forms.css : ce fichier détermine à quoi ressembleront vos formulaires et éléments d’entrées

• elements/icons.css : contient des styles pour les icônes et avatars utilisés sur votre site.

• elements/layout.css : détermine à quoi ressemblera votre page : barres latérales, emballage de la page, corps principal, entête, pied de page, etc.

• elements/modules.css : Beaucoup de contenu dans Elgg s’affiche dans des boîtes avec un titre et un corps de contenu. Nous les avons appelées des modules. Il en existe de quelques sortes: info, aside - sur le côté, featured - en vedette, dropdown - déroulant, popup, widget. Les styles des widgets sont également inclus dans ce fichier, car ils sont un sous-ensemble des modules.

• elements/navigation.css : Ce fichier détermine à quoi ressembleront tous vos menus.

• elements/typography.css : ce fichier détermine à quoi ressemblera le contenu et les titres de votre site.

• rtl.css : des règles personnalisées pour les utilisateurs qui consultent votre site dans une langue de droite à gauche.

• admin.css : un thème totalement distinct pour la zone d’administration (généralement pas remplacé).

• elgg.css : compile tous les fichiers du noyau du dossier elements/* dans un seul fichier (NE PAS REMPLACER).

• éléments/reset.css : contient une feuille de style de réinitialisation qui force les éléments à avoir le même rendu par défaut

Variables CSS

Elgg utilise CssCrush pour prétraiter les fichiers CSS. Cela nous donne la flexibilité d’utiliser des variables CSS globales. Les plugins devraient, dans la mesure du possible, utiliser des variables CSS globales et étendre le thème de base avec leurs variables plugin, afin qu’ils puissent être simplement modifiés par d’autres plugins.

Pour ajouter ou modifier des variables, utilisez l’événement vars:compiler, css. Notez que vous devrez peut-être vider le cache pour voir vos modifications en action.

Pour obtenir une liste des variables par défaut du noyau, voyez engine/theme.php.

Extension d’une vue

Il existe deux manières de modifier les vues :

La première façon est d’ajouter des éléments supplémentaires à une vue existante via la section views_extensions dans la définition de votre elgg-plugin.php.

Par exemple, la configuration suivante va ajouter mytheme/css au fichier css du noyau de Elgg :

<?php
        return [
                'view_extensions' => [
                        'elgg.css' => [
                                'mytheme/css' => [],
                        ],
                ],
        ];

Surcharge des vues

Les plugins peuvent avoir une arborescence des vues, n’importe quel fichier qui existe ici remplacera tout fichier dans l’arborescence des vues du noyau existante… ainsi par exemple, si mon plugin a un fichier :

/mod/myplugin/views/default/elements/typography.css

ceci va remplacer :

/views/default/elements/typography.css

Mais seulement quand le plugin est actif.

Cela vous donne un contrôle total sur l’apparence et le comportement de Elgg. Cela vous offre la possibilité de modifier légèrement ou de remplacer totalement les vues existantes.

Icônes

À partir de Elgg 2.0, les icônes par défaut de Elgg proviennent de la bibliothèque FontAwesome. Vous pouvez utiliser l’une de ces icônes en appelant :

elgg_view_icon('icon-name');

icon-name peut être n’importe laquelle des icônes de FontAwesome sans le préfixe fa--.

Par défaut, vous obtiendrez la variante de style solid des icônes. En ajoutant au nom de l’icône l’un des suffixes -solid, -regular ou -light, vous pouvez cibler un style spécifique. Soyez avisé ; la variante de style light n’est disponible qu’en tant qu’icône sous licence FontAwesome Pro.

Outils

Nous vous avons fourni quelques outils de développement pour vous aider à mettre en place des thèmes : activez le plugin “Developers” et accédez à la page “Theme Preview” - Aperçu du thème - pour commencer à suivre les progrès de votre thème.

Personnaliser la page d’accueil

La page d’index principale de Elgg est servie via une vue des ressource.

Par conséquent, vous pouvez le remplacer en fournissant votre propre fichier de ressources dans your_plugin/views/default/resources/index.php.

Écrire une mise à niveau de plugin

De temps en temps, il arrive un moment où un plugin doit modifier le contenu ou la structure des données qu’il a stockées soit dans la base de données, soit dans le répertoire des données.

La raison de ceci pourrait être que la structure des données doit être convertie en une structure plus efficace ou plus flexible. Ou peut-être en raison d’un bogue les éléments de données ont été enregistrés d’une manière non valide, et ils doivent être convertis dans le format correct.

De telles migrations et conversions peuvent prendre beaucoup de temps s’il y a beaucoup de données à traiter. C’est pourquoi Elgg fournit la classe Elgg\Upgrade\AsynchronousUpgrade qui peut être utilisée pour implémenter des mises à niveau de longue durée.

Déclarer la mise à niveau d’un plugin

Le plugin peut communiquer la nécessité d’une mise à niveau avec la clé upgrades dans le fichier elgg-plugin.php. Chaque valeur du tableau doit être le nom complet d’une classe de mise à niveau qui étend la classe Elgg\Upgrade\AsynchronousUpgrade.

Exemple tiré du fichier mod/blog/elgg-plugin.php :

return [
        'upgrades' => [
                Blog\Upgrades\AccessLevelFix::class,
                Blog\Upgrades\DraftStatusUpgrade::class,
        ]
];

Les noms de classe dans l’exemple se réfèrent aux classes :

• mod/blog/classes/Blog/Upgrades/AccessLevelFix

• mod/blog/classes/Blog/Upgrades/DraftStatusUpgrade

Note

Les classes de mise à niveau du noyau Elgg peuvent être déclarées dans engine/lib/upgrades/async-upgrades.php.

La classe de mise à niveau

Une classe qui étend la classe Elgg\Upgrade\AsynchronousUpgrade a beaucoup de liberté sur la façon dont elle souhaite gérer le traitement réel des données. Elle doit cependant déclarer certaines variables constantes et également prendre soin de marquer si chaque élément traité a été mis à niveau avec succès ou non.

La structure de base de la classe est la suivante :

<?php

namespace Blog\Upgrades;

use Elgg\Upgrade\AsynchronousUpgrade;
use Elgg\Upgrade\Result;

/**
 * Fixes invalid blog access values
 */
class AccessLevelFix extends AsynchronousUpgrade {

        /**
         * Version of the upgrade
         *
         * @return int
         */
        public function getVersion() {
                return 2016120300;
        }

        /**
         * Should the run() method receive an offset representing all processed items?
         *
         * @return bool
         */
        public function needsIncrementOffset() {
                return true;
        }

        /**
         * Should this upgrade be skipped?
         *
         * @return bool
         */
        public function shouldBeSkipped() {
                return false;
        }

        /**
         * The total number of items to process in the upgrade
         *
         * @return int
         */
        public function countItems() {
                // return count of all blogs
        }

        /**
         * Runs upgrade on a single batch of items
         *
         * @param Result $result Result of the batch (this must be returned)
         * @param int    $offset Number to skip when processing
         *
         * @return Result Instance of \Elgg\Upgrade\Result
         */
        public function run(Result $result, $offset) {
                // fix 50 blogs skipping the first $offset
        }
}

Avertissement

Ne présumez pas quand votre classe sera instanciée ou quand/combien de fois ses méthodes publiques seront appelées.

Méthodes de la classe

getVersion()

Cela doit renvoyer un entier représentant la date à laquelle la mise à niveau a été ajoutée. La valeur se compose de huit chiffres au format yyyymmdnn où:

• yyyy représente l’année

• mm représente le mois (avec le zéro initial)

• dd représente le jour (avec le zéro initial)

• nn est un numéro d’incrément (à partir de 00) qui est utilisé au cas où deux mises à niveau distinctes auraient été ajoutées au cours de la même journée

shouldBeSkipped()

Cela devrait renvoyer false à moins que la mise à niveau ne soit pas nécessaire.

Avertissement

Si true est renvoyé, la mise à niveau ne peut pas être exécutée plus tard.

needsIncrementOffset()

Si true, votre méthode run() recevra comme $offset le nombre d’éléments déjà traités. Ceci est utile si vous ne modifiez que des données et que vous devez utiliser le $offset dans une fonction comme elgg_get_entities() pour savoir combien d’éléments ont déjà été traités.

Si false, votre méthode run() recevra comme $offset le nombre total d’échecs. false doit être utilisé si votre processus supprime ou déplace des données en dehors du processus. Par exemple, si vous supprimez 50 objets sur chaque run(), vous n’avez pas vraiment besoin de $offset.

countItems()

Récupère le nombre total d’éléments à traiter pendant la mise à niveau. Si ce nombre est inconnu, Batch::UNKNOWN_COUNT peut être retourné, mais run() doit alors marquer manuellement la mise à niveau terminée.

run()

Cette fonction doit effectuer une partie de la mise à niveau effective. Et en fonction de la durée nécessaire, elle peut être appelée plusieurs fois au cours d’une seule demande.

Elle reçoit deux arguments :

• $result : Une instance de l’objet Elgg\Upgrade\Result

• $offset : Le décalage à partir duquel la prochaine portion de mise à niveau doit commencer (ou le nombre total de défaillances)

Pour chaque élément que la méthode traite, elle doit appeler selon les cas :

• $result->addSuccesses() : Si l’élément a bien été mis à niveau

• $result->addFailures() : Si l’élément n’a pas pu être mis à niveau

Les deux méthodes ont par défaut un seul élément, mais vous pouvez éventuellement passer le nombre d’éléments.

En outre, elle peut définir autant de messages d’erreur que nécessaire dans le cas où quelque chose ne va pas :

• $result->addError("Le message d'erreur est indiqué ici")

Si countItems() renvoie Batch::UNKNOWN_COUNT, alors à un moment donné run() doit appeler $result->markComplete() pour terminer la mise à niveau.

Dans la plupart des cas, votre méthode run() voudra passer le paramètre $offset à l’une des fonctions elgg_get_entities() :

/**
 * Process blog posts
 *
 * @param Result $result The batch result (will be modified and returned)
 * @param int    $offset Starting point of the batch
 * @return Result Instance of \Elgg\Upgrade\Result;
 */
public function run(Result $result, $offset) {
        $blogs = elgg_get_entitites([
                'type' => 'object'
                'subtype' => 'blog'
                'offset' => $offset,
        ]);

        foreach ($blogs as $blog) {
                if ($this->fixBlogPost($blog)) {
                        $result->addSuccesses();
                } else {
                        $result->addFailures();
                        $result->addError("Failed to fix the blog {$blog->guid}.");
                }
        }

        return $result;
}

getUpgrade()

Utilisez cette fonction pour obtenir l’entité ElggUpgrade associée à cette mise à niveau.

Interface d’administration

Chaque mise à niveau étendant la classe Elgg\Upgrade\AsynchronousUpgrade est répertoriée dans le panneau d’administration après avoir déclenché la mise à niveau du site depuis le tableau de bord d’administration.

Lors de l’exécution des mises à niveau, Elgg fournit :

• Durée estimée de la mise à niveau

• Nombre d’éléments traités

• Nombre d’erreurs

• Messages d’erreur possibles

Vues

Introduction

Les vues sont responsables de la création des sorties. Elles gèrent tout depuis :

• la disposition / mise en page des pages

• des morceaux de sortie d’affichage (comme un pied de page ou une barre d’outils)

• des liens individuels et des entrées de formulaire.

• des images, js, et css nécessaires pour votre page web

Utiliser les vues

À leur niveau le plus élémentaire, les vues par défaut ne sont que des fichiers PHP avec des extraits de html :

<h1>Hello, World!</h1>

En supposant que cette vue se trouve dans /views/default/hello.php, nous pourrions l’afficher comme ceci :

echo elgg_view('hello');

Pour votre commodité, Elgg est livré avec un bon nombre de vues par défaut. Afin de garder les choses gérables, elles sont organisées en sous-répertoires. Elgg gère parfaitement cette organisation. Par exemple, notre vue simple peut être située dans /views/default/hello/world.php, auquel cas elle sera appelée comme ceci :

echo elgg_view('hello/world');

Le nom de la vue reflète simplement l’emplacement de la vue dans le répertoire des vues.

Les vues comme modèles - templates

Vous pouvez transmettre des données arbitraires à une vue via le tableau $vars. Notre vue hello/world pourrait être modifié pour accepter une variable comme ceci :

<h1>Hello, <?= $vars['name']; ?>!</h1>

Dans ce cas, nous pouvons passer un paramètre de nom arbitraire à la vue :

echo elgg_view('hello/world', ['name' => 'World']);

qui produirait la sortie suivante :

<h1>Hello, World!</h1>

Avertissement

Les vues ne font aucune sorte d’assainissement automatique de la sortie par défaut. Vous êtes responsable de faire par vous-même l’assainissement correct pour prévenir les attaques XSS et similaires.

Les vues en tant qu’actifs pouvant être mis en cache

Comme mentionné précédemment, les vues peuvent contenir du JS, du CSS, ou même des images.

Les actifs doivent correspondre à certaines exigences :

• Elles ne doivent pas utiliser de paramètre de $vars

• Ils ne doivent pas modifier leur sortie en fonction de l’état global, tels que

  • qui est connecté

  • l’heure de la journée

• Ils doivent avoir une extension de fichier valide

  • Mauvais : my/cool/template

  • Bon : my/cool/template.html

Par exemple, supposons que vous vouliez charger certains CSS sur une page. Vous pouvez définir une vue mystyles.css, qui ressemblerait à ceci :

/* /views/default/mystyles.css */
.mystyles-foo {
  background: red;
}

Note

Omettez l’extension « .php » du nom de fichier et Elgg reconnaîtra automatiquement la vue comme pouvant être mise en cache.

Pour obtenir une URL vers ce fichier, vous utiliseriez elgg_get_simplecache_url :

// Returns "https://mysite.com/.../289124335/default/mystyles.css
elgg_get_simplecache_url('mystyles.css');

Elgg ajoute automatiquement les numéros magiques que vous voyez là pour le cache-busting et définit les entêtes Expires à long terme sur le fichier renvoyé.

Avertissement

Elgg pourrait décider de modifier l’emplacement ou la structure de l’URL retournée dans une version ultérieure pour une raison quelconque, et les numéros d’invalidation du cache « cache-busting » changent à chaque fois que vous videz les caches de Elgg, de sorte que l’URL exacte n’est pas stable par design.

Avec cela à l’esprit, voici quelques anti-modèles à éviter :

• Ne vous fiez pas à la structure/emplacement exacts de cette URL

• N’essayez pas de générer les URLs vous-même

• Ne stockez pas les URLs renvoyées dans une base de données

Sur la page où vous souhaitez charger le css, appelez :

elgg_require_css('mystyles');

Vues et actifs tierce-partie - assets

La meilleure manière de servir des actifs tiers est par le biais des vues. Toutefois, au lieu de copier/coller manuellement les actifs au bon endroit dans /views/*, vous pouvez mapper les actifs dans le système de vues via la clef "views" dans le fichier de configuration elgg-plugin.php de votre plugin.

La valeur des vues doit être un tableau à 2 dimensions. Le premier niveau mappe un type de vue à une liste de mappage de vues. Le deuxième niveau associe les noms des vues à des chemins de fichiers, soit absolus, soit relatifs au répertoire racine de Elgg.

Si vous ajoutez vos actifs au suivi de version, pointez-les comme ceci :

<?php // mod/example/elgg-plugin.php
return [
    // view mappings
    'views' => [
        // viewtype
        'default' => [
            // view => /path/from/filesystem/root
            'js/jquery-ui.js' => __DIR__ . '/node_modules/components-jqueryui/jquery-ui.min.js',
        ],
    ],
];

Pour pointer vers les actifs installés avec composer, utilisez les chemins install-root-relative en omettant le slash initial :

<?php // mod/example/elgg-plugin.php
return [
    'views' => [
        'default' => [
            // view => path/from/install/root
            'js/jquery-ui.js' => 'vendor/npm-asset/components-jqueryui/jquery-ui.min.js',
        ],
    ],
];

Le noyau de Elgg utilise cette fonctionnalité largement, cependant la valeur est retournée directement à partir de /engine/views.php.

Note

Vous n’avez pas besoin d’utiliser NPM, Composer Asset Plugin, ou n’importe quel autre script pour gérer les actifs de votre plugin, mais nous vous recommandons fortement d’utiliser un gestionnaire de package quel qu’il soit, car cela facilite grandement la mise à niveau.

En spécifiant des répertoires supplémentaires pour les vues

Dans elgg-plugin.php vous pouvez également spécifier des répertoires à scanner pour les vues. Il suffit de fournir un préfixe de nom de vue se terminant par / et un chemin de répertoire (comme ci-dessus).

<?php // mod/file/elgg-plugin.php
return [
    'views' => [
        'default' => [
            'file/icon/' => __DIR__ . '/graphics/icons',
        ],
    ],
];

Avec ce qui précède, les fichiers trouvés dans le dossier icons seront interprétés comme des vues. Par exemple, la vue file/icon/general.gif sera créée et mappée vers mod/file/graphics/icons/general.gif.

Note

Il s’agit d’un scan entièrement récursif. Tous les fichiers trouvés seront introduits dans le système de vues.

Plusieurs chemins peuvent partager le même préfixe, il suffit de donner un tableau de chemins :

<?php // mod/file/elgg-plugin.php
return [
    'views' => [
        'default' => [
            'file/icon/' => [
                __DIR__ . '/graphics/icons',
                __DIR__ . '/more_icons', // processed 2nd (may override)
            ],
        ],
    ],
];

Types de vues - Viewtypes

Vous pouvez vous demandez : « Pourquoi avoir /views/default/hello/world.php au lieu de simplement /views/hello/world.php ? ».

Le sous-répertoire dans /views détermine le type de vue, ou viewtype, des vues qu’il contient. Un type de vue correspond généralement au format de sortie des vues.

Le type de vue par défaut est supposé être HTML et d’autres actifs statiques nécessaires pour rendre une page Web réactive dans un navigateur de bureau ou mobile, mais il peut également être :

• RSS

• ATOM

• JSON

• HTML optimisé pour mobile

• HTML optimisé pour TV

• De nombreux autres formats de données

Vous pouvez forcer Elgg à utiliser un type de vue particulier pour afficher la page en définissant la variable d’entrée view comme ceci : https://mysite.com/?view=rss.

Vous pourriez également écrire un plugin pour définir ceci automatiquement à l’aide de la fonction elgg_set_viewtype(). Par exemple, votre plugin peut détecter que la page a été consultée avec la chaîne de navigateur d’un iPhone, et définir le type de vue sur iphone en appelant :

elgg_set_viewtype('iphone');

Le plugin fournirait probablement également un ensemble de vues optimisées pour ces appareils.

Modifier des vues via des plugins

Sans modifier le noyau de Elgg, Elgg offre plusieurs manières de personnaliser quasiment toutes les sorties :

• Vous pouvez remplacer une vue, en modifiant complètement le fichier utilisé pour l’afficher.

• Vous pouvez étendre une vue en y insérant la sortie d’une autre vue avant ou après.

• Vous pouvez modifier les entrées d’une vue par événement.

• Vous pouvez modifier la sortie d’une vue via un événement.

Surcharger les vues - « override »

Les vues dans les répertoires des plugins remplacent toujours les vues du répertoire du noyau ; toutefois, quand les plugins remplacent les vues d’autres plugins, les vues des derniers plugins remplacent celles des précédents.

Par exemple, si nous voulions personnaliser la vue hello/world pour utiliser un h2 au lieu d’un h1, nous pourrions créer un fichier mod/exemple/views/default/hello/world.php comme ceci :

<h2>Hello, <?= $vars['name']; ?></h2>

Note

Quand vous considérez la maintenance à long terme, la surcharge des vues du noyau et des plugins inclus a un coût : les mises à niveau peuvent apporter des changements dans les vues, et si vous les avez remplacées, vous n’obtiendrez pas ces changements ou devrez les réintégrer dans vos vues.

Vous souhaiterez peut-être plutôt modifier l’entrée input ou la sortie output de la vue via des événements.

Note

Elgg met en cache les chemins des vues. Cela signifie que vous devez désactiver le cache système quand vous développez avec des vues. Lorsque vous installez les modifications apportées dans un environnement de production, vous devez vider les caches.

Étendre les vues

Il peut y avoir d’autres situations dans lesquelles vous ne voulez pas remplacer l’ensemble de la vue, et plutôt y ajouter un peu plus de contenu au début ou à la fin. Dans Elgg, c’est ce qu’on appelle étendre une vue.

Par exemple, au lieu de remplacer la vue hello/world, nous pourrions l’étendre comme ceci :

elgg_extend_view('hello/world', 'hello/greeting');

Si le contenu de /views/default/hello/greeting.php est :

<h2>How are you today?</h2>

Ensuite, chaque fois que nous appelons elgg_view('hello/world');, nous obtiendrons :

<h1>Hello, World!</h1>
<h2>How are you today?</h2>

Vous pouvez ajouter des choses avant la vue en transmettant au 3ème paramètre une valeur inférieure à 500 :

// appends 'hello/greeting' to every occurrence of 'hello/world'
elgg_extend_view('hello/world', 'hello/greeting');

// prepends 'hello/greeting' to every occurrence of 'hello/world'
elgg_extend_view('hello/world', 'hello/greeting', 450);

Toutes les extensions de vue doivent être enregistrées dans le elgg-plugin.php de votre plugin.

Modifier l’entrée d’une vue

Il peut être utile de modifier le tableau $vars d’une vue avant que la vue ne soit rendue.

Avant le rendu de chaque vue, le tableau $vars est filtré par l” événement ["view_vars", $view_name]. Chaque fonction de gestionnaire enregistrée reçoit ces arguments :

• $event - la chaîne "view_vars"

• $view_name - le nom de la vue (le premier argument est passé à elgg_view())

• $returnvalue - le tableau modifié $vars

• $params - un tableau contenant :

  • vars - le tableau original $vars, inchangé

  • view - le nom de la vue

  • viewtype - Le type de vue en train d’être affiché

Exemple de modification des entrées d’une vue

Ici, nous allons modifier la limite de pagination par défaut pour la vue des commentaires :

elgg_register_event_handler('view_vars', 'page/elements/comments', 'myplugin_alter_comments_limit');

function myplugin_alter_comments_limit(\Elgg\Event $event) {
    $vars = $event->getValue();

    // only 10 comments per page
    $vars['limit'] = elgg_extract('limit', $vars, 10);

    return $vars;
}

Modification de la sortie d’une vue

Parfois, il est préférable de modifier la sortie d’une vue au lieu de la remplacer.

La sortie de chaque vue est exécutée via l”événement ["view", $view_name] avant d’être renvoyée par elgg_view(). Chaque fonction de gestionnaire enregistrée reçoit ces arguments :

• $event - la chaîne "view"

• $view_name - le nom de la vue (le premier argument est passé à elgg_view())

• $result - la sortie modifiée de la vue

• $params - un tableau contenant :

  • viewtype - Le type de vue en train d’être affiché

Pour modifier le rendu de la vue, le gestionnaire n’a qu’à modifier $returnvalue et renvoyer une nouvelle chaîne.

Exemple de modification de la sortie d’une vue

Ici, nous allons éliminer le fil d’Ariane lorsqu’il ne contient aucun lien.

elgg_register_event_handler('view', 'navigation/breadcrumbs', 'myplugin_alter_breadcrumb');

function myplugin_alter_breadcrumb($event, $type, $returnvalue, $params) {
    // we only want to alter when viewtype is "default"
    if ($params['viewtype'] !== 'default') {
        return $returnvalue;
    }

    // output nothing if the content doesn't have a single link
    if (false === elgg_strpos($returnvalue, '<a ')) {
        return '';
    }

    // returning nothing means "don't alter the returnvalue"
}

Remplacer complètement le rendu d’une vue

Vous pouvez prédéfinir la sortie de la vue en définissant $vars['__view_output']. La valeur sera renvoyée sous forme de chaîne. Les extensions de vue ne seront pas utilisées et l’événement view ne sera pas déclenché.

elgg_register_event_handler('view_vars', 'navigation/breadcrumbs', 'myplugin_no_page_breadcrumbs');

function myplugin_no_page_breadcrumbs(\Elgg\Event $event) {
    if (elgg_in_context('pages')) {
        return ['__view_output' => ""];
    }
}

Note

Pour plus de facilité d’utilisation, vous pouvez également utiliser un callback d’événement par défaut déjà existant pour bloquer la sortie \Elgg\Values::preventViewOutput

Affichage des entités

Si vous ne savez pas ce qu’est une entité, commencez par lire cette page.

Le code suivant affiche automatiquement l’entité dans $entity :

echo elgg_view_entity($entity);

Comme vous le savez après la lecture de l’introduction au modèle de données, toutes les entités ont un type (object, site, user ou group), et éventuellement un sous-type (qui pourrait être n’importe quoi - “blog”, “forumpost”, “banane”).

''elgg_view_entity va automatiquement rechercher une vue appelée type/subtype ; s’il n’y a pas de sous-type, elle recherchera type/type. À défaut, elle essaiera type/default avant de renoncer.

Les flux RSS de Elgg fonctionnent généralement en affichant la vue object/default du type de vue “rss”.

Par exemple, la vue pour afficher un article de blog peut être object/blog. La vue pour afficher un utilisateur est user/default.

Vues partielle et complète des entités

elgg_view_entity dispose en fait de plusieurs paramètres, bien que seul le tout premier soit nécessaire. Les trois premiers sont :

• $entity - L’entité à afficher

• ''$viewtype - Le type de vue à afficher (par défaut celui qui est utilisé actuellement, mais il peut être forcé - par exemple pour afficher un extrait RSS dans une page HTML)

• $full_view - Détermine s’il faut afficher la version complète de l’entité. (Par défaut à true.)

Ce dernier paramètre est transmis à la vue via $vars['full_view']. C’est à vous de déterminer comment vous souhaitez l’utiliser ; le comportement habituel consiste à afficher uniquement des commentaires et des informations de ce type si cela est défini sur true.

Lister des entités

Ceci est ensuite utilisé dans les fonctions de liste fournies. Pour afficher automatiquement une liste d’articles de blog (voir le tutoriel complet), vous pouvez appeler :

echo elgg_list_entities([
    'type' => 'object',
    'subtype' => 'blog',
]);

Cette fonction vérifie s’il y a des entités ; s’il y en a, elle affiche d’abord la vue navigation/pagination afin d’afficher un moyen de passer d’une page à l’autre. Elle appelle ensuite successivement elgg_view_entity sur chaque entité avant de renvoyer le résultat.

Notez que elgg_list_entities permet à l’URL de définir ses options limit et offset, aussi définissez-les explicitement si vous avez besoin de valeurs particulières (par exemple si vous ne les utilisez pas pour la pagination).

Elgg sait qu’il peut fournir automatiquement un flux RSS sur les pages qui utilisent elgg_list_entities. Il initialise l’événement ["head","page"] (qui est utilisé par l’entête) afin de fournir une découverte automatique RSS, c’est pourquoi vous pouvez voir l’icône RSS orange sur ces pages dans certains navigateurs.

Les listes d’entités tenteront par défaut de charger les propriétaires des entités et les propriétaires de leur conteneur. Si vous voulez éviter ce comportement, vous pouvez le désactiver.

echo elgg_list_entities([
    'type' => 'object',
    'subtype' => 'blog',

    // disable owner preloading
    'preload_owners' => false,
]);

Voyez aussi ces informations de contexte sur la base de données de Elgg.

Si vous souhaitez afficher un message lorsque la liste ne contient pas d’élément à répertorier, vous pouvez transmettre un message avec no_results, ou true pour le message par défaut. Si vous voulez encore plus de contrôle sur le message le message no_results peut également passer une Closure (une fonction anonyme).

echo elgg_list_entities([
    'type' => 'object',
    'subtype' => 'blog',

    'no_results' => elgg_echo('notfound'),
]);

Rendu d’une liste avec une autre vue

Vous pouvez définir une autre vue pour afficher des éléments de liste à l’aide du paramètre item_view.

Dans certains cas, les vues d’entité par défaut peuvent ne pas convenir à vos besoins. L’utilisation de item_view vous permet de personnaliser l’apparence, tout en préservant la pagination, le balisage HTML de la liste, etc.

Prenons les deux exemples suivants :

echo elgg_list_entities([
    'type' => 'group',
    'relationship' => 'member',
    'relationship_guid' => elgg_get_logged_in_user_guid(),
    'inverse_relationship' => false,
    'full_view' => false,
]);

echo elgg_list_entities([
    'type' => 'group',
    'relationship' => 'invited',
    'relationship_guid' => (int) $user_guid,
    'inverse_relationship' => true,
    'item_view' => 'group/format/invitationrequest',
]);

Dans le premier exemple, nous affichons une liste de groupes dont un utilisateur est membre à l’aide de la vue de groupe par défaut. Dans le deuxième exemple, nous voulons afficher une liste de groupes dans lesquels l’utilisateur a été invité.

Étant donné que les invitations ne sont pas des entités, elles n’ont pas leurs propres vues et ne peuvent pas être répertoriées à l’aide de elgg_list_ *. Nous fournissons une vue d’élément alternative, qui utilisera l’entité de groupe pour afficher une invitation qui contient un nom de groupe et des boutons pour accéder ou rejeter l’invitation.

Rendu d’une liste sous forme de tableau

Depuis Elgg 2.3, vous pouvez afficher les listes sous forme de tableaux. Définissez $options[`list_type'] = 'table' et fournissez un tableau d’objets TableColumn dans $options['columns']. Le service elgg()->table_columns fournit plusieurs méthodes pour créer des objets de colonnes basés sur des vues (comme page/components/column/* ), des propriétés, ou des méthodes.

Dans cet exemple, nous répertorions les derniers objets mon_plugin dans un tableau de 3 colonnes : icône de l’entité, nom d’affichage, et la date dans un format convivial.

echo elgg_list_entities([
    'type' => 'object',
    'subtype' => 'my_plugin',

    'list_type' => 'table',
    'columns' => [
        elgg()->table_columns->icon(),
        elgg()->table_columns->getDisplayName(),
        elgg()->table_columns->time_created(null, [
            'format' => 'friendly',
        ]),
    ],
]);

Consultez la classe Elgg\Views\TableColumn\ColumnFactory pour plus d’informations sur la façon dont les colonnes sont spécifiées et rendues. Vous pouvez ajouter ou remplacer les méthodes de elgg()->table_columns de diverses façons, en fonction des vues, des propriétés/méthodes sur les éléments, ou des fonctions données.

Icônes

Elgg supporte deux types d’icônes : les icônes génériques qui aident pour le style des pages (par exemple, afficher l’icône de suppression) et les icônes des Entités (par exemple l’avatar d’un utilisateur).

Icônes génériques

À partir de Elgg 2.0, les icônes génériques sont basées sur la bibliothèque FontAwesome. Vous pouvez obtenir n’importe laquelle des icônes prises en charge en appelant elgg_view_icon($icon_name, $vars); où :

• $icon_name est le nom de l’icône FontAwesome (sans fa-) par exemple user

• $vars est facultatif, par exemple vous pouvez définir une classe supplémentaire

elgg_view_icon() appelle la vue output/icon avec le nom d’icône donné et affiche toutes les classes correctes pour restituer l’icône FontAwesome. Si vous souhaitez remplacer une icône par une autre icône, vous pouvez écrire un événement view_vars, output/icon pour remplacer le nom de l’icône par votre remplacement.

A des fins de rétro-compatibilité, certains anciens noms d’icônes Elgg sont traduits en une icône FontAwesome correspondante.

Icônes des entités

Pour afficher une icône appartenant à une Entité appelez elgg_view_entity_icon($entity, $size, $vars); où :

• $entity est l”ElggEntity dont vous voulez afficher l’icône

• $size est la dimension demandée. Par défaut Elgg supporte large, medium, small, tiny et topbar (master est également disponible, mais ne l’utilisez pas)

• $vars pour passer des informations additionnelles à la vue de l’icône

elgg_view_entity_icon() appelle une vue dans l’ordre :

• icon/<type>/<subtype>

• icon/<type>/default

• icon/default

Ainsi si vous souhaitez personnaliser la mise en page de l’icône, vous pouvez surcharger la vue correspondante.

Un exemple d’affichage d’un avatar utilisateur est

// get the user
$user = elgg_get_logged_in_user_entity();

// show the small icon
echo elgg_view_entity_icon($user, 'small');

// don't add the user_hover menu to the icon
echo elgg_view_entity_icon($user, 'small', [
        'use_hover' => false,
]);

Connexe

Recommandations pour la structure d’une page

Les pages Elgg utilisent un pageshell - coquille HTML - global, une disposition ou mise en page principale et plusieurs éléments de page. Il est recommandé d’utiliser toujours la disposition default car tous les éléments de la page peuvent être contrôlés en utilisant de cette disposition.

Si vous n’utilisez pas la disposition default vous pouvez appeler

$layout_area = elgg_view_layout($layout_name, [
        'content' => $content,
        'section' => $section,
]);

Les différents éléments de la page sont passés sous la forme d’un array dans le deuxième paramètre. Les clefs du tableau correspondent à des éléments de la disposition. Les valeurs de tableau contiennent le html qui devrait être affiché dans ces zones :

$layout_area = elgg_view_layout('default', [
        'content' => $content,
]);

$layout_area = elgg_view_layout('default', [
        'content' => $content,
        'sidebar' => $sidebar,
]);

Vous pouvez ensuite, finalement, passer ceci dans la fonction elgg_view_page :

echo elgg_view_page($title, $layout_area);

Si vous utilisez la disposition default, vous pouvez également passer le tableau avec les éléments de page directement à elgg_view_page :

echo elgg_view_page($title, [
        'content' => $content,
        'sidebar' => $sidebar,
]);

Vous pouvez contrôler de nombreux éléments de la page :

echo elgg_view_page('This is the browser title', [
        'title' => 'This is the page title',
        'content' => $content,
        'sidebar' => false, // no default sidebar
        'sidebar_alt' => $sidebar_alt, // show an alternate sidebar
]);

Voir aussi

Regardez la vue page/layouts/default pour obtenir plus d’informations sur les éléments de page pris en charge

Simplecache - Cache simple

Voir aussi

• Performance

• Vues

Le Simplecache est un mécanisme conçu pour atténuer la nécessité de régénérer dynamiquement certaines vues. Au lieu de cela, elles sont générées une seule fois, enregistrées comme un fichier statique, et servies d’une manière qui contourne entièrement le moteur Elgg.

Si Simplecache est désactivé (ce qui peut être fait à partir du panneau d’administration), ces vues seront servies comme d’habitude, à l’exception des CSS du site.

Les critères pour savoir si une vue convient pour Simplecache sont les suivants :

• La vue ne doit pas changer en fonction de qui la regarde ou de quand elle est affichée

• La vue ne doit pas dépendre des variables qui lui sont transmises (à l’exception des variables globales comme l’URL du site qui ne changent jamais)

Régénérer le Simplecache

Vous pouvez régénérer la Simplecache à tout moment en :

• Chargement de /upgrade.php, même si vous n’avez rien à mettre à niveau

• Dans le panneau d’administration, cliquez sur “Vider les caches”

• Activation ou désactivation d’un plugin

• Réordonner vos plugins

Utiliser le Simplecache dans vos plugins

Enregistrer des vues avec Simplecache

Vous pouvez enregistrer une vue dans Simplecache avec la fonction suivante lors de la phase d’initialisation :

elgg_register_simplecache_view($viewname);

Accéder à la vue mise en cache

Si vous avez enregistré un fichier JavaScript ou CSS avec Simplecache et que vous l’avez mis dans le dossier des vues sous la forme votre_vue.js ou votre_vue.css, vous pouvez très facilement obtenir l’URL de cette vue mise en cache en appelant elgg_get_simplecache_url($vue). Par exemple :

$js = elgg_get_simplecache_url('your_view.js');
$css = elgg_get_simplecache_url('your_view.css');

Page/elements/foot vs footer

page/elements/footer est le contenu qui s’affiche dans cette partie de la page :

<div class="elgg-page-footer">
        <div class="elgg-inner">
                <!-- page/elements/footer goes here -->
        </div>
</div>

Son contenu est visible des utilisateurs finaux, et c’est habituellement l’endroit où vous mettriez un plan du site ou une autre navigation secondaire, les mentions légales, l’indication propulsé par elgg, etc.

page/elements/foot est inséré juste avant la balise de fin </body> et est principalement destiné à insérer des scripts qui ne fonctionnent pas déjà avec elgg_require_js('amd/module'); . En d’autres termes, vous ne devriez jamais remplacer cette vue et vous n’avez probablement pas besoin de l’étendre non plus. Utilisez simplement les fonctions elgg_*_js à la place

Réseau privé - « Walled Garden »

Elgg prend en charge un mode Walled Garden - jardin clos, ou réseau privé. Dans ce mode, presque toutes les pages ne sont accessible qu’aux seuls utilisateurs connectés. Ceci est utile pour les sites qui n’autorisent pas l’inscription publique.

Activer le mode réseau privé - Walled Garden

Pour activer le mode Walled Garden dans Elgg, accédez à la section Administration. Dans le menu de la barre latérale droite, sous la section « Configurer », développez « Paramètres » puis cliquez sur « Avancé ».

Dans la page Paramètres avancés, recherchez l’option libellée « Restreindre les pages aux utilisateurs connectés ». Activez cette option, puis cliquez sur « Enregistrer » pour basculer votre site en mode Walled Garden.

Exposer des pages à travers le Walled Garden

De nombreux plugins étendent Elgg en ajoutant des pages. Le mode Walled Garden empêchera ces pages d’être consultées par les utilisateurs déconnectés. Elgg utilise events pour gérer quelles pages sont visibles à travers le Walled Garden.

Les auteurs de plugins doivent enregistrer les pages comme publiques si elles doivent être visibles à travers le walled garden :

• en définissant 'walled' => false dans la configuration des routes

• en répondant à l’événement public_pages, walled_garden. La valeur renvoyée est un tableau d’expressions rationnelles regexp pour les pages publiques.

Le code suivant montre comment exposer http://exemple.org/mon_plugin/public_page à travers le walled garden. Cela suppose que le plugin a enregistré une route pour mon_plugin/public_page.

// Preferred way
elgg_register_route('my_plugin:public_page', [
    'path' => '/my_plugin/public_page',
    'resource' => 'my_plugin/public_page',
    'walled' => false,
]);

// Legacy approach
elgg_register_event_handler('public_pages', 'walled_garden', 'my_plugin_walled_garden_public_pages');

function my_plugin_walled_garden_public_pages(\Elgg\Event $event) {
   $pages = $event->getValue();

   $pages[] = 'my_plugin/public_page';

   return $pages;
}

Web services

Construisez une API HTTP pour votre site.

Elgg fournit un framework puissant pour la création de services web. Cela permet aux développeurs d’exposer des fonctionnalités à d’autres sites Web et applications de bureau, ainsi que des intégrations avec des applications web tierces. Bien que nous appelions l’API RESTful, il s’agit en fait d’un hybride REST/RPC similaire aux API fournies par des sites comme Flickr et Twitter.

Pour créer une API pour votre site Elgg, vous devez effectuer 4 choses :

• activer le plugin web services

• exposer des méthodes

• mettre en place l’authentification de l’API

• mettre en place l’authentification utilisateur

De plus, vous pourriez vouloir contrôler quels types d’authentification sont disponibles sur votre site. Cela sera également traité.

Sécurité

Il est essentiel que les services web soient utilisés via des protocoles sécurisés. N’activez pas les services web si votre site n’est pas servi par HTTPS. Ceci est particulièrement important si vous autorisez l’authentification par clef d’API uniquement.

Si vous utilisez des outils tiers qui exposent des méthodes d’API, assurez-vous d’effectuer un audit de sécurité approfondi. Vous pouvez vouloir vous assurer que l’authentification API est requise pour TOUTES les méthodes, même si elles nécessitent l’authentification de l’utilisateur. Les méthodes qui ne nécessitent pas d’authentification API peuvent être facilement utilisées pour spammer votre site.

Assurez-vous que la validité des clefs d’API est limitée et fournissez à vos clients API des mécanismes pour renouveler leurs clefs.

Exposer des méthodes

Les méthodes API peuvent être exposées de l’une des deux manières : - en utilisant la section web_services dans le fichier elgg-plugin.php de votre plugin - ou lors de l’événement 'register', 'api_methods'

À titre d’exemple, supposons que vous souhaitiez exposer une fonction qui renvoie du texte à l’application appelante. La fonction pourrait ressembler à ceci

function my_echo($string) {
    return $string;
}

Puisque nous fournissons cette fonction pour permettre aux développeurs de tester leurs clients d’API, nous n’aurons besoin ni d’authentification API ni d’authentification utilisateur. Cet appel enregistre la fonction avec le framework API des services web :

// as part of the elgg-plugin.php
'web_services' => [
    'test.echo' => [
        'GET' => [ // the HTTP call method (GET|POST)
            'callback' => 'my_echo', // required
            'description' => 'A testing method which echos back a string', // optional, the description of the API method
            'params' => [ // optional, input parameters for the API method
                'string' => ['type' => 'string'],
            ],
            'require_api_auth' => false, // optional, requires API authentication (default: false)
            'require_user_auth' => false, // optional, requires User authentication (default: false)
            'associative' => false, // optional, provide the input params as an array to the callback function (default: false)
        ],
    ],
],

// as part of the 'register', 'api_methods' event
function my_plugin_event_handler(\Elgg\Event $event) {
    $results = $event->getValue();

    $results['test.echo']['GET'] = [
        'callback' => 'my_echo',
        'description' => 'A testing method which echos back a string',
        'params' => [
            'string' => ['type' => 'string'],
        ],
    ];

    return $results;
}

Note

Si aucune description n’est fournie dans la définition de la méthode API, le système vérifiera l’existence de la clé de langage web_services:api_methods:<method>:<http call method>:description

Si vous ajoutez ce code à un plugin puis allez sur http://yoursite.com/services/api/rest/json/?method=system.api.list, vous devriez maintenant voir votre méthode test.echo répertoriée comme un appel API. De plus, pour tester la méthode exposée à partir d’un navigateur Web, vous pouvez accéder à l’URL : http://yoursite.com/services/api/rest/json/?method=test.echo&string=testing et vous devriez voir des données JSON comme celles-ci :

{
    "status":0,
    "result":"testing"
}

Les plugins peuvent filtrer la sortie de méthodes API individuelles en enregistrant un gestionnaire pour l’événement 'rest:output',$method.

Formats de réponse

JSON est le format par défaut, mais il est possible de récupérer du XML et du PHP sérialisé en activant le plugin data_views et en remplaçant json par xml ou php dans les URL ci-dessus.

Vous pouvez également ajouter des formats de réponse supplémentaires en définissant de nouveaux types de vues.

Paramètres

Les paramètres attendus par chaque méthode doivent être répertoriés comme un tableau associatif, où la clef représente le nom du paramètre, et la valeur contient un tableau avec les champs type, default et required.

Les valeurs soumises pour chaque paramètre de la requête API devraient correspondre au type déclaré. L’API renverra une exception si la validation échoue.

Les types de paramètres reconnus sont :

• integer (ou int)

• boolean (ou bool) 'false', 0 et '0' seront évalués comme false, le reste sera évalué comme true

• string

• float

• array

Les types non reconnus lancent une exception d’API.

Vous pouvez utiliser des champs supplémentaires pour décrire votre paramètre, par exemple description.

// as part of the elgg-plugin.php
'web_services' => [
    'test.greet' => [
        'GET' => [
            'callback' => 'my_greeting',
            'description' => 'A testing method which greets the user with a custom greeting',
            'params' => [
                'name' => [
                    'type' => 'string',
                    'required' => true,
                    'description' => 'Name of the person to be greeted by the API',
                ],
                'greeting' => [
                    'type' => 'string',
                    'required' => false,
                    'default' => 'Hello',
                    'description' => 'Greeting to be used, e.g. "Good day" or "Hi"',
                ],
            ],
        ],
    ],
],

Note

Si un paramètre manquant n’a pas de valeur par défaut, l’argument sera null. Avant Elgg v2.1, un bogue provoquait le décalage vers la gauche des arguments ultérieurs dans ce cas.

Recevoir des paramètres sous forme de tableau associatif

Si vous avez un grand nombre de paramètres de méthode, vous pouvez forcer le script d’exécution à invoquer la fonction de rappel avec un seul argument qui contient un tableau associatif de paires de paramètre => valeur (au lieu que chaque paramètre soit un argument distinct). Pour ce faire, définissez $assoc sur true dans elgg_ws_expose_function().

    function greet_me($values) {
            $name = elgg_extract('name', $values);
            $greeting = elgg_extract('greeting', $values, 'Hello');
            return "$greeting, $name";
    }

// as part of the elgg-plugin.php
'web_services' => [
    'test.greet' => [
        'GET' => [
            'callback' => 'greet_me',
            'description' => 'A testing method which echos a greeting',
            'params' => [
                'name' => [
                    'type' => 'string',
                ],
                'greeting' => [
                    'type' => 'string',
                    'required' => false,
                    'default' => 'Hello',
                ],
            ],
            'associative' => true,
        ],
    ],
],

Note

Si un paramètre manquant n’a pas de valeur par défaut, null sera utilisé.

API d’authentification

Vous pouvez souhaiter contrôler l’accès à certaines des fonctions que vous exposez. Peut-être que vous exposez des fonctions afin d’intégrer Elgg avec une autre plate-forme opensource sur le même serveur. Dans ce cas, vous souhaitez seulement permettre à cette autre application d’accéder à ces méthodes. Une autre possibilité est que vous souhaitez limiter ce à quoi des développeurs externes ont accès via votre API. Ou peut-être voulez-vous limiter le nombre d’appels qu’un développeur peut passer auprès de votre API en une seule journée.

Dans tous ces cas, vous pouvez utiliser les fonctions d’authentification de l’API de Elgg pour contrôler l’accès. Elgg fournit deux méthodes intégrées pour effectuer l’authentification auprès de l’API : la première basée sur la clef, et la signature HMAC. Vous pouvez également ajouter vos propres méthodes d’authentification. L’approche basée sur les clefs est très similaire à ce que font Google, FlickR, ou Twitter. Les développeurs peuvent demander une clef (une chaîne aléatoire) et transmettre cette clef avec tous les appels nécessitant l’authentification auprès de l’API. Les clefs sont stockées dans la base de données et si un appel API est effectué sans clef ou avec une mauvaise clef, l’appel est refusé et un message d’erreur est renvoyé.

Authentification par clef

A titre d’exemple, écrivons une fonction qui renvoie le nombre d’utilisateurs qui se sont inscrits sur votre site depuis un certain horodatage.

function count_new_users(int $since) {
    return elgg_count_entities([
        'type' => 'user',
        'created_since' => $since,
    ]);
}

Maintenant, exposons-le et faisons du nombre de minutes un paramètre obligatoire :

    // as part of the elgg-plugin.php
'web_services' => [
    'users.new' => [
        'GET' => [
            'callback' => 'count_new_users',
            'description' => 'Number of users who have used the site in the past x minutes',
            'params' => [
               'since' => [
                    'type' => 'int',
                    'required' => true,
                ],
            ],
            'require_api_auth' => true,
        ],
    ],
],

Cette fonction est maintenant disponible, et si vous cochez system.api.list, vous verrez qu’elle nécessite l’authentification API. Si vous testez la méthode avec un navigateur Web, cela renvoie un message d’erreur concernant l’échec de l’authentification API. Pour tester cette méthode, vous avez besoin d’une clef API. À partir de Elgg 3.2 les clefs API peuvent être générées par le plugin webservices. Il permet de créer une clef publique et privée, et vous devrez utiliser la clef publique pour ce type d’authentification API. Prenez une clef, puis effectuez une requête GET avec votre navigateur sur cette méthode d’API en passant dans la chaîne de paramètre la clef api_key. Cela pourrait ressembler à quelque chose comme ceci: http://yoursite.com/services/api/rest/xml/?method=users.active&api_key=1140321cb56c71710c38feefdf72bc462938f59f.

Authentification par signature

Le Authentification HMAC est similaire à ce qui est utilisé avec OAuth ou le service S3 d’Amazon. Il s’agit d’utiliser à la fois une clef publique et une clef privée. Si vous voulez vous assurer que les appels à l’API proviennent du développeur dont vous pensez qu’ils viennent, et que vous voulez vous assurer que les données ne sont pas altérées pendant la transmission, vous devriez utiliser cette méthode d’authentification. Soyez conscient que cela demande beaucoup plus de travail et que cela pourrait décourager des développeurs quand il existe d’autres sites qui n’utilisent qu’une simple authentification basée sur les clefs.

Authentification utilisateur

Jusqu’à présent, vous avez permis aux développeurs d’extraire des données de votre site Elgg. Maintenant, nous allons comment pousser des données dans Elgg. Dans ce cas, cela va être fait par un utilisateur. Par exemple vous pouvez avoir créé une application de bureau qui permet à vos utilisateurs de poster sur le fil sans aller sur le site. Vous allez devoir exposer une méthode pour afficher sur le fil et vous assurer qu’un utilisateur ne peut pas publier à l’aide du compte de quelqu’un d’autre. Elgg fournit une approche basée sur des jetons pour l’authentification utilisateur. Cela permet à un utilisateur de soumettre son nom d’utilisateur et son mot de passe afin d’obtenir en échange un jeton, en utilisant la méthode auth.gettoken. Ce jeton peut ensuite être utilisé pendant un certain temps comme paramètre auth_token pour authentifier tous les appels à l’API, jusqu’à-ce qu’il expire. Si vous ne voulez pas que vos utilisateurs fassent confiance à leurs mots de passe pour des applications tierces, vous pouvez également étendre la capacité actuelle d’utiliser une approche comme OAuth.

Écrivons notre fonction de publication sur le Fil :

function my_post_to_wire($text) {

    $text = elgg_substr($text, 0, 140);

    $access = ACCESS_PUBLIC;

    // returns guid of wire post
    return thewire_save_post($text, $access, "api");
}

Exposer cette fonction est la même chose qu’auparavant, sauf que nous avons besoin de l’authentification de l’utilisateur et que nous allons faire cela via des requêtes POST plutôt que des requêtes HTTP.

    // as part of the elgg-plugin.php
'web_services' => [
    'thewire.post' => [
        'POST' => [
            'callback' => 'my_post_to_wire',
            'description' => 'Post to the wire. 140 characters or less',
            'params' => [
               'text' => [
                    'type' => 'string',
                ],
            ],
            'require_api_auth' => true,
            'require_user_auth' => true,
        ],
    ],
],

Veuillez noter que vous ne pourrez pas tester ceci à l’aide d’un navigateur Web comme vous l’avez fait avec les autres méthodes. Vous devez écrire du code client pour ce faire.

Créer votre propre API

Dès que vous vous sentirez à l’aise avec le framework d’API des web services de Elgg, vous voudrez prendre du recul et concevoir votre API. Quel type de données essayez-vous d’exposer ? Qui ou qu’est-ce qui seront les utilisateurs de l’API ? Comment voulez-vous qu’ils aient accès aux clef d’authentification ? Comment allez-vous documenter votre API ? N’oubliez pas de jeter un œil aux API créées par les sites Web populaires 2.0 pour l’inspiration. Si vous attendez que des développeurs tiers créent des applications à l’aide de votre API, vous voudrez probablement fournir un ou plusieurs clients dans un langage spécifique.

Déterminer l’authentification disponible

L’API des services Web de Elgg utilise un type d’architecture de module d’authentification enfichable « pluggable authentication module (PAM) » pour gérer la manière dont les utilisateurs et les développeurs sont authentifiés. Cela vous donne la flexibilité d’ajouter et de supprimer des modules d’authentification. Vous ne voulez pas utiliser le PAM gestionnaire d’authentification utilisateur par défaut, mais préférez utiliser OAuth ? Vous pouvez le faire.

La première étape consiste à enregistrer une fonction de rappel pour l’événement 'rest', 'init' :

elgg_register_event_handler('rest', 'init', 'rest_plugin_setup_pams');

Ensuite, dans la fonction de rappel, vous enregistrez les PAMs que vous souhaitez utiliser :

function rest_plugin_setup_pams() {
    // user token can also be used for user authentication
    elgg_register_pam_handler(\Elgg\WebServices\PAM\UserToken::class);

    // simple API key check
    elgg_register_pam_handler(\Elgg\WebServices\PAM\APIKey::class, 'sufficient', 'api');
}

Connexe

Authentification HMAC

Le framework d’API RESTful de Elgg fournit des fonctions pour prendre en charge un schéma de signature HMAC pour l’authentification API. Le client doit envoyer la signature HMAC ainsi qu’un ensemble d’en-têtes HTTP spéciaux lors de l’exécution d’un appel qui nécessite l’authentification API. Cela garantit que l’appel API est effectué à partir du client déclaré et que les données n’ont pas été falsifiées.

Le HMAC doit être construit à partir des données suivantes :

• La clef d’API publique qui vous identifie auprès du serveur api de Elgg, tel que fourni par le plugin APIAdmin

• La clef privée d’API fournie par Elgg (qui accompagne la clef publique)

• L’heure unix actuelle en secondes

• Une valeur « nonce » créée pour l’occasion afin de garantir que deux requêtes faites à la même seconde ont des signatures différentes

• Une représentation encodée pour l’URL de la chaîne de caractères des paramètres GET, par ex. method=test.test&foo=bar

• Si vous envoyez des données post, le hash de ces données

Quelques informations supplémentaires doivent être ajoutées à l’entête HTTP pour que ces données soient traitées correctement :

• X-Elgg-apikey - La clef publique d’API

• X-Elgg-time - L’heure Unix utilisée dans le calcul HMAC

• X-Elgg-nonce - une chaîne aléatoire

• X-Elgg-hmac - Le HMAC encodé en base64

• X-Elgg-hmac-algo - L’algorithme utilisé dans le calcul HMAC

Si vous envoyez des données POST vous devez également envoyer :

• X-Elgg-posthash - Le hash des données POST

• X-Elgg-posthash-algo - Algorithme utilisé pour le hachage des données POST

• Content-type - Le type de contenu des données que vous envoyez (en cas de doute, utilisez application/octet-stream)

• Content-Length - La longueur en octets de vos données POST

Elgg fournit un exemple de client API qui implémente cette signature HMAC : \Elgg\WebServices\ElggApiClient. Il constitue une bonne référence sur la manière de le mettre en œuvre.

Algorithmes de hachage pris en charge

• sha256 : recommandé

• sha1 : rapide mais moins sûr

• md5 : faible et sera supprimé à l’avenir

Calcul du hachage des données POST

Le hachage des données post doit être calculé sur toutes les données POST à l’aide de l’un des algorithmes de hachage pris en charge. Le résultat du hachage doit être signalé dans l’en-tête X-Elgg-posthash et l’algorithme de hachage utilisé doit être signalé dans l’en-tête X-Elgg-posthash-algo.

Calcul du hachage HMAC

Le HMAC global doit être calculé sur les données suivantes (dans l’ordre) en utilisant la clef secrète d’API comme le secret HMAC et avec l’un des algorithmes de hachage pris en charge :

1. un horodatage UNIX, indiquez cet horodatage dans l’en-tête X-Elgg-time

2. une chaîne aléatoire, indiquez cette chaîne dans l’en-tête X-Elgg-nonce

3. la clef publique d’API, indiquer cette clef d’API dans l’en-tête X-Elgg-apikey

4. la chaîne de requête url (par exemple method=test.test&foo=bar)

5. lorsqu’il s’agit d’une requête POST, ajoutez le posthash tel qu’indiqué dans l’entête X-Elgg-posthash

La chaîne résultante doit être codée en base64, puis l’URL codée et indiquée dans l’en-tête X-Elgg-hmac. L’algorithme de hachage utilisé doit être signalé dans X-Elgg-hmac-algo.

Cache de hachage

Pour des raisons de sécurité, chaque hachage HMAC doit être unique, tous les hachages soumis sont stockés pendant 25 heures pour éviter la réutilisation.

Résultats de l’API

Structure d’un résultat réussi

Un résultat d’API réussi ressemble à ceci :

{
        "status": 0,
        "result": "API result"
}

Selon l’appel API, result peut contenir n’importe quel type de contenu (chaîne, nombre, tableau, objet, etc.).

Exemple de résultat numérique (par exemple un nombre d’utilisateurs) :

{
        "status": 0,
        "result": 10
}

Exemple d’objet de résultat (par exemple un utilisateur) :

{
        "status": 0,
        "result": {
                "name": "Some user",
                "username": "apiexample",
                "email": "user@example.com"
        }
}

Structure d’un résultat d’erreur

Lorsqu’un appel API échoue, le résultat ressemble à ceci :

{
        "status": -1,
        "message": "The reason the API call failed"
}

Codes d’état par défaut

Le champ status contient toujours un nombre représentant le résultat. Toute valeur autre que 0 est considérée comme une erreur.

• 0 : C’est un résultat réussi

• -1 : Il s’agit d’un résultat d’erreur générique

• -20 : le jeton d’authentification utilisateur est manquant, est invalide ou a expiré

• -30 : La clé api a été désactivée

• -31 : La clé api est inactive

• -32 : La clef api est invalide

Les développeurs peuvent implémenter leurs propres codes d’état pour représenter différents états d’erreur, de sorte que la demande n’a pas à s’appuyer sur le message d’erreur pour savoir ce qui s’est passé.

Note

result et message peuvent contenir des messages dans différentes langues. Cela dépend de la langue utilisateur lors de l’utilisation d’appels API authentifiés par l’utilisateur ou de la langue de site pour les autres appels API. Gardez à l’esprit que la langue peut changer, que ce soit par l’utilisateur ou par un administrateur du site pour la langue du site.

Widgets

Les widgets sont des zones de contenu que les utilisateurs peuvent déplacer dans leur page pour personnaliser la mise en page. Ils peuvent typiquement être personnalisés par leur propriétaire pour afficher plus ou moins de contenu et déterminer qui peut voir le widget. Par défaut, Elgg fournit des plugins pour personnaliser la page de profil et le tableau de bord avec des widgets.

Structure

Pour créer un widget, créez deux vues :

• widgets/widget/edit

• widgets/widget/content

content.php est responsable pour tout le contenu qui sera affiché dans le widget. Le fichier edit.php contient toutes les fonctions d’édition supplémentaires que vous souhaitez proposer à l’utilisateur. Vous n’avez pas besoin d’ajouter de niveau d’accès car ceci est pris en charge par le framework des widgets.

Note

L’utilisation de cases à cocher HTML pour définir des drapeaux pour le widget est problématique parce que si la case n’est pas cochée, le champ de la case à cocher est omis de l’envoi du formulaire. Le résultat est que vous pouvez seulement définir ces champs, et pas les supprimer. La vue « input/checkboxes » ne va pas fonctionner correctement dans le panneau d’édition d’un widget.

Enregistrez le widget

Une fois que vous avez créé vos pages edit et view, vous devez initialiser le widget du plugin.

La manière la plus simple de faire cela est d’ajouter la section widgets à votre fichier de configuration elgg-plugin.php.

return [
        'widgets' => [
                'filerepo' => [
                        'context' => ['profile'],
                ],
        ]
];

Alternativement, vous pouvez aussi utiliser une fonction pour ajouter un widget. Ceci est effectué au sien de la fonction init() du plugin.

// Add generic new file widget
elgg_register_widget_type([
    'id' => 'filerepo',
    'name' => elgg_echo('widgets:filerepo:name'),
    'description' => elgg_echo('widgets:filerepo:description'),
    'context' => ['profile'],
]);

Note

Le seul attribut requis est l”id.

Widgets multiples

Il est possible d’ajouter plusieurs widgets pour un plugin. Vous n’avez qu’à initialiser autant de répertoires de widgets que vous voulez.

// Add generic new file widget
elgg_register_widget_type([
    'id' => 'filerepo',
    'name' => elgg_echo('widgets:filerepo:name'),
    'description' => elgg_echo('widgets:filerepo:description'),
    'context' => ['profile'],
]);

// Add a second file widget
elgg_register_widget_type([
    'id' => 'filerepo2',
    'name' => elgg_echo('widgets:filerepo2:name'),
    'description' => elgg_echo('widgets:filerepo2:description'),
    'context' => ['dashboard'],
]);

// Add a third file widget
elgg_register_widget_type([
    'id' => 'filerepo3',
    'name' => elgg_echo('widgets:filerepo3:name'),
    'description' => elgg_echo('widgets:filerepo3:description'),
    'context' => ['profile', 'dashboard'],
]);

Assurez-vous que les répertoires correspondants suivants existent dans la structure de votre plugin :

'Plugin'
    /views
        /default
            /widgets
               /filerepo
                  /edit.php
                  /content.php
               /filerepo2
                  /edit.php
                  /content.php
               /filerepo3
                  /edit.php
                  /content.php

Nom et description magiques du widget

Quand vous enregistrez un widget vous pouvez omettre de lui donner un nom et une description. Si la traduction est fournie dans le format suivant, elle sera utilisée. Pour le nom : widgets:<widget_id>:name et pour la description widgets:<widget_id>:description. Si vous vous vous assurez que ces traductions existent bien dans le fichier de traduction, vous avez très peu de travail pour enregistrer le widget.

elgg_register_widget_type(['id' => 'filerepo']);

Comment restreindre les emplacements où les widgets peuvent être utilisés

Le widget peut définir le contexte dans lequel il peut être utilisé (uniquement sur le profil avec le contexte « profile », sur le tableau de bord avec « dashboard », etc.).

elgg_register_widget_type([
    'id' => 'filerepo',
    'context' => ['profile', 'dashboard', 'other_context'],
]);

Autoriser des widgets multiples sur la même page

Par défaut vous ne pouvez ajouter qu’un seul widget du même type sur une page. Si vous voulez plus d’un widget du même type sur la page, vous pouvez le spécifier quand vous enregistrez le widget :

elgg_register_widget_type([
    'id' => 'filerepo',
    'multiple' => true,
]);

Enregistrez des widgets dans un événement

Si, par exemple, vous souhaitez enregistrer des widgets de manière conditionnelle, vous pouvez également utiliser un événement pour enregistrer des widgets.

function my_plugin_init() {
    elgg_register_event_handler('handlers', 'widgets', 'my_plugin_conditional_widgets_event');
}

function my_plugin_conditional_widgets_event(\Elgg\Event $event) {
    if (!elgg_is_active_plugin('file')) {
        return;
    }

    $return = $event->getValue();

    $return[] = \Elgg\WidgetDefinition::factory([
        'id' => 'filerepo',
    ]);

    return $return;
}

Modifiez les propriétés de widget d’un enregistrement de widget existant

Si, par exemple, vous souhaitez modifier les contextes autorisés d’un widget déjà enregistré, vous pouvez le faire en ré-enregistrant le widget avec elgg_register_widget_type, car cela remplacera une définition de widget déjà existante. Si vous souhaitez encore plus de contrôle, vous pouvez également utiliser l’événement handlers, widgets pour modifier la définition du widget.

function my_plugin_init() {
    elgg_register_event_handler('handlers', 'widgets', 'my_plugin_change_widget_definition_event');
}

function my_plugin_change_widget_definition_event(\Elgg\Event $event) {
    $return = $event->getValue();

    foreach ($return as $key => $widget) {
        if ($widget->id === 'filerepo') {
            $return[$key]->multiple = false;
        }
    }

    return $return;
}

Widgets par défaut

Si votre plugin utilise le canevas des widgets, vous pouvez enregistrer le support d’un widget par défaut avec le noyau de Elgg, qui va se charger de tout le reste.

Pour annoncer le support des widgets par défaut dans votre plugin, enregistrez-vous à l’événement get_list, default_widgets :

elgg_register_event_handler('get_list', 'default_widgets', 'my_plugin_default_widgets_event');

function my_plugin_default_widgets_event(\Elgg\Event $event) {
    $return = $event->getValue();

    $return[] = [
        'name' => elgg_echo('my_plugin'),
        'widget_context' => 'my_plugin',
        'widget_columns' => 3,

        'event_name' => 'create',
        'event_type' => 'user',
        'entity_type' => 'user',
        'entity_subtype' => ELGG_ENTITIES_ANY_VALUE,
    ];

    return $return;
}

Dans le gestionnaire d’événements, poussez un tableau dans la valeur de retour définissant votre prise en charge de widget par défaut et quand créer des widgets par défaut. Les tableaux nécessitent la définition des clés suivantes :

• name - Le nom de la page des widgets. Ceci est affiché sur l’onglet dans l’interface d’administration.

• widget_context - Le contexte depuis lequel la page des widgets est appelée. (Si ce n’est pas défini explicitement, ce sera l’id de votre plugin.)

• widget_columns - Combien de colonnes la page widgets va utiliser.

• event_name - Le nom de l’événement Elgg pour créer de nouveaux widgets.

• event_type - Le type de l’événement Elgg pour créer de nouveaux widgets.

• entity_type - Le type d’entité pour lequel créer de nouveaux widgets.

• entity_subtype - Le sous-type d’entité pour lequel créer de nouveaux widgets. Peut être ELGG_ENTITIES_ANY_VALUE pour le créer pour tous les types d’entités.

Pour créer des widgets, vous devez enregistrer l’événement suivant :

elgg_register_event_handler('create:after', 'object', 'Elgg\Widgets\CreateDefaultWidgetsHandler');

Quand un objet déclenche un événement qui correspond à event, entity_type, et entity_subtype, le noyau de Elgg va regarder les widgets par défaut qui correspondent au widget_context et va les copier vers l’owner_guid et le container_guid de l’objet. Tous les paramètres du widget seront également copiés.

Tutoriels

Suivez toutes les étapes requises pour personnaliser Elgg.

Les instructions sont suffisamment détaillées pour que vous n’ayez pas besoin de beaucoup d’expérience de développement avec Elgg.

Hello world

Ce tutoriel vous montre comment créer un nouveau plugin qui consiste en une nouvelle page qui affiche le texte « Hello world ».

Avant toute chose, vous devez installer Elgg.

Dans ce tutoriel, nous allons supposer que l’URL de votre site est https://elgg.example.com.

Tout d’abord, créez un répertoire qui va contenir les fichiers du plugin. Il devrait être placé dans le répertoire mod/ situé dans le répertoire d’installation de Elgg. Dans notre cas, créez mod/hello/.

Fichier composer

Elgg a besoin que votre plugin dispose d’un fichier composer qui contient des informations sur le plugin. A cette fin, créez un fichier nommé composer.json dans le répertoire de votre plugin et copiez ce code dedans :

{
            "name": "elgg/hello",
            "type": "elgg-plugin",
            "description": "Hello World plugin",
            "license": "GPL-2.0-only",
    }

Enregistrer une route

L’étape suivante est d’enregistrer une route dont l’objectif est de traiter les requêtes que les utilisateurs font vers l’URL https://elgg.example.com/hello.

Mettez à jour elgg-plugin.php pour qu’il ressemble à ceci :

<?php

return [
    'routes' => [
                'default:hello' => [
                        'path' => '/hello',
                        'resource' => 'hello',
                ],
        ],
];

Cet enregistrement indique à Elgg qu’il devrait appeler la vue ressource hello quand un utilisateur navigue vers https://elgg.example.com/hello.

Fichier de la vue d’affichage

Créez mod/hello/views/default/resources/hello.php avec ce contenu :

<?php

echo elgg_view_page('Hello', [
    'title' => 'Hello world!',
    'content' => 'My first page!',
]);

Le code crée un tableau de paramètres à passer à la fonction elgg_view_layout(), comprenant :

• Le titre de la page

• Le contenu de la page

• Un filter qui est laissé vide puisqu’il n’y a pour le moment rien à filtrer

Ceci crée la mise en page générale « layout » de base pour la page. Cette mise en page est ensuite passée à travers elgg_view_page() qui assemble et génère la page complète.

Dernière étape

Pour terminer, activez le plugin depuis la page d’administration de Elgg : https://elgg.example.com/admin/plugins` (le nouveau plugin apparaît en bas)

Vous pouvez maintenant vous rendre sur l’adresse https://elgg.example.com/hello/ et vous devriez voir votre nouvelle page !

Personnaliser la page d’accueil

Pour remplacer la page d’accueil, surchargez simplement la vue de Elgg resources/index en créant un fichier à /views/default/resources/index.php.

Toute sortie de cette vue deviendra votre nouvelle page d’accueil.

Vous pouvez utiliser une approche similaire avec n’importe quelle autre page de Elgg ou des plugins officiels.

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 :

• Installation de Elgg

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.

Intégrer un éditeur de texte

Construisez votre propre plugin wysiwyg.

Elgg est actuellement distribué avec un plugin pour CKEditor, et était précédemment distribué avec le support de TinyMCE. Cependant, s’il y a un éditeur wysiwyg que vous préférez, vous pourriez utiliser ce tutoriel pour construire le vôtre.

Tous les formulaires dans Elgg devraient essayer d’utiliser les vues de saisie situées dans views/default/input. Si ces vues sont utilisées, il est plus aisé pour les auteurs de plugins de remplacer une vue, ici input/longtext, par une vue avec leur wysiwyg.

Ajoutez la bibliothèque de code WYSIWYG

Vous devez maintenant télécharger TinyMCE dans un répertoire de votre plugin. Nous vous encourageons fortement à utiliser composer pour gérer les dépendances tierces, car il est tellement plus facile de mettre à niveau et de maintenir de cette façon :

composer require npm-asset/tinymce

Dites à Elgg quand et comment charger TinyMCE

Maintenant que vous avez :

• créé le fichier start

• initialisé le plugin

• chargé le code wysiwyg

Il est temps de dire à Elgg comment appliquer TinyMCE aux champs de saisie de texte.

Nous allons le faire en étendant la vue input/longtext et en incluant du javascript. Créez une vue tinymce/longtext et ajoutez le code suivant :

<?php

    /**
     * Elgg long text input with the tinymce text editor intacts
     * Displays a long text input field
     */

?>
<!-- include tinymce -->
<script language="javascript" type="text/javascript" src="<?php echo $vars['url']; ?>mod/tinymce/tinymce/jscripts/tiny_mce/tiny_mce.js"></script>
<!-- intialise tinymce, you can find other configurations here http://wiki.moxiecode.com/examples/tinymce/installation_example_01.php -->
<script language="javascript" type="text/javascript">
   tinyMCE.init({
    mode : "textareas",
    theme : "advanced",
    theme_advanced_buttons1 : "bold,italic,underline,separator,strikethrough,justifyleft,justifycenter,justifyright, justifyfull,bullist,numlist,undo,redo,link,unlink,image,blockquote,code",
    theme_advanced_buttons2 : "",
    theme_advanced_buttons3 : "",
    theme_advanced_toolbar_location : "top",
    theme_advanced_toolbar_align : "left",
    theme_advanced_statusbar_location : "bottom",
    theme_advanced_resizing : true,
    extended_valid_elements : "a[name|href|target|title|onclick],img[class|src|border=0|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name],
hr[class|width|size|noshade],font[face|size|color|style],span[class|align|style]"
});
</script>

Ensuite, dans le fichier elgg-plugin.php de votre plugin étendez la vue input/longtext :

return [
    'view_extensions' => [
            'input/longtext' => [
                    'tinymce/longtext' => [],
            ],
    ],
];

Et voilà ! Maintenant, chaque fois que quelqu’un utilise input/longtext TinyMCE sera chargé et appliqué à ce champ de saisie de texte.

Widget simple

Créez un widget qui va afficher “Hello, World!”, et en option n’importe quel texte souhaité par l’utilisateur.

Dans Elgg, les widgets sont ces composants que vous pouvez déplacer sur votre page de profil ou le tableau de bord d’administration.

Ce tutoriel suppose que vous connaissez les concepts de base de Elgg tels que :

• Vues

• Plugins

Vous devriez les revoir si cela devient confus en cours de route.

Ajouter le code de la vue du widget

Elgg scanne automatiquement certains répertoires des plugins pour trouver des fichiers spécifiques. Les vues Vues facilitent l’ajout de votre propre code d’affichage, ou la possibilité de faire d’autres choses telles que surcharger le comportement par défaut de Elgg. Pour le moment, nous allons simplement ajouter le code d’affichage pour votre widget. Créez un fichier /views/default/widgets/helloworld/content.php. “helloworld” sera le nom de votre widget à l’intérieur du plugin hello. Dans ce fichier ajoutez le code :

<?php

echo "Hello, world!";

Ceci va ajouter ces mots au canevas du widget lorsqu’il sera affiché. Elgg prend soin de charger le widget.

Enregistrer votre widget

Elgg a besoin qu’on lui indique explicitement que le plugin contient un widget afin qu’il scanne le répertoire des vues des widgets. Cela se fait en enregistrant le widget dans votre elgg-plugin.php :

<?php
    return [
                'widgets' => [
                            'helloworld' => [
                                    'name' => 'Hello, world!',
                                    'description' => 'The "Hello, world!" widget',
                            ],
                    ],
            ];

Rendez-vous maintenant sur votre page de profil avec un navigateur web et ajoutez le widget “hello, world”. Il devrait afficher “Hello, world!”.

Note

Pour de vrais widgets, c’est toujours une bonne idée de respecter Internationalisation.

Permettre les personnalisations par l’utilisateur

Cliquez sur le lien d’édition dans la barre d’outils du widget que vous avez créé. Vous allez remarquer que le seul contrôle qu’il vous offre par défaut est celui du niveau d’accès (sur qui peut voir le widget).

Supposez que vous voulez permettre à l’utilisateur de contrôler quel message d’accueil est affiché dans le widget. De la même manière que Elgg charge automatiquement content.php pour afficher un widget, il charge edit.php quand un utilisateur tente de modifier un widget. Ajoutez le code suivant dans /views/default/widgets/helloworld/edit.php :

<div>
    <label>Message:</label>
    <?php
        //This is an instance of the ElggWidget class that represents our widget.
        $widget = $vars['entity'];

        // Give the user a plain text box to input a message
        echo elgg_view('input/text', array(
            'name' => 'params[message]',
            'value' => $widget->message,
            'class' => 'hello-input-text',
        ));
    ?>
</div>

Notez la relation entre les valeurs passées aux champs nom “name” et valeur “value” de input/text. Le nom du champ de la boîte de saisie de texte est params[message] parce que Elgg va automatiquement gérer les variables des widgets placées dans le tableau params. Le nom de la variable PHP correspondante sera message. Si nous voulions utiliser le champ greeting au lieu de message nous passerions respectivement les valeurs params[greeting] et $widget->greeting.

La raison pour laquelle nous définissons l’option “value” du tableau est que ceci indique à la vue d’édition de se souvenir de ce que l’utilisateur a saisi la dernière fois qu’il a modifié la valeur du texte du message.

Maintenant pour afficher le message de l’utilisateur nous devons modifier content.php pour qu’il utilise cette variable message. Éditez /views/default/widgets/helloworld/content.php et modifiez-le pour :

<?php

$widget = $vars['entity'];

// Always use the corresponding output/* view for security!
echo elgg_view('output/text', array('value' => $widget->message));

Vous devriez maintenant pouvoir saisir un message dans la boîte de texte et le voir apparaître dans le widget.

Documentation du design de conception

Acquérez une compréhension profonde de comment fonctionne Elgg et de pourquoi il est construit de cette manière.

Actions

Les actions sont la première modalité d’interaction des utilisateurs avec un site Elgg.

Aperçu

Dans Elgg, une action est le code qui est exécuté pour faire des modifications dans la base de données quand un utilisateur effectue quelque chose. Par exemple, le fait de se connecter, de publier un commentaire, ou de créer un article de blog sont des actions. Le script d’action traite les entrées, effectue les modifications appropriées dans la base de données, et fournit un retour à l’utilisateur à propos de l’action.

Gestionnaire d’action

Les actions sont enregistrées durant le processus de démarrage « boot » en appelant elgg_register_action(). Toutes les URLs d’action commencent par action/ et sont servies par le contrôleur front end de Elgg à travers le service action. Cette approche est différente de celle d’applications PHP traditionnelles qui envoient l’information à un fichier spécifique. Le service action réalise des CSRF vérifications de sécurité, et appelle le fichier de script d’action enregistré, puis renvoie éventuellement l’utilisateur vers une nouvelle page. En utilisant le service action au lieu d’un seul fichier de script, Elgg fournit automatiquement une sécurité et une extensibilité améliorées.

Voyez Formulaires + Actions pour plus de détails sur comment enregistrer et construire une action. Pour regarder les actions du noyau, regardez dans le répertoire /actions.

Base de données

Une discussion solide sur le design du modèle de données de Elgg et ses motivations.

Aperçu

Dans Elgg, tout fonctionne sur un modèle de données unifié construit sur des unités atomiques de données appelées entités.

Il est recommandé que les plugins n’interagissent pas directement avec la base de données, afin de créer un système plus stable et une meilleure expérience utilisateur parce que les contenus créés par différents plugins peuvent être mélangés ensemble de manière cohérente. Avec cette approche, les plugins sont plus rapides à développer, et sont en même temps plus puissants.

Chaque entité dans le système hérite de la classe ElggEntity. Cette classe contrôle les permissions d’accès, la propriété, le conteneur, et fournit une API cohérente pour accéder aux propriétés des entités et les modifier.

Vous pouvez étendre les entités avec des informations supplémentaires de deux manières :

Metadata : Ces informations décrivent l’entité, elles sont habituellement

ajoutées par l’auteur de l’entité quand l’entité est créée ou modifiée. Des exemples de métadonnées incluent les tags, un numéro ISBN ou un ID tierce-partie, une adresse, des coordonnées géographiques, etc. Imaginez les métadonnées comme un simple système de stockage clef-valeur.

Annotations : Ces informations étendent l’entité avec des propriétés, habituellement

ajoutées par une tierce-partie. De telles propriétés comprennent par exemple les notations, les likes ou les votes.

Les principales différences entre métadonnées et annotations :

• les métadonnées n’ont pas de propriétaire, alors que les annotations en ont

• les métadonnées ne disposent pas de contrôle d’accès, alors que les annotations en disposent

• les métadonnées sont préchargées lorsque l’entité est construite, alors que les annotations ne sont chargées que sur demande

Ces différences peuvent avoir des implications sur les performances et votre logique applicative, aussi considérez avec soin la manière dont vous souhaiter attacher des données à vos entités.

Dans certains cas, il peut être préférable d’éviter d’utiliser ces métadonnées et annotations et de créer de nouvelles entités à la place, puis de les attacher via container_guid ou une relation.

Modèle de données

Le diagramme du modèle de données de Elgg

Entités

ElggEntity est la classe de base pour le modèle de données de Elgg et supporte un jeu de propriétés et de méthodes communes.

• Un identifiant global unique (Globally Unique IDentifier - Voir GUIDs).

• Permissions d’accès . (Quand un plugin demande des données, il n’accède jamais à des données que l’utilisateur actuel n’a pas la permission de voir.)

• Un sous-type arbitraire (plus d’informations ci-dessous).

• Un propriétaire

• Le site auquel appartient cette entité.

• Un conteneur, utilisé pour associer le contenu avec un groupe ou un utilisateur.

Types

Les véritables entités seront des instances de quatre sous-classes différentes, chacune ayant une propriété type distincte et leur propres propriétés et méthodes additionnelles.

Type	Classe PHP	Représente
object	ElggObject	Les plupart des contenus créés par les utilisateurs, tels que des articles de blog, des chargements de fichiers, et des signets.
group	ElggGroup	Un groupe organisé d’utilisateurs avec sa propre page de profil
user	ElggUser	Un utilisateur du système
site	ElggSite	Le site servi par l’installation Elgg

Chaque type a sa propre API étendue. Par ex. les utilisateurs peuvent être en contact avec d’autres utilisateurs, un groupe peut avoir des membres, tandis que les objets peuvent être aimés et commentés.

Sous-types « subtypes »

Chaque entité doit définir un sous-type subtype, que les plugins utilisent pour spécialiser encore l’entité. Elgg facilite le fait de rechercher des entités spécifiques d’un sous-type donné (ou de plusieurs), ainsi que de leur assigner des comportements et vues spéciales.

Les sous-types sont communément donnés aux instances de ElggEntity pour définir le type de contenu créé. Par ex. le plugin blog crée des objets avec le sous-type "blog".

Par défaut, les utilisateurs, les groupes et les sites ont respectivement les sous-types user, group et site.

Les plugins peuvent utiliser des classes d’entités personnalisées qui étendent la classe de base du type. Pour cela, ils doivent enregistrer leur classe au démarrage (par ex. dans le gestionnaire 'init', 'system'), en utilisant elgg_set_entity_class(). Par exemple, le plugin blog pourrait utiliser elgg_set_entity_class('object', 'blog', \ElggBlog::class).

Les plugins peuvent utiliser elgg-plugin.php pour définir une classe d’entité via le paramètre raccourci entities.

Trucs à savoir sur les sous-types

• Avant que la méthode save() d’une entité soit appelée, le sous-type doit être défini en écrivant une chaîne de caractère dans la propriété subtype.

• Le sous-type ne peut pas être changé après l’enregistrement.

GUIDs

Un GUID est un entier qui définit de manière unique chaque entité dans une installation Elgg (un IDentifiant Global Unique - Globally Unique IDentifier). Il est assigné automatiquement la première fois qu’une entité est enregistré, et ne peut jamais être changé.

Certaines fonctions de l’API de Elgg fonctionnent avec des GUIDs au lieu d’objets ElggEntity.

ElggObject

Le type d’entité ElggObject représente un type de contenu arbitraire au sein d’une installation Elgg ; des choses telles que des articles de blog, des fichiers, etc.

Au-delà des propriétés standards de ElggEntity, les ElggObjects supportent également :

• title Le titre de l’objet (texte sans HTML)

• description Une description de l’objet (HTML)

La plupart des autrse données à propos de l’objet sont généralement stockées via des métadonnées.

ElggUser

Le type d’entité ElggUser représente les utilisateurs au sien d’une installation Elgg. Ils seront définis comme désactivés jusqu’à-ce que leur compte ait été activé (à moins qu’ils n’aient été créés à partir du panneau d’administration).

Au-delà des propriétés standards de ElggEntity, les ElggUsers supportent également :

• name Le nom de l’utilisateur en texte brut. Par ex. « Hugh Jackman »

• username Leur identifiant. Par ex. « hjackman »

• password Une version hachée de leur mot de passe

• email Leur adresse e-mail

• language Leur code de langue par défaut.

• code Leur code de session (déplacé vers une table séparée dans la 1.9).

• last_action Le timestamp UNIX de la dernière fois qu’ils ont chargé une page

• prev_last_action La précédente valeur de last_action

• last_login Le timestamp UNIX de leur dernière connexion

• prev_last_login la précédente valeur de last_login

ElggSite

Le type d’entité ElggSite représente votre installation Elgg (via l’URL de votre site).

Au-delà des propriétés standards de ElggEntity, les ElggSites supportent également :

• name Le nom du site

• description Une description du site

• url L’adresse du site

ElggGroup

Le type d’entité ElggGroup représente une association d’utilisateurs Elgg. Les utilisateurs peuvent rejoindre, quitter les groupes, et y publier du contenu.

Au-delà des propriétés standards de ElggEntity, les ElggGroups supportent également :

• name Le nom du groupe (texte sans HTML)

• description Une description du groupe (HTML)

ElggGroup a des méthodes additionnelles pour gérer le contenu et les adhésions.

Le plugin Groups

A ne pas confondre avec le type d’entité ElggGroup, Elgg vient avec un plugin appelé « Groups » qui fournit une UI/UX par défaut pour que les utilisateurs du site interagissent avec les groupes. Chaque groupe dispose d’un forum de discussion et d’une page de profil qui relient les utilisateurs au contenu dans le groupe..

Vous pouvez modifier l’expérience utilisateur via les moyens traditionnels d’extension de plugin, ou remplacer complètement le plugin Groups par votre propre plugin.

Écrire un plugin compatibles avec les groupes

Les développeurs de plugins ne devraient pas trop s’inquiéter de l’écriture de fonctionnalités compatibles avec les groupes, mais il y a quelques points clefs :

Ajouter du contenu

En passant le groupe en tant que container_guid via un champ de saisie caché, vous pouvez utiliser un seul formulaire et une seule action pour ajouter du contenu à la fois pour un utilisateur ou pour un groupe.

Utilisez ElggEntity->canWriteToContainer(0, $type, $subtype) pour déterminer si l’utilisateur actuel a le droit d’ajouter du contenu à un groupe.

Soyez attentif au fait que vous allez devoir passer le GUID du conteneur ou l’identifiant à la page responsable de la publication, et la valeur associée, de sorte que ceci puisse être ensuite conservé dans votre formulaire sous forme de champ de saisie caché, pour un passage plus aisé vers vos actions. Au sein d’une action « create », vous allez avoir besoin de récupérer ce champ de saisie et de l’enregistrer sous forme de propriété de votre nouvel élément (la valeur par défaut est le conteneur actuel de l’utilisateur) :

$user = elgg_get_logged_in_user_entity();
$container_guid = (int) get_input('container_guid');

if ($container_guid) {
    $container = get_entity($container_guid);

    if (!$container instanceof \ElggEntity || !$container->canWriteToContainer($user->guid, 'object', 'my_content_subtype')) {
        return elgg_error_response(elgg_echo('actionunauthorized'));
    }
} else {
    $container_guid = elgg_get_logged_in_user_guid();
}

$object = new ElggObject();
$object->container_guid = $container_guid;

...

// redirect to the created object
return elgg_ok_response('', $object->getURL());

Propriété

Les entités ont une propriété GUID owner_guid, qui définit son propriétaire. Typiquement ceci renvoie au GUID d’un utilisateur, quoique les sites et les utilisateurs eux-même n’ont souvent pas de propriétaire (valeur de 0).

La propriété d’une entité détermine, d’une part, si vous pouvez ou non accéder à cette entité, ou la modifier.

Conteneurs « containers »

Afin de rechercher aisément du contenu par groupe ou utilisateur, le contenu est généralement défini comme « contenu » soit par l’utilisateur qui l’a publié, soit par le groupe dans lequel l’utilisateur l’a publié. Ceci signifie que la propriété container_guid des nouveaux objets sera définie avec la valeur du ElggUser actuel ou du ElggGroup cible.

Par ex., trois articles de blog peuvent avoir des propriétaires différentes, mais être tous contenus dans le groupe où ils ont été publiés.

Note : Ceci n’est pas toujours vrai. Les entités des commentaires sont contenues par l’objet commenté, et dans certains plugins tierce-partie le conteneur peut être utilisé pour modéliser des relations parents-enfants entre entités (par ex. un objet dossier « folder qui contient un objet fichier).

Annotations

Les annotations sont des éléments de données attachées à une entité qui permet aux utilisateurs de laisser des évaluations, ou d’autres types de réactions pertinentes. Un plugin de sondage pourrait enregistrer des votes sous forme d’annotations.

Les annotations sont stockées sous formes d’instances de la classe ElggAnnotation.

Chaque annotation dispose de :

• Un type d’annotation interne (tel que comment)

• Une valeur (qui peut être une chaîne de caractères ou un entier)

• Un niveau d’accès distinct de celui de l’entité à laquelle elle est attachée

• Un propriétaire

Comme pour les métadonnées, les valeurs sont stockées sous forme de chaines de caractères à moins que la valeur donnée soit un entier PHP (is_int($value) vaut true), ou à moins que $vartype soit spécifié manuellement comme integer.

Ajouter une annotation

La manière la plus simple d’ajouter une annotation est d’utiliser la méthode annotate sur une entité, qui est définie comme :

public function annotate(
    $name,           // The name of the annotation type (eg 'comment')
    $value,          // The value of the annotation
    $access_id = 0,  // The access level of the annotation
    $owner_id = 0,   // The annotation owner, defaults to current user
    $vartype = ""    // 'text', 'bool' or 'integer'
)

Par exemple, pour donner une notation à une entité, vous pouvez appeler :

$entity->annotate('rating', $rating_value, $entity->access_id);

Lire des annotations

Pour récupérer les annotations d’une entité, vous pouvez appeler la méthode suivante :

$annotations = $entity->getAnnotations(
    $name,    // The type of annotation
    $limit,   // The number to return
    $offset,  // Any indexing offset
    $order,   // 'asc' or 'desc' (default 'asc')
);

Si votre type d’annotation utilise largement des valeurs entières, plusieurs fonctions mathématiques utiles sont fournies :

$averagevalue = $entity->getAnnotationsAvg($name);  // Get the average value
$total = $entity->getAnnotationsSum($name);         // Get the total value
$minvalue = $entity->getAnnotationsMin($name);      // Get the minimum value
$maxvalue = $entity->getAnnotationsMax($name);      // Get the maximum value

Fonctions d’assistance utiles

Commentaires

Si vous souhaitez fournir une fonctionnalité de commentaire sur les objets de votre plugin, la fonction suivante va fournir le listing complet, le formulaire et les actions :

function elgg_view_comments(ElggEntity $entity)

Métadonnées

Les métadonnées dans Elgg vous permettent de stocker les données supplémentaires d’une entité au-delà des champs prédéfinis que cette entité supporte. Par exemple, ElggObjects ne supporte que les champs d’entités basiques plus un titre et une description, mais vous pouvez souhaiter inclure également des tags ou un numéro ISBN. De manière similaire, vous pourriez souhaiter que les utilisateurs puissent enregistrer une date de naissance.

Sous le capot, les métadonnées sont stockées sous forme d’instance de la classe ElggMetadata, mais vous n’avez pas à vous soucier de cela en pratique (quoique si vous êtes intéressé, voyez la référence de la classe ElggMetadata). Ce que vous avez besoin de savoir :

• Vous pouvez potentiellement avoir plusieurs éléments de chaque type de métadonnée attachés à la même entité

• Comme les annotations, les valeurs sont stockées sous forme de chaînes de caractères, de booléens ou d’entiers

Le cas simple

Ajouter des métadonnées

Pour ajouter une métadonnée à une entité, appelez simplement :

$entity->metadata_name = $metadata_value;

Par exemple, pour ajouter une date d’anniversaire à un utilisateur :

$user->dob = $dob_timestamp;

Ou pour ajouter des tags à un objet :

$object->tags = array('tag one', 'tag two', 'tag three');

Lorsque vous ajoutez une métadonnée de cette manière :

• Réassigner une métadonnée va remplacer l’ancienne valeur

Ceci convient pour la plupart des objectifs. Faites attention à bien noter quels attributs sont des métadonnées et lesquels sont natifs au type d’entité avec lequel vous travaillez. Vous n’avez pas besoin d’enregistrer une entité après avoir ajouté ou modifié des métadonnées. Vous devez enregistrer une entité si vous avez changé l’un des ses attributs natifs. A titre d’exemple, si vous avez changé l’id de l’accès d’un ElggObject, vous devez l’enregistrer, faute de quoi la modification ne sera pas conservée dans la base de données.

Lire des métadonnées

Pour récupérer une métadonnée, traitez-la comme une propriété d’une entité :

$tags_value = $object->tags;

Notez que ceci va retourner la valeur absolue de la métadonnée. Pour récupérer des métadonnées sous forme d’objet ElggMetadata, vous aurez besoin d’utiliser les méthodes décrites dans la section contrôle plus fin ci-dessous.

Si vous stockez de multiples valeurs dans cette métadonnée (comme dans l’exemple « tags » ci-dessus), vous obtiendrez un tableau de toutes ces valeurs. Si vous stockez seulement une valeur, vous récupérerez une chaîne de caractères ou un entier. Stocker un tableau avec seulement une valeur vous retournera une chaîne de caractères. Par ex.

$object->tags = array('tag');
$tags = $object->tags;
// $tags will be the string "tag", NOT array('tag')

Pour récupérer toujours un tableau, castez simplement vers un tableau ;

$tags = (array)$object->tags;

Lire des métadonnées comme des objets

elgg_get_metadata est la meilleure fonction pour récupérer les métadonénes sous forme d’objets ElggMetadata :

Par ex., pour récupérer la date de naissance d’un utilisateur

elgg_get_metadata([
    'metadata_name' => 'dob',
    'guid' => $user_guid,
]);

Ou pour récupérer tous les objets de métadonnées :

elgg_get_metadata([
    'guid' => $user_guid,
    'limit' => false,
]);

Erreurs courantes

« Ajouter » des métadonnées à la suite

Notez que vous ne pouvez pas « ajouter » des valeurs aux tableaux de métadonnées comme si c’étaient des tableaux php normaux. Par exemple, le code suivant ne fera pas ce qu’il semblerait qu’il devrait faire.

$object->tags[] = "tag four";

Essayer de stocker des tableaux indexés

Elgg ne supporte pas le stockage de tableaux indexés (paires clef/valeur) dans les métadonnées. Par exemple, le code suivant ne fonctionne pas comme vous pourriez le penser de prime abord :

// Won't work!! Only the array values are stored
$object->tags = array('one' => 'a', 'two' => 'b', 'three' => 'c');

Au lieu de cela, vous pouvez conserver cette information de cette manière :

$object->one = 'a';
$object->two = 'b';
$object->three = 'c';

Conserver des GUIDs dans des métadonnées

Quoiqu’il existe certains cas pour stocker les GUIDs d’entités dans des métadonnées, les relations Relationships sont une construction bien plus adaptée pour relier les entités les unes aux autres.

Relations

Les relations vous permettent d’associer des entités ensemble. Exemples : un artiste a des fans, un utilisateur est membre d’une organisation, etc.

La classe ElggRelationship modélise une relation directe entre deux entités, en faisant la déclaration :

« {sujet} est un {nom} de {cible}. »

Nom de l’API	Modèles	Représente
guid_one	Le sujet	Quelle entité est reliée
relationship	Le nom	Le type de relation
guid_two	La cible	L’entité à laquelle le sujet est relié

Le type de relation peut également être un verbe, faisant la déclaration :

« {sujet} {verbe} {cible}. »

Par ex. Utilisateur A aime « likes » l’article de blog B

Chaque relation a une direction. Imaginez un archer qui tire une flèche vers une cible ; la flèche se déplace dans une direction, en reliant le sujet (l’archer) à la cible.

Une relation n’implique pas de réciprocité. A suit B n’implique pas que B suive A.

Les relations Relationships_ n’ont pas de contrôle d’accès. Elles ne sont jamais cachées d’une vue et peuvent être modifiées par le code à n’importe quel niveau de privilège, avec l’avertissement que les entités d’une relation peuvent être invisible en raison du contrôle d’accès !

Travailler avec des relations

Créer une relation

Par exemple pour établir que l’utilisateur « $user est un fan de l’artiste $artist » (l’utilisateur est le sujet, l’artiste est la cible):

$success = $user->addRelationship($artist->guid, 'fan');

Ceci déclenche l’événement [create, relationship], en lui passant l’objet ElggRelationship créé. Si un gestionnaire retourne false, la relation ne sera pas créée et $success vaudra false.

Vérifier une relation

Par exemple pour vérifier que l’utilisateur « $user est un fan de l’artiste $artist »:

if ($user->hasRelationship($artist->guid, 'fan')) {
    // relationship exists
}

Supprimer une relation

Par exemple pour pouvoir affirmer que l’utilisateur « $user n’est désormais plus un fan de l’artiste $artist »:

$was_removed = $user->removeRelationship($artist->guid, 'fan');

Ceci déclenche l’événement [delete, relationship], en lui passant l’objet ElggRelationship associé. Si un gestionnaire retourne false, la relation sera conservée, et $was_removed vaudra false.

Autres fonctions utiles :

• \ElggRelationship->delete(): supprime par objet

• \ElggEntity->removeAllRelationships(): supprime toutes les relations associées à une entité

Trouver des relations et des entités associées

Vous trouverez ci-dessous quelques fonctions permettant de récupérer des objets relationnels et/ou des entités associées :

• elgg_get_relationship() : récupère un objet relationship par son ID

• elgg_get_relationships() : récupère des relations

• elgg_get_entities() : récupère les entités dans les relations de différentes manières

Par ex. retrouver les utilisateurs qui ont rejoint votre groupe en janvier 2014.

$entities = elgg_get_entities(array(
    'relationship' => 'member',
    'relationship_guid' => $group->guid,
    'inverse_relationship' => true,

    'relationship_created_time_lower' => 1388534400, // January 1st 2014
    'relationship_created_time_upper' => 1391212800, // February 1st 2014
));

Contrôle d’accès

Les contrôle d’accès granulaires sont l’un des principes de design fondamentaux dans Elgg, et une fonctionnalité qui a été au cœur du système tout au long de son développement. L’idée est simple : un utilisateur devrait avoir un contrôle total sur qui peut voir un élément de donnée qu’il ou elle a créé.

Niveau d’accès dans le modèle de données

Pour parvenir à cela, chaque entité et annotation contient une propriété access_id, qui correspond à l’un des niveau d’accès prédéfinis ou à une entrée dans la table access_collections de la base de données.

Niveaux d’accès prédéfinis

• ACCESS_PRIVATE (valeur : 0) Privé.

• ACCESS_LOGGED_IN (valeur : 1) Utilisateurs connectés.

• ACCESS_PUBLIC (valeur : 2) Données publiques.

Niveaux d’accès définis par l’utilisateur

Vous pouvez définir des groupes d’accès additionnels et les assigner à une entité, ou une annotation. Un certain nombre de fonctions ont été définies pour vous y aider ; voyez Listes de Contrôle d’Accès pour plus d’informations.

Comment les accès affectent la récupération de données

Toutes les récupérations de données fonctionnent au-dessus de la couche de la base de données - par exemple elgg_get_entities ne retournera que les éléments que l’utilisateur actuel a l’autorisation de voir. Il n’est pas possible de récupérer des éléments auxquels l’utilisateur actuel n’a pas accès. Ceci rend très difficile de créer un trou de sécurité pour récupérer des données.

Accès en écriture

Les règles suivantes gouvernent les accès en écriture :

• Le propriétaire d’une entité peut toujours la modifier

• Le propriétaire d’un conteneur peut modifier tout ce qui est dedans (notez que cela ne signifie pas que le propriétaire d’un groupe peut modifier toutes les publications dans ce groupe)

• Les administrateurs peuvent tout éditer

Vous pouvez remplacer ce comportement en utilisant un event appelé permissions_check, qui transmet l’entité en question à toute fonction ayant annoncé qu’elle souhaite être référencée. Renvoyer true autorisera l’accès en écriture ; renvoyer false le bloquera. Voir le guide de référence des événement pour la vérification des permissions pour plus de détails.

Schéma

La base de données contient un certain nombre de tables primaires et secondaires. Vous pouvez suivre les évolutions du schéma dans engine/schema/migrations/

L’ensemble de caractères de la base de données doit être utf8mb4, ce qui fournira une prise en charge complète des caractères unicode lors du stockage des données.

InnoDB

À partir de Elgg 3.0, la base de données utilise le moteur InnoDB. Pour une installation ou une migration correcte, certains paramètres peuvent devoir être ajustés dans les paramètres de la base de données.

• innodb_large_prefix devrait être on

• innodb_file_format devrait être Barracuda

• innodb_file_per_table devrait être 1

Tables principales

Voici la description des principales tables. Gardez à l’esprit que pour une installation de Elgg donnée, les tables vont avoir un préfixe (typiquement « elgg_ »).

Table : entities - entités

Ceci est la table principale Entities qui contient les utilisateurs, sites, objets et groupes Elgg. Quand vous installez Elgg la première fois elle est automatiquement peuplée avec votre premier site.

Elle contient les champs suivants :

• guid Un compteur auto-incrémenté qui produit un GUID qui identifie de manière unique cette entité dans le système

• type Le type d’entity - object, user, group ou site

• subtype Le sous-type d’entité

• owner_guid Le GUID de l’entité du propriétaire

• container_guid Le GUID dans laquelle cette entité est contenue - soit un utilisateur « user » soit un groupe « group »

• access_id Contrôles d’accès sur cette entité

• time_created Le timestamp Unix de création de l’entité

• time_updated Le timestamp Unix de la dernière modification de l’entité

• enabled Si “yes” -oui- l’entité est accessible, si “no” -non- l’entité a été désactivée (Elgg traite cela comme si elle avait été supprimée sans toutefois la supprimer réellement de la base de données)

Table : metadata

Cette table contient des métadonnées Metadata, des informations supplémentaires attachées à une entité.

• id Un IDentifiant unique

• entity_guid L’entité à laquelle cette métadonnée est attachée

• name Le nom de la chaîne

• value La valeur de la chaîne

• value_type La classe de la valeur, soit texte « text » ou un entier « integer »

• time_created Le timestamp Unix de la date de création de la métadonnée

• enabled Si “yes” -oui- l’élément est accessible, si “no” -non- l’élément a été désactivé

Table : annotations

Cette table contient les Annotations, ce qui est distinct des Metadata.

• id Un IDentifiant unique

• entity_guid L’entité à laquelle cette métadonnée est attachée

• name Le nom de la chaîne

• value La valeur de la chaîne

• value_type La classe de la valeur, soit texte « text » ou un entier « integer »

• owner_guid Le GUID du propriétaire qui a défini cette annotation

• access_id Un Contrôle d’Accès sur cette annotation

• time_created Le timestamp Unix de la date de création de l’annotation.

• enabled Si “yes” -oui- l’élément est accessible, si “no” -non- l’élément a été désactivé

Table : relationships - relations

Cette table définit les relations Relationships, qui relient une entité avec une autre.

• guid_one Le GUID de l’entité sujet.

• relationship Le type de relation.

• guid_two Le GUID de l’entité cible.

Tables secondaires

Table : access_collections

Cette table définit les Collections d’Accès, qui donnent accès aux utilisateurs aux Entités ou aux Annotations.

• id Un IDentifiant unique

• *name Le nom de la collection d’accès

• owner_guid Le GUID de l’entité propriétaire (par ex. un utilisateur ou un groupe)

• subtype le sous-type de la collection d’accès (par ex. friends ou group_acl)

Événements

Aperçu

Elgg a un événement système qui peut être utilisé pour remplacer ou étendre les fonctionnalités du noyau.

Les plugins modifient le système en créant des gestionnaires (callables tels que des fonctions et des méthodes) et en les enregistrant pour gérer les événements.

Quand un événement est déclenché, un jeu des gestionnaires est exécuté par ordre de priorité. Les arguments sont passés à chaque gestionnaire qui peut ainsi influencer le processus. Après exécution, la fonction déclencheuse « trigger » retourne une valeur qui dépend du comportement des gestionnaires.

Voir aussi

• Liste des événements dans le noyau

Événements Elgg Events

Les événements Elgg Events sont déclenchés quand un objet Elgg est créé, modifié ou supprimé ; et à différentes étapes importantes du chargement du framework Elgg. Exemples : lors de la création d’un article de blog ou de l’identification d’un utilisateur.

Ces événements sont principalement utilisés pour informer le reste du système que quelque chose s’est produit.

Certains événements sont également utilisés pour modifier la sortie, la configuration ou le comportement du système.

Chaque événement Elgg a un nom et un type (système, utilisateur, objet, nom de relation, annotation, groupe) décrivant le type d’objet passé aux gestionnaires.

Événements antérieurs « Before » et postérieurs « After »

Certains événements sont séparés en « before » -avant- et « after » -après-. Ceci évite la confusion autour de l’état du système en cours de modification. Par ex. Est-ce que l’utilisateur est identifié au cours de l’événement [login, user] ?

Les événements Précédents ont des noms se terminant par « :before » et sont déclenchés avant que quelque chose ne se produise. Les gestionnaires peuvent annuler l’événement en renvoyant false. Lorsque false est renvoyé par un gestionnaire, les gestionnaires suivants ne seront pas appelés.

Les événements Suivants, dont les noms se terminent par « :after », sont déclenchés après que quelque chose s’est produit. Les gestionnaires ne peuvent pas annuler ces événements ; tous les gestionnaires seront toujours appelés.

Là où des événements :before et :after sont disponibles, les développeurs sont encouragés à faire la transition vers eux, même si d’anciens événements resteront supportés pour des raisons de compatibilité descendante.

Gestionnaires d’événement Elgg

Les gestionnaires d’événement Elgg sont appelables :

<?php

/**
 * @param \Elgg\Event $event The event object
 *
 * @return bool if false, the handler is requesting to cancel the event
 */
function event_handler(\Elgg\Event $event) {
    ...
}

Dans event_handler1, l’objet Event dispose de diverses méthodes pour récupérer le nom, le type d’objet, et l’objet de l’événement. Voyez la classe Elgg\Event pour plus d’informations.

Enregistrez un gestionnaire d’événement Elgg Event

Enregistrez votre gestionnaire pour un événement en utilisant elgg_register_event_handler :

<?php

elgg_register_event_handler($event, $type, $handler, $priority);

Paramètres :

• $event Le nom de l’événement.

• $type Le type d’événement (par exemple « user » ou « object ») ou “all” pour tous les types sur lesquels l’événement est déclenché.

• $handler Le callback - la fonction de rappel du gestionnaire.

• $priority La priorité - 0 en premier et la valeur par défaut est 500.

Exemple :

<?php

// Register the function myPlugin_handle_create_object() to handle the
// create object event with priority 400.
elgg_register_event_handler('create:after', 'object', 'myPlugin_handle_create_object', 400);

Avertissement

Si vous gérez l’événement « update » d’un objet, évitez d’appeler save() dans votre gestionnaire d’événement. Tout d’abord ce n’est probablement pas nécessaire car l’objet est enregistré après que l’événement soit terminé, mais aussi parce que save() appelle un autre événement « update » et ne rend plus disponible $object->getOriginalAttributes().

Classes invocables comme gestionnaires

Vous pouvez utiliser une classe avec une méthode __invoke() comme gestionnaire. Enregistrez simplement le nom de la classe et il sera instancié (sans argument) pour toute la durée de vie de l’événement.

<?php

namespace MyPlugin;

class UpdateObjectHandler {
    public function __invoke(\Elgg\Event $event) {

    }
}

// in init, system
elgg_register_event_handler('update', 'object', MyPlugin\UpdateObjectHandler::class);

Déclencher un événement Elgg Event

Vous pouvez déclencher un événement personnalisé en utilisant elgg_trigger_event :

<?php

if (elgg_trigger_event($event, $object_type, $object)) {
    // Proceed with doing something.
} else {
    // Event was cancelled. Roll back any progress made before the event.
}

Pour les événements avec des états ambigus, tels que l’identification d’un utilisateur, vous devriez utiliser Événements antérieurs « Before » et postérieurs « After » en appelant elgg_trigger_before_event ou elgg_trigger_after_event. Ceci clarifie pour le gestionnaire d’événement l’état auquel s’attendre et quels événements peuvent être annulés.

<?php

// handlers for the user, login:before event know the user isn't logged in yet.
if (!elgg_trigger_before_event('login', 'user', $user)) {
    return false;
}

// handlers for the user, login:after event know the user is logged in.
elgg_trigger_after_event('login', 'user', $user);

Paramètres :

• $event Le nom de l’événement.

• $object_type Le type d’objet (par ex. « user » ou « object »).

• $object L’objet (par ex. une instance de ElggUser ou ElggGroup)

La fonction va retourner false si n’importe lequel des gestionnaires sélectionnés retourne false et si l’événement est interruptible, sinon elle retournera true.

Déclencher un Événement avec des résultats

Les Événements avec résultats permettent aux plugins de déterminer ou de modifier une valeur de manière collaborative. Par exemple, pour décider si un utilisateur est autorisé à modifier une entité ou à ajouter des options de configuration supplémentaires à un plugin.

Un événement a une valeur transmise à la fonction de déclenchement, et chaque gestionnaire a la possibilité de modifier cette valeur avant qu’elle ne soit transmise au gestionnaire suivant. Une fois le dernier gestionnaire terminé, la valeur finale est renvoyée par le déclencheur.

Vous pouvez déclencher un événement personnalisé en utilisant elgg_trigger_event_results :

<?php

// filter $value through the handlers
$value = elgg_trigger_event_results($name, $type, $params, $value);

Paramètres :

• $name Le nom de l’événement.

• $type Le type d’événement ou « all » pour tous les types.

• $params Des données arbitraires passées par le déclencheur aux gestionnaires.

• $value La valeur initiale de l’événement.

Déclenche une séquence Elgg Event

Au lieu de déclencher manuellement l’événement :before et after, il est possible de déclencher une séquence d’événements. Cela déclenchera l’événement :before, puis l’événement réel et enfin l’événement :after.

elgg()->events->triggerSequence($event, $type, $object, $callable);

Lorsqu’ils sont appelés avec par exemple 'cache:clear', 'system', les trois événements suivants sont déclenchés

• 'cache:clear:before', 'system'

• 'cache:clear', 'system'

• 'cache:clear:after', 'system'

Paramètres :

• $event Le nom de l’événement.

• $object_type Le type d’objet (par ex. « user » ou « object »).

• $object L’objet (par ex. une instance de ElggUser ou ElggGroup)

• $callable Appelable à exécuter lors d’un événement réussi, avant event:after

Dés-inscrire des Gestionnaires d’événement

Les fonctions elgg_unregister_event_handler peuvent être utilisées pour supprimer les gestionnaires déjà enregistrés par un autre plugin ou le coeur de Elgg. Les paramètres sont dans le même ordre que les fonctions d’enregistrement, sauf qu’il n’y a pas de paramètre de priorité.

<?php

elgg_unregister_event_handler('login', 'user', 'myPlugin_handle_login');

Les fonctions anonymes ou les objets invocables ne peuvent pas être enregistrés, mais des « callbacks », fonctions de rappel de méthode dynamiques peuvent être dé-enregistrés en donnant la version statique de la fonction de rappel :

<?php

$obj = new MyPlugin\Handlers();
elgg_register_event_handler('foo', 'bar', [$obj, 'handleFoo']);

// ... elsewhere

elgg_unregister_event_handler('foo', 'bar', 'MyPlugin\Handlers::handleFoo');

Même si le gestionnaire d’événement référence un appel à une méthode dynamique, le code ci-dessus va bien supprimer le gestionnaire.

Ordre d’appel des gestionnaires

Les gestionnaires sont d’abord appelés par ordre de priorité, puis par ordre d’enregistrement.

Note

Avant Elgg 2.0, l’enregistrement avec le mot-clef all provoquait un appel tardif des gestionnaires, même s’ils avaient été enregistrés avec des priorités plus faibles.

Internationalisation

Elgg 1.0 et supérieur diffèrent des versions précédentes dans le sens où ces versions utilisent un tableau de valeur texte personnalisé plutôt que gettext. Ceci améliore la performance du système et la fiabilité du système de traduction.

TODO : plus svp

AMD

Aperçu

Si vous souhaitez utiliser JavaScript dans Elgg : nous utilisons un système compatible AMD (Asynchronous Module Definition).

Ceci discute des bénéfices de l’utilisation d’AMD dans Elgg.

Pourquoi AMD ?

Nous avons beaucoup travaillé pour rendre le JavaScript de Elgg plus maintenable et plus utile. Nous avons fait quelques grands pas dans la version 1.8 en introduisant l’objet et la bibliothèque JavaScript « elgg », mais avons rapidement réalisé que l’approche que nous prenions n’était pas susceptible de passer à l’échelle.

La taille du JS sur le web augmente, et le JS dans Elgg s’accroît également. Nous voulons que Elgg soit capable d’offrir une solution qui rende le développement JS aussi productif et maintenable que possible pour aller plus loin.

Les raisons de choisir AMD sont nombreuses et bien documentées. Mettons en avant seulement les raisons les plus pertinentes dans la mesure où elles sont liées à Elgg spécifiquement.

1. Gestion des dépendances simplifiée

Les modules AMD se chargent de manière asynchrone et s’exécutent dès que leurs dépendances sont disponibles, ce qui élimine le besoin de préciser des « priorités » et des emplacements « location » lorsqu’on enregistre une bibliothèque JS dans Elgg. De plus, vous n’avez pas besoin de vous soucier de charger explicitement les dépendances d’un module dans PHP. Le chargeur AMD (RequireJS en l’occurrence) prend soin de tous ces tracas pour vous. Il est également possible d’avoir des dépendances texte avec le plugin text de RequireJS, de sorte que le templating côté client devrait être un plaisir.

2. AMD fonctionne dans tous les navigateurs. Dès maintenant.

Les développeurs Elgg ont déjà écrit beaucoup de JavaScript. Nous savons que vous voulez en écrire plus. Nous ne pouvons pas accepter d’attendre 5-10 ans pour qu’une solution native de modules JS soit disponible dans tous les navigateurs avant que nous puissions organiser notre JavaScript d’une manière maintenable.

3. Vous n’avez pas besoin d’une étape de build pour développer avec AMD.

Nous apprécions le cycle édition-mise à jour du web. Nous voulions faire en sorte que toute personne qui développe avec Elgg puisse continuer à expérimenter ce plaisir. Des formats de modules synchrones comme Closure ou CommonJS n’étaient tout simplement pas une option pour nous. Mais même si AMD n’a pas besoin d’une étape de build, il reste cependant très adapté pour le build. Grâce au wrapper define(), il est possible de concaténer de multiples modules dans un seul fichier et de livrer l’ensemble en une seule fois dans un environnement de production. 1

AMD est un système de chargement de modules largement éprouvé et bien pensé pour le web d’aujourd’hui. Nous avons beaucoup de gratitude pour le travail qui a été mis dedans, et sommes excités de l’offrir comme la solution standard pour le développement JavaScript dans Elgg depuis Elgg 1.9.

1

Ceci n’est pas encore supporté par le noyau de Elgg, mais nous sommes en train de nous pencher dessus dans la mesure où la réduction des allers-retours est critique pour une bonne première expérience, particulièrement sur les appareils mobiles.

Sécurité

L’approche de Elgg pour les diverses questions de sécurité communes à toutes les applications web.

Astuce

Pour signaler une vulnérabilité potentielle dans Elgg, envoyez un e-mail à security@elgg.org.

Mots de passe

Validation du mot de passe

La seule restriction que Elgg impose sur un mot de passe est qu’il doit contenir au moins 6 caractères par défaut, même si cela puisse être modifié dans /elgg-config/settings.php. Des critères supplémentaires peuvent être ajoutés par un plugin en s’enregistrant auprès de l’événement registeruser:validate:password.

Hachage du mot de passe

Les mots de passe ne sont jamais stockés en clair, seulement sous forme de valeur de hachage avec sel produit par bcrypt. Ceci est effectué via la fonction standard password_hash(). Sur des systèmes plus anciens, le polyfill password-compat est utilisé, mais l’algorithme est identique.

Les installations Elgg créées avant la version 1.10 peuvent avoir des chaînes de hachage de mot de passe « historiques » résiduelles créées en utilisant MD5 avec sel. Elles sont migrées vers bcrypt lorsque les utilisateurs se connectent, et sont totalement retirées lorsque le système est mis à niveau vers Elgg 3.0. Dans le même temps, nous sommes heureux d’inciter les propriétaires de sites à retirer manuellement ces chaînes de hachage historique, même si cela force ces utilisateurs à réinitialiser leur mot de passe.

Mitigation du mot de passe

Elgg a un mécanisme de mitigation des mots de passe qui rend les attaques par dictionnaire depuis l’extérieur très difficiles. Un utilisateur n’est autorisé qu’à 5 tentatives de connexion par période de 5 minutes.

Réinitialisation du mot de passe

Si un utilisateur oublie son mot de passe, la génération d’un nouveau mot de passe aléatoire peut être demandée. Après la demande, un e-mail est envoyé avec une URL unique. Quand l’utilisateur visite cette URL, un nouveau mot de passe est envoyé par e-mail à l’utilisateur.

Sessions

Elgg utilise la gestion des session PHP avec des gestionnaires personnalisés. Les données de sessions sont stockées dans la base de données. Le cookie de session contient l’id de session qui lie l’utilisateur au navigateur. Les métadonnées de l’utilisateur sont conservées dans la session, notamment le GUID, l’identfiant et l’adresse e-mail.

La durée de vie de la session est contrôlée par la configuration PHP du serveur, et additionnellement à travers les options dans le fichier /elgg-config/settings.php.

Fixation de session

Elgg protège contre la fixation de session en régénérant l’id de session lorsqu’un utilisateur se connecte.

Cookie « Se souvenir de moi »

Afin de permettre aux utilisateurs de rester identifiés pour une période plus longue, que le navigateur ait été fermé ou non, Elgg utilise un cookie (nommé par défaut elggperm) qui contient ce qui peut être considéré comme un super identifiant de session. Cet identifiant est conservé dans la table des cookies. Quand une session est initiée, Elgg vérifie la présence du cookie elggperm. S’il existe et que le code de session dans le cookie correspond au code dans la table des cookies, l’utilisateur correspondant est automatiquement connecté.

Lorsqu’un utilisateur change son mot de passe, tous les cookies permanents sont supprimés de la base de données.

La durée de vie des cookies persistants peut être contrôlée dans le fichier /elgg-config/settings.php. La durée de vie par défaut est de 30 jours. Les entrées de la base de données pour les cookies persistants seront supprimées après l’expiration de la durée de vie.

Authentification alternative

Note

Cette section est très lacunaire

Pour remplacer le système d’authentification par défaut des utilisateurs de Elgg, un plugin pourrait remplacer l’action par défaut login par sa propre action. Une meilleure alternative est d’enregistrer un gestionnaire d’authentification PAM en utilisant elgg_register_pam_handler() qui gère l’authentification des utilisateurs sur la base de nouvelles exigences.

HTTPS

Note

Vous devez activer le support de SSL sur votre serveur pour que chacune de ces techniques fonctionne.

Vous pouvez servir l’ensemble de votre site par SSL en changeant l’URL du site pour inclure « https » au lieu de seulement « http ».

XSS

Le filtrage est utilisé dans Elgg pour rendre les attaques XSS plus difficiles. L’objectif du filtrage est de supprimer les JavaScript et autres saisies dangereuses des utilisateurs.

Le filtrage est effectué via la fonction elgg_sanitize_input(). Cette fonction récupère une chaîne et renvoie une chaîne filtrée. Il déclenche un événement sanitize, input.

Par défaut Elgg est fourni avec le code de filtrage htmLawed. Les développeurs peuvent ajouter n’importe quel code additionnel ou de remplacement sous forme de plugin.

La fonction elgg_sanitize_input() est appelée pour chaque saisie utilisateur dès lors que la saisie est obtenue à travers un appel à get_input(). Si pour une raison quelconque un développeur souhaite ne pas appliquer le filtrage par défaut sur certaines saisies utilisateur, la fonction get_input() dispose d’un paramètre pour désactiver le filtrage.

CSRF / XSRF

Elgg génère des jetons de sécurité pour empêcher la contrefaçon de requêtes inter-sites. Ceux-ci sont intégrés dans tous les formulaires et les requêtes AJAX modificatrices d’état dès lors que la bonne API est utilisée. Lisez-en plus dans le guide de développement Formulaires + Actions.

URLs signées

Il est possible de protéger les URLs avec une signature unique. Lisez-en plus dans le Guide de développement Formulaires + Actions.

Injection SQL

L’API de Elgg’s assainit toutes les entrées avant d’effectuer des requêtes dans la base de données. Lisez-en plus dans la documentation de design Base de données.

Vie privée

Elgg utilise un système d’ACL pour contrôler quels utilisateurs ont accès aux divers éléments de contenu. Lisez-en plus dans la documentation du design de la base de données Base de données.

Sécurisation

Les administrateurs du site peuvent configurer des paramètres qui vont aider à sécuriser le site. Lisez-en plus dans le Guide d’administration Sécurité.

Loggable

Loggable est une interface héritée par toute classe qui veut que les événements liés à ses objets membres soient enregistrés dans le journal système. ElggEntity et ElggExtender héritent tous deux de Loggable.

Loggable définit plusieurs méthodes de classe qui sont utilisées pour l’enregistrement du journal système par défaut, et peuvent être utilisées pour définir vos propres journaux (ainsi que pour d’autres objectifs) :

• getSystemLogID() Retourne un identifiant unique pour l’objet à des fins de conservation dans le journal système. C’est généralement le GUID de l’objet

• getClassName() Retourne le nom de la classe de l’objet

• getType() Retourne le type d’objet

• getSubtype() Récupère le sous-type de l’objet

• getObjectFromID($id) Pour un ID donné, retourne l’objet qui lui est associé

Informations de la base de données

Le journal système par défaut est enregistré dans la table system_log de la base de données. Il contient les champs suivants :

• id - Un identifiant numérique unique de la ligne

• object_id - Le GUID de l’entité sur laquelle l’action est effectuée

• object_class - La classe de l’entité sur laquelle l’action est effectuée (par ex. ElggObject)

• object_type - Le type d’entité sur laquelle l’action est effectuée (par ex. object)

• object_subtype - Le sous-type d’entité sur laquelle l’action est effectuée (par ex. blog)

• event - L’événement enregistré (par ex. create ou update)

• performed_by_guid - Le GUID de l’entité agissante (l’utilisateur qui réalise l’action)

• owner_guid - Le GUID de l’utilisateur à qui appartient l’entité sur laquelle l’action est effectuée

• access_id - Le niveau d’accès associé avec cette entrée de journal

• time_created - Le timestamp UNIX de la date de l’événement

Guides du contributeur

Contribuez à rendre Elgg encore meilleur.

Elgg est un projet communautaire. Il dépend du soutien de volontaires pour réussir. Voici plusieurs manières d’aider :

Écrire du code

Comprenez les standards et processus de Elgg pour que vos propositions de modification soient acceptées aussi vite que possible.

Agrément de licence

En proposant un patch vous acceptez de publier le code sous une licence GPLv2 et une licence MIT.

Demandes de fusion - Pull Requests

Les Pull requests (PRs) sont le meilleur moyen de contribuer au noyau de Elgg. L’équipe de développement les utilise y compris pour les modifications les plus mineures.

Pour de nouvelles fonctionnalités, soumettez une demande de fonctionnalité ou parlez-en avec nous en premier lieu, et assurez-vous que l’équipe du noyau approuve votre proposition avant de passer beaucoup de temps sur du code.

Listes de vérification

Utilisez ces listes de vérification réduites pour les nouveaux PRs sur Github afin de garantir des contributions de haute qualité et d’aider tout le monde à comprendre le statut des PRs ouverts.

Demandes de correction de bug - bugfix PRs :

- [ ] Commit messages are in the standard format
- [ ] Includes regression test
- [ ] Includes documentation update (if applicable)
- [ ] Is submitted against the correct branch
- [ ] Has LGTM from at least one core developer

Demandes de fonctionnalité - feature PRs :

- [ ] Commit messages are in the standard format
- [ ] Includes tests
- [ ] Includes documentation
- [ ] Is submitted against the correct branch
- [ ] Has LGTM from at least two core developers

Choisir une branche vers laquelle publier

Le tableau suivant suppose que la dernière version stable est la 2.1.

Type de changement	Branche vers laquelle publier
Correctif de sécurité	Ne le faites pas ! Envoyez un e-mail à security@elgg.org pour des conseils.
Correctif de bug	1.12 (ou 2.1 si le correctif pour 1.12 est trop complexe)
Performance	2.x
Dépréciation	2.x
Fonctionnalité mineure	2.x
Fonctionnalité majeure	master - maître
Introduit un changement non rétro-compatible	master - maître

Si vous ne savez pas quelle branche choisir, demandez !

La différence entre des fonctionnalités mineures et majeures est subjective et soumise à l’appréciation de l’équipe du noyau.

Format du message de commit

Nous exigeons un format particulier afin de permettre de publier plus souvent, avec des journaux des modifications et un historique des modifications améliorés. Suivez simplement les étapes suivantes :

1. Commencez par le type en sélectionnant la dernière catégorie qui s’applique dans cette liste :

   • docs - uniquement la documentation a été mise à jour

   • chore - corvée - ceci comprend les remaniements, refactorisation de code, les changements de style de code, l’ajout de tests manquants, l’intégration continue, etc.

   • perf - l’objectif principal est d’améliorer la performance

   • fix - ceci corrige un bug

   • deprecate - la modification rend obsolète une partie de l’API

   • break - le changement casse n’importe une partie de l’API

   • feature - ajoute une nouvelle fonctionnalité pour les utilisateurs ou pour les développeurs

   • removed - cela supprime une fonctionnalité destinée aux utilisateurs ou aux développeurs

   • security - la modification affecte la sécurité d’une manière ou d’une autre. Merci de ne pas pousser ce commit vers un repository public. Contactez plutôt security@elgg.org.

   Par ex., si votre commit fait des remaniements pour corriger un bug, cela reste un « fix ». Cependant, si ce bug est lié à la sécurité, le type doit être « security » et vous devriez envoyer un e-mail à security@elgg.org avant de procéder. En cas de doute, faites au mieux, et un relecteur vous fournira des conseils.

2. Entre parenthèses, ajoutez le component, une courte chaîne qui décrit le sous-système en train d’être modifié.

   Quelques exemples : views, i18n, seo, a11y, cache, db, session, router, <plugin_name>.

3. Ajoutez une virgule, un espace, et un court résumé summary des modifications, qui va apparaître dans le journal des modifications - changelog.

   Aucune ligne ne devrait dépasser 100 caractères en longueur, aussi gardez un résumé concis.

   Bon résumé	Mauvais résumé (problème)
   les propriétaires de pages voient leur propre bloc propriétaire sur les pages	correction de bug (vague)
   la vue du graphique en barres n’échoue plus si “foo” n’est pas défini	met à jour views/default/bar.php de sorte que la vue bar ne soit plus… (info redondante)
   réduit la mise en page de la rivière pour rentrer sur un iPhone	modifie la mise en page de la rivière (vague)
   elgg_foo() gère les tableaux pour $bar	dans elgg_foo() vous pouvez maintenant passer un tableau pour $bar et la fonction sera… (déplacez les précisions vers la description)
   supprime la couleur du lien de l’entête des commentaires dans la rivière	corrige la bdd pour que… (info redondante)
   requiert un titre non-vide pour enregistrer les pages	peut enregistrer des pages sans titre (résume de manière confuse l’ancien comportement)

4. (recommandé) Sautez une ligne et ajoutez une description des modifications. Incluez leur raison d’être, toute information sur la compatibilité ascendante ou descendante, et toute raison pour laquelle cette modification devait être faite d’une certaine manière. Par exemple :

   Nous accélérons la migration des tables en utilisant une seule requête INSERT INTO … SELECT au lieu de ligne par ligne. Cette migration se produit durant la mise à niveau vers Elgg 1.9.

   A moins que votre modification soit triviale/évidente, une description est requise.

5. Si le commit correspond à une demande - « issue » - Github, sautez une ligne et ajoutez Fixes # suivi par le numéro de demande. Par ex. Fixes #1234. Vous pouvez inclure de multiples demande en les séparant par des virgules.

   GitHub va fermer automatiquement la demande quand le commit est fusionné. Si vous souhaitez simplement faire référence à une demande, utilisez plutôt Refs #.

Quand c’est terminé, votre message de commit aura le format :

type(component): summary

Optional body
Details about the solution.
Opportunity to call out as breaking change.

Closes/Fixes/Refs #123, #456, #789

Voici un exemple de bon message de commit :

perf(upgrade): speeds up migrating remember me codes

We speed up the Remember Me table migration by using a single INSERT INTO ... SELECT query instead of row-by-row.
This migration takes place during the upgrade to 1.9.

Fixes #6204

Réécrire des messages de commits

Si votre PR ne se conforme pas au format standard de message de commit, nous vous demanderons de le réécrire.

Pour modifier seulement le dernier commit :

1. Amendez le commit: git commit --amend (git ouvre le message dans un éditeur de texte).

2. Changez le message et enregistrez/quittez l’éditeur.

3. Forcez l’envoi de votre branche : git push -f your_remote your_branch (votre PR sera mis à jour).

4. Renommez le titre du PR pour correspondre

Sinon vous pourrez avoir besoin d’effectuer un « rebase » interactif :

1. Faites un rebase des derniers N commits: git rebase -i HEAD~N où N est le nombre. (Git va ouvrir le fichier git-rebase-todo pour modification)

2. Pour les commits qui ont besoin d’être modifiés, modifiez pick en r (pour « reword », reformulation) et enregistrez/quittez l’éditeur.

3. Modifiez le message (ou les messages) de commit, enregistrez/quitter l’éditeur (git va présenter un fichier pour chaque commit qui a besoin d’une reformulation).

4. git push -f your_remote your_branch pour forcer un push de la branche (ce qui met à jour votre PR).

5. Renommez le titre du PR pour correspondre

Standards de développements

Elgg utilise un ensemble de normes basées en partie sur les normes PEAR et PSR2. Vous pouvez voir le jeu de règles dans vendor/elgg/sniffs/src/Elgg/ruleset.xml.

Pour vérifier les violations des standards de votre code (à condition que vous ayez installé Elgg avec les dépendances dev), exécutez :

phpcs --standard=vendor/elgg/sniffs/src/Elgg -s path/to/dir/to/check

Pour corriger automatiquement des violations réparables, exécutez :

phpcbf --standard=vendor/elgg/sniffs/src/Elgg path/to/dir/to/fix

Tester

Elgg dispose de tests automatisés à la fois pour PHP et JavaScript. Toutes les nouvelles contributions doivent intégrer les tests appropriés.

Voir aussi

Écrire des tests

Recommandations générales

Découpez les tests par comportements que vous souhaitez tester et utilisez des noms qui décrivent le comportement. Par ex. :

• Pas si bon : Une seule grosse méthode testAdd().

• Mieux : Des méthodes testAddingZeroChangesNothing et testAddingNegativeNumberSubtracts

Efforcez-vous d’utiliser des designs à base de composants qui permettent de tester en isolement, sans de grands graphes de dépendances ou d’accès à la base de données. L’injection de dépendances est ici critique.

Tests PHP

PHPUnit

Située dans engine/tests/phpunit, c’est notre suite de tests préférée. Elle n’utilise pas d’accès à la base de données, et n’a qu’un accès superficiel à l’API des entités.

• Si possible, nous vous encourageons à créer des composants qui sont testables dans cette suite.

• Envisagez de séparer le stockage de votre composant de sorte que la logique métier puisse être testée ici.

• Dépendez des classes Elgg\Filesystem\* plutôt que d’utiliser les fonctions du système de fichiers PHP.

Tester les interactions entre services

Dans l’idéal, vos tests devraient construire vos propres graphes d’objet isolés pour des manipulations directes, mais ce n’est pas toujours possible.

Si votre test dépend des Services Internes de Elgg (_elgg_services() qui renvoie un Elgg\Di\InternalContainer), réalisez que cela maintient une instance singleton pour la plupart des services qu’il fournit, et que de nombreux services conservent également leurs propres références locales vers ces services.

Du fait de ces références locales, replacer les services sur le SP = « Service Provider » - Fournisseur de Service - au sein d’un test n’aura souvent pas l’effet désiré. Au lieu de cela, vous pourriez avoir besoin d’utiliser la fonctionnalité disponible dans les services eux-mêmes :

• Le service events a des méthodes backup() et restore().

• Le service logger a des méthodes disable() et enable().

Tests Jasmine

Les fichiers de test doivent être nommés *Test.js et devraient être placés soit dans js/tests/ ou à côté de leurs fichiers sources dans views/default/**.js. Karma va automatiquement sélectionner les nouveaux fichiers *Test.js et exécuter ces tests.

Test générique

define(['elgg'], function(elgg) {
        describe("This new test", function() {
                it("fails automatically", function() {
                        expect(true).toBe(false);
                });
        });
});

Effectuer les tests

Elgg utilise Karma avec Jasmine pour effectuer des tests unitaires JS.

Vous devez avoir nodejs et yarn installés.

Tout d’abord installez toute les dépendances de développement :

yarn

Exécutez les tests une seule fois puis quittez :

yarn test

Vous pouvez également exécuter les tests en continu pendant le développement de sorte qu’ils s’exécutent à chaque enregistrement :

karma start js/tests/karma.conf.js

Déboguer les tests JS

Vous pouvez exécuter la suite de test au sein des outils de développement de Chrome :

yarn run chrome

Ceci va renvoyer une URL telle que http://localhost:9876/.

1. Ouvrez l’URL dans Chrome, et cliquez sur « Debug ».

2. Ouvrez les outils de développement de Chrome et l’onglet Console.

3. Rechargez la page.

Si vous modifiez un test, vous devrez quitter Karma avec Ctrl-c et le redémarrer.

Meilleures pratiques de développement

Rendez votre code plus facile à lire, plus facile à maintenir, et plus facile à déboguer. Un usage consistant de ces recommandations signifie moins de travail de devinettes pour les développeurs, ce qui signifie des développeurs plus heureux, et plus productifs.

Développement en général

Ne. Vous. Répétez. Pas

Si vous copiez-collez des morceaux significatifs de code, considérez qu’il y a une opportunité de réduire la redondance en introduisant une fonction, un argument supplémentaire, une vue, ou une nouvelle classe de composant.

Par ex. Si vous trouvez des vues qui sont identiques à l’exception d’une seule valeur, remaniez-les en une seule vue qui accepte une option.

Note: Pour la publication d’un correctif de bug, un peu de duplication est préférable à de la refactorisation. Corrigez les bugs de la manière la plus simple possible, et refactorisez pour réduire la redondance dans la branche de la prochaine version mineure.

Adoptez SOLID et GRASP

Utilisez ces principes pour le design OO pour résoudre des problèmes en utilisant des composants couplés librement, et essayez de rendre tous les composants et le code d’intégration testables.

Les espacements ne coûtent rien

N’ayez pas peur d’utiliser des blocs de code séparés. Utilisez un espace unique pour séparer les paramètres des fonctions et les concaténations de chaînes.

Noms de variable

Utilisez des noms de variables auto-documentés. $group_guids est mieux que $array.

Évitez les doubles négations. Préférez $enable = true à $disable = false.

Nom des interfaces

Utilisez le motif Elgg\{Namespace}\{Name}.

N’ajoutez pas de préfixe I ou de suffixe Interface.

Nous n’utilisons aucun préfixe ou suffixe de sorte que nous sommes encouragés à :

• nommez les classes d’implémentation de manière plus descriptive (le nom « default » est déjà pris).

• typez sur les interfaces, parce que c’est la manière la plus courte et la plus simple de faire.

Nommez les implémentations comme Elgg\{Namespace}\{Interface}\{Implementation}.

Fonctions

Autant que possible, ayez des fonctions/méthodes qui renvoient un type unique. Utilisez des valeurs vides telle que array(), "", ou 0 pour indiquer l’absence de résultat.

Faites attention aux cas où des valeurs de retour valides (telles que "0") pourraient être interprétées comme vides.

Les fonctions qui ne déclenchent pas une exception lors d’une erreur devraient retourner false lorsqu’elles échouent.

Note

Les fonctions/méthodes d’un particulièrement bas niveau, non API, qui ne devraient pas échouer dans des conditions normales, devraient lancer une exception au lieu de renvoyer false.

Les fonctions qui ne renvoient qu’un booléen devraient être préfixées par is_ ou has_ (par ex., elgg_is_logged_in(), elgg_has_access_to_entity()).

Syntaxe ternaire

Acceptable seulement pour des déclarations sur une seule ligne, non imbriquées.

Minimisez la complexité

Minimisez les blocs imbriqués et les chemins d’exécution distincts au sein du code. Faites un Retour rapide pour réduire les niveaux imbriqués et la charge cognitive lors de la lecture du code.

Utilisez les commentaires à bon escient

Les bons commentaires décrivent le « pourquoi. » Le bon code décrit le « comment. » Par ex. :

Mauvais :

// increment $i only when the entity is marked as active.
foreach ($entities as $entity) {
        if ($entity->active) {
                $i++;
        }
}

Bon :

// find the next index for inserting a new active entity.
foreach ($entities as $entity) {
        if ($entity->active) {
                $i++;
        }
}

Ajoutez toujours un commentaire s’il n’est pas évident que quelque chose doit être fait d’une certaine manière. D’autres développeurs qui regardent le code devraient être découragés de réorganiser le code d’une manière qui le casserait.

// Can't use empty()/boolean: "0" is a valid value
if (elgg_is_empty($str)) {
    throw new \Elgg\Exceptions\Http\BadRequestException(elgg_echo('foo:string_cannot_be_empty'));
}

Commitez de manière efficace

• Péchez par excès de commits atomiques qui sont précisément ciblés sur la modification d’un seul aspect du système.

• Évitez de mélanger des modifications qui ne sont pas liées ou des modifications importantes des espaces. Les commits avec de nombreux changements sont effrayants et rendent les demandes de fusion - Pull Requests - difficiles à évaluer.

• Utilisez des outils git visuels pour façonner des diffs extrêmement précis et lisibles.

Incluez des tests

A chaque fois que c’est possible, incluez des tests unitaires pour le code que vous ajoutez ou modifiez.

Conservez des corrections simples des bugs

Évitez la tentation de refactoriser le code pour la publication d’une correction de bug. Faire cela a tendance à introduire des régressions, à casser la fonctionnalité dans ce qui devrait être une version stable.

Recommandations PHP

Voici les standards de développement requis pour le noyau de Elgg et pour tous les plugins inclus. Les développeurs de plugins sont fortement encouragés à adopter ces standards.

Les développeurs devraient lire en premier le Guide des Standards de Développement PSR-2.

Les standards de Elgg étendent PSR-2, mais diffèrent des manières suivantes :

• Indentez en utilisant le caractère tabulation, pas des espaces.

• Les parenthèses ouvrantes pour les classes, méthodes, et fonctions doivent être sur la même ligne.

• Si une ligne dépasse 100 caractères, envisagez de la remanier (par ex. en introduisant des variables).

• La compatibilité avec PSR-1 est encouragée, mais pas strictement requise.

Documentation

• Incluez des commentaires PHPDoc sur les fonctions et les classes (toutes les méthodes ; et les propriétés déclarées quand c’est approprié), y compris les types et descriptions de tous les paramètres.

• Dans les listes de déclarations @param, le début des noms de variables et des descriptions doivent être alignés.

• Annotez les classes, les méthodes, les propriétés et les fonctions avec @internal à moins qu’elles ne soient destinées au public, qu’elles ne soient déjà d’une visibilité limitée ou qu’elles ne soient dans une classe déjà marquée comme @internal.

• Utilisez // ou /* */ pour les commentaires.

• Utilisez seulement les commentaires // à l’intérieur du corps des fonctions et méthodes.

Règles de nommage

• Utilisez des traits de soulignements - « underscores » - pour séparer les mots dans les noms de fonctions, de variables, et les propriétés. Les noms de méthodes utilisent la syntaxe camelCase.

• Les noms de fonctions pour un usage public doivent commencer par elgg_.

• Tous les autres noms de fonctions doivent commencer par _elgg_.

• Nommez les globales et les constantes en MAJUSCULE (ACCESS_PUBLIC, $CONFIG).

Divers

Pour les pré-requis PHP, voyez composer.json.

N’utilisez pas les balises PHP raccourcies <? ou <%. Il est possible d’utiliser <?= dans la mesure où cela est toujours activé à partir de PHP 5.4.

Quand vous créez des chaînes de caractères avec des variables :

• utilisez des chaînes de caractères avec des guillemets doubles

• enveloppez les variables avec des accolades

Mauvais (difficile à lire) :

echo 'Hello, '.$name."!  How is your {$time_of_day}?";

Bon :

echo "Hello, {$name}!  How is your {$time_of_day}?";

Retirez les espaces vides à la fin des lignes.

Validation de la valeur

Quand vous travaillez avec des saisies utilisateur, préparez les saisies en dehors de la méthode de validation.

Mauvais :

function validate_email($email) {
        $email = trim($email);

        // validate
}

$email = get_input($email);

if (validate_email($email)) {
        // the validated email value is now out of sync with an actual input
}

Bon :

function validate_email($email) {
        // validate
}

$email = get_input($email);
$email = trim($email);

if (validate_email($email)) {
        // green light
}

Utilisez les exceptions

N’ayez pas peur d’utiliser les exceptions. Elles sont plus faciles à gérer que des sorties de fonction mixtes :

Mauvais :

/**
* @return string|bool
*/
function validate_email($email) {
        if (empty($email)) {
                return 'Email is empty';
        }

        // validate

        return true;
}

Bon :

/**
* @return void
* @throws \Elgg\Exceptions\InvalidArgumentException
*/
function validate_email($email) {
        if (empty($email)) {
                throw new \Elgg\Exceptions\InvalidArgumentException('Email is empty');
        }

        // validate and throw if invalid
}

Documentez les valeurs de retour

N’utilisez pas @return void sur des méthodes qui renvoient une valeur ou null.

Mauvais :

/**
* @return bool|void
*/
function validate_email($email) {
        if (empty($email)) {
                return;
        }

        // validate

        return true;
}

Bon :

/**
* @return bool|null
*/
function validate_email($email) {
        if (empty($email)) {
                return null;
        }

        // validate

        return true;
}

Recommandations CSS

Enregistrez le CSS dans des fichiers avec une extension .css.

Utilisez des abréviations quand c’est possible

Mauvais :

background-color: #333333;
background-image:  url(...);
background-repeat:  repeat-x;
background-position:  left 10px;
padding: 2px 9px 2px 9px;

Bon :

background: #333 url(...) repeat-x left 10px;
padding: 2px 9px;

Utilisez les traits d’union « - », pas les tirets de soulignement ou underscores « _ »

Mauvais :

.example_class {}

Bon :

.example-class {}

Note

Vous devriez préfixer vos identifiants et noms de classe avec un texte qui identifie votre plugin.

Une propriété par ligne

Mauvais :

color: white;font-size: smaller;

Bon :

color: white;
font-size: smaller;

Déclarations de propriété

Celles-ci devraient être espacées comme ceci : propriété: valeur;

Mauvais :

color:value;
color :value;
color : value;

Bon :

color: value;

Préfixes fournisseurs - vendor

• Regroupez les préfixes fournisseurs pour la même propriété

• La version la plus longue des préfixes fournisseurs en premier

• Incluez toujours la version sans préfixe fournisseur

• Ajoutez une ligne supplémentaire entre les groupes avec préfixes fournisseurs et les autres propriétés

Mauvais :

-moz-border-radius: 5px;
border: 1px solid #999999;
-webkit-border-radius: 5px;
width: auto;

Bon :

border: 1px solid #999999;

-webkit-border-radius: 5px;
-moz-border-radius: 5px;
border-radius: 5px;

width: auto;

Regroupez les sous-propriétés

Mauvais :

background-color: white;
color: #0054A7;
background-position: 2px -257px;

Bon :

background-color: white;
background-position: 2px -257px;
color: #0054A7;

Recommandations JavaScript

Les mêmes standards de formatage que PHP s’appliquent.

Les fonctions correspondantes devraient être dans un module AMD avec un espace de nom.

Les expressions d’une fonction devraient se terminer par un point-virgule.

define(['elgg'], function(elgg) {
        function toggles(event) {
                event.preventDefault();
                $(target).slideToggle('medium');
        };
});

APIs obsolètes

De temps en temps, des fonctions et des classes doivent être dépréciées au profit de nouveaux remplacements. Dans la mesure où les auteurs de plugins tierce-partie s’appuient sur une API cohérente, la compatibilité ascendante doit être maintenue, mais ne sera pas maintenue indéfiniment dans la mesure où les auteurs de plugins sont supposés mettre à jour leurs plugins. Afin de maintenir la compatibilité ascendante, les API obsolètes vont suivre les recommandations suivantes :

• Les versions mineures (1.x) qui déprécient une API doivent inclure une fonction/classe d’emballage « wrapper » (ou tout autre moyen approprié) qui maintient la compatibilité ascendante, y compris tout bug de la fonction/classe originelle. Cette couche de compatibilité utilise elgg_deprecated_notice('...', '1.11') pour journaliser le fait que cette fonction est obsolète.

• La révision majeure suivante (2.0) supprime la couche de compatibilité. Toute utilisation de l’API obsolète devrait être corrigé auparavant.

Base de données

Contribuer aux modifications du schéma de la base de données

Migrations de la base de données

Elgg utilise Phinx pour gérer les migrations de la base de données.

Créer une migration

Pour créer une nouvelle migration, exécutez ce qui suit dans votre console :

vendor/bin/phinx create -c engine/schema/migrations.php MigrationClassName

Ceci va générer un squelette de migration horodaté dans engine/schema/migrations/. Suivez la documentation de Phinx pour appeler les méthodes nécessaires pour modifier les tables de la base de données.

Exécuter une migration

Les migrations sont exécutées à chaque fois que vous exécutez upgrade.php. Si vous préférez exécuter les migrations manuellement, vous pouvez le faire via la ligne de commande :

// When Elgg is the root project
vendor/bin/phinx migrate -c engine/schema/migrations.php

// When Elgg is installed as a Composer dependency
vendor/bin/phinx migrate -c vendor/elgg/elgg/engine/schema/migrations.php

Vérifiez la documentation Phinx pour des drapeaux additionnels qui vous autorisent à effectuer une seule migration ou un jeu de migrations dans un intervalle de temps.

Contribuer à la Documentation

La nouvelle documentation devrait s’intégrer correctement avec le reste de la documentation de Elgg.

Tester les documentations localement

Elgg dispose d’un script grunt qui construit automatiquement les docs, les ouvre dans une fenêtre de navigateur, et les recharge automatiquement pendant que vous faites des modifications (le rechargement ne prend que quelques secondes). Vous aurez besoin d’avoir yarn et sphinx installés pour pouvoir utiliser ces scripts.

cd path/to/elgg/
yarn
grunt

C’est aussi simple que cela ! Grunt va continuer à s’exécuter, à vérifier les docs pour des modifications, et à reconstruire automatiquement.

Note

Vous devrez peut-être installer “sphinxcontrib-phpdomain”. Vous pouvez le faire avec la commande suivante : pip install -U sphinxcontrib-phpdomain

Suivez l’organisation du document existant

L’organisation actuelle n’est pas nécessairement La Vraie Manière d’organiser les documentations, mais la cohérence est mieux que l’aléatoire.

intro/*

C’est tout ce que les tout nouveaux utilisateurs ont besoin de savoir (installation, fonctionnalités, licence, etc.)

admin/*

Guides pour les administrateurs. Orienté tâches.

guides/*

Guides de l’API pour les développeurs de plugins. Style recette de cuisine. Exemples solides. Éléments de code solides. Découpé par services (actions, i18n, routage, base de données, etc.). Ceci ne devrait discuter que de l’API publique et de son comportement, pas des détails d’implémentation ou de raisonnement.

design/*

Documentation de conception -design docs- pour les personnes qui veulent avoir une meilleure compréhension de comment/pourquoi le noyau est construit de cette manière. Ceci devrait discuter des détails d’implémentation internes des divers services, de quels compromis ont été faits, et du raisonnement derrière la décision finale. Devrait être utile aux personnes qui veulent contribuer ou pour la communication entre les développeurs du noyau.

contribute/*

Guides des contributeurs pour les diverses manières dont des personnes peuvent participer au sein du projet.

appendix/*

Des informations plus détaillées/méta/de contexte à propos du projet (historique, feuille de route, etc.)

Utilisez « Elgg » d’une manière grammaticalement correcte

Elgg n’est pas un acronyme, l’écrire en majuscules (ELGG ou E-LGG) est incorrect. Veuillez ne pas le faire.

En Français, Elgg ne prend pas d’article quand il est utilisé comme un nom. Voici quelques exemples à imiter :

• “J’utilise Elgg pour mon site web”

• “Installez Elgg pour mettre votre communauté en ligne”

Quand il est utilisé comme adjectif, l’article s’applique au nom principal, aussi vous devriez en utiliser un. Par exemple :

• « Allez sur le site de la communauté Elgg pour trouver de l’aide. »

• « Hier, j’ai construis un réseau avec Elgg »

Ce conseil peut ne pas être valable pour d’autres langues que l’anglais.

Évitez les pronoms à la première personne

Faites référence au lecteur comme « vous ». Ne vous incluez pas dans la narration habituelle.

Avant :

Quand nous aurons terminé l’installation de Elgg, nous irons rechercher quelques plugins !

Après :

Quand vous aurez terminé l’installation de Elgg, recherchez quelques plugins !

Pour faire référence à vous-même (à éviter si possible), utilisez votre nom et écrivez à la troisième personne. Ceci permet aux futurs lecteurs/éditeurs de savoir de qui les opinions sont exprimées.

Avant :

Je pense que le meilleur moyen pour faire X est d’utiliser Y.

Après :

Evan pense que le meilleur moyen pour faire X est d’utiliser Y.

Éliminer le superflu

Avant :

Si vous souhaitez utiliser une bibliothèque javascript tierce dans le framework Elgg, vous devez prendre soin d’appeler la fonction elgg_register_external_file pour l’enregistrer.

Après :

Pour utiliser une bibliothèque javascript tierce-partie, appelez elgg_register_external_file pour l’enregistrer.

Préférez les dates absolues aux dates relatives

Il est difficile de dire quand une phrase ou un paragraphe particuliers ont été écrits, aussi les dates relatives deviennent vite incompréhensibles. Les dates absolues donnent également au lecteur une bonne indication de si un projet a été abandonné, ou si un conseil est toujours d’actualité.

Avant :

Récemment le truc a été machin. Bientôt, la chose sera machin aussi.

Après :

Récemment (à partir de septembre 2013), le truc a été machin. Il est prévu que la chose soit également machin d’ici octobre 2013.

Ne rappelez pas au lecteur de contribuer

Concentrez-vous pour ne traiter que du sujet en question. Des sollicitations constantes pour du travail gratuit sont agaçantes et donnent l’impression que le projet est dans le besoin. Si des personnes souhaitent contribuer au projet, elles peuvent visiter le guide du contributeur.

Internationaliser la documentation

Quand vous modifiez la documentation, pensez à mettre à jour les modèles de traduction de la documentation avant de faire un commit :

cd docs/
make gettext

Pour plus d’information, voyez https://www.sphinx-doc.org/fr/master/usage/advanced/intl.html#translating-with-sphinx-intl

Points d’attention spécifiques

Quand vous traduisez la documentation soyez conscients de la syntaxe spécifique dans les fichiers de documentation.

Liens de traduction

• Traduisez le texte dans des liens anonymes (par ex., `prononciation`__), mais maintenez l’ordre de tous les liens anonymes dans un bloc unique. S’il y a deux liens anonymes à traduire dans un seul bloc de traduction, il ne doivent pas être inversés l’un par rapport à l’autre.

• Traduisez le texte des liens nommés (par ex., `site de démo`_) mais seulement si vous maintenez le noms en utilisant la bonne syntaxe rST. Dans ce cas ce devrait être `traduction de "site de démo" <demo site_>`_.

NE traduisez PAS

• Tout ce qui se situe entre des caractères trait vertical ne devrait pas être traduit (par ex., master).

• Le code, à moins que ce soit un commentaire dans le code.

Traductions

Les traductions démultiplient l’impact que Elgg peut avoir en le rendant accessible à un plus grand pourcentage du monde.

La communauté sera toujours reconnaissante à ceux qui travaillent dur pour fournir des traductions de haute qualité pour l’UI et la documentation de Elgg.

Transifex

Toutes les traductions pour le projet Elgg sont gérées avec Transifex.

https://www.transifex.com/organization/elgg

Les auteurs de plugins sont encouragés à coordonner les traductions via Transifex également, de sorte que la communauté entière puisse être unie, et que cela facilite la possibilité pour les traducteurs de contribuer à la traduction de n’importe quel plugin dans l’écosystème Elgg.

Récupérez les traductions

Les traductions faites dans Transifex ont besoin d’être récupérées périodiquement dans le dépôt de code de Elgg. Ceci peut être effectué avec le script .scripts/languages.php inclus dans le code source de Elgg.

Les pré-requis pour exécuter le script sont :

• Accès à la ligne de commande

• Git

• Transifex CLI tool

Le script va effectuer les étapes suivantes :

1. Créez une nouvelle branche git nommée {branch}_i18n_{timestamp}

2. Récupérez les traductions pour toutes les langues qui ont au moins 95% des chaînes traduites

3. Retirez les éventuels codes de langue invalides

4. Commitez les modifications vers la branche

Après cela, faites un push de la branche vers Github et faites une nouvelle Pull Request.

Par exemple, si vous voulez récupérer les traductions pour la branche 3.x, exécutez les commandes suivantes :

php .scripts/languages.php 3.x
git push -u your_fork 3.x_i18n_1515151617

Exécutez la commande sans paramètre pour obtenir des informations plus détaillées sur son utilisation.

Configuration Transifex

La configuration pour Transifex se trouve dans le code source de Elgg dans le fichier .tx/config.

Ce fichier définit :

• Le projet Transifex associé avec la version majeure de Elgg

• L’emplacement des tous les fichiers qui ont du contenu traduisible

Lisez la documentation Transifex pour plus d’information.

Nouvelle version majeure de Elgg

Chaque version majeure de Elgg doit disposer de son propre projet dans Transifex. De cette manière nous pouvons nous assurer que les chaînes ajoutées et retirées entre les versions ne créent pas de conflit les unes avec les autres. Par exemple une clef de traduction retirée dans Elgg 4 ne devrait pas être retirée des traductions faites pour Elgg 3. De même, une nouvelle chaîne ajoutée seulement pour Elgg 4 ne devrait pas être incluses dans les traductions prévues pour Elgg 3.

Le processus pour mettre en place une nouvelle version majeure est le suivant :

1. Récupérez les dernières traductions depuis Transifex vers la précédente version majeure

2. Fusionnez la branche git de la version précédente vers la nouvelle afin de s’assurer que toutes les dernières clefs de traduction sont présentes

3. Créez un nouveau projet Transifex sur https://app.transifex.com/elgg/

4. Mettez à jour le fichier .tx/config dans la branche de développement de la nouvelle version majeure

   • Mettez à jour la configuration pour pointer vers le nouveau projet Transifex

   • Retirez la configuration des plugins retirés

   • Ajoutez la configuration des nouveaux plugins

5. Poussez les sources de traduction vers le nouveau projet Transifex avec la commande :

   tx push -s
   

6. Copiez le nouveau fichier de configuration temporairement (sans commit) vers la version majeure précédente, et poussez les traductions existantes depuis là vers le nouveau projet :

   tx push -t -f --no-interactive
   

Plus tard, une fois que la branche dédiée (par exemple 3.x) a été créée pour la version majeure, configurez Transifex pour qu’il y récupère automatiquement les nouvelles clés de traduction depuis https://app.transifex.com/elgg/elgg-core- 3/content/. De cette façon, vous n’avez pas à répéter manuellement l’étape 5 chaque fois que de nouvelles clés de traduction sont ajoutées.

Il est important de toujours avoir une branche n.x en plus des branches créées pour des versions mineures spécifiques (n.1, n.2, etc.). De cette manière les URLs des sources automatiquement mises à jour n’ont pas besoin d’être mises à jour à chaque fois qu’une nouvelle branche mineure est créée.

Signaler des problèmes

Signalez bugs et demandes de fonctionnalités sur https://github.com/Elgg/Elgg/issues. Voyez ci-dessous pour des recommandations.

LIMITES DE RESPONSABILITÉ

Attention

Les problèmes de sécurité devraient être signalés à security @ elgg . org ! Merci de ne publier aucun faille de sécurité sur github !!

Note

Les demandes d’aide relèvent du site de la communauté. Les tickets avec des demandes d’aide seront fermés.

Important

Nous ne pouvons donner aucune garantie sur la date à laquelle votre ticket sera résolu.

Rapports de bugs

Avant de soumettre un rapport de bug :

• Recherchez un ticket existant à propos du problème que vous rencontrez. Ajoutez toute information supplémentaire à cet endroit.

• Vérifiez que le problème est reproductible

  • Sur la dernière version de Elgg

  • Avec tous les plugins tierce-partie désactivés

Liste de contrôle pour un bon signalement de bug :

• Comportement attendu et comportement constaté

• Des étapes claires pour reproduire le problème

• La version de Elgg que vous utilisez

• Les navigateurs affectés par ce problème

Demandes de fonctionnalité

Avant de soumettre une demande de fonctionnalité :

• Vérifiez sur le site de la communauté si un plugin existe avec les fonctionnalités dont vous avez besoin.

• Envisagez si vous le pouvez de développer un plugin qui fasse ce dont vous avez besoin.

• Recherchez parmi les tickets fermés pour voir si quelqu’un d’autre a suggéré la même fonctionnalité, mais que cela a été refusé. Vous devez pouvoir expliquer pourquoi votre suggestion devrait être examinée cette fois-ci.

Liste de contrôle pour une bonne demande de fonctionnalité :

• Explication détaillée de la fonctionnalité

• Cas d’usages réels

• API proposée

Devenir un soutien financier

Tous les fonds recueillis par l’intermédiaire du réseau de supporters Elgg vont directement pour :

• Développement du noyau Elgg

• La fourniture d’infrastructures (elgg.org, github, etc)

Il s’agit d’un excellent moyen d’aider au développement de Elgg !

Avantages

Pour seulement $50 par an pour les individus, ou $150 par an pour les organisations, vous pouvez être listé comme soutien sur notre page des soutiens. Les soutiens de Elgg apparaissent dans cette liste sauf s’ils demandent à ne pas l’être.

Les soutiens ont l’autorisation d’ajouter ce logo officiel sur leur site s’ils le souhaitent :

Limite de responsabilité

Nous avons une politique de non-remboursement sur les souscriptions de soutien. Si vous souhaitez arrêter votre soutien, allez sur Paypal et annulez votre souscription. Vous ne serez pas débité l’année suivante.

Être un soutien de Elgg ne donne en aucun cas le droit à un individu ou à une organisation le droit de parler au nom du projet Elgg, de commercialiser en son nom, ou de laisser entendre qu’ils sont liés au projet Elgg. Ils peuvent toutefois mentionner le fait qu’ils sont soutien du projet Elgg.

Si vous avez des questions à propos de cet avertissement, écrivez à info@elgg.org.

Nous nous réservons le droit de retirer ou refuser une souscription sans avertissement préalable à notre entière discrétion. Il n’y a pas de politique de remboursement.

S’il n’y a pas d’utilisation évidente de Elgg, votre site sera relié avec l’attribut « nofollow ».

S’inscrire

Si vous souhaitez devenir un sponsor de Elgg:

• lisez l”avertissement ci-dessus

• sur la page des soutiens, souscrivez via Paypal

• envoyez un e-mail à info@elgg.org avec :

  • la date de votre souscription

  • votre nom (et le nom de l’organisation, s’il y a lieu)

  • votre site web

  • votre profil sur la communauté Elgg

Une fois que tous les détails ont été reçus, nous vous ajouterons à la liste appropriée. Merci pour votre soutien !

Ajouter un Service à Elgg

Le guide sur les services présente des informations générales sur l’utilisation des services Elgg.

Pour ajouter un nouvel objet de service à Elgg :

1. Annotez votre classe comme @internal s’il s’agit d’un service interne.

2. Ouvrez la classe Elgg\Di\InternalContainer et/ou Elgg\Di\PublicContainer.

3. Ajoutez une annotation @property-read au début de votre service. Cela permet aux IDE et aux analyseurs de code statique de comprendre le type de la propriété lors de l’utilisation de _elgg_services() ou elgg().

4. Enregistrez votre service dans engine\internal_services.php ou engine\public_services.php en utilisant le câblage automatique - autowiring- ou avec une usine - factory.

Injectez vos dépendances

Elgg utilise PHP-DI pour l’enregistrement et la résolution des services. Les dépendances peuvent être câblées automatiquement (en fonction de l’argument typé du constructeur, les services peuvent être injectés) ou un service peut être construit dans une usine.

Note

Pour plus d’informations sur PHP-DI, visitez leur site Web.

Faire qu’un service fasse partie de l’API publique

Si votre service est conçu pour être utilisé par des développeurs de plugins :

1. Faites une interface Elgg\Services\<Name> qui ne contient que ces méthodes nécessaires dans l’API publique.

2. Faites que la classe de votre service implémente cette interface.

3. Pour les méthodes qui sont dans l’interface, déplacez la documentation dans l’interface. Vous pouvez simplement utiliser {@inheritdoc} dans les PHPDocs des méthodes de votre classe.

4. Documentez votre service dans docs/guides/services.rst (ce fichier)

5. Ouvrez le test PHPUnit Elgg\ApplicationTest et ajoutez la clef de votre service au tableau $names dans testServices().

6. Ouvrez la classe Elgg\Application.

7. Ajoutez une déclaration @property-read pour documenter votre service, mais utilisez votre interface pour le type, et pas le nom de la classe de votre service.

Désormais votre service sera disponible via l’accès à la propriété sur l’instance Elgg\Application :

// using the public foo service
$three = elgg()->foo->add(1, 2);

Note

Pour des exemples, voyez le service config, qui comprend l’interface Elgg\Services\Config et la classe d’implémentation effective Elgg\Config.

Cycle de vie d’un Service et Fabriques - « Factories »

Par défaut, les services enregistrés sur le fournisseur de service sont partagés - « shared », ce qui signifie que le fournisseur de service va conserver l’instance créée pour le reste de la requête, et servir la même instance à tous ceux qui demandent la propriété.

Si vous avez besoin que les développeurs puissent construire des objets qui soient pré-câblés aux services Elgg, vous pouvez avoir besoin d’ajouter une méthode de fabrique publique à Elgg\Application. Voici un exemple qui retourne une nouvelle instance en utilisant les services internes de Elgg :

public function createFoo($bar) {
    $logger = $this->services->logger;
    $db = $this->services->db;
    return new Elgg\Foo($bar, $logger, $db);
}

Écrire des tests

Vision

Nous voulons rendre les tests manuels inutiles pour les développeurs du noyau, les auteurs de plugins, et les administrateurs de sites en rendant possible et en faisant la promotion de tests rapides et automatisés à tous les niveaux de Elgg.

Nous avons hâte d’un monde dans lequel les développeurs du noyau n’ont pas besoin de faire de tests manuels pour vérifier la correction du code contribué à Elgg. De manière similaire, nous envisageons un monde dans lequel les administrateurs de site peuvent mettre à niveau et installer de nouveaux plugins avec la certitude que tout fonctionne bien ensemble.

Effectuer les tests

Suite de tests du noyau Elgg

Actuellement nos tests se partagent en deux parties :

• Les tests PHPUnit sont situés dans /tests/phpunit – ceux-ci sont répartis entre les tests unitaires et les tests d’intégration.

Dans la mesure où il existe un fichier de configuration phpunit.xml à la racine de Elgg, les tests devraient être aussi simples que :

git clone http://github.com/Elgg/Elgg
cd Elgg
phpunit

Si vous écrivez un test unitaire, vous pouvez étendre la classe \Elgg\UnitTestCase ou si vous écrivez un test d’intégration, vous pouvez étendre la classe \Elgg\IntegrationTestCase. Ces classes ont des fonctions d’aide lors de l’écriture de tests. Les fonctions suivantes sont souvent utilisées :

• up() - utilisé pour préparer chaque test exécuté dans le scénario de test

• down() - exécuté après chaque test exécuté dans le scénario de test. Principalement utilisé pour nettoyer / restaurer.

• createUser() - crée une entité ElggUser à utiliser dans votre test

• createGroup() - crée une entité ElggGroup à utiliser dans votre test

• createObject() - crée une entité ElggObject à utiliser dans votre test

Tests des plugins

Idéalement, les plugins sont configurés d’une telle manière qu’ils peuvent faire l’objet de tests unitaires de la même manière que le noyau de Elgg. Les développeurs de plugins sont libres d’implémenter leurs propres méthodes pour les tests unitaires, mais nous encourageons tout le monde à les rendre aussi simple que pour le noyau de Elgg :

git clone http://github.com/developer/elgg-plugin plugin
cd plugin
phpunit

Tests de bout en bout

Dans la mesure où les plugins de Elgg ont une telle capacité à remplacer, filtrer et modifier Elgg et le comportement d’autres plugins, il est important de pouvoir exécuter des tests de bout en bout sur un serveur de pré-production avec votre configuration finale avant de déployer en production.

Note

ToDo : Faciliter l’exécution de tous les tests d’intégration et d’acceptabilité depuis le panneau admin en utilisant la configuration courante du plugin. (sans se soucier de corruption de la base de données !)

Motivation

Brièvement, les gains escomptés des tests sont :

• Une confiance accrue dans le système.

• Plus de liberté pour remanier le code.

• Une documentation intégrée et à jour.

Nous adorons les contributions communautaires, mais afin de maintenir la stabilité nous ne pouvons pas accepter de contributions extérieures sans vérifier au préalable leur correction. En promouvant les tests automatisés, les développeurs du noyau peuvent éviter les ennuis d’une vérification manuelle avant d’accepter un patch. Cela signifie également que les développeurs externes n’ont pas à perdre de temps à gagner la confiance de l’équipe du noyau. SI un patch arrive et qu’il dispose de tests pour le vérifier, nous pouvons être confiants dans le fait qu’il fonctionne sans avoir besoin de se soucier de la réputation de l’auteur.

Notez que ces bénéfices peuvent également s’étendre au dépôt des plugins. Les propriétaires de sites sont encouragés à « tester les plugins minutieusement » avant de les déployer sur un site de production. En mars 2013, ceci signifiait tester manuellement toutes les fonctionnalités que le plugin promet d’offrir. Mais Elgg fournit un grand nombre de fonctionnalités, et il n’est pas raisonnable de tester chacune d’entre elles sur chaque navigateur que vous voulez supporter et sur chaque appareil que vous voulez supporter. Mais que se passerait-il si les développeurs de plugins pouvaient écrire des tests pour leurs plugins, et si les propriétaires de sites pouvaient simplement exécuter ces tests pour tous les plugins installés pour vérifier si la fonctionnalité est bien conservée ? Alors ils ne seraient pas limités à seulement prendre des plugins de développeurs « de confiance » ou des versions « stables ». Ils pourraient voir que, en réalité, rien n’a été cassé quand ils ont mis à niveau ce plugin critique depuis la version 1.3 vers la 2.5, et publier la mise à niveau en production en toute confiance.

La raison pour laquelle ce n’est pas le cas actuellement est parce que Elgg lui-même n’est pas encore si facile à tester à ce niveau. Nous voulons changer cela.

Stratégie

Nous avons quelques principes pour nous guider, dont nous pensons qu’ils seront utiles pour faire de cette vision une réalité.

En bref, nous prônons :

• Intégration continue – si les vérifications de Github ne sont pas satisfaisantes, nous ne sommes pas satisfaits

• L’injection des dépendances – Pour créer un code hautement testable et modulaire

• BDD - « Behaviour Driven Development » ou Développement Orienté Comportement – Les tests devraient vérifier des fonctionnalités et fournir de la documentation, et pas simplement reprendre l’API de la Classe

Intégration continue

Nous exécutons tous nos tests avec les Actions GitHub afin de pouvoir obtenir des commentaires en temps réel sur l’exactitude des demandes de fusion -pull requests- et du développement au fur et à mesure de sa progression. ** Si les vérifications de GitHub ne réussissent pas, nous ne faisons pas de commit dans le dépôt. ** Cela nous permet de fusionner les demandes de fusion à un rythme rapide, tant qu’elles réussissent les tests. Cela nous permet également de rejeter les demandes de fusion sans examen détaillé si elles ne réussissent pas les tests. Nous pouvons dépasser la question « ça marche ou pas » et parler des choses dont les humains ont besoin de parler : la conception d’API, l’utilité pour le projet, si cela appartient au noyau ou à un plugin, etc. Nous voulons qu’autant de fonctionnalités que possible fournies par le noyau de Elgg -Elgg core- puissent être vérifiées automatiquement par des tests exécutés sur GitHub Actions.

Injection des dépendances

Afin de maximiser la testabilité, toutes les dépendances doivent être explicites. Les fonctions globales, les Singletons, et les localiseurs de service sont mortels pour la testabilité parce qu’il est impossible de dire quelles dépendances se cachent sous le capot, et qu’il est encore plus difficile de modéliser ces dépendances. La capacité de modélisation est critique parce que vous voulez que vos tests unitaires ne testent qu’une seule classe à la fois. Les échecs de test dans un TestCase ne devraient pas aboutir à la rupture d’une dépendance ; les échecs des tests ne devraient indiquer de rupture que dans la classe en train d’être testée. Ceci rend tout plus facile à déboguer. En mars 2013, l’essentiel de Elgg présupposait et utilisait encore l’état global, ce qui a rendu les plugins Elgg et le noyau Elgg historiquement très difficiles à tester. Heureusement, nous avons pris la direction opposée, et beaucoup de travail dans Elgg 1.9 a été consacré à la refactorisation des composants de base pour qu’ils soient plus dépendants et injectables. Nous récoltons déjà les fruits de cet effort.

Behavior-Driven Development - Développement Orienté Comportement

Pour nous ceci signifie que nous nommons les tests d’après les fonctionnalités plutôt que d’après les méthodes. Quand vous testez des fonctionnalités, vous êtes encouragés à écrire moins de tests, plus petits, et plus logiques. Quand un test échoue, cela permet de savoir exactement quelle fonctionnalité est compromise. De plus, en nommant vos tests d’après les fonctionnalités, la liste des tests fournit une documentation des fonctionnalités que le système supporte. La documentation est typiquement quelque chose de problématique à conserver à jour, mais quand la documentation et la vérification sont une seule et même chose, il devient très facile de maintenir la documentation à jour.

Considérez ces deux méthodes de test :

• testRegister()

• testCanRegisterFilesAsActionHandlers()

En regardant seulement les noms, testRegister vous indique que la classe testée a probablement une méthode nommée « register ». Si ce test est passé, il vérifie probablement qu’elle se comporte correctement, mais ne vous dit pas ce qui caractérise un comportement correct, ou ce que l’auteur original du test essayait de vérifier. Si cette méthode a plusieurs usages corrects que vous devez tester, cette convention de nommage succincte vous encourage également à écrire un très long test qui teste toutes les conditions et fonctionnalités de ladite méthode. L’échec du test pourrait être causée par la compromission de n’importe laquelle d’entre elles, et cela prendra plus de temps pour savoir où se situe le véritable problème.

De l’autre côté, testCanRegisterFilesAsActionHandlers vous indique qu’il y a ces choses appelées « actions » qui ont besoin d’être « gérées » (« handled »), et que des fichiers peuvent être enregistrés comme des gestionnaires valides pour les actions. Ceci expose mieux aux nouveaux venus la terminologie du projet et communique clairement l’intention du test pour ceux qui sont déjà familiers avec la terminologie.

Pour un bon exemple de ce que nous recherchons, regardez /tests/phpunit/Elgg/ViewServiceTest.php

Tâches principales

Certaines tâches autour de Elgg sont réservées à l’équipe des développeurs du noyau dans la mesure où elles demandent certaines permissions spéciales. Les guides ci-dessous décrivent le processus pour ces actions.

Déplacer un plugin vers son propre dépôt

Étapes d’extraction d’un plugin

Déplacez le code vers son propre dépôt

Suivez le guide Github pour transformer un sous-dossier en un nouveau dépôt Splitting a subfolder out into a new repository. Ceci va faire en sorte que l’historique des commits soit préservé.

Dépendances

Si le plugin a des dépendances sur des bibliothèques externes, assurez-vous que ces dépendances soient gérées. Par exemple, si une bibliothèque PHP est requise qui est livrée incluse avec le noyau de Elgg, assurez-vous de l’ajouter dans le fichier composer.json de ce plugin dans la mesure où vous ne pouvez pas vous compter sur le fait que le noyau de Elgg conserve cette bibliothèque.

Commitez le code

Durant ce guide GitHub un nouveau dépôt est créé pour le plugin que vous essayez de déplacer.

Dans la mesure où une tentative a déjà été faite pour extraire certains des plugins vers leur propre dépôt il se peut que le dépôt existe déjà.

Si le dépôt n’existait pas pour le plugin, assurez-vous que vous le créez dans l” organisation Elgg.

Si le dépôt existe déjà, le meilleur moyen de mettre à jour le code serait de faire une Pull Request. Ceci risque cependant probablement d’échouer à cause d’une différence dans la manière dont le dépôt a été initialement créé (comme discuté dans Problème avec GitHub).

Les dépôts initiaux ont été créés avec

git subtree split

et le guide appelle

git filter-branch --prune-empty --subdirectory-filter

Ceci va laisser une différence dans les commits que Github est incapable de résoudre. Dans ce cas vous devrez forcer un push des modifications vers le dépôt du plugin Elgg existant.

Avertissement

Dans la mesure où cela va réécrire tout l’historique du dépôt du plugin, assurez-vous que vous savez que c’est bien ce que vous voulez faire.

Packagist

Assurez-vous que le composer.json du plugin contient bien toutes les informations pertinentes. Voici un exemple :

{
        "name": "elgg/<name of the repository>",
        "description": "<a description of the plugin>",
        "type": "elgg-plugin",
        "keywords": ["elgg", "plugin"],
        "license": "GPL-2.0-only",
        "support": {
                "source": "https://github.com/elgg/<name of the repository>",
                "issues": "https://github.com/elgg/<name of the repository>/issues"
        },
        "conflict": {
                "elgg/elgg": "< <minimal Elgg required version>"
        }
}

La règle conflict est ici pour aider à éviter l’installation de ce plugin dans une version de Elgg non supportée.

Ajoutez le dépôt à Packagist, pour les dépôts existants ceci a déjà été fait. Assurez-vous que Packagist est mis à jour correctement avec tous les commits.

Taguer une release

Pour que Composer puisse mettre en cache le plugin pour une installation plus rapide, une version doit être publiée dans le repository. La première version qui doit être taguée est probablement la même version que celle mentionnée dans elgg-plugin.php ou composer.json. Après cela le développement peut commencer, en suivant le schéma de version Semver.

Traductions

Si les traductions pour le plugin doivent être gérées par Transifex, ajoutez le plugin à Transifex.

Nettoyage du noyau de Elgg

Maintenant que le plugin a été déplacé dans son propre dépôt, il est temps de faire une Pull Request sur le noyau de Elgg pour supprimer le code originel.

Supprimez le plugin

• Supprimez le plugin du dossier mod

• Recherchez le nom du plugin dans le noyau pour trouver toute référence qui aurait également besoin d’être retirée (par ex. anciennes documentations, tests spéciaux, etc.)

Traductions

Dans la mesure où le plugin ne fait plus partie du noyau de Elgg, assurez-vous que la configuration de Transifex ne contient plus le plugin.

Plugins inclus

Si le plugin est toujours distribué inclus avec la publication d’une nouvelle version de Elgg, assurez-vous d’ajouter le plugin dans composer.json.

Composer

Vérifiez les dépendances composer du noyau pour identifier si des exigences qui étaient spécifiques pour le plugin retiré peuvent également être retirées des dépendances du noyau.

Documentation

Ajoutez une mention dans la documentation Notes de mise à niveau qui indique que le plugin a été retiré du noyau de Elgg.

Processus de publication d’une nouvealle version - release

Publier une nouvelle version de Elgg.

Voici le processus suivi par l’équipe du noyau pour publier une nouvelle version de Elgg. Nous publions cette information dans un esprit d’ouverture, et pour faciliter l’intégration de nouveaux membres de l’équipe.

Pré-requis

• Accès SSH à elgg.org

• Accès aux commits sur http://github.com/Elgg/Elgg

• Accès admin à https://elgg.org/

• Accès au compte Twitter

• Node.js et Yarn installés

• Sphinx installé (easy_install sphinx && easy_install sphinx-intl)

• Client Transifex installé (easy_install transifex-client)

• Compte Transifex avec accès au projet Elgg

• Accès administrateur à Read The Docs

• Accès administrateur à Scrutinizer

Fusionnez les commits à partir des branches les plus basses

Déterminez la branche LTS. Nous devons fusionner tous les nouveaux commits jusqu’ici en passant par les autres branches.

Pour chaque branche

Vérifiez la branche, assurez-vous qu’elle est à jour, et créez une nouvelle branche de travail avec la fusion. Par ex. ici nous fusionnons les commits de la 1.12 dans la 2.0 :

git checkout 2.0
git pull
git checkout -b merge112
git merge 1.12

Note

Si elle est déjà à jour (aucun commit à fusionner), nous pouvons nous arrêter ici pour cette branche.

S’il y a des conflits, résolvez-les, git add ., et git merge.

Faites un PR pour la branche et attendez le résultat des tests automatiques et l’approbation par un autre développeur (ou plusieurs).

git push -u my_fork merge112

Une fois la fusion effectuée, nous répéterions le processus pour fusionner les commits de la 2.0 dans la 2.1.

Préparation pour la première nouvelle version stable mineure/majeure

• Mettez à jour Politique de support pour inclure la date de la nouvelle date de version mineure/majeure et complétez les vides de la version précédente.

• Mettez à jour les badges du fichier README.md pour indiquer les nouveaux numéros de version corrects.

Préparation pour une nouvelle version majeure

• Modifiez la configuration Transifex pour pousser les traductions vers un autre projet

Préparez la publication

Faites un PR avec les mises à jour des traductions

Installez les pré-requis :

easy_install transifex-client
easy_install sphinx
easy_install sphinx-intl

Note

Sur Windows, vous devrez exécuter ces commandes dans une console avec des privilèges admin

Exécutez le script languages.php. Par exemple, pour extraire les traductions :

php .scripts/languages.php 3.x

Faites une demande de fusion -PR- avec les nouvelles traductions et faites-la fusionner avant l’étape suivante.

Ensuite, accédez manuellement à la page /admin/site_settings et vérifiez qu’elle se charge. Si ce n’est pas le cas, un fichier de langue de Transifex peut avoir une erreur de syntaxe PHP. Corrigez l’erreur et modifiez votre commit avec le nouveau fichier :

# only necessary if you fixed a language file
git add .
git commit --amend

Faites le PR de la version

Mettez à jour votre clone git local.

Fusionnez les derniers commits vers le haut en commençant par la branche supportée la plus basse.

Visitez https://github.com/Elgg/Elgg/compare/<new>...<old> et soumettez le PR si quoi que ce soit a besoin d’être fusionné plus haut.

Note

Sur Windows, vous devrez exécuter ces commandes dans une console avec des privilèges admin

Exécutez le script release.php. Par exemple, pour publier 1.12.5 :

git checkout 1.12
php .scripts/release.php 1.12.5

Ceci crée une branche release-1.12.5 dans votre repo local.

Ensuite, soumettez une demande de fusion -PR- via GitHub pour les tests automatisés et l’approbation par un autre développeur :

git push your-remote-fork release-1.12.5

Taguez la release

Une fois approuvée et fusionnée, créez une version sur GitHub :

• Allez sur les releases

• Cliquez sur “Draft a new release”

• Saisissez la version

• Sélectionnez la bonne branche (par ex. 1.12 pour une release 1.12.x, 2.3 pour une release 2.3.x, etc.)

• Définissez le titre de la release comme “Elgg {version}”

• Collez la partie de CHANGELOG.md relative à cette release dans la description

Note

GitHub est configuré pour écouter la création d’une nouvelle version afin de créer automatiquement la version ZIP de Elgg. Une fois la version créée, attendez quelques minutes et le ZIP devrait être ajouté à la version.

Un peu d’administration pour terminer

• Marquez les jalons de release Github comme terminés

• Déplacez les tickets non résolus des jalons publiés vers des jalons ultérieurs

Actions supplémentaires pour la première nouvelle mineure / majeure

• Créez une nouvelle branche sur GitHub (par exemple 3.3)

• Définissez la nouvelle branche comme branche par défaut (facultatif, mais suggéré pour les versions stables)

• Configurez Read The Docs pour créer la nouvelle branche (pas le nouveau tag)

• Configurez Scrutinizer pour créer la nouvelle branche

• Vérifiez le projet de démarrage Elgg pour les pré-requis potentiels / modifications de configuration dans le composer.json

• Ajoutez la nouvelle version mineure/majeure au référentiel Elgg/community_plugins afin que les développeurs puissent télécharger des plugins pour la nouvelle version

• Mettez à jour la configuration de build pour Elgg reference (sur le serveur web Elgg.org)

# in the file /root/elgg-scripts/cron/make_reference
# set the main build branch to the correct branch
# make sure if you change the main build branch to add the previous branch to the other branches to build
# the new configuration will be applied by the daily cron

Action supplémentaire pour la première nouvelle majeure

• Sur GitHub ajoutez une règle de protection de branche (par exemple 4.*)

• Configurez Scrutinizer pour suivre les nouvelles branches principales (par exemple 4.*)

Mettez à jour le site web

Mettez à jour la page de téléchargement de elgg.org

• Clonez https://github.com/Elgg/community

• Ajoutez la nouvelle version dans classes/Elgg/Releases.php

• Commitez et poussez les modifications

• Téléchargez la version ZIP depuis GitHub

• Chargez le ZIP sur le serveur web elgg.org

sudo mv ~/elgg-x.y.z.zip /var/www/www.elgg.org/download
sudo chown deploy:deploy /var/www/www.elgg.org/download/elgg-x.y.z.zip

Mettez à jour elgg.org

• Clonez https://github.com/Elgg/www.elgg.org

• (facultatif) Modifiez la version de Elgg requise dans composer.json

• Mettez à jours les vendors

composer update

• Commitez et poussez les modifications

• Faites un pull vers le site en activité

sudo -su deploy
cd /var/www/www.elgg.org
git pull
composer install --no-dev

• Allez sur la panneau admin de la communauté

• Videz le cache APC

• Exécutez la mise à niveau

Faites l’annonce

Ceci devrait être la toute dernière chose à faire.

1. Ouvrez https://github.com/Elgg/Elgg/blob/<tag>/CHANGELOG.md et copiez le contenu pour cette version

2. Connectez-vous sur https://elgg.org/blog et rédigez un nouvel article de blog avec un sommaire

3. Copiez le contenu dans le CHANGELOG, supprimez le formattage, et supprimez manuellement les balises SVG

4. Ajoutez les tags release et elgg2.x où x est le nom de la branche en train d’être publiée

5. Tweetez depuis le compte Twitter account de Elgg

Annexes

Informations diverses à propos du projet.

Notes de mise à niveau

Si vous mettez à niveau vos plugins et votre site Web vers une nouvelle version majeure de Elgg, les modifications notables suivantes s’appliquent.

Voir les guides d’administration pour savoir comment mettre à niveau un site en production.

De 5.0 à 5.1

Changements dans la structure DOM

Afin d’améliorer l’accessibilité, la structure DOM HTML a été légèrement modifiée. Certaines sections de la page ont été modifiées de div à header, main ou footer. Les classes ou la position dans le DOM n’ont pas été modifiées.

Vues obsolètes

• page/elements/<section>/after est obsolète : étendez le bon page/elements/<section>

• page/elements/<section>/before est obsolète : ajoutez le bon préfixe page/elements/<section>

• resources/comments/edit est obsolète : cette ressource n’est plus utilisée

Routes obsolètes

• edit:object:comment est obsolète : la modification des commentaires utilise un formulaire en ligne

De 4.x à 5.0

CKEditor

L’éditeur a été mis à jour vers la version 5. Cela apporte quelques nouvelles fonctionnalités (comme les mentions et les images dans le contenu) mais impacte également les plugins existants. Les plus notables sont The Wire (qui a désormais également mentionné le support) et la suppression du plugin Embed.

Le menu “longtext” associé n’est plus disponible.

Composer

Pré-requis PHP

La version minimale de PHP est maintenant 8.0.

Faker

La bibliothèque faker n’est plus maintenue par fzaninotto, nous sommes donc passés à un fork qui est maintenu par FakerPHP.

Événements et Hooks

Ces deux concepts similaires ont été fusionnés et nous ne ferons désormais référence qu’à des événements. Les « crochets » du service public n’existent plus. Tous les hooks peuvent maintenant être enregistrés dans la section « événements » de votre plugin. Si vous utilisez des rappels de hook qui attendent un argument ElggHook d’indication de type, vous devrez le mettre à jour vers ElggEvent.

Créer un événement

Les événements create, <object|group|user|site> ne peuvent plus être utilisés pour empêcher la création de l’entité. Utilisez create:before si vous souhaitez empêcher la création.

Paramètres privés

Le concept de paramètres privés a été supprimé du système. Tous les paramètres privés ont été copiés dans les métadonnées. Toutes les fonctions associées ont été supprimées.

Fil d’Ariane intégré au système de menu

Les fonctions d’assistance pour le menu du fil d’Ariane ont été modifiées pour utiliser elgg_register_menu_item() pour ajouter des éléments au menu du fil d’Ariane. Les événements liés au fil d’Ariane ont été supprimés au profit des événements de menu standards.

Mises à niveau

Les mises à niveau asynchrones ou système ne sont plus des classes qui implémentent des interfaces, mais étendent des classes abstraites. Mettez à jour vos mises à niveau pour étendre les classes appropriées. La raison de ce changement est de pouvoir accéder à l’entité ElggUpgrade à partir du Batch qui exécute une partie de la mise à niveau. Vous pouvez accéder à la mise à niveau en appelant $this->getUpgrade().

Session

Si vous utilisez le service de session directement (ou via elgg_get_session()), vous devrez peut-être mettre à jour votre code. Diverses fonctions de cette classe ont été déplacées vers le service elgg()->session_manager.

Gestionnaires d’accès

Le middleware PageOwnerCanEditGatekeeper requiert désormais de définir un propriétaire de page. Ce contrôleur d’accès requiert désormais également un utilisateur connecté à tout moment.

Plugin Files

Les fichiers téléchargés à l’aide du plugin de fichiers « file » ne sont plus stockés avec le propriétaire mais avec l’entité du fichier. Les icônes de fichiers ont également été modifiées. Les images d’icônes ne sont disponibles que pour les types de fichiers image. La taille des icônes a été modifiée pour utiliser les tailles d’icône par défaut.

Plugin Embed

Le plugin embed a été supprimé.

JavaScript

Hooks système

Les fonctions de hook javascript ont été déplacées vers un module AMD. Si vous avez utilisé des hooks javascript, vous devez mettre à jour votre code pour utiliser le module elgg/hook. Le concept de “hooks instantanés” n’est plus présent dans le système.

L’événement 'init', 'system' n’est plus déclenché en javascript.

Fonctions supprimées

• elgg.is_in_object_array

• elgg.is_instant_hook

• elgg.is_triggered_hook

• elgg.push_to_object_array

• elgg.register_hook_handler utilise la fonction register fournie par le module elgg\hooks

• elgg.register_instant_hook

• elgg.set_triggered_hook

• elgg.trigger_hook utilisez la fonction trigger fournie par le module elgg\hooks

Exceptions

L’utilisation des exceptions dans Elgg a été revisitée. \Elgg\Exceptions\InvalidParameterException a été supprimé et remplacé par l’exception correcte. L’utilisation de \Elgg\Exceptions\InvalidArgumentException a également été vérifiée. Dans certains cas, l’exception a été remplacée par une exception plus appropriée.

ElggRiverItem

Il n’est désormais plus permis de définir des données arbitraires pendant l’exécution sur un ElggRiverItem. Étant donné que les données n’étaient disponibles que pendant l’exécution et n’étaient pas enregistrées dans la base de données, cette distinction a été supprimée. Lors de la définition d’un attribut non pris en charge, une \Elgg\Exceptions\RuntimeException est levée.

// this is allowed
$item = new \ElggRiverItem();
$item->subject_guid = elgg_get_logged_in_user_guid();

// this is no longer allowed (causes an \Elgg\Exceptions\RuntimeException)
$item = new \ElggRiverItem();
$item->foo = 'bar';

Options des métadonnées dans les fonctions de récupération (« getter »)

Auparavant, il existait une magie qui transformait la chaîne metadata_value en tableau si elle contenait un ,.

Cette magie a été supprimée. Vous devez maintenant fournir le tableau vous-même. En raison de cette magie, il était impossible de rechercher une valeur de métadonnées contenant un ,.

// previously
$options = [
        'metadata_name_value_pairs' => [
                'some_name' => 'some_value1, some_value2',
        ],
];

// would result into, thus giving it an OR value
$options = [
        'metadata_name_value_pairs' => [
                'name' => 'some_name',
                'value' => [
                        'some_value1',
                        'some_value2',
                ],
                'operand' => '=',
        ],
];

Modification dans les fonctions

Les fonctions suivantes ont maintenant leurs arguments et/ou valeurs de retour typées, ce qui peut provoquer des erreurs TypeError. De plus, certaines fonctions de classe ont leur type de valeur de retour indiqué et vous devez mettre à jour la définition de votre fonction. Certaines fonctions peuvent avoir leurs arguments modifiés, ou le type de retour a été modifié.

Types de retour des fonctions des bibliothèques

• elgg_add_admin_notice() renvoie maintenant null en cas d’erreur au lieu d’un bool

• elgg_create_river_item() renvoie désormaisun ElggRiverItem, ou null en cas d’échec

• elgg_delete_metadata() ne renvoie plus null

• elgg_delete_river() ne renvoie plus null

• elgg_deprecated_notice() ne renvoie plus bool

• elgg_generate_entity_url() renvoie maintenant null en cas d’erreur au lieu d’un bool

• elgg_generate_url() renvoie maintenant null en cas d’erreur au lieu d’un bool

• elgg_get_annotation_from_id() renvoie désormais null au lieu d’un bool si aucune annotation n’est trouvée

• elgg_get_download_url() renvoie maintenant null en cas d’erreur

• elgg_get_entity_as_row() renvoie désormais null au lieu d’un bool si aucune entité n’est trouvée

• elgg_get_entity_dates() ne renvoie plus un bool

• elgg_get_form_footer() ne renvoie plus un bool

• elgg_get_inline_url() renvoie maintenant null en cas d’erreur

• elgg_get_metadata_from_id() renvoie désormais null si aucune métadonnée n’a pu être trouvée

• elgg_get_page_owner_entity() renvoie désormais null si le propriétaire de la page n’a pas pu être trouvé

• elgg_get_river_item_from_id() renvoie désormais null si aucun élément de rivière n’a pu être trouvé

• elgg_get_system_cache() renvoie désormais une instance de \Elgg\Cache\BaseCache au lieu de \ElggCache

• elgg_get_uploaded_file() renvoie désormais null si aucun fichier n’a pu être trouvé ou si le fichier n’était pas valide

• elgg_normalize_site_url() renvoie désormais null lorsque l’URL n’est pas une URL de site

• elgg_register_action() ne renvoie plus un bool

• elgg_register_menu_item() n’a plus de valeur de retour

• elgg_register_widget_type() n’a plus de valeur de retour

• elgg_set_form_footer() n’a plus de valeur de retour

• elgg_trigger_after_event() n’a plus de valeur de retour

• elgg_unregister_action() n’a plus de valeur de retour

• elgg_unregister_event_handler() n’a plus de valeur de retour

• elgg_unregister_notification_event() n’a plus de valeur de retour

• elgg_unregister_notification_method() n’a plus de valeur de retour

• elgg_unregister_widget_type() n’a plus de valeur de retour

• elgg_view_annotation() ne renvoie plus un bool

• elgg_view_comments() ne renvoie plus un bool

• elgg_view_list_item() ne renvoie plus un bool

• elgg_view_relationship() ne renvoie plus un bool

• get_entity() renvoie désormais null au lieu d’un bool si aucune entité n’est trouvée

• get_user() renvoie désormais null au lieu d’un bool si aucun utilisateur n’est trouvé

• elgg_ws_expose_function() ne renvoie plus un bool

Paramètres de fonction des fonctions des bibliothèques

• blog_prepare_form_vars() requiert désormais un ElggBlog pour $blog et un ElggAnnotation pour $revision

• bookmarks_prepare_form_vars() requiert désormais un ElggBookmark pour $bookmark

• discussion_prepare_form_vars() requiert désormais un ElggDiscussion pour $topic

• elgg_add_action_tokens_to_url() requiert désormais un string pour $url et un bool pour $html_encode

• elgg_can_edit_widget_layout() requiert désormais un string pour $context et un int pour $user_guid

• elgg_clear_event_handlers() requiert désormais un string pour $event et $type

• elgg_clear_sticky_form() requiert désormais un string pour $context

• elgg_create_widget() requiert désormais un int pour $owner_guid et $access_id et un string pour $handler et $context

• elgg_define_js() requiert désormais un string pour $name et un array pour $config

• elgg_delete_system_cache() requiert désormais un string pour $type

• elgg_echo() requiert désormais un string pour $message_key et un string pour $language

• elgg_enqueue_notification_event() n’a plus besoin d’un $type

• elgg_entity_exists() requiert désormais un int pour $guid

• elgg_entity_gatekeeper() requiert désormais un int pour $guid, un string pour $type, un string pour $subtype et un bool pour $validate_can_edit

• elgg_error_response() requiert désormais un string ou un array pour $message et un string pour $forward_url

• elgg_extend_view() requiert désormais un string pour $view et $view_extension

• elgg_extract() requiert désormais un bool pour $strict

• elgg_format_bytes() requiert désormais un int pour $size et $precision

• elgg_format_element() requiert désormais un string pour $tag_name et un string pour $text

• elgg_format_html() requiert désormais un string pour $html

• elgg_generate_action_url() requiert désormais un string pour $action et un booléen pour $add_csrf_tokens

• elgg_generate_entity_url() requiert désormais un string pour $resource et $subresource

• elgg_generate_url() requiert désormais un string pour $name

• elgg_get_config() requiert désormais un string pour $name

• elgg_get_download_url() requiert désormais un bool pour $use_cookie et un string pour $expires

• elgg_get_embed_url() requiert désormais un string pour $size

• elgg_get_entity_class() requiert désormais un string pour $type et un string pour $subtype

• elgg_get_excerpt() requiert désormais un string pour $text et un int pour $num_chars

• elgg_get_friendly_upload_error() requiert désormais un int pour $error_code

• elgg_get_friendly_time() requiert désormais un int pour $time et $current_time

• elgg_get_friendly_title() requiert désormais un string pour $title

• elgg_get_icon_sizes() requiert désormais un string pour $entity_type et $entity_subtype

• elgg_get_ini_setting_in_bytes() requiert désormais un string pour $setting

• elgg_get_inline_url() requiert désormais un bool pour $use_cookie et un string pour $expires

• elgg_get_login_url() requiert désormais un string pour $fragment

• elgg_get_metadata_from_id() requiert désormais un int pour $id

• elgg_get_registration_url() requiert désormais un string pour $fragment

• elgg_get_request_data() requiert désormais un bool pour $filter_result

• elgg_get_simplecache_url() requiert désormais un string pour $view et $sub_view

• elgg_get_sticky_value() requiert désormais un string pour $form_name et une chaine de caractères pour $variable et un a bool pour $filter_result

• elgg_get_sticky_values() requiert désormais un string pour $form_name et un bool pour $filter_result

• elgg_get_title_input() requiert désormais un string pour $variable et une chaîne de caractères pour $default

• elgg_get_uploaded_file() requiert désormais un string pour $input_name et un bool pour $check_for_validity

• elgg_get_uploaded_files() requiert désormais un string pour $input_name

• elgg_get_view_extensions() requiert désormais un string pour $view

• elgg_get_widget_types() requiert désormais un string ou un array pour $context

• elgg_get_widgets() requiert désormais un int pour $owner_guid et un string pour $context

• elgg_group_tool_gatekeeper() requiert désormais un string pour $tool_name et un int pour $group_guid

• elgg_html_decode() requiert désormais un string pour $string

• elgg_http_add_url_query_elements() requiert désormais un string pour $url

• elgg_http_build_url() requiert désormais un bool pour $html_encode

• elgg_http_get_signed_url() requiert désormais un string pour $url et $expires

• elgg_http_remove_url_query_element() requiert désormais un string pour $url et un string pour $element

• elgg_http_url_is_identical() requiert désormais un string pour $url1 et $url2 et un array pour $ignore_params

• elgg_http_validate_signed_url() requiert désormais un string pour $url

• elgg_in_context() requiert désormais un string pour $context

• elgg_is_sticky_form() requiert désormais un string pour $form_name

• elgg_is_widget_type() requiert désormais un string pour $handler et $context

• elgg_language_key_exists() requiert désormais un string pour $key et un string pour $language

• elgg_list_entities() requiert désormais un callable pour $getter et un callable pour $viewer

• elgg_list_entities_from_relationship_count() requiert désormais un array pour $options

• elgg_list_relationships() requiert désormais un array pour $options

• elgg_load_system_cache() requiert désormais un string pour $type

• elgg_make_sticky_form() requiert désormais un string pour $form_name

• elgg_normalize_site_url() requiert désormais un string pour $unsafe_url

• elgg_normalize_url() requiert désormais un string pour $url

• elgg_ok_response() requiert désormais un string ou un array pour $message et un string pour $forward_url

• elgg_parse_emails() requiert désormais un string pour $text

• elgg_push_context() requiert désormais un string pour $context

• elgg_redirect_response() requiert désormais un string pour $forward_url

• elgg_register_action() requiert désormais un string pour $filename

• elgg_register_ajax_view() requiert désormais un string pour $view

• elgg_register_error_message() requiert désormais un string|array pour $message

• elgg_register_event_handler() requiert désormais un string pour $event et $type et un int pour $priority et un callable|string pour $callable

• elgg_register_menu_item() requiert désormais un string pour $menu_name et un array|\ElggMenuItem pour $menu_item

• elgg_register_notification_event() requiert désormais un string pour $object_type et $object_subtype

• elgg_register_notification_method() requiert désormais un string pour $name

• elgg_register_route() requiert désormais un string pour $name

• elgg_register_simplecache_view() requiert désormais un string pour $view_name

• elgg_register_success_message() requiert désormais un string|array pour $message

• Le premier argument ($handler) de elgg_register_title_button() a été supprimé et requiert un string pour $name, $entity_type et $entity_subtype

• elgg_register_viewtype_fallback() requiert désormais un string pour $viewtype

• elgg_register_widget_type() ne supporte plus pour $options qu’un array adapté pour \Elgg\WidgetDefinition::factory()

• elgg_remove_config() requiert désormais un string pour $name

• elgg_require_js() requiert désormais un string pour $name

• elgg_save_config() requiert désormais un string pour $name

• elgg_save_resized_image() requiert désormais un string pour $source et un string pour $destination

• elgg_save_system_cache() requiert désormais un string pour $type

• elgg_set_config() requiert désormais un string pour $name

• elgg_set_context() requiert désormais un string pour $context

• elgg_set_entity_class() requiert désormais un string pour $type et un string pour $subtype et un string pour $class

• elgg_set_form_footer() requiert désormais un string pour $footer

• elgg_set_http_header() requiert désormais un string pour $header et un bool pour $replace

• elgg_set_page_owner_guid() requiert désormais un int pour $guid

• elgg_set_view_location() requiert désormais un string pour $view, $location et $viewtype

• elgg_set_viewtype() requiert désormais un string pour $viewtype

• elgg_strip_tags() requiert désormais un string pour $string et $allowable_tags

• elgg_trigger_after_event() requiert désormais un string pour $event et $type

• elgg_trigger_before_event() requiert désormais un string pour $event et $type

• elgg_trigger_deprecated_event() requiert désormais un string pour $event, $type, $message et $version

• elgg_trigger_event() requiert désormais un string pour $event et $type

• elgg_unregister_ajax_view() requiert désormais un string pour $view

• elgg_register_event_handler() requiert désormais un string pour $event et $type et un callable|string pour $callable

• elgg_unregister_menu_item() requiert désormais un string pour $menu_name et $item_name

• elgg_unregister_notification_event() requiert désormais un string pour $object_type et $object_subtype

• elgg_unregister_notification_method() requiert désormais un string pour $name

• elgg_unregister_route() requiert désormais un string pour $name

• elgg_unregister_widget_type() requiert désormais un string pour $handler

• elgg_unrequire_js() requiert désormais un string pour $name

• elgg_validate_invite_code() requiert désormais un string pour $username et $code

• elgg_validate_registration_data() requiert désormais un string pour $username, $name et $email, un bool pour $multiple et un string|array pour $password

• elgg_view() requiert désormais un string pour $view et $viewtype et un bool pour $recurse

• elgg_view_annotation_list() requiert désormais un array pour $annotations

• elgg_view_deprecated() requiert désormais un string pour $view, $message et $version

• elgg_view_comments() requiert désormais un ElggEntity pour $entity et un bool pour $add_comment

• elgg_view_entity_icon() requiert désormais un string pour $size et un array pour $vars

• elgg_view_entity_list() requiert désormais un array pour $entities

• elgg_view_exists() requiert désormais un string pour $view et $viewtype et un array pour $vars

• elgg_view_form() requiert désormais un string pour $action et un array pour $form_vars et $body_vars

• elgg_view_icon() requiert désormais un string pour $name et un array pour $vars

• elgg_view_image_block() requiert désormais un string pour $type, $title et $body

• elgg_view_layout() requiert désormais un string pour $layout_name et un array pour $vars

• elgg_view_message() requiert désormais un string pour $type et $body

• elgg_view_page() requiert désormais un string pour $title et $page_shell, un array pour $vars et un string|array pour $body

• elgg_view_relationship_list() requiert désormais un array pour $relationships

• elgg_view_river_item() requiert désormais un ElggRiverItem pour $item

• elgg_view_resource() requiert désormais un string pour $name

• elgg_view_title() requiert désormais un string pour $title

• embed_get_list_options() requiert désormais un array pour $options

• embed_list_items() requiert désormais un array pour $entities et $vars

• file_prepare_form_vars() requiert désormais un ElggFile pour $file

• get_entity() requiert désormais un int pour $guid

• get_input() requiert désormais un string pour $variable et un bool pour $filter_result

• get_user() requiert désormais un int pour $guid

• groups_get_group_join_menu_item() requiert désormais un ElggUser pour $user

• groups_get_group_leave_menu_item() requiert désormais un ElggUser pour $user

• groups_get_invited_groups() requiert désormais un int pour $user_guid, un bool pour $return_guids et un array pour $options

• notify_user() requiert désormais un int|array pour $to et un int pour $from et un string pour $subject et $message

• pages_get_navigation_tree() requiert désormais un ElggEntity pour $container

• pages_prepare_form_vars() requiert désormais un ElggPage pour $page, un int pour $parent_guid et un ElggAnnotation pour $revision

• pages_prepare_parent_breadcrumbs() requiert désormais un ElggPage pour $page

• set_input() requiert désormais un string pour $variable

• thewire_filter() requiert désormais un string pour $text

• thewire_get_hashtags() requiert désormais un string pour $text

• thewire_save_post() requiert désormais un string pour $text et $method et un int pour $userid, $access_id et $parent_guid

• uservalidationbyemail_request_validation() requiert désormais un int pour $user_guid

• elgg_ws_expose_function() requiert désormais un string pour $method, $description et $call_method, un array pour $parameters et un bool pour $require_api_auth, $require_user_auth et $assoc

• elgg_ws_register_service_handler() requiert désormais un string pour $handler

• elgg_ws_unexpose_function() requiert désormais un string pour $method et un string pour $http_request_method

• elgg_ws_unregister_service_handler() requiert désormais un string pour $handler

Types de retour des fonctions de classes

• \ElggEntity::deleteMetadata() ne renvoie plus null

• \ElggEntity::getOwnedAccessCollection() ne renvoie plus false mais null quand aucune collection d’accès n’a été trouvée

• \ElggEntity::setContainerGUID() ne renvoie plus un int

• \ElggFile::getDownloadURL() renvoie maintenant null en cas d’erreur

• \ElggFile::getInlineURL() renvoie maintenant null en cas d’erreur

• \ElggMenuItem::factory() ne renvoie plus null en cas d’erreur

• \Elgg\Page::getParentEntity() ne renvoie plus false mais null si aucune entité parente n’a été trouvée

Paramètres de la fonction de classe

• \ElggAccessCollection::getObjectFromID() requiert désormais un int pour $id

• \ElggAnnotation::getObjectFromID() requiert désormais un int pour $id

• \ElggEntity::addRelationship() requiert désormais un int pour $guid_two et un string pour $relationship

• \ElggEntity::cache() requiert désormais un bool pour $persist

• \ElggEntity::canAnnotate() requiert désormais un int pour $user_guid et un string pour $annotation_name

• \ElggEntity::canComment() requiert désormais un int pour $user_guid

• \ElggEntity::canDelete() requiert désormais un int pour $user_guid

• \ElggEntity::canEdit() requiert désormais un int pour $user_guid

• \ElggEntity::canWriteToContainer() requiert désormais un int pour $user_guid et un string pour $type et $subtype

• \ElggEntity::countAnnotations() requiert désormais un string pour $name

• \ElggEntity::countEntitiesFromRelationship() requiert désormais un string pour $relationship et un bool pour $inverse_relationship

• \ElggEntity::delete() requiert désormais un bool pour $recursive

• \ElggEntity::deleteAnnotations() requiert désormais un string pour $name

• \ElggEntity::deleteIcon() requiert désormais un string pour $type

• \ElggEntity::deleteMetadata() requiert désormais un string pour $name

• \ElggEntity::deleteOwnedAnnotations() requiert désormais un string pour $name

• \ElggEntity::disable() requiert désormais un string pour $reason et un bool pour $recursive

• \ElggEntity::disableAnnotations() requiert désormais un string pour $name

• \ElggEntity::enable() requiert désormais un bool pour $recursive

• \ElggEntity::enableAnnotations() requiert désormais un string pour $name

• \ElggEntity::getAnnotationsAvg() requiert désormais un string pour $name

• \ElggEntity::getAnnotationsMax() requiert désormais un string pour $name

• \ElggEntity::getAnnotationsSum() requiert désormais un string pour $name

• \ElggEntity::getIcon() requiert désormais un string pour $size et $type

• \ElggEntity::getIconLastChange() requiert désormais un string pour $size et $type

• \ElggEntity::getIconURL() requiert désormais un string ou un array pour $params

• \ElggEntity::getObjectFromID() requiert désormais un int pour $id

• \ElggEntity::getOwnedAccessCollections() requiert désormais un array pour $options

• \ElggEntity::getOwnedAccessCollection() requiert désormais un string pour $subtype

• \ElggEntity::getMetadata() requiert désormais un string pour $name

• \ElggEntity::getVolatileData() requiert désormais un string pour $name

• \ElggEntity::hasIcon() requiert désormais un string pour $size et $type

• \ElggEntity::removeAllRelationships() ne permet plus de transmettre null à $relationship

• \ElggEntity::removeRelationship() requiert désormais un int pour $guid_two et un string pour $relationship

• \ElggEntity::saveIconFromElggFile() requiert désormais un string pour $type

• \ElggEntity::saveIconFromLocalFile() requiert désormais un string pour $input_name et $type

• \ElggEntity::saveIconFromUploadedFile() requiert désormais un string pour $input_name et $type

• \ElggEntity::setContainerGUID() requiert désormais un int pour $container_guid

• \ElggEntity::setDisplayName() requiert désormais un string pour $display_name

• \ElggEntity::setMetadata() requiert désormais un string pour $name et $value_type et un bool pour $multiple

• \ElggEntity::setTempMetadata() requiert désormais un string pour $name et un bool pour $multiple

• \ElggEntity::setVolatileData() requiert désormais un string pour $name

• \ElggEntity::updateLastAction() requiert désormais un int pour $posted

• \ElggMetadata::getObjectFromID() requiert désormais un int pour $id

• \ElggRelationship::getObjectFromID() requiert désormais un int pour $id

• \ElggFile::getDownloadURL() requiert désormais un bool pour $use_cookie et un string pour $expires

• \ElggFile::getInlineURL() requiert désormais un bool pour $use_cookie et un string pour $expires

• \ElggGroup::isToolEnabled() requiert désormais un string pour $name

• \ElggMenuItem::factory() requiert désormais un array pour $options

• \ElggTempFile::getDownloadURL() requiert désormais un bool pour $use_cookie et un string pour $expires

• \ElggTempFile::getInlineURL() requiert désormais un bool pour $use_cookie et un string pour $expires

• \Elgg\WebServices\Di\ApiRegistrationService::registerApiMethod() requiert désormais un \Elgg\WebServices\ApiMethod comme unique paramètre

Classes déplacées

• \ElggAutoP a été déplacé vers \Elgg\Views\AutoParagraph

• \ElggCache a été déplacé vers \Elgg\Cache\BaseCache

• \ElggDiskFilestore a été déplacé vers \Elgg\Filesystem\Filestore\DiskFilestore

• \ElggFilestore a été déplacé vers \Elgg\Filesystem\Filestore

• \ElggRewriteTester a été déplacé vers \Elgg\Router\RewriteTester

• \ElggTempDiskFilestore a été déplacé vers \Elgg\Filesystem\Filestore\TempDiskFilestore

• \Elgg\Database\SiteSecret a été déplacé vers \Elgg\Security\SiteSecret

APIs dépréciées

• elgg_clear_plugin_hook_handlers utilisez elgg_clear_event_handlers

• elgg_register_plugin_hook_handler utilisez elgg_register_event_handler

• elgg_trigger_plugin_hook utilisez elgg_trigger_event_results

• elgg_unregister_plugin_hook_handler utilisez elgg_unregister_event_handler

• get_user_by_email utilisez elgg_get_user_by_email

• get_user_by_username utilisez elgg_get_user_by_username

Classes retirées

• Elgg\WebServices\ApiKeyForm

• Loggable cette interface a été fusionnée dans la classe ElggData

Fonctions supprimées

• blog_prepare_form_vars

• bookmarks_prepare_form_vars

• discussion_prepare_form_vars

• elgg_get_breadcrumbs

• elgg_pop_breadcrumb

• elgg_set_email_transport utilisez _elgg_services()->set('mailer', ...)

• elgg_trigger_deprecated_plugin_hook

• elgg_ws_expose_function utilisez elgg-plugin.php ou l’événement 'register', 'api_methods'

• file_prepare_form_vars

• get_user_by_email utilisez elgg_get_user_by_email

• get_user_by_username utilisez elgg_get_user_by_username

• groups_prepare_form_vars

• messages_prepare_form_vars

• pages_prepare_form_vars

• thewire_latest_guid

Fonctions de classe supprimées

• \ElggWidget::saveSettings()

Événements supprimés

• access:collections:addcollection, collection utilisez la séquence create, access_collection

• access:collections:deletecollection, collection utilisez la séquence delete, access_collection

• prepare, breadcrumbs utilisez register, menu:breadcrumbs

• widget_settings, <widget_handler>

Exceptions supprimées

• \Elgg\Exceptions\InvalidParameterException

Constantes

• La constante REFERER mal orthographiée a été supprimée. Utilisez plutôt REFERRER.

• La constante REFERRER a été remplacée par une chaîne de caractères avec la valeur __elgg_referrer

De 4.2 à 4.3

Dépréciation de rel= »toggle » et rel= »popup »

Si vous utilisez rel="toggle" ou rel="popup" pour afficher du contenu caché, vous devrez mettre à jour votre code. Le javascript correct sera automatiquement chargé si vous dessinez du contenu en utilisant output/url (directement ou indirectement) et passez la classe elgg-popup ou elgg-toggle. Si vous avez besoin de fonctionnalités popup/toggle sur vos propres éléments, vous devrez définir la bonne classe et exiger le bon javascript (elgg/popup ou elgg/toggle).

Gestionnaires PAM

Les gestionnaires PAM, qui gèrent l’authentification, ont été retravaillés. L’enregistrement utilise désormais un service DI au lieu d’une variable statique dans une classe.

En raison de la refonte, les gestionnaires PAM peuvent désormais également être des classes invocables et le noyau Elgg (y compris le plugin Webservices) l’utilise. Si, en tant que développeur, vous avez dé-enregistré certains gestionnaires PAM, veuillez vérifier le nouveau code.

APIs dépréciées

Fonctions de la bibliothèque

• add_entity_relationship() utilisez \ElggEntity->addRelationship()

• add_translation() utilisez elgg()->translator->addTranslation()

• add_user_to_access_collection() utilisez \ElggAccessCollection->addMember()

• can_edit_access_collection() utilisez \ElggAccessCollection->canEdit()

• check_entity_relationship() utilisez \ElggEntity->hasRelationship() ou \ElggEntity->getRelationship()

• check_rate_limit_exceeded() utilisez elgg_is_authentication_failure_limit_reached()

• create_access_collection() utilisez elgg_create_access_collection()

• current_page_url() utilisez elgg_get_current_url()

• delete_access_collection() utilisez \ElggAccessCollection->delete()

• delete_relationship() utilisez \ElggRelationship->delete()

• elgg_authenticate() utilisez elgg_pam_authenticate()

• elgg_clear_sticky_value()

• elgg_delete_metadata_by_id() utilisez \ElggMetadata->delete()()

• elgg_get_engine_path()

• elgg_get_loaded_external_files() utilisez elgg_get_loaded_external_resources()

• elgg_register_external_view() utilisez elgg_register_ajax_view() et elgg_register_simplecache_view()

• elgg_unregister_external_view() utilisez elgg_unregister_ajax_view()

• execute_new_password_request() utilisez elgg_save_new_password()

• filter_tags() utilisez elgg_sanitize_input()

• find_active_users() utilisez elgg_get_entities()

• force_user_password_reset() utilisez \ElggUser->setPassword()

• generate_invite_code() utilisez elgg_generate_invite_code()

• generate_random_cleartext_password() utilisez elgg_generate_password()

• get_access_array() utilisez elgg_get_access_array()

• get_access_collection() utilisez elgg_get_access_collection()

• get_current_language() utilisez elgg_get_current_language()

• get_default_access() utilisez elgg_get_default_access()

• get_dir_size()

• get_entity_relationships() utilisez elgg_get_relationships()

• get_entity_statistics() utilisez elgg_get_entity_statistics()

• get_members_of_access_collection() utilisez \ElggAccessCollection->getMembers()

• get_online_users() utilisez elgg_list_entities()

• get_readable_access_level() utilisez elgg_get_readable_access_level()

• get_relationship() utilisez elgg_get_relationship()

• get_write_access_array() utilisez elgg_get_write_access_array()

• has_access_to_entity() utilisez \ElggEnity->hasAccess() ou elgg_has_access_to_entity()

• is_email_address() utilisez elgg_is_valid_email()

• log_login_failure() utilisez elgg_register_authentication_failure()

• login() utilisez elgg_login()

• logout() utilisez elgg_logout()

• parse_urls() utilisez elgg_parse_urls()

• register_pam_handler() utilisez elgg_register_pam_handler()

• register_user() utilisez elgg_register_user()

• remove_entity_relationship() utilisez \ElggEntity->removeRelationship()

• remove_entity_relationships() utilisez \ElggEntity->removeAllRelationships()

• remove_user_from_access_collection() utilisez \ElggAccessCollection->removeMember()

• reset_login_failure_count() utilisez elgg_reset_authentication_failures()

• send_new_password_request() utilisez elgg_request_new_password()

• string_to_tag_array() utilisez elgg_string_to_array()

• unregister_pam_handler() utilisez elgg_unregister_pam_handler()

Fonctions de classe

• \ElggEntity->deleteRelationships() utilisez \ElggEntity->removeAllRelationships()

• \ElggUser->getFriends() utilisez \ElggUser->getEntitiesFromRelationship()

• \ElggUser->getFriendsObjects() utilisez \ElggUser->getEntitiesFromRelationship()

• \ElggUser->getFriendsOf() utilisez \ElggUser->getEntitiesFromRelationship()

• \ElggUser->isFriend() utilisez \ElggUser->isFriendOf()

Evénements

• 'annotate', '{$entity->getType()}' utilisez l’événement 'create', 'annotate'

Hooks

• 'action_gatekeeper:upload_exceeded_msg', 'all'

• 'classes', 'icon' utilisez le hook 'view_vars', 'output/icon'

• 'fail', 'auth'

• 'file:icon:url', 'override' utilisez le hook 'entity:icon:url', 'object'

• 'find_active_users', 'system'

• 'form:values', 'blog'

• 'is_member', 'group' utilisez le hook 'gatekeeper', 'all'

• 'page_owner', 'system' utilisez les définitions de route

• 'status', 'user' utilisez l’événement 'create', 'object'

• 'validate', 'input' utilisez le hook 'sanitize', 'input'

Classes

• \ElggPAM utilisez elgg_pam_authenticate()

Paramètres de fonction remarquables

• Passer order_by_metadata ou order_by_annotation à elgg_get_entities est obsolète. Utilisez sort_by à la place.

Valeurs de configuration obsolètes

• elgg_settings_file

• path utilisez elgg_get_root_path()

• pluginspath utilisez elgg_get_plugins_path()

• site_guid utilisez elgg_get_site_entity()->guid

• sitedescription utilisez elgg_get_site_entity()->description

• sitename utilisez elgg_get_site_entity()->getDisplayName()

• url utilisez elgg_get_site_url()

De 4.1 à 4.2

Stash remplacé par Phpfastcache

La bibliothèque de cache interne Stash a été remplacée par Phpfastcache. Phpfastcache est mieux entretenu, fournit plus de pilotes de cache et ajoute plus de fonctionnalités à l’implémentation du cache. Cette modification ne devrait causer aucun problème sur les installations existantes. Si vous avez configuré Memcache ou Redis dans votre elgg-config/settings.php, vous pourriez avoir besoin de mettre à jour votre configuration.

Valeurs booléennes des Metadata et des Annotation

Le modèle de base de données a été modifié pour conserver les valeurs booléennes intactes entre l’enregistrement et la récupération. Avant ce changement, si vous enregistriez une valeur booléenne, elle était renvoyée sous la forme d’un entier. Désormais elle reste un booléen.

Avertissement

Si vous avez précédemment enregistré des valeurs booléennes, elles seront sous forme d’entiers dans la base de données (jusqu’à ce qu’elles soient de nouveau enregistrées).

Fonctions des messages système

Le fonctions system_message() et register_error() ont été remplacées par elgg_register_success_message() et elgg_register_error_message(). Les nouvelles fonctions ont la capacité de passer des options supplémentaires au registre des messages système.

Fonctions Javascript

Les bibliothèques javascript Elgg ont connu une refonte massive. Beaucoup de fonctions ont été dépréciées. Vous pouvez trouver toutes les fonctions obsolètes et globales dans views/default/core/js/deprecated.js.

Messages système

Si vous utilisez les messages système dans votre javascript, vous devriez maintenant requérir le module elgg/system_messages.

Jetons de sécurité

Si vous utilisez elgg.security.addToken() dans votre javascript, vous devriez maintenant requérir le module elgg/security.

Traductions

Si vous utilisez elgg.echo() dans votre javascript, vous devriez maintenant requérir le module elgg/i18n.

Fonctions UI

Le menu déroulant de l’utilisateur n’est plus initialisé à partir du fichier ui.js global, mais requiert le javascript à la demande à partir de la vue icon/user/default.

ElggUser & ElggEntity

Les équivalents javascript de ElggUser et ElggEntity ne devraient plus être utilisés. L’entité utilisateur connecté ne devrait plus être référencée dans les données de la page elgg.session.user. Vous pouvez trouver ses attributs dans elgg.user sous forme de tableau.

Sécurité

output/url a maintenant ajouté des fonctionnalités de sécurité pour aider à bloquer les sorties générées par des utilisateurs malveillants. La vue prend en charge $vars['allowed_schemes'] qui contient une liste des schémas d’URL autorisés. Le $vars['href'] fourni est mis en correspondance avec la liste autorisée. Si l’URL n’a pas de schéma autorisé, l’URL sera préfixée par denied:.

Cela aidera à empêcher que des entrées utilisateur telles que javascript:alert('just testing'); ne soient présentées aux utilisateurs.

Par défaut, les schémas suivants sont autorisés : http, https, ftp, sftp, ssh, file

Si vous utilisez le modèle elgg_view('output/url', ['text' => 'something', 'href' => 'javascript:void(0);']) mettez à jour votre code pour définir `` href`` à false.

Groupes

Le nom du menu des onglets de la page des membres du groupe a été remplacé pour utiliser la logique de menu de filtre par défaut. Réécrivez vos hooks de plugin menu:groups_members en menu:filter:groups/members. Puisqu’il s’agit d’un menu différent, l’entité de groupe actuelle est désormais disponible dans le paramètre de hook filter_entity.

APIs dépréciées

Fonctions de la bibliothèque

• elgg_view_menu_item() utilisez elgg_view('navigation/menu/elements/item/url', ['item' => $myMenuItem])

• register_error() utilisez elgg_register_error_message()

• system_message() utilisez elgg_register_success_message()

De 4.0 à 4.1

Capacités des entités

Une nouvelle façon d’enregistrer les capacités des entités a été introduite. Les fonctions associées suivantes ont été dépréciées :

• elgg_register_entity_type() utilisez elgg_entity_enable_capability($type, $subtype, 'searchable')

• elgg_unregister_entity_type() utilisez elgg_entity_disable_capability($type, $subtype, 'searchable')

• get_registered_entity_types() utilisez elgg_entity_types_with_capability('searchable')

• is_registered_entity_type() utilisez elgg_entity_has_capability($type, $subtype, 'searchable')

La variable de configuration registered_entities n’est plus disponible.

Les capacités actuellement implémentées sont “commentable”, “likable” et “searchable”.

Commentaires imbriqués

La prise en charge des commentaires imbriqués a été ajoutée. Cette fonctionnalité doit être activée dans les paramètres du site. Pour faire ce travail, des modifications ont été apportées aux commentaires liés à JavaScript et CSS. Si vous utilisez un style spécifique ou avez des fonctionnalités personnalisées liées à cette fonctionnalité, vous devrez peut-être leur accorder une attention supplémentaire.

APIs dépréciées

Fonctions de la bibliothèque

• elgg_get_version() utilisez elgg_get_release()

• get_user_by_code() utilisez elgg_get_user_by_persistent_token() où vous devez uniquement fournir le jeton, pas le jeton haché

Hooks plugin

• 'likes:is_likable', '<type>:<subtype>' utilisez $entity->hasCapability('likable')

De 3.x à 4.0

Composer

Pré-requis PHP

Pour être compatible avec PHP 8, nous devions augmenter la version minimale de PHP à 7.4. Les versions PHP < 7.4 sont déjà en fin de vie.

Projet composer

La racine du projet composer n’est plus gérée comme un plugin semi-fonctionnel. Les langues du répertoire languages ne sont plus importées, les vues du répertoire views ne sont plus enregistrées, les services PHP DI du elgg-services.php ne sont plus enregistrés et le fichier start.php n’est plus inclus.

Si vous avez besoin d’une modification spécifique à votre installation Elgg, vous devez créer un plugin et vous assurer que le plugin est le dernier dans l’ordre des plugins pour vous permettre de surcharger tout ce que vous avez besoin de changer.

Doctrine DBAL

Elgg a remplacé la v2 de la dépendance doctrine/dbal par la v3. L’un des changements les plus notables est que si vous travaillez avec QueryBuilders et utilisez la fonction $qb->fetch(), vous n’obtiendrez plus un objet, mais un tableau. Si vous voulez que vos lignes soient utilisables comme classes, vous pouvez utiliser elgg()->db->getData($qb). Un autre changement important est que si vous fournissez vos propres paramètres de requête, vous ne devez plus préfixer les clés avec deux points dans les paramètres, mais continuer à le faire dans la requête.

PHP-DI

Cette fonctionnalité a été mise à jour pour utiliser la dernière version de PHP-DI. Le changement le plus notable pour Elgg est la nécessité de changer la définition de votre service de plugin pour utiliser \DI\create() au lieu de \DI\object().

ZendMail remplacé par LaminasMail

En raison de la dépréciation de la bibliothèque Zend\Mail et de son remplacement par Laminas\Mail toutes les références ont été mises à jour.

Dépendances composer supprimées

• bower-asset/jquery-treeview les js et css associés ne sont plus disponibles dans le système

• bower-asset/jquery.imgareaselect les js et css associés ne sont plus disponibles dans le système

• npm-asset/formdata-polyfill tous les navigateurs modernes ont un support, plus besoin d’un polyfill

• npm-asset/jquery-form utilisez la fonctionnalité native FormData

• npm-asset/weakmap-polyfill tous les navigateurs modernes ont un support, plus besoin d’un polyfill

• simpletest/simpletest

JavaScript

AJAX

Les fonctions d’assistance Ajax suivantes ont été supprimées au profit de leurs homologues dans le module asynchrone elgg/Ajax. * elgg.action() * elgg.get() * elgg.getJSON() * elgg.post()

La fonction ajax elgg.api a été déplacée vers la fonction executeMethod dans le module asynchrone elgg/webservices du plugin webservices. D’autres fonctions et attributs elgg.ajax ont été supprimés du système. De plus, la gestion héritée des appels ajax a été supprimée du système.

Classes

La logique javascript pour démarrer automatiquement du javascript pour votre plugin et enregistrer des hooks via la classe Elgg/Plugin a été supprimée du système. Cette fonctionnalité n’a jamais été utilisée par le noyau et à peine vue dans les plugins. Utilisez le javascript chargé par AMD ou étendez elgg.js pour un javascript toujours chargé.

La classe javascript ElggPriorityList a été supprimée du système.

Hooks système

Les modules AMD pour elgg/init et elgg/ready ont été supprimés. Le hook init, system est toujours disponible, mais cela n’a de sens de s’appuyer sur ce hook que pour des bibliothèques js non chargées par AMD. Les déclencheurs boot, system et ready, system ont été supprimés du système. Remplacez par init, system pour le même effet.

jQuery

La bibliothèque jQuery a été mise à jour vers la dernière version (v3.5.x). Il s’agit d’une mise à jour majeure de la version utilisée dans Elgg 3.x. Pour plus d’informations sur ce qui a changé entre ces versions, vous devriez jeter un œil au site Web de jQuery.

jQuery UI

La bibliothèque jQuery UI a été mise à jour vers la v1.12.x. La bibliothèque n’est plus chargée en entier par défaut. Si vous devez utiliser des fonctionnalités de la bibliothèque, vous pouvez les exiger dans votre propre script. Par exemple, pour pouvoir utiliser la fonctionnalité de tri, procédez comme suit :

require('jquery-ui/widgets/sortable');

// or in your own AMD script
define(['jquery-ui/widgets/sortable'], function() {
        // use the sortable
});

Changements JS divers

• Le module AMD elgg/widgets ne renvoie plus d’objet et ne vous oblige plus à appeler init sur le module

Notifications

La gestion des notifications avant Elgg 1.9 a été supprimée. Les fonctions et hooks associés n’existent plus.

Abonnements

La relation dans la base de données qui stocke la méthode d’abonnement pour les notifications a été modifiée de notifymethod à notify:method.

Destinataires multiples

Un ElggEmail prend désormais en charge plusieurs destinataires en To, Cc et Bcc. Les fonctions de récupération associées telles que getTo() renverront désormais toujours un tableau.

Paramètres

Un stockage générique pour les préférences de notification a été introduit dans \ElggUser::setNotificationSetting() et \ElggUser::getNotificationSettings(), les paramètres de notification ont maintenant un but “purpose”.

Par exemple, group_join peut être utilisé pour gérer l’abonnement par défaut que vous obtenez avec un groupe lorsque vous rejoignez le groupe.

Le plugin Notifications a une gestion générique de l’affichage et de l’enregistrement des paramètres. Pour afficher le paramètre, étendez la vue notifications/settings/records (pluriel) avec une vue qui utilise notifications/settings/record (singulier).

Lors de la demande de paramètres de notification autres que le paramètre par défaut, si l’utilisateur n’a pas encore enregistré de paramètre, cela reviendra aux paramètres de notification par défaut.

La gestion des préférences de notification pour l’ajout de nouveaux utilisateurs à une collection d’amis a été supprimée.

Salutation et signature de la notification

Pour pouvoir avoir une salutation et une signature plus génériques pour les notifications de courrier sortant, nous avons supprimé ces textes de diverses chaînes de traduction et les avons déplacés vers des traductions génériques. Cela signifie que vous devrez mettre à jour vos traductions pour refléter le nouveau texte et également vérifier votre code pour les utilisations des notifications où vous fournissez votre propre texte de salutation ou de signature. Vous pouvez en savoir plus sur ce nouveau comportement dans Notifications.

Plugin Notifications

Le plugin Notifications a été supprimé. Toutes les fonctionnalités du plugin font désormais partie du noyau Elgg. Certaines pages (comme les paramètres de notification de groupe) ont été déplacées vers le bon plugin.

Cela signifie que les gestionnaires d’événements, les gestionnaires de crochets, les actions, les vues et les clés de langue ont été déplacés, retirés ou renommés.

Gestion de l’événement de notification

Les hooks de notification ne reçoivent plus le paramètre origin.

Notification sur le site

Le plugin de notifications du site affiche désormais l’objet de la notification par défaut. Si une notification de site a été créée avec la fonction d’usine SiteNotification::factory(), davantage d’informations de la notification d’origine sont stockées avec la notification de site :

• Le sujet de la notification subject est stocké dans title

• Le résumé de la notification summary est stocké dans summary

• Le corps de la notification body est stocké dans description

Séparation de OkResponse, ErrorResponse et RedirectResponse

Les classes Elgg\Http\ErrorResponse et Elgg\Http\RedirectResponse étaient des extensions de Elgg\Http\OkReponse, ce qui compliquait la validation des réponses (par exemple dans les hooks). Les classes ont été séparées pour permettre des contrôles plus faciles et plus clairs.

Toutes les classes étendent maintenant Elgg\Http\Response et implémentent Elgg\Http\ReponseBuilder. Le code d’erreur HTTP par défaut lors de l’utilisation de elgg_error_response() a été modifié pour renvoyer un code d’état 400.

Modèle de données

Modifications de schéma

• Les colonnes access_id, owner_guid et enabled dans la table metadata ont été supprimées

• La colonne enabled dans la table river a été supprimée

• La colonne relationship dans la table entity_relationships a maintenant une longueur maximale de 255 (au lieu de 50)

Attributs ElggEntity

Définir les attributs type, subtype et enabled d’une ElggEntity n’est plus possible en utilisant la fonction de définition magique. Changer le type n’est plus possible, utilisez la classe de base correcte pour votre entité (ex. ElggObject, ElggGroup ou ElggUser).

Pour changer le subtype utilisez la fonction setSubtype($subtype)

// this no longer works and throws an \Elgg\Exceptions\InvalidArgumentException
$object = new ElggObject();
$object->subtype = 'my_subtype';

// The correct use is
$object->setSubtype('my_subtype');

Pour changer l’état activé enabled d’une entité utilisez les fonctions correctes

// this no longer works and throws an \Elgg\Exceptions\InvalidArgumentException
$object = new ElggObject();
$object->enabled = 'no';

// The correct use is
$object->enable(); // to enable
$object->disable(); // to disable

Attributs ElggUser

La définition des métadonnées admin et banned d’un ElggUser n’est plus possible en utilisant la fonction de définition magique.

Pour changer l’état d’administrateur admin, utilisez les fonctions makeAdmin() and removeAdmin()

// this no longer works and throws an \Elgg\Exceptions\InvalidArgumentException
$user = new ElggUser()
$user->admin = 'yes';

// The correct use is
$user->makeAdmin(); // to give the admin role
$user->removeAdmin(); // to remove the admin role

Pour changer l’état de bannissement banned, utilisez les fonctions ban() et unban()

// this no longer works and throws an \Elgg\Exceptions\InvalidArgumentException
$user = new ElggUser()
$user->banned = 'yes';

// The correct use is
$user->ban(); // to ban the user
$user->unban(); // to unban the user

Développement de plugin

Initialisation du plugin

Les fichiers suivants ne sont plus inclus lors de l’amorçage d’un plugin :

• activate.php utilisez PluginBootstrap->activate()

• deactivate.php utilisez PluginBootstrap->deactivate()

• views.php utilisez elgg-plugin.php

• start.php utilisez elgg-plugin.php et/ou PluginBootstrap

Manifeste du plugin

Le fichier manifeste du plugin n’est plus utilisé. Des éléments du manifeste ont été supprimés ou déplacés vers différents emplacements.

Il n’est plus possible d’exiger un paramètre php ini spécifique.

• pré-requis de version de php -> composer require

• pré-requis d’extension php -> composer require

• conflits du plugin -> conflits composer

• pré-requis du plugin -> elgg-plugin

• pré-requis de position du plugin -> elgg-plugin

• version du plugin -> elgg-plugin

• activation du plugin lors de l’installation -> elgg-plugin

• nom du plugin -> elgg-plugin

• description du plugin -> composer.json

• catégories du plugin -> composer.json

• licence du plugin -> composer.json

• lien vers le repo du plugin -> composer.json

• lien de publication du plugin -> composer.json

• lien vers la page d’accueil du plugin -> composer.json

• auteurs/contributeurs du plugin -> composer.json

Champs de configuration hookables

Certains plugins avaient la possibilité de configurer les champs des entités dans leur configuration. Ces fonctionnalités ont été remplacées par un service central qui fournit un mécanisme pour demander une configuration de champ hookable pour un certain type/sous-type.

Vous pouvez demander ces configurations à l’aide du code suivant :

$fields = elgg()->fields->get('<entity_type>', '<entity_subtype');

Les résultats seront un tableau avec des configurations de champs utilisables dans elgg_view_field($field)

La fonctionnalité associée suivante a été remplacée par cette nouvelle méthode :

• La configuration pour pages n’est plus disponible dans elgg_get_config('pages') utilisez elgg()->fields->get('object', 'page')

• La configuration pour group n’est plus disponible dans elgg_get_config('group') utilisez elgg()->fields->get('group', 'group')

• La configuration de profile_fields n’est plus disponible dans elgg_get_config('profile_fields') utilisez elgg()->fields->get('user', 'user')

• La configuration de pages, group et user:profile via elgg_set_config n’est plus possible. Utilisez une fonction de rappel sur le hook fields, <entity_type>:<entity_subtype>.

• Le hook profile:fields, group a été remplacé par le nouveau hook fields, group:group

• Le hook profile:fields, user a été remplacé par le nouveau hook fields, user:user

Menus

Au lieu d’enregistrer _elgg_setup_vertical_menu et _elgg_menu_transform_to_dropdown pour les menus, ceci est remplacé par l’utilisation des variables de menu prepare_vertical et prepare_dropdown. Les régler sur true vous donnera le même effet. Cela permet un contrôle individuel dans les vues lorsque cela est nécessaire.

Le marquage automatique comme sélectionné “selected” des éléments de menu parent de l’élément de menu sélectionné se produira désormais toujours pour chaque menu.

Onglets de filtre

La préparation des onglets pour le menu de filtrage en utilisant la fonction elgg_get_filter_tabs() et le hook 'filter_tabs', '<context>' a été supprimée. Vous pouvez maintenant utiliser le hook 'register', 'menu:filter:filter' pour ajouter/supprimer des éléments depuis le même endroit.

Les onglets all, mine et friends seront générés automatiquement si des routes sont disponibles pour des pages similaires à la route actuelle. Par exemple si la route actuelle est collection:object:blog:all les onglets seront générés pour la route collection:object:blog:owner et collection:object:blog:friends.

Menu du titre

Le menu title sera désormais rempli avec le menu entity si l’entité entity est fournie à la mise en page. C’est surtout utile sur la page d’informations d’une entité (par exemple blog/view). La plupart des entrées du menu entity seront ajoutées à un menu déroulant - à l’exception de l’élément de menu edit (si disponible) : cet élément sera présenté à côté du menu déroulant.

echo elgg_view_page('title', [
        'content' => elgg_view_entity($entity),
        'entity' => $entity, // <= will make sure the entity menu is available in the title menu
]);

Enregistrement des noms de métadonnées de balise

En raison de diverses limitations de cette implémentation, elle a été supprimée du système. Les fonctions d’API associées suivantes ont été supprimées :

• elgg_get_registered_tag_metadata_names()

• elgg_register_tag_metadata_name()

• elgg_unregister_tag_metadata_name()

Si vous avez besoin que des champs spécifiques puissent être recherchés, vous devez les enregistrer avec les crochets search:fields associés. Les clés de langue des balises tagnames:xxx associées ne sont plus enregistrées dans le système.

La fonction ElggEntity::getTags() renverra désormais uniquement les métadonnées de balise avec le nom tags par défaut. Si vous souhaitez vérifier des champs supplémentaires contenant des balises, vous devez le demander spécifiquement.

Widgets par défaut

La gestion magique de la création de widgets par défaut a été réduite. Vous devez maintenant enregistrer le rappel Elgg\Widgets\CreateDefaultWidgetsHandler dans l’événement lorsque vous souhaitez que les widgets par défaut soient créés. La configuration default_widget_info n’est plus présente dans le système. Utilisez le hook get_list, default_widgets pour obtenir la valeur.

Vous devez également mettre à jour les données de votre gestionnaire de hook get_list, default_widgets pour renvoyer event_name (anciennement event) et event_type.

Permissions du conteneur

Les paramètres de fonction pour ElggEntity::canWriteToContainer() nécessitent maintenant un $type et un $subtype à transmettre. Il s’agit de donner plus d’informations au hook résultant afin de pouvoir déterminer si un utilisateur est autorisé à accéder en écriture au conteneur.

Plugins

Plugin Activity

Ce plugin a reçu une réécriture bien nécessaire. Les différentes pages (all/owner/friends) ont maintenant leurs propres vues de ressources et de listes.

Plugin Diagnostics

Ce plugin a été supprimé, mais l’action pour générer un rapport est toujours disponible. Vous pouvez le trouver sur la page d’administration Information/Server.

Plugin Discussions

• Ce plugin n’ajoute plus d’onglet au menu des filtres sur les pages des groupes

• L’élément de menu du site discussions est maintenant toujours présent

Plugin Search

La sortie des résultats de la recherche n’utilise plus la classe d’assistance Elgg\Search\Formatter pour la préparation du contenu du résultat. Cette logique a été entièrement déplacée dans les vues.

Les fonctions associées prepareEntity et getSearchView dans la classe Elgg\Search\Service ont été supprimées.

Le hook search:format, entity a été retiré.

Plugin Web services

Le plugin Web Services a reçu une réécriture complète, ceci est principalement lié au fonctionnement interne du plugin.

Classes retirées

• ElggHMACCache a été remplacé par _elgg_services()->hmacCacheTable (pour un usage interne uniquement)

• Elgg\Notifications\Event a été remplacé par Elgg\Notifications\SubscriptionNotificationEvent

Fonctions supprimées

• create_api_user() a été remplacé par _elgg_services()->apiUsersTable->createApiUser()

• create_user_token() a été remplacé par _elgg_services()->usersApiSessions->createToken()

• get_api_user() a été remplacé par _elgg_services()->apiUsersTable->getApiUser()

• get_standard_api_key_array() utilisez \Elgg\WebServices\ElggApiClient::setApiKeys()

• get_user_tokens() a été remplacé par _elgg_services()->usersApiSessions->getUserTokens()

• pam_auth_session()

• remove_api_user() a été remplacé par _elgg_services()->apiUsersTable->removeApiUser()

• remove_expired_user_tokens() a été remplacé par _elgg_services()->usersApiSessions->removeExpiresTokens()

• remove_user_token() a été remplacé par _elgg_services()->usersApiSessions->removeToken()

• send_api_call() utilisez \Elgg\WebServices\ElggApiClient

• send_api_get_call() utilisez \Elgg\WebServices\ElggApiClient

• send_api_post_call() utilisez \Elgg\WebServices\ElggApiClient

• service_handler()

• validate_user_token() a été remplacé par _elgg_services()->usersApiSessions->validateToken()

• ws_page_handler()

• ws_rest_handler() a été remplacé par \Elgg\WebServices\RestServiceController

Changements divers

• La valeur de configuration pour servicehandler a été supprimée

• Dans certains cas extrêmes, la valeur par défaut d’un paramètre API ne sera pas appliquée

Fonctions typées

Les fonctions suivantes ont maintenant leurs arguments typés, cela peut provoquer des erreurs TypeError. De plus, certaines fonctions de classe ont une valeur de retour typée, et vous devriez mettre à jour votre définition de fonction.

Paramètres de la fonction de classe

• ElggEntity::setLatLong() requiert maintenant un nombre à virgule flottante float pour $lat et $long

• ElggUser::setNotificationSetting() requiert maintenant une chaîne de caractères string pour $method et un booléen bool pour $enabled

• Elgg\Database\Seeds\Seed::__construct() requiert maintenant un entier int pour $limit

• Elgg\Http\ErrorResponse::__construct() requiert maintenant un entier int pour $status_code

• Elgg\Http\OkResponse::__construct() requiert maintenant un entier int pour $status_code

• Elgg\Http\RedirectResponse::__construct() requiert maintenant un entier int pour $status_code

• Elgg\I18n\Translator::getInstalledTranslations() requiert maintenant un booléen bool pour $calculate_completeness

• SiteNotification::setActor() requiert maintenant une chaîne ElggEntity pour $entity

• SiteNotification::setURL() requiert maintenant une chaîne de caractères string pour $url

• SiteNotification::setRead() requiert maintenant un booléen bool pour $read

Type de retour d’une fonction de classe

• Elgg\Upgrade\Batch::getVersion() requiert maintenant une valeur de retour entière int

• Elgg\Upgrade\Batch::shouldBeSkipped() requiert maintenant une valeur de retour booléenne bool

• Elgg\Upgrade\Batch::needsIncrementOffset() requiert maintenant une valeur de retour booléenne bool

• Elgg\Upgrade\Batch::countItems() requiert maintenant un entier int comme valeur de retour

• Elgg\Upgrade\Batch::run() requiert maintenant une valeur de retour Elgg\Upgrade\Result

Paramètres de la fonction de bibliothèque

• add_user_to_access_collection() requiert maintenant un entier int pour $user_guid et $collection_id

• can_edit_access_collection() requiert maintenant un entier int pour $collection_id et $user_guid

• create_access_collection() requiert maintenant une chaîne de caractères string pour $name et un entier int pour $owner_guid

• delete_access_collection() requiert maintenant un entier int pour $collection_id

• elgg_action_exists() exige maintenant une chaîne de caractères string pour $action

• elgg_add_admin_notice() requiert maintenant une chaîne de caractères string pour $id et $message

• elgg_admin_notice_exists() requiert maintenant une chaîne de caractères string pour $id

• elgg_annotation_exists() requiert maintenant un entier int pour $entity_guid, une chaîne de caractères string pour $name et un entier int pour $owner_guid

• elgg_delete_admin_notice() requiert maintenant une chaîne de caractères string pour $id

• elgg_delete_annotation_by_id() requiert maintenant un entier int pour $id

• elgg_deprecated_notice() requiert maintenant une chaîne de caractères string pour $msg et $dep_version

• elgg_error_response() requiert maintenant un entier int pour $status_code

• elgg_get_access_collections() requiert maintenant un tableau array pour $options

• elgg_get_annotation_from_id() requiert maintenant un entier int pour $id

• elgg_get_subscriptions_for_container() requiert maintenant un entier int pour $container_guid

• elgg_get_plugin_from_id() requiert maintenant une chaîne de caractères string pour $plugin_id

• elgg_get_plugin_setting() requiert maintenant une chaîne de caractères string pour $name et $plugin_id

• elgg_get_plugin_user_setting() requiert maintenant une chaîne de caractères string pour $name et $plugin_id et un entier int pour $user_guid

• elgg_get_plugins() requiert maintenant une chaîne de caractères string pour $status

• elgg_get_river_item_from_id() requiert maintenant un entier int pour $id

• elgg_list_annotations() requiert maintenant un tableau array pour $options

• elgg_ok_response() requiert maintenant un entier int pour $status_code

• elgg_plugin_exists() requiert maintenant une chaîne de caractères string pour $plugin_id

• elgg_redirect_response() requiert maintenant un entier int pour $status_code

• elgg_register_action() requiert maintenant une chaîne de caractères string pour $action et $access

• elgg_send_email() requiert maintenant un \Elgg\Email pour $email

• elgg_set_plugin_user_setting() requiert maintenant une chaîne de caractères string pour $name et $plugin_id et un entier int pour $user_guid

• elgg_unregister_action() requiert maintenant une chaîne de caractères string pour $action

• get_access_array() requiert maintenant un entier int pour $user_guid

• get_access_collection() requiert maintenant un entier int pour $collection_id

• get_entity_statistics() requiert maintenant un entier int pour $owner_guid

• get_members_of_access_collection() requiert maintenant un entier int pour $collection_id et un booléen bool pour $guids_only

• get_readable_access_level() requiert maintenant un entier int pour $entity_access_id

• get_write_access_array() requiert maintenant un entier int pour $user_guid et un booléen bool for $flush

• has_access_to_entity() requiert maintenant une ElggEntity pour $entity et ElggUser pour $user

• remove_user_from_access_collection() requiert maintenant un entier int pour $user_guid et $collection_id

• system_log_get_log() requiert maintenant un tableau array pour $options

• messageboard_add() requiert maintenant les types ElggUser, ElggUser, string et int

• elgg_register_external_file() requiert maintenant que tous les arguments soient de type string

• elgg_unregister_external_file() requiert maintenant que tous les arguments soient de type string

• elgg_load_external_file() requiert maintenant que tous les arguments soient de type string

• elgg_get_loaded_external_files() requiert maintenant que tous les arguments soient de type string

Modification dans les paramètres de fonction

Fonctions de classe

• Elgg\Http\ResponseBuilder::setStatusCode() n’a plus de valeur par défaut

• ElggEntity::canWriteToContainer() n’a plus de valeur par défaut pour $type et $subtype mais ces paramètres sont obligatoires

Fonctions de la bibliothèque

• elgg_get_page_owner_guid() n’accepte plus $guid comme paramètre

• get_access_array() n’accepte plus $flush comme paramètre

• elgg_register_external_file() n’accepte plus $priority comme paramètre

Renommage des fonctions de callback du gestionnaire de hook/d’événement

Une attention particulière est requise si vous désenregistrez les callbacks dans vos plugins car vous devrez peut-être mettre à jour votre code.

Noyau

• access_friends_acl_get_name() changé pour Elgg\Friends\AclNameHandler::class

• access_friends_acl_add_friend() changé pour Elgg\Friends\AddToAclHandler::class

• access_friends_acl_create() changé pour Elgg\Friends\CreateAclHandler::class

• access_friends_acl_remove_friend() changé pour Elgg\Friends\RemoveFromAclHandler::class

• _elgg_add_admin_widgets() changé pour Elgg\Widgets\CreateAdminWidgetsHandler::class

• _elgg_admin_check_admin_validation() changé pour Elgg\Users\Validation::checkAdminValidation()

• _elgg_admin_header_menu() changé pour Elgg\Menus\AdminHeader::register() et Elgg\Menus\AdminHeader::registerMaintenance()

• _elgg_admin_footer_menu() changé pour Elgg\Menus\AdminFooter::registerHelpResources()

• _elgg_admin_notify_admins_pending_user_validation() changé pour Elgg\Users\Validation::notifyAdminsAboutPendingUsers()

• _elgg_admin_page_menu() changé pour Elgg\Menus\Page::registerAdminAdminister() et Elgg\Menus\Page::registerAdminConfigure() et Elgg\Menus\Page::registerAdminInformation()

• _elgg_admin_page_menu_plugin_settings() changé pour Elgg\Menus\Page::registerAdminPluginSettings()

• _elgg_admin_prepare_admin_notification_make_admin() changé pour Elgg\Notifications\MakeAdminUserEventHandler

• _elgg_admin_prepare_admin_notification_remove_admin() changé pour Elgg\Notifications\RemoveAdminUserEventHandler

• _elgg_admin_prepare_user_notification_make_admin() changé pour Elgg\Notifications\MakeAdminUserEventHandler

• _elgg_admin_prepare_user_notification_remove_admin() changé pour Elgg\Notifications\RemoveAdminUserEventHandler

• _elgg_admin_save_notification_setting() changé pour Elgg\Users\Settings::setAdminValidationNotification()

• _elgg_admin_set_registration_forward_url() changé pour Elgg\Users\Validation::setRegistrationForwardUrl()

• _elgg_admin_user_unvalidated_bulk_menu() changé pour Elgg\Menus\UserUnvalidatedBulk::registerActions()

• _elgg_admin_user_validation_login_attempt() changé pour Elgg\Users\Validation::preventUserLogin()

• _elgg_admin_user_validation_notification() changé pour Elgg\Users\Validation::notifyUserAfterValidation()

• _elgg_admin_upgrades_menu() changé pour Elgg\Menus\Filter::registerAdminUpgrades()

• Les actions _elgg_cache_init() ont été combinées dans Elgg\Application\SystemEventHandlers::ready()

• _elgg_clear_caches() changé pour Elgg\Cache\EventHandlers::clear()

• _elgg_comments_access_sync() changé pour Elgg\Comments\SyncContainerAccessHandler::class

• _elgg_comments_container_permissions_override() changé pour Elgg\Comments\ContainerPermissionsHandler::class

• _elgg_comments_permissions_override() changé pour Elgg\Comments\EditPermissionsHandler::class

• _elgg_comments_prepare_content_owner_notification() changé pour Elgg\Notifications\CreateCommentEventHandler

• _elgg_comments_prepare_notification() changé pour Elgg\Notifications\CreateCommentEventHandler

• _elgg_comments_social_menu_setup() changé pour Elgg\Menus\Social::registerComments()

• _elgg_create_default_widgets() changé pour Elgg\Widgets\CreateDefaultWidgetsHandler::class

• _elgg_create_notice_of_pending_upgrade() changé pour Elgg\Upgrade\CreateAdminNoticeHandler::class

• _elgg_db_register_seeds() changé pour Elgg\Database\RegisterSeedsHandler::class

• _elgg_disable_caches() changé pour Elgg\Cache\EventHandlers::disable()

• _elgg_default_widgets_permissions_override() changé pour Elgg\Widgets\DefaultWidgetsContainerPermissionsHandler::class

• _elgg_disable_password_autocomplete() changé pour Elgg\Input\DisablePasswordAutocompleteHandler::class

• _elgg_enable_caches() changé pour Elgg\Cache\EventHandlers::enable()

• _elgg_filestore_move_icons() changé pour Elgg\Icons\MoveIconsOnOwnerChangeHandler::class

• _elgg_filestore_touch_icons() changé pour Elgg\Icons\TouchIconsOnAccessChangeHandler::class

• _elgg_head_manifest() changé pour Elgg\Views\AddManifestLinkHandler::class

• _elgg_annotations_default_menu_items() changé pour Elgg\Menus\Annotation::registerDelete()

• _elgg_walled_garden_menu() changé pour Elgg\Menus\WalledGarden::registerHome()

• _elgg_site_menu_init() changé pour Elgg\Menus\Site::registerAdminConfiguredItems()

• _elgg_site_menu_setup() changé pour Elgg\Menus\Site::reorderItems()

• _elgg_entity_menu_setup() changé pour Elgg\Menus\Entity::registerEdit() et Elgg\Menus\Entity::registerDelete()

• _elgg_entity_navigation_menu_setup() changé pour Elgg\Menus\EntityNavigation::registerPreviousNext()

• _elgg_enqueue_notification_event() changé pour Elgg\Notifications\EnqueueEventHandler::class

• _elgg_groups_container_override() changé pour Elgg\Groups\MemberPermissionsHandler::class

• _elgg_groups_comment_permissions_override() changé pour Elgg\Comments\GroupMemberPermissionsHandler::class

• _elgg_htmlawed_filter_tags() changé pour Elgg\Input\ValidateInputHandler::class

• _elgg_invalidate_caches() changé pour Elgg\Cache\EventHandlers::invalidate()

• _elgg_widget_menu_setup() changé pour Elgg\Menus\Widget::registerEdit() et Elgg\Menus\Widget::registerDelete()

• _elgg_login_menu_setup() changé pour Elgg\Menus\Login::registerRegistration() et Elgg\Menus\Widget::registerResetPassword()

• _elgg_nav_public_pages() changé pour Elgg\WalledGarden\ExtendPublicPagesHandler::class

• _elgg_notifications_cron() changé pour Elgg\Notifications\ProcessQueueCronHandler::class

• _elgg_notifications_smtp_default_message_id_header() changé pour Elgg\Email\DefaultMessageIdHeaderHandler::class

• _elgg_notifications_smtp_thread_headers() changé pour Elgg\Email\ThreadHeadersHandler::class

• _elgg_rebuild_public_container() changé pour Elgg\Cache\EventHandlers::rebuildPublicContainer()

• _elgg_river_update_object_last_action() changé pour Elgg\River\UpdateLastActionHandler::class

• _elgg_rss_menu_setup() changé pour Elgg\Menus\Footer::registerRSS()

• _elgg_plugin_entity_menu_setup() changé pour Elgg\Menus\Entity::registerPlugin()

• _elgg_purge_caches() changé pour Elgg\Cache\EventHandlers::purge()

• _elgg_river_menu_setup() changé pour Elgg\Menus\River::registerDelete()

• _elgg_save_notification_user_settings() changé pour Elgg\Notifications\SaveUserSettingsHandler::class

• _elgg_session_cleanup_persistent_login() changé pour Elgg\Users\CleanupPersistentLoginHandler::class

• _elgg_set_lightbox_config() changé pour Elgg\Javascript\SetLightboxConfigHandler::class

• _elgg_set_user_default_access() changé pour Elgg\Users\Settings::setDefaultAccess()

• _elgg_set_user_email() changé pour Elgg\Users\Settings::setEmail()

• _elgg_set_user_password() changé pour Elgg\Users\Settings::setPassword()

• _elgg_set_user_language() changé pour Elgg\Users\Settings::setLanguage()

• _elgg_set_user_name() changé pour Elgg\Users\Settings::setName()

• _elgg_set_user_username() changé pour Elgg\Users\Settings::setUsername()

• _elgg_send_email_notification() changé pour Elgg\Notifications\SendEmailHandler::class

• _elgg_upgrade_completed() changé pour Elgg\Upgrade\UpgradeCompletedAdminNoticeHandler::class

• _elgg_upgrade_entity_menu() changé pour Elgg\Menus\Entity::registerUpgrade()

• _elgg_user_ban_notification() changé pour Elgg\Users\BanUserNotificationHandler::class

• _elgg_user_get_subscriber_unban_action() changé pour Elgg\Notifications\UnbanUserEventHandler

• _elgg_user_prepare_unban_notification() changé pour Elgg\Notifications\UnbanUserEventHandler

• _elgg_user_settings_menu_register() changé pour Elgg\Menus\Page::registerUserSettings() et Elgg\Menus\Page::registerUserSettingsPlugins()

• _elgg_user_settings_menu_prepare() changé pour Elgg\Menus\Page::cleanupUserSettingsPlugins()

• elgg_user_hover_menu() changé pour Elgg\Menus\UserHover::registerAvatarEdit() et Elgg\Menus\UserHover::registerAdminActions()

• _elgg_user_set_icon_file() changé pour Elgg\Icons\SetUserIconFileHandler::class

• _elgg_user_title_menu() changé pour Elgg\Menus\Title::registerAvatarEdit()

• _elgg_user_page_menu() changé pour Elgg\Menus\Page::registerAvatarEdit()

• _elgg_user_topbar_menu() changé pour Elgg\Menus\Topbar::registerUserLinks()

• _elgg_user_unvalidated_menu() changé pour Elgg\Menus\UserUnvalidated::register()

• _elgg_views_amd() changé pour Elgg\Views\AddAmdModuleNameHandler::class

• _elgg_views_file_help_upload_limit() changé pour Elgg\Input\AddFileHelpTextHandler::class

• _elgg_views_init() a été combiné dans Elgg\Application\SystemEventHandlers::init()

• _elgg_views_minify() changé pour Elgg\Views\MinifyHandler::class

• _elgg_views_prepare_favicon_links() changé pour Elgg\Page\AddFaviconLinksHandler::class

• _elgg_views_preprocess_css() changé pour Elgg\Views\PreProcessCssHandler::class

• _elgg_views_send_header_x_frame_options() changé pour Elgg\Page\SetXFrameOptionsHeaderHandler::class

• _elgg_walled_garden_init() fusionné dans Elgg\Application\SystemEventHandlers::initLate()

• _elgg_walled_garden_remove_public_access() changé pour Elgg\WalledGarden\RemovePublicAccessHandler::class

• _elgg_widgets_widget_urls() changé pour Elgg\Widgets\EntityUrlHandler::class

• elgg_prepare_breadcrumbs() changé pour Elgg\Page\PrepareBreadcrumbsHandler::class

• Elgg\Profiler::handleOutput changé pour Elgg\Debug\Profiler::class

• users_init combiné dans Elgg\Application\SystemEventHandlers::initLate()

Plugins

• _developers_entity_menu changé pour Elgg\Developers\Menus\Entity::registerEntityExplorer

• _developers_page_menu changé pour Elgg\Developers\Menus\Page::register

• _elgg_activity_owner_block_menu changé pour Elgg\Activity\Menus\OwnerBlock::registerUserItem et Elgg\Activity\Menus\OwnerBlock::registerGroupItem

• blog_archive_menu_setup changé pour Elgg\Blog\Menus\BlogArchive::register

• blog_owner_block_menu changé pour Elgg\Blog\Menus\OwnerBlock::registerUserItem et Elgg\Blog\Menus\OwnerBlock::registerGroupItem

• blog_prepare_notification changé pour Elgg\Blog\Notifications\PublishBlogEventHandler

• blog_register_db_seeds changé pour Elgg\Blog\Database::registerSeeds

• bookmarks_footer_menu changé pour Elgg\Bookmarks\Menus\Footer::register

• bookmarks_owner_block_menu changé pour Elgg\Bookmarks\Menus\OwnerBlock::registerUserItem et Elgg\Bookmarks\Menus\OwnerBlock::registerGroupItem

• bookmarks_page_menu changé pour Elgg\Bookmarks\Menus\Page::register

• bookmarks_prepare_notification changé pour Elgg\Bookmarks\Notifications\CreateBookmarksEventHandler

• bookmarks_register_db_seeds changé pour Elgg\Bookmarks\Database::registerSeeds

• ckeditor_longtext_id changé pour Elgg\CKEditor\Views::setInputLongTextIDViewVar

• ckeditor_longtext_menu changé pour Elgg\CKEditor\Menus\LongText::registerToggler

• dashboard_default_widgets changé pour Elgg\Dashboard\Widgets::extendDefaultWidgetsList

• developers_log_events changé pour Elgg\Developers\HandlerLogger::trackEvent et Elgg\Developers\HandlerLogger::trackHook

• diagnostics_basic_hook changé pour Elgg\Diagnostics\Reports::getBasic

• diagnostics_globals_hook changé pour Elgg\Diagnostics\Reports::getGlobals

• diagnostics_phpinfo_hook changé pour Elgg\Diagnostics\Reports::getPHPInfo

• diagnostics_sigs_hook changé pour Elgg\Diagnostics\Reports::getSigs

• discussion_comment_permissions changé pour Elgg\Discussions\Permissions::preventCommentOnClosedDiscussion

• discussion_get_subscriptions changé pour Elgg\Discussions\Notifications::addGroupSubscribersToCommentOnDiscussionSubscriptions

• discussion_owner_block_menu changé pour Elgg\Discussions\Menus\OwnerBlock::registerGroupItem

• discussion_prepare_comment_notification changé pour Elgg\Discussions\Notifications::prepareCommentOnDiscussionNotification

• discussion_prepare_notification changé pour Elgg\Discussions\Notifications\CreateDiscussionEventHandler

• discussion_register_db_seeds changé pour Elgg\Discussions\Database::registerSeeds

• Elgg\DevelopersPlugins\* changé pour Elgg\Developers\*

• Elgg\Discussions\Menus::registerSiteMenuItem changé pour Elgg\Discussions\Menus\Site::register

• Elgg\Discussions\Menus::filterTabs changé pour Elgg\Discussions\Menus\Filter::filterTabsForDiscussions

• embed_longtext_menu changé pour Elgg\Embed\Menus\LongText::register

• embed_select_tab changé pour Elgg\Embed\Menus\Embed::selectCorrectTab

• embed_set_thumbnail_url changé pour Elgg\Embed\Icons::setThumbnailUrl

• expages_menu_register_hook changé pour Elgg\ExternalPages\Menus\ExPages::register

• file_handle_object_delete changé pour Elgg\File\Icons::deleteIconOnElggFileDelete

• file_prepare_notification changé pour Elgg\File\Notifications\CreateFileEventHandler

• file_register_db_seeds changé pour Elgg\File\Database::registerSeeds

• file_set_custom_icon_sizes changé pour Elgg\File\Icons::setIconSizes

• file_set_icon_file changé pour Elgg\File\Icons::setIconFile

• file_set_icon_url changé pour Elgg\File\Icons::setIconUrl

• file_owner_block_menu changé pour Elgg\File\Menus\OwnerBlock::registerUserItem et Elgg\File\Menus\OwnerBlock::registerGroupItem

• _elgg_friends_filter_tabs changé pour Elgg\Friends\Menus\Filter::registerFilterTabs

• _elgg_friends_page_menu changé pour Elgg\Friends\Menus\Page::register

• _elgg_friends_register_access_type changé pour Elgg\Friends\Access::registerAccessCollectionType

• _elgg_friends_setup_title_menu changé pour Elgg\Friends\Menus\Title::register

• _elgg_friends_setup_user_hover_menu changé pour Elgg\Friends\Menus\UserHover::register

• _elgg_friends_topbar_menu changé pour Elgg\Friends\Menus\Topbar::register

• _elgg_friends_widget_urls changé pour Elgg\Friends\Widgets::setWidgetUrl

• _elgg_send_friend_notification changé pour Elgg\Friends\Notifications::sendFriendNotification

• Elgg\Friends\FilterMenu::addFriendRequestTabs changé pour Elgg\Friends\Menus\Filter::addFriendRequestTabs

• Elgg\Friends\RelationshipMenu::addPendingFriendRequestItems changé pour Elgg\Friends\Menus\Relationship::addPendingFriendRequestItems

• Elgg\Friends\RelationshipMenu::addPendingFriendRequestItems changé pour Elgg\Friends\Menus\Relationship::addPendingFriendRequestItems

• Elgg\Friends\Relationships::createFriendRelationship changé pour Elgg\Friends\Relationships::removePendingFriendRequest

• _groups_gatekeeper_allow_profile_page changé pour Elgg\Groups\Access::allowProfilePage

• _groups_page_menu changé pour Elgg\Groups\Menus\Page::register

• _groups_page_menu_group_profile changé pour Elgg\Groups\Menus\Page::registerGroupProfile

• _groups_relationship_invited_menu changé pour Elgg\Groups\Menus\Relationship::registerInvitedItems

• _groups_relationship_member_menu changé pour Elgg\Groups\Menus\Relationship::registerRemoveUser

• _groups_relationship_membership_request_menu changé pour Elgg\Groups\Menus\Relationship::registerMembershipRequestItems

• _groups_title_menu changé pour Elgg\Groups\Menus\Title::register

• _groups_topbar_menu_setup changé pour Elgg\Groups\Menus\Topbar::register

• groups_access_default_override changé pour Elgg\Groups\Access::overrideDefaultAccess

• groups_create_event_listener changé pour Elgg\Groups\Group::createAccessCollection

• groups_default_page_owner_handler changé pour Elgg\Groups\PageOwner::detectPageOwner

• groups_entity_menu_setup changé pour Elgg\Groups\Menus\Entity::register et Elgg\Groups\Menus\Entity::registerFeature

• groups_fields_setup changé pour Elgg\Groups\FieldsHandler

• groups_members_menu_setup changé pour Elgg\Groups\Menus\GroupsMembers::register

• groups_set_access_collection_name changé pour Elgg\Groups\Access::getAccessCollectionName

• groups_set_url changé pour Elgg\Groups\Group::getEntityUrl

• groups_setup_filter_tabs changé pour Elgg\Groups\Menus\Filter::registerGroupsAll

• groups_update_event_listener changé pour Elgg\Groups\Group::updateGroup

• groups_user_join_event_listener changé pour Elgg\Groups\Group::joinGroup

• groups_user_leave_event_listener changé pour Elgg\Groups\Group::leaveGroup

• groups_write_acl_plugin_hook changé pour Elgg\Groups\Access::getWriteAccess

• invitefriends_add_friends changé pour Elgg\InviteFriends\Users::addFriendsOnRegister

• invitefriends_register_page_menu changé pour Elgg\InviteFriends\Menus\Page::register

• likes_permissions_check changé pour Elgg\Likes\Permissions::allowLikedEntityOwner

• likes_permissions_check_annotate changé pour Elgg\Likes\Permissions::allowLikeOnEntity

• likes_social_menu_setup changé pour Elgg\Likes\Menus\Social::register

• members_register_filter_menu changé pour Elgg\Members\Menus\Filter::register

• messages_can_edit changé pour Elgg\Messages\Permissions::canEdit

• messages_can_edit_container changé pour Elgg\Messages\Permissions::canEditContainer

• messages_purge changé pour Elgg\Messages\User::purgeMessages

• messages_register_topbar changé pour Elgg\Messages\Menus\Topbar::register

• messages_user_hover_menu changé pour Elgg\Messages\Menus\UserHover::register et Elgg\Messages\Menus\Title::register

• notifications_update_collection_notify changé pour Elgg\Notifications\Relationships::updateUserNotificationsPreferencesOnACLChange

• notifications_update_friend_notify changé pour Elgg\Friends\Relationships::applyFriendNotificationsSettings

• notifications_relationship_remove changé pour Elgg\Friends\Relationships::deleteFriendNotificationSubscription et Elgg\Groups\Relationships::removeGroupNotificationSubscriptions

• _notifications_page_menu changé pour Elgg\Notifications\Menus\Page::register

• _notification_groups_title_menu changé pour Elgg\Notifications\Menus\Title::register

• pages_container_permission_check changé pour Elgg\Pages\Permissions::allowContainerWriteAccess

• pages_entity_menu_setup changé pour Elgg\Pages\Menus\Entity::register

• pages_icon_url_override changé pour Elgg\Pages\Icons::getIconUrl

• pages_owner_block_menu changé pour Elgg\Pages\Menus\OwnerBlock::registerUserItem et Elgg\Pages\Menus\OwnerBlock::registerGroupItem

• pages_prepare_notification changé pour Elgg\Pages\Notifications\CreatePageEventHandler

• pages_register_db_seeds changé pour Elgg\Pages\Database::registerSeeds

• pages_set_revision_url changé pour Elgg\Pages\Extender::setRevisionUrl

• pages_write_access_options_hook changé pour Elgg\Pages\Views::removeAccessPublic

• pages_write_access_vars changé pour Elgg\Pages\Views::preventAccessPublic

• pages_write_permission_check changé pour Elgg\Pages\Permissions::allowWriteAccess

• Elgg\Pages\Menus::registerPageMenuItems changé pour Elgg\Pages\Menus\PagesNav::register

• _profile_admin_page_menu changé pour Elgg\Profile\Menus\Page::registerAdminProfileFields

• _profile_fields_setup changé pour Elgg\Profile\FieldsHandler

• _profile_title_menu changé pour Elgg\Profile\Menus\Title::register

• _profile_topbar_menu changé pour Elgg\Profile\Menus\Topbar::register

• _profile_user_hover_menu changé pour Elgg\Profile\Menus\UserHover::register

• _profile_user_page_menu changé pour Elgg\Profile\Menus\Page::registerProfileEdit

• profile_default_widgets_hook changé pour Elgg\Profile\Widgets::getDefaultWidgetsList

• reportedcontent_user_hover_menu changé pour Elgg\ReportedContent\Menus\UserHover::register

• search_exclude_robots changé pour Elgg\Search\Site::preventSearchIndexing

• search_output_tag changé pour Elgg\Search\Views::setSearchHref

• site_notifications_register_entity_menu changé pour Elgg\SiteNotifications\Menus\Entity::register

• site_notifications_send changé pour Elgg\SiteNotifications\Notifications::createSiteNotifications

• _uservalidationbyemail_user_unvalidated_bulk_menu changé pour Elgg\UserValidationByEmail\Menus\UserUnvalidatedBulk::register

• _uservalidationbyemail_user_unvalidated_menu changé pour Elgg\UserValidationByEmail\Menus\UserUnvalidated::register

• uservalidationbyemail_after_registration_url changé pour Elgg\UserValidationByEmail\Response::redirectToEmailSent

• uservalidationbyemail_check_manual_login changé pour Elgg\UserValidationByEmail\User::preventLogin

• uservalidationbyemail_disable_new_user changé pour Elgg\UserValidationByEmail\User::disableUserOnRegistration

• system_log_archive_cron changé pour Elgg\SystemLog\Cron::rotateLogs

• system_log_default_logger changé pour Elgg\SystemLog\Logger::log

• system_log_delete_cron changé pour Elgg\SystemLog\Cron::deleteLogs

• system_log_listener changé pour Elgg\SystemLog\Logger::listen

• system_log_user_hover_menu changé pour Elgg\SystemLog\Menus\UserHover::register

• thewire_add_original_poster changé pour Elgg\TheWire\Notifications\CreateTheWireEventHandler

• thewire_owner_block_menu changé pour Elgg\TheWire\Menus\OwnerBlock::register

• thewire_prepare_notification changé pour Elgg\TheWire\Notifications\CreateTheWireEventHandler

• thewire_setup_entity_menu_items changé pour Elgg\TheWire\Menus\Entity::register

Exceptions retravaillées

Toutes les exceptions du système Elgg étendent désormais Elgg\Exceptions\Exception et se trouvent dans l’espace de noms Elgg\Exceptions

Exceptions déplacées

• ClassException utilisez Elgg\Exceptions\ClassException

• ConfigurationException utilisez Elgg\Exceptions\ConfigurationException

• CronException utilisez Elgg\Exceptions\CronException

• DatabaseException utilisez Elgg\Exceptions\DatabaseException

• DataFormatException utilisez Elgg\Exceptions\DataFormatException

• InstallationException utilisez Elgg\Exceptions\Configuration\InstallationException

• InvalidParameterException utilisez Elgg\Exceptions\InvalidParameterException

• IOException utilisez Elgg\Exceptions\FileSystem\IOException

• LoginException utilisez Elgg\Exceptions\LoginException

• PluginException utilisez Elgg\Exceptions\PluginException

• RegistrationException utilisez Elgg\Exceptions\Configuration\RegistrationException

• SecurityException utilisez Elgg\Exceptions\SecurityException

• Elgg\Database\EntityTable\UserFetchFailureException utilisez Elgg\Exceptions\Database\UserFetchFailureException

• Elgg\Di\FactoryUncallableException utilisez Elgg\Exceptions\Di\FactoryUncallableException

• Elgg\Di\MissingValueException utilisez Elgg\Exceptions\Di\MissingValueException

• Elgg\Http\Exception\AdminGatekeeperException utilisez Elgg\Exceptions\Http\Gatekeeper\AdminGatekeeperException

• Elgg\Http\Exception\AjaxGatekeeperException utilisez Elgg\Exceptions\Http\Gatekeeper\AjaxGatekeeperException

• Elgg\Http\Exception\GroupToolGatekeeperException utilisez Elgg\Exceptions\Http\Gatekeeper\GroupToolGatekeeperException

• Elgg\Http\Exception\LoggedInGatekeeperException utilisez Elgg\Exceptions\Http\Gatekeeper\LoggedInGatekeeperException

• Elgg\Http\Exception\LoggedOutGatekeeperException utilisez Elgg\Exceptions\Http\Gatekeeper\LoggedOutGatekeeperException

• Elgg\Http\Exception\UpgradeGatekeeperException utilisez Elgg\Exceptions\Http\Gatekeeper\UpgradeGatekeeperException

• Elgg\I18n\InvalidLocaleException utilisez Elgg\Exceptions\I18n\InvalidLocaleException

• Elgg\BadRequestException utilisez Elgg\Exceptions\Http\BadRequestException

• Elgg\CsrfException utilisez Elgg\Exceptions\Http\CsrfException

• Elgg\EntityNotFoundException utilisez Elgg\Exceptions\Http\EntityNotFoundException

• Elgg\EntityPermissionsException utilisez Elgg\Exceptions\Http\EntityPermissionsException

• Elgg\GatekeeperException utilisez Elgg\Exceptions\Http\GatekeeperException

• Elgg\GroupGatekeeperException utilisez Elgg\Exceptions\Http\Gatekeeper\GroupGatekeeperException

• Elgg\HttpException utilisez Elgg\Exceptions\HttpException

• Elgg\PageNotFoundException utilisez Elgg\Exceptions\Http\PageNotFoundException

• Elgg\ValidationException utilisez Elgg\Exceptions\Http\ValidationException

• Elgg\WalledGardenException utilisez Elgg\Exceptions\Http\Gatekeeper\WalledGardenException

Exceptions supprimées

• CallException

• ClassNotFoundException

• IncompleteEntityException

• InvalidClassException

• NotificationException

• NotImplementedException du plugin Web Services

Traits retravaillés

Afin de mieux organiser l’espace de noms Elgg, tous les Traits ont été déplacés vers l’espace de noms Elgg\Traits

• Elgg\Cacheable a été déplacé vers Elgg\Traits\Cacheable

• Elgg\Cli\PluginsHelper a été déplacé vers Elgg\Traits\Cli\PluginsHelper

• Elgg\Cli\Progressing a été déplacé vers Elgg\Traits\Cli\Progressing

• Elgg\Database\Seeds\Seeding\GroupHelpers a été déplacé vers Elgg\Traits\Seeding\GroupHelpers

• Elgg\Database\Seeds\Seeding\TimeHelpers a été déplacé vers Elgg\Traits\Seeding\TimeHelpers

• Elgg\Database\Seeds\Seeding a été déplacé vers Elgg\Traits\Seeding

• Elgg\Database\LegacyQueryOptionsAdapter a été déplacé vers Elgg\Traits\Database\LegacyQueryOptionsAdapter

• Elgg\Debug\Profilable a été déplacé vers Elgg\Traits\Debug\Profilable

• Elgg\Di\ServiceFacade a été déplacé vers Elgg\Traits\Di\ServiceFacade

• Elgg\Entity\ProfileData a été déplacé vers Elgg\Traits\Entity\ProfileData

• Elgg\Loggable a été déplacé vers Elgg\Traits\Loggable

• Elgg\Notifications\EventSerialization a été déplacé vers Elgg\Traits\Notifications\EventSerialization

• Elgg\TimeUsing a été déplacé vers Elgg\Traits\TimeUsing

Modifications d’API diverses

• La valeur par défaut pour ignore_empty_body et prevent_double_submit lors de l’utilisation de elgg_view_form a été changé pour true.

• Les formulaires de paramètres de plugin (plugins/{$plugin_id}/settings) ne reçoivent plus $vars['plugin'], utilisez $vars['entity']

• Elgg\Router\Middleware\WalledGarden::isPublicPage() ne peut plus être appelé de manière statique

• Elgg\Cli\Plugin Helper::get Dependents() n’est plus disponible publiquement

• ElggPlugin::getLanguagesPath() n’est plus disponible publiquement

• Un \ElggBatch n’implémente plus l’interface Elgg\BatchResult mais a toujours les mêmes fonctionnalités

• Une \ElggEntity n’implémente plus l’interface Locatable mais a toujours les mêmes fonctionnalités

• Un \Elgg\Event n’implémente plus les interfaces \Elgg\ObjectEvent et \Elgg\UserEvent mais a toujours les mêmes fonctionnalités

• La vue output/icon n’utilise plus la variable de vue convert

• ElggData::save() renvoie désormais toujours un bool tel que documenté. Toutes les classes d’extension ont été mises à jour (par exemple ElggEntity, ElggMetadata, ElggRelationship, etc.)

• Elgg\Email::getTo() renvoie désormais toujours un array

• ElggPlugin::activate() et ElggPlugin::deactivate() peuvent maintenant lancer une Elgg\Exceptions\PluginException avec plus d’informations sur l’échec

• \ElggRelationship::RELATIONSHIP_LIMIT a été supprimé utilisez ElggDatabaseRelationshipsTable::RELATIONSHIP_COLUMN_LENGTH``

• Les constantes ORIGIN_SUBSCRIPTIONS et ORIGIN_INSTANT dans \Elgg\Notifications\Notification ont été supprimées

• Vous ne pouvez plus utiliser l’événement delete, <entity_type> pour empêcher la suppression d’une entité. Utilisez l’événement delete:before, <entity_type>

• Les fichiers externes ne sont plus classés par priorité mais seront retournés dans le même ordre qu’ils sont enregistrés

• L’interface Friendable a été supprimée. Les fonctions implémentées dans ElggUser ont été déplacées vers Elgg\Traits\Entity\Friends

• Le drapeau de configuration profile_using_custom n’est plus disponible

• La valeur de retour de elgg_create_river_item() sera false dans le cas où la création a été empêchée par l’événement 'create:before', 'river'

• La constante ELGG_PLUGIN_USER_SETTING_PREFIX a été supprimée, utilisez la fonction d’assistance \ElggUser::getNamespacedPluginSettingName()

• La constante ELGG_PLUGIN_INTERNAL_PREFIX a été supprimée, pour obtenir le nom de paramètre privé de priorité du plugin utilisez \ElggPlugin::PRIORITY_SETTING_NAME

• La classe SiteNotificationFactory a été supprimée, utilisez SiteNotification::factory()

• La classe Elgg\Email\Address ne lance plus Laminas\Mail\Exception\InvalidArgumentException mais lance maintenant Elgg\Exceptions\InvalidArgumentException

APIs dépréciées

Fonctions de classe

• ElggPlugin::getUserSetting() utilisez ElggUser::getPluginSetting()

• ElggPlugin::setUserSetting() utilisez ElggUser::setPluginSetting()

Fonctions de la bibliothèque

• forward() utilisez des instances Elgg\Exceptions\HttpException ou elgg_redirect_response()

Hooks plugin

• 'usersettings', 'plugin' utilisez le hook 'plugin_setting', '<entity type>'

Fonctions supprimées

Fonctions de classe

• Elgg\Config::getEntityTypes() utilisez la constante Elgg\Config::ENTITY_TYPES

• ElggFile::setDescription() utilisez $file->description = $new_description

• ElggGroup::addObjectToGroup()

• ElggGroup::removeObjectFromGroup()

• ElggPlugin::getAllUserSettings()

• ElggPlugin::getDependencyReport()

• ElggPlugin::getError()

• ElggPlugin::unsetAllUserSettings()

• ElggPlugin::unsetAllUserAndPluginSettings() utilisez ElggPlugin::unsetAllEntityAndPluginSettings()

• ElggWidget::getContext() utilisez $entity->context

• ElggWidget::setContext() utilisez $entity->context = $context

• Elgg\Notifications\NotificationsService::getDeprecatedHandler()

• Elgg\Notifications\NotificationsService::getMethodsAsDeprecatedGlobal() utilisez elgg_get_notification_methods()

• Elgg\Notifications\NotificationsService::registerDeprecatedHandler()

• Elgg\Notifications\NotificationsService::setDeprecatedNotificationSubject()

• Elgg\Email::getRecipient() utilisez Elgg\Email::getTo()

• Elgg\Email::setRecipient()

• Elgg\Entity::getLocation() utilisez $entity->location

• Elgg\Entity::setLocation() utilisez $entity->location = $location

Fonctions de la bibliothèque

• access_get_show_hidden_status() utilisez elgg()->session->getDisabledEntityVisibility()

• diagnostics_md5_dir()

• elgg_add_subscription() utilisez \ElggEntity::addSubscription()

• elgg_get_available_languages() utilisez elgg()->translator->getAvailableLanguages()

• elgg_get_all_plugin_user_settings()

• elgg_get_entities_from_plugin_user_settings() utilisez elgg_get_entities() avec les paramètres de configuration privés et préfixez le nom de votre paramètre avec plugin:user_setting:

• elgg_get_filter_tabs() utilise les hooks de menu sur 'register', 'menu:filter:<filter_id>'

• elgg_get_loaded_css() utilisez elgg_get_loaded_external_files('css', 'head')

• elgg_get_loaded_js() utilisez elgg_get_loaded_external_files('js', $location)

• elgg_get_system_messages() utilisez elgg()->system_messages->loadRegisters()

• elgg_prepend_css_urls()

• elgg_remove_subscription() utilisez \ElggEntity::removeSubscription()

• elgg_set_plugin_setting() utilisez $plugin->setSetting($name, $value)

• elgg_set_plugin_user_setting() utilisez ElggUser::setPluginSetting()

• elgg_set_system_messages() utilisez elgg()->system_messages->saveRegisters()

• elgg_unset_plugin_setting() utilisez $plugin->unsetSetting($name)

• elgg_unset_plugin_user_setting() utilisez ElggUser::removePluginSetting()

• get_language_completeness() utilisez elgg()->translator->getLanguageCompleteness()

• get_installed_translations() utilisez elgg()->translator->getInstalledTranslations()

• group_access_options()

• pages_is_page()

• system_log_get_log()

• system_log_get_log_entry()

• system_log_get_object_from_log_entry()

• system_log_get_seconds_in_period()

• system_log_archive_log()

• system_log_browser_delete_log()

• thewire_get_parent() utilisez \ElggWire::getParent()

• validate_email_address() utilisez elgg()->accounts->assertValidEmail()

• validate_password() utilisez elgg()->accounts->assertValidPassword()

• validate_username() utilisez elgg()->accounts->assertValidUsername()

Vues / ressources supprimées

• admin/develop_tools/inspect/webservices

• elgg/thewire.js

• input/urlshortener

• messages/js a été déplacé vers forms/messages/process.js

• navigation/menu/elements/item_deps la fonctionnalité a été fusionnée dans navigation/menu/elements/item

• object/plugin/elements/contributors

• notifications/groups

• notifications/personal utilisez notifications/settings ou notifications/users

• notifications/settings/personal a été déplacé vers notifications/settings/records

• notifications/settings/collections

• notifications/settings/other étend notifications/settings/records

• notifications/subscriptions/groups utilisez forms/notifications/subscriptions/groups

• notifications/subscriptions/users utilisez forms/notifications/subscriptions/users

• resources/comments/view utilisez \Elgg\Controllers\CommentEntityRedirector

• resources/river utilisez resources/activity/all ou resources/activity/owner ou resources/activity/friends

• reportedcontent/admin_css

• thewire/previous

Hooks/événements retirés

• L’événement created, river a été supprimé. Utilisez l’événement create:after, river.

• Le hook creating, river a été supprimé. Utilisez l’événement create:before, river si vous souhaitez bloquer la création d’un élément river.

• Le hook filter_tabs, <context> a été supprimé. Utilisez le hook register, menu:filter:<filter_id>

• Le hook output, ajax a été supprimé. Utilisez le hook ajax_response si vous souhaitez modifier les résultats.

• Le hook reportedcontent:add a été supprimé. Utilisez l’événement create, object pour empêcher la création.

• Le hook reportedcontent:archive a été supprimé. Utilisez le hook permissions_check, object.

• Le hook reportedcontent:delete a été supprimé. Utilisez l’événement delete, object pour empêcher la suppression.

Actions supprimées

• L’action reportedcontent/delete a été remplacée par une action de suppression d’entité générique

De 3.2 à 3.3

Version de PHP

PHP 7.1 a atteint sa fin de vie en décembre 2019. Pour assurer la sécurité des sites Elgg, nous demandons maintenant au moins PHP 7.2 pour les nouvelles installations.

Si vous faites une mise à niveau depuis une installation de Elgg précédente, assurez-vous que vous avez la bonne version de PHP installée.

Afin de pouvoir tester Elgg sur PHP 7.4, nous avons dû mettre à jour la suite de test PHPUnit à la version 8.5. Cela peut nécessiter quelques réécritures de vos propres tests d’unité/intégration.

Utilisation plus simple de la disposition “default”

Actuellement, le modèle le plus courant est de faire ce qui suit :

$title = 'All blogs';

$content = elgg_list_entities([
        'type' => 'object',
        'subtype' => 'blog',
]);

$layout = elgg_view_layout('default', [
        'title' => $title,
        'content' => $content,
]);

echo elgg_view_page($title, $layout);

Nous avons rendu ce genre de modèle plus simple. Vous pouvez maintenant passer un tableau d’options de disposition au deuxième paramètre de elgg_view_page. La fonction elgg_view_page utilisera ce tableau pour l’envelopper dans la disposition “default”. Elle ajoute également le titre de la page à la mise en page.

La nouvelle manière de le faire est :

echo elgg_view_page('All blogs', [
        'content' => elgg_list_entities([
                'type' => 'object',
                'subtype' => 'blog',
        ]),
]);

Noms de disposition dépréciés

Pour faciliter la transition de Elgg 2.x à 3.x, nous avons gardé certains anciens noms de mise en page (“one_sidebar”, “one_column”, “two_sidebar” et “content”) intacts lorsqu’ils sont utilisés dans la fonction elgg_view_layout. À partir de Elgg 3.3, ces noms de disposition sont obsolètes et vous devez mettre à jour votre code pour utiliser la nouvelle disposition “default”.

Lorsque vous modifiez l’utilisation du nom de disposition “content”, vous devriez tenir compte du fait que la mise en page “content” génère un menu de filtre. Ce menu est légèrement différent du menu “filter” habituel, généré dans la disposition “default”. Il utilise d’autres noms de hook. Si vous avez déjà désactivé le filtre dans votre disposition, vous pouvez modifier la disposition sans aucun problème.

Modifications du manifeste du plugin

Nous travaillons à la suppression du fichier de manifeste de plugin. Certaines caractéristiques du manifeste seront remplacées et d’autres seront abandonnées. Pour faciliter un peu cette transition, nous avons déjà déprécié les fonctions suivantes de l’api ElggPluginManifest :

• getCopyright()

• getDonationsPageURL()

• getSuggests() utilisez les suggestions dans composer

APIs dépréciées

• elgg_disable_query_cache()

• elgg_enable_query_cache()

• elgg_format_attributes() utilisez elgg_format_element()

• elgg_flush_caches() utilisez elgg_clear_caches()

• elgg_get_menu_item()

• elgg_get_ordered_event_handlers() utilisez elgg()->events->getOrderedHandlers()

• elgg_get_ordered_hook_handlers() utilisez elgg()->hooks->getOrderedHandlers()

• elgg_invalidate_simplecache() utilisez elgg_clear_caches()

• elgg_is_menu_item_registered()

• elgg_view_entity_annotations()

• execute_delayed_write_query() utilisez elgg()->db->registerDelayedQuery()

• execute_delayed_read_query() utilisez elgg()->db->registerDelayedQuery()

• run_sql_script()

• elgg_unset_all_plugin_settings() utilisez \ElggPlugin::unsetAllSettings()

• elgg_get_file_simple_type() utilisez elgg()->mimetype->getSimpleType()

• ElggFile::detectMimeType() utilisez elgg()->mimetype->getMimeType()

• generate_action_token() utilisez elgg()->csrf->generateActionToken()

• elgg_split()

Valeurs de configuration obsolètes

• simplecache_lastupdate utilisez lastcache

Commandes CLI obsolètes

• elgg-cli flush utilisez elgg-cli cache:clear

Hooks obsolètes

• entity:annotate, <entity_type>

De 3.1 à 3.2

Accès en écriture d’un utilisateur

Pour résoudre un problème où les collections d’accès appartenant à l’utilisateur telles que Friends ou Friend Collections s’affichaient toujours dans la liste déroulante d’accès lors de la création de contenu, même si les plugins associés sont désactivés, nous avons dû modifier une certaine logique interne. Si vous souhaitez qu’un sous-type de collection d’accès soit disponible dans l’accès en écriture, vous devez maintenant enregistrer le sous-type avec un hook de plugin. Voir la référence du hook du plugin pour “access:collections:write:subtypes” pour plus de détails.

État activé des éléments de la rivière

L’état activé - enabled - des éléments de la rivière a été déprécié. Vous ne devez plus utiliser cette propriété lorsque vous travaillez avec des éléments de la rivière.

De 3.0 à 3.1

Version de PHP

PHP 7.0 a atteint sa fin de vie en janvier 2019. Pour assurer la sécurité des sites Elgg, nous exigeons maintenant au moins PHP 7.1 pour les nouvelles installations.

Si vous faites une mise à niveau depuis une installation de Elgg précédente, assurez-vous que vous avez la bonne version de PHP installée.

Captures d’écran du plugin

Les captures d’écran ajoutées aux plugins ne sont plus prises en charge et ne seront plus affichées dans les détails du plugin.

Chargement des fichiers externes

L’utilisation de elgg_register_js, de elgg_unregister_js et de elgg_load_js est déconseillée. Assurez-vous que votre javascript est un module AMD et utilisez elgg_require_js pour l’inclure.

L’utilisation de elgg_register_css, de elgg_unregister_css et de elgg_load_css est déconseillée. Vous pouvez enregistrer et inclure les css avec la nouvelle fonction elgg_require_css.

Définition du propriétaire de la page

La définition du propriétaire de la page via un paramètre de la fonction elgg_get_page_owner_guid est obsolète. Utilisez elgg_set_page_owner_guid.

Simpletests

Les tests simples du noyau ont été supprimés du système. Ils sont tous remplacés par des tests unitaires PHP ou des tests d’intégration. La commande cli simpletest est devenue obsolète.

Fonctions de rappel - callbacks - de hook et d’événement

Les arguments des hooks et des fonctions de rappel historiques sont déconseillés. Vous devez passer au nouveau style d’arguments dès que possible.

// old style hook callback
function hook_callback($name, $type, $return_value, $params) {

}

// new style hook callback
function hook_callback(\Elgg\Hook $hook) {
        // now you can use a few new functions
        $params = $hook->getParams();
        $return = $hook->getValue();

        $specific_param = $hook->getParam('specific_param', 'default')
        $entity = $hook->getEntityParam();
        $user = $hook->getUserParam();
}

// old style event callback
function event_callback($name, $type, $object) {

}

// new style event callback
function event_callback(\Elgg\Event $event) {
        // now you can use a few new functions
        $object = $event->getObject();
}

Routes obsolètes

• previous:object:thewire Cette route n’était pas utilisée. Elle a maintenant été marquée comme obsolète.

Bibliothèques CSS obsolètes

• jquery.imgareaselect N’utilisez pas ce fichier css externe.

• jquery.treeview N’utilisez pas ce fichier css externe.

Bibliothèques JS obsolètes

• elgg.avatar_cropper Évitez de dépendre de cette bibliothèque javascript externe.

• jquery.imgareaselect Évitez de dépendre de cette bibliothèque javascript externe.

• jquery.treeview Évitez de dépendre de cette bibliothèque javascript externe.

APIs dépréciées

• access_show_hidden_entities() Utilisez elgg_call() avec le drapeau ELGG_SHOW_DISABLED_ENTITIES.

• autoregister_views()

• count_messages() Utilisez elgg()->system_messages->count().

• disable_user_entities()

• elgg_enable_entity() Utilisez ElggEntity::enable().

• elgg_get_file_list() Utilisez un itérateur de répertoire PHP.

• elgg_instanceof() Utilisez l’opérateur de type instanceof de PHP.

• elgg_is_admin_user() Utilisez ElggUser::isAdmin().

• elgg_set_ignore_access() Utilisez elgg_call() avec le drapeau ELGG_IGNORE_ACCESS.

• elgg_sort_3d_array_by_value()

• get_access_list() Utilisez get_access_array().

• get_language() Utilisez get_current_language().

• get_number_users() Utilisez elgg_count_entities().

• pages_register_navigation_tree()

• ini_get_bool()

• is_not_null()

• update_access_collection()

Actions obsolètes

• admin/delete_admin_notice Remplacé par une action générique entity/delete.

• avatar/crop Géré dans l’action avatar/upload.

• avatar/remove Géré dans l’action avatar/upload.

• blog/delete Remplacé par l’action générique entity/delete.

• messages/delete Remplacé par l’action générique entity/delete.

• site_notifications/delete Remplacé par l’action générique entity/delete.

De 2.x à 3.0

PHP 7.0 est désormais requis

5.6 atteint sa fin de vie. PHP 7.0 est maintenant nécessaire pour installer et exécuter Elgg.

$CONFIG est supprimé !

Pas exactement, cependant vous devez auditer cet usage et devriez le remplacer par elgg_get_config() et elgg_set_config(), comme recommandé depuis Elgg 1.9.

La variable globale $CONFIG est maintenant un proxy pour le conteneur de configuration de Elgg, et les modifications échoueront si vous essayez de modifier directement les propriétés du tableau. Par exemple, $CONFIG->cool_fruit[] = 'Poire';. Le bon côté est que ces échecs émettront des NOTICEs.

Vues supprimées

• forms/account/settings : l’extension de usersettings peut désormais étendre la vue forms/usersettings/save

• forms/admin/site/advanced/system

• resources/file/download

• output/checkboxes : utilisez output/tags si vous voulez le même comportement

• input/write_access : mod/pages utilise désormais le hook de plugin access:collections:write.

• invitefriends/form

• page/layouts/content : utilisez page/layouts/default

• page/layouts/one_column : utilisez page/layouts/default

• page/layouts/one_sidebar : utilisez page/layouts/default

• page/layouts/two_sidebar : utilisez page/layouts/default

• page/layouts/walled_garden : utilisez page/layouts/default

• page/layouts/walled_garden/cancel_button

• page/layouts/two_column_left_sidebar

• page/layouts/widgets/add_panel

• page/elements/topbar_wrapper : mettez à jour votre utilisation de page/elements/topbar pour inclure une vérification si l’utilisateur est connecté

• pages/icon

• groups/group_sort_menu : utilisez le hook plugin register, filter:menu:groups/all

• groups/my_status

• groups/profile/stats

• subscriptions/form/additions : étendez plutôt notifications/parameters/other

• likes/count : des modifications peuvent désormais être apportées à l’élément de menu likes_count

• likes/css : les likes utilisent désormais elgg/likes.css

• resources/members/index

• messageboard/css

• notifications/subscriptions/personal

• notifications/subscriptions/collections

• notifications/subscriptions/form

• notifications/subscriptions/jsfuncs

• notifications/subscriptions/forminternals

• notifications/css

• pages/input/parent

• river/item : utilisez elgg_view_river_item() pour afficher des éléments de la rivière

• river/user/default/profileupdate

• admin.js

• aalborg_theme/homepage.png

• aalborg_theme/css

• resources/avatar/view: Utilisez l’API des icônes d’entités

• ajax_loader.gif

• button_background.gif

• button_graduation.png

• elgg_toolbar_logo.gif

• header_shadow.png

• powered_by_elgg_badge_drk_bckgnd.gif

• powered_by_elgg_badge_light_bckgnd.gif

• sidebar_background.gif

• spacer.gif

• toptoolbar_background.gif

• two_sidebar_background.gif

• ajax_loader_bw.gif: utilisez graphics/ajax_loader_bw.gif

• elgg_logo.png : utilisez graphics/elgg_logo.png

• favicon-128.png : utilisez graphics/favicon-128.png

• favicon-16.png : utilisez graphics/favicon-16.png

• favicon-32.png : utilisez graphics/favicon-32.png

• favicon-64.png : utilisez graphics/favicon-64.png

• favicon.ico : utilisez graphics/favicon.ico

• favicon.svg : utilisez graphics/favicon.svg

• friendspicker.png : utilisez graphics/friendspicker.png

• walled_garden.jpg : utilisez graphics/walled_garden.jpg

• core/friends/collection

• core/friends/collections

• core/friends/collectiontabs

• core/friends/tablelist

• core/friends/talbelistcountupdate

• lightbox/elgg-colorbox-theme/colorbox-images/*`

• navigation/menu/page : utilise désormais navigation/menu/default et un hook de préparation - prepare

• navigation/menu/site : utilise désormais la vue par défaut

• page/elements/by_line: Utilisez object/elements/imprint

• forms/admin/site/advanced/security : l’information du secret du site a été déplacé vers forms/admin/security/settings

• river/object/file/create : regardez Rivière - Flux d’activité

• river/object/page/create : regardez Rivière - Flux d’activité

• river/object/page_top/create : regardez Rivière - Flux d’activité

• river/relationship/member : regardez Rivière - Flux d’activité

• object/page_top : utilisez object/page

• ajax/discussion/reply/edit : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion/replies : Voyez Les réponses aux discussions ont été converties en commentaires

• object/discussion_reply : Voyez Les réponses aux discussions ont été converties en commentaires

• resources/discussion/reply/edit : Voyez Les réponses aux discussions ont été converties en commentaires

• resources/elements/discussion_replies : Voyez Les réponses aux discussions ont été converties en commentaires

• river/elements/discussion_replies : Voyez Les réponses aux discussions ont été converties en commentaires

• river/object/discussion/create

• river/object/discussion_reply/create : Voyez Les réponses aux discussions ont été converties en commentaires

• search/object/discussion_reply/entity : Voyez Les réponses aux discussions ont été converties en commentaires

• rss/discussion/replies : Voyez Les réponses aux discussions ont été converties en commentaires

• search/header

• search/layout dans les deux types de vues default et rss

• search/no_results

• search/object/comment/entity

• search/css: Déplacé vers search/search.css

• search/startblurb

• bookmarks/bookmarklet.gif

• blog_get_page_content_list

• blog_get_page_content_archive

• blog_get_page_content_edit

• forms/invitefriends/invite: utilisez forms/friends/invite

• resources/invitefriends/invite: utilisez resources/friends/invite

• resources/reportedcontent/add

• resources/reportedcontent/add_form

• resources/site_notifications/view: Utilisez resources/site_notifications/owner

• resources/site_notifications/everyone : Utilisez resources/site_notifications/all

Fonctions/méthodes supprimées

Toutes les fonctions dans engine/lib/deprecated-1.9.php ont été supprimées. Voir https://github.com/Elgg/Elgg/blob/2.0/engine/lib/deprecated-1.9.php pour ces fonctions. Chaque déclaration @deprecated comprend des instructions sur ce qu’il faut utiliser à la place. Toutes les fonctions de engine/lib/deprecated-1.10.php ont été supprimées. Voir https://github.com/Elgg/Elgg/blob/2.0/engine/lib/deprecated-1.10.php pour ces fonctions. Chaque déclaration @deprecated comprend des instructions sur ce qu’il faut utiliser à la place.

• elgg_register_library : exigez - require - vos bibliothèques afin qu’elles soient disponibles globalement pour d’autres plugins

• elgg_load_library

• activity_profile_menu

• can_write_to_container : Utilisez ElggEntity->canWriteToContainer()

• create_metadata_from_array

• metadata_array_to_values

• datalist_get

• datalist_set

• detect_extender_valuetype

• developers_setup_menu

• elgg_disable_metadata

• elgg_enable_metadata

• elgg_get_class_loader

• elgg_get_metastring_id

• elgg_get_metastring_map

• elgg_register_class

• elgg_register_classes

• elgg_register_viewtype

• elgg_is_registered_viewtype

• file_delete: Utilisez ElggFile->deleteIcon()

• file_get_type_cloud

• file_type_cloud_get_url

• get_default_filestore

• get_site_entity_as_row

• get_group_entity_as_row

• get_missing_language_keys

• get_object_entity_as_row

• get_user_entity_as_row

• update_river_access_by_object

• garbagecollector_orphaned_metastrings

• groups_access_collection_override

• groups_get_group_tool_options : Utilisez elgg()->group_tools->all()

• groups_join_group : Utilisez ElggGroup::join

• groups_prepare_profile_buttons : Utilisez le hook register, menu:title

• groups_register_profile_buttons : Utilisez le hook register, menu:title

• groups_setup_sidebar_menus

• groups_set_icon_url

• groups_setup_sidebar_menus

• messages_notification_msg

• set_default_filestore

• generate_user_password : Utilisez ElggUser::setPassword

• row_to_elggrelationship

• run_function_once : Utilisez l’interface Elgg\Upgrade\Batch

• system_messages

• notifications_plugin_pagesetup

• elgg_format_url : Utilisez elgg_format_element() ou la vue « output/text » pour échapper le HTML.

• get_site_by_url

• elgg_override_permissions : N’est plus utilisé comme gestionnaire pour les hooks permissions_check et container_permissions_check

• elgg_check_access_overrides

• AttributeLoader est devenu obsolète et a été supprimé

• Application::loadSettings

• ElggEntity::addToSite

• ElggEntity::disableMetadata

• ElggEntity::enableMetadata

• ElggEntity::getSites

• ElggEntity::removeFromSite

• ElggEntity::isFullyLoaded

• ElggEntity::clearAllFiles

• ElggPlugin::getFriendlyName : Utilisez ElggPlugin::getDisplayName()

• ElggPlugin::setID

• ElggPlugin::unsetAllUsersSettings

• ElggFile::setFilestore : les objets ElggFile ne peuvent plus utiliser de répertoire de fichiers personnalisé.

• ElggFile::size : Utilisez getSize

• ElggDiskFilestore::makeFileMatrix : Utilisez Elgg\EntityDirLocator

• ElggData::get : Peut habituellement être remplacé par la lecture de la propriété

• ElggData::getClassName : Utilisez get_class()

• ElggData::set : Peut habituellement être remplacé par l’écriture de propriété

• ElggEntity::setURL : Voyez getURL pour plus de détails sur le hook plugin

• ElggMenuBuilder::compareByWeight : Utilisez compareByPriority

• ElggMenuItem::getWeight : Utilisez getPriority

• ElggMenuItem::getContent : Utilisez elgg_view_menu_item()

• ElggMenuItem::setWeight : Utilisez setPriority

• ElggRiverItem::getPostedTime : Utilisez getTimePosted

• ElggSession a supprimé toutes les méthodes dépréciées

• ElggSite::addEntity

• ElggSite::addObject

• ElggSite::addUser

• ElggSite::getEntities : Utilisez elgg_get_entities()

• ElggSite::getExportableValues : Utilisez toObject

• ElggSite::getMembers : Utilisez elgg_get_entities()

• ElggSite::getObjects : Utilisez elgg_get_entities()

• ElggSite::listMembers : Utilisez elgg_list_entities()

• ElggSite::removeEntity

• ElggSite::removeObject

• ElggSite::removeUser

• ElggSite::isPublicPage : Logique déplacée vers le routeur et qui ne devrait pas être consultée directement

• ElggSite::checkWalledGarden : Logique déplacée vers le routeur et qui ne devrait pas être accédée directement

• ElggUser::countObjects : Utilisez elgg_get_entities()

• Logger::getClassName : Utilisez get_class()

• Elgg\Application\Database::getTablePrefix : Lisez la propriété prefix

• elgg_view_access_collections()

• ElggSession::get_ignore_access : Utilisez getIgnoreAccess

• ElggSession::set_ignore_access : Utilisez setIgnoreAccess

• profile_pagesetup

• pages_can_delete_page : Utilisez $entity->canDelete()

• pages_search_pages

• pages_is_page : utilisez $entity instanceof ElggPage

• discussion_comment_override : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_can_edit_reply : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_reply_menu_setup : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_reply_container_logic_override : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_reply_container_permissions_override : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_update_reply_access_ids : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_search_discussion : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_add_to_river_menu : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_prepare_reply_notification : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_redirect_to_reply : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion_ecml_views_hook : Voyez Les réponses aux discussions ont été converties en commentaires

• search_get_where_sql

• search_get_ft_min_max

• search_get_order_by_sql

• search_consolidate_substrings

• search_remove_ignored_words

• search_get_highlighted_relevant_substrings

• search_highlight_words

• search_get_search_view

• search_custom_types_tags_hook

• search_tags_hook

• search_users_hook

• search_groups_hook

• search_objects_hook

• members_list_popular

• members_list_newest

• members_list_online

• members_list_alpha

• members_nav_popular

• members_nav_newest

• members_nav_online

• members_nav_alpha

• uservalidationbyemail_generate_code

Toutes les fonctions liées à la table des sous-types d’entités :

• add_subtype : Utilisez elgg_set_entity_class lors de l’exécution

• update_subtype : Utilisez elgg_set_entity_class lors de l’exécution

• remove_subtype

• get_subtype_id

• get_subtype_from_id

• get_subtype_class : Utilisez elgg_get_entity_class

• get_subtype_class_from_id

Tous les caches ont été consolidés en une seule couche d’API. Les fonctions et méthodes suivantes ont été supprimées :

• is_memcache_available

• _elgg_get_memcache

• _elgg_invalidate_memcache_for_entity

• ElggMemcache

• ElggFileCache

• ElggStaticVariableCache

• ElggSharedMemoryCache

• L’interface Elgg\Cache\Pool et toutes les classes d’extension

À la suite des modifications apportées au journal du système - system log :

• system_log_default_logger : déplacé dans le plugin system_log

• system_log_listener : déplacé dans le plugin system_log

• system_log : déplacé dans le plugin system_log

• get_system_log : renommé system_log_get_log et déplacé dans le plugin system_log

• get_log_entry : renommé system_log_get_log_entry et déplacé dans le plugin system_log

• get_object_from_log_entry : renommé system_log_get_object_from_log_entry et déplacé dans le plugin system_log

• archive_log : renommé system_log_archive_log et déplacé dans le plugin system_log

• logbrowser_user_hover_menu : renommé system_log_user_hover_menu et déplacé dans le plugin system_log

• logrotate_archive_cron : renommé system_log_archive_cron et déplacé dans le plugin system_log

• logrotate_delete_cron : renommé system_log_delete_cron et déplacé dans le plugin system_log

• logrotate_get_seconds_in_period : renommé system_log_get_seconds_in_period et déplacé dans le plugin system_log

• log_browser_delete_log : renommé system_log_browser_delete_log et déplacé dans le plugin system_log

APIs dépréciées

• ban_user : Utilisez ElggUser->ban()

• create_metadata : Utilisez la définition avec ElggEntity ou ElggEntity->setMetadata()

• update_metadata : Utilisez ElggMetadata->save()

• get_metadata_url

• create_annotation : Utilisez ElggEntity->annotate()

• update_metadata : Utilisez ElggAnnotation->save()

• elgg_get_user_validation_status : Utilisez ElggUser->isValidated()

• make_user_admin : Utilisez ElggUser->makeAdmin()

• remove_user_admin : Utilisez ElggUser->removeAdmin()

• unban_user : Utilisez ElggUser->unban()

• elgg_get_entities_from_attributes : Utilisez elgg_get_entities()

• elgg_get_entities_from_metadata : Utilisez elgg_get_entities()

• elgg_get_entities_from_relationship : Utilisez elgg_get_entities()

• elgg_get_entities_from_private_settings : Utilisez elgg_get_entities()

• elgg_get_entities_from_access_id : Utilisez elgg_get_entities()

• elgg_list_entities_from_metadata : Utilisez elgg_list_entities()

• elgg_list_entities_from_relationship : Utilisez elgg_list_entities()

• elgg_list_entities_from_private_settings : Utilisez elgg_list_entities()

• elgg_list_entities_from_access_id : Utilisez elgg_list_entities()

• elgg_list_registered_entities : Utilisez elgg_list_entities()

• elgg_batch_delete_callback

• \Elgg\Project\Paths::sanitize : Utilisez \Elgg\Project\Paths::sanitize()

• elgg_group_gatekeeper : Utilisez elgg_entity_gatekeeper()

• get_entity_dates : Utilisez elgg_get_entity_dates()

• messages_set_url : Utilisez ElggEntity::getURL()

Variables globales supprimées

• $CURRENT_SYSTEM_VIEWTYPE

• $DEFAULT_FILE_STORE

• $ENTITY_CACHE

• $SESSION: Utilisez l’API fournie par elgg_get_session()

• $CONFIG->site_id : Utilisez 1

• $CONFIG->search_info

• $CONFIG->input : Utilisez set_input et get_input

Classes/interfaces supprimées

• FilePluginFile : remplacez par ElggFile (ou chargez avec get_entity())

• Elgg_Notifications_Notification

• Elgg\Database\EntityTable\UserFetchResultException.php

• Elgg\Database\MetastringsTable

• Elgg\Database\SubtypeTable

• Exportable et ses méthodes export et getExportableValues : Utilisez toObject

• ExportException

• Importable et sa méthode import.

• ImportException

• ODD et toutes les classes commençant par ODD*.

• XmlElement

• Elgg_Notifications_Event : Utilisez \Elgg\Notifications\Event

• Elgg\Mail\Address : utilisez Elgg\Email\Address

• ElggDiscussionReply : utilisez ElggComment voyez Les réponses aux discussions ont été converties en commentaires

Modifications de schéma

Le moteur de stockage des tables de la base de données a été changé de MyISAM à InnoDB. Vous devrez peut-être optimiser les paramètres de votre base de données pour cette modification. La table datalists a été supprimée. Tous les paramètres de la table datalists ont été fusionnés dans la table config.

Les chaînes de métadonnées - metastrings - de la base de données ont été dénormalisées à des fins de performance. Nous avons supprimé la table metastrings et mis toutes les valeurs de chaîne directement dans les tables de métadonnées et d’annotation. Vous devez mettre à jour vos requêtes personnalisées pour refléter ces modifications. Les alias de table msv et msn ne sont plus disponibles. Il est préférable de ne pas s’appuyer sur les alias de table utilisés dans les requêtes du noyau. Si vous avez besoin d’utiliser des clauses personnalisées, vous devriez faire vos propres jointures.

Dans la table users_entity, les colonnes password et hash ont été supprimées.

La table geocode_cache a été supprimée car elle n’était plus utilisée.

La colonne subtype dans la table entities ne contient plus d’ID de sous-type, mais une chaîne avec le sous-type. La table entity_subtypes a été supprimée.

les colonnes type, subtype et access_id de la table river ont été abandonnées. Pour les requêtes sans elgg_get_river() joignez la table entities sur object_guid pour vérifier le type et le sous-type de l’entité. La colonne d’accès n’est plus utilisée depuis un certain temps : les requêtes sont conçues pour garantir l’accès aux trois entités (subject, object et target).

Changements dans les fonctions de récupération elgg_get_entities, elgg_get_metadata et elgg_get_annotations

elgg_get_entities accepte désormais toutes les options qui étaient auparavant réparties entre elgg_get_entities_from_metadata, elgg_get_entities_from_annotations, elgg_get_entities_from_relationship, elgg_get_entities_from_private_settings et elgg_get_entities_from_access_id. Ces dernières ont été dépréciées.

La transmission d’instructions MySQL brutes aux options est obsolète. Il est conseillé d’utiliser des Closures qui reçoivent une instance de \Elgg\Database\QueryBuilder et de préparer l’instruction à l’aide de la couche d’abstraction de la base de données. D’une part, cela permettra de s’assurer que toutes les instructions sont correctement aseptisées à l’aide du pilote de base de données, d’autre part, il nous permettra de passer à une construction de requête orientée objet qui soit testable.

Les instructions wheres ne devraient pas utiliser de chaînes SQL brutes, et plutôt passer une instance de \Elgg\Database\Clauses\WhereClause ou une Closure qui renvoie une instance de \Doctrine\DBAL\Query\Expression\CompositeExpression :

elgg_get_entities([
   'wheres' => [
        function(\Elgg\Database\QueryBuilder $qb, $alias) {
           $joined_alias = $qb->joinMetadataTable($alias, 'guid', 'status');
           return $qb->compare("$joined_alias.name", 'in', ['draft', 'unsaved_draft'], ELGG_VALUE_STRING);
        }
   ]
]);

Les clauses joins, order_by, group_by, selects ne devraient pas utiliser de chaînes SQL brutes. Utilisez les Closures qui reçoivent une instance de \Elgg\Database\QueryBuilder et renvoyez une instruction préparée - prepared statement.

L’option reverse_order_by a été supprimée.

Les plugins ne devraient pas s’appuyer sur des alias de table jointes et sélectionnées. Les Closures transmises au tableau d’options recevront un deuxième argument correspondant à l’alias de table sélectionné. Les plugins doivent effectuer leurs propres jointures et utiliser des alias de jointure en conséquence.

Notez que toute l’API privée autour de la construction de chaînes SQL brutes a également été supprimée. Si vous l’utilisiez dans vos plugins, soyez informé que tout ce qui est marqué comme @access private ou @internal dans le noyau peut être modifié et supprimé à tout moment, et que nous ne garantissons aucune compatibilité arrière pour ces fonctions. NE LES UTILISEZ PAS. Si vous avez besoin de les utiliser, ouvrez un ticket sur Github et nous envisagerons d’ajouter un équivalent public.

Propriétés de l’entité booléenne

Le stockage des métadonnées, des annotations et des valeurs de paramètres privés a été aligné.

Les valeurs booléennes sont transformées en entiers lorsqu’elles sont enregistrées : false est stocké comme 0 et true est stocké comme 1. Cela a des implications de rupture pour les paramètres privés, qui étaient précédemment stockés comme des chaînes vides pour les valeurs false. Les plugins doivent écrire leurs propres scripts de migration pour modifier les valeurs de la BD des chaînes vides à 0 (pour les paramètres privés qui sont censés stocker des valeurs booléennes) afin de s’assurer que elgg_get_entities() peut récupérer ces valeurs avec private_setting_name_value_pairs contenant des valeurs false. Cela s’applique aux paramètres de plugin, ainsi qu’à tous les paramètres privés ajoutés aux entités.

Modifications des métadonnées

Les métadonnées ne sont plus contrôlées par accès. Si votre plugin a créé des métadonnées avec un accès restreint, ces restrictions ne seront pas respectées. Vous devez utiliser des annotations ou des entités à la place, qui fournissent un contrôle d’accès.

Ne lisez pas ou n’écrivez pas la propriété access_id sur les objets ElggMetadata.

Les métadonnées ne sont plus activées ou désactivées. Vous ne pouvez plus effectuer les appels API enable et disable sur les métadonnées.

Les métadonnées n’ont plus de owner_guid. Il n’est plus possible d’interroger les métadonnées sur la base de leur owner_guids. Par conséquence, ElggMetadata::canEdit() renvoie toujours true indépendamment de l’utilisateur connecté, à moins que cela soit explicitement remplacé par un hook de plugin.

Permissions et droits d’accès

Le service des capacités de l’utilisateur ne déclenche plus les hooks de vérification des autorisations lorsque :

• les autorisations sont vérifiées pour un utilisateur administrateur

• les autorisations sont vérifiées lorsque l’accès est ignoré avec elgg_set_ignore_access()

Cela signifie que les plugins ne peuvent plus modifier les autorisations dans les cas mentionnés ci-dessus.

elgg_check_access_overrides() a été supprimé, car les plugins n’auront plus besoin de valider les remplacements d’accès.

Les traductions pour les niveaux d’accès de Elgg par défaut ont de nouvelles clefs de traduction.

Modifications Multisite

Avant la version 3.0, Elgg disposait d’une certaine prise en charge (partielle) pour avoir plusieurs sites dans la même base de données. Ce concept multisite a été complètement supprimé dans la version 3.0. Les entités n’ont plus l’attribut site_guid. Cela signifie qu’il n’y a plus la possibilité d’avoir des entités sur différents sites. Si vous avez actuellement plusieurs sites dans votre base de données, la mise à niveau de Elgg vers Elgg 3.0 échouera. Vous devez séparer les différents sites en bases de données/tables distinctes.

En lien avecla suppression du concept multisite de Elgg, il n’est plus nécessaire que les entités aient une relation “member_of_site” avec l’entité du site. Toutes les fonctions liées à l’ajout/suppression de cette relation ont été supprimées. Toutes les relations existantes seront supprimées dans le cadre de cette mise à niveau.

La définition de ElggSite::$url n’a aucun effet. La lecture de l’URL du site est toujours faite depuis la valeur définie par $CONFIG->wwwroot dans settings.php, ou calculée par Symphony Request.

ElggSite::save() échouera si ce n’est pas le site principal.

Modifications de la sous-table des entités

La sous-table sites_entity pour ElggSite n’existe plus. Tous les attributs ont été déplacés vers les métadonnées. La sous-table groups_entity pour ElggGroup n’existe plus. Tous les attributs ont été déplacés vers les métadonnées. La sous-table objects_entity pour ElggObject n’existe plus. Tous les attributs ont été déplacés vers les métadonnées. La sous-table users_entity pour ElggUser n’existe plus. Tous les attributs ont été déplacés vers les métadonnées.

Si vous avez des requêtes personnalisées faisant référence à cette table, vous devez les mettre à jour. Si vous avez une fonction qui s’appuie sur Entity->getOriginalAttributes(), sachez que cela ne renvoie que les attributs de base d’une ElggEntity et ne contient plus les attributs secondaires.

Collection d’accès des Contacts et des Groupes

La table des collections d’accès dispose maintenant d’une colonne de sous-type. Ces données supplémentaires permettent d’identifier le but de l’ACL. Les collections d’accès appartenant à l’utilisateur sont supposées être utilisées comme collections de contacts - Friends Collections - et ont le sous-type “friends_collection”. L’information de collection d’accès des groupes était auparavant conservée dans la métadonnée group_acl. Avec l’introduction du sous-type ACL, cette information a été déplacée vers l’attribut de sous-type ACL.

L’access_id ACCESS_FRIENDS a été migré vers une collection d’accès réelle (avec le sous-type friends). Toutes les entités et annotations ont été mises à jour pour utiliser le nouvel id de collection d’accès. La collection d’accès est créée lors de la création d’un utilisateur. Lorsqu’une relation du type friends est créée, le guid associé sera également ajouté à la collection d’accès. Vous ne pouvez plus enregistrer ou mettre à jour les entités avec l’id d’accès ACCESS_FRIENDS.

Les sous-types n’ont plus d’ID

Les sous-types d’entités ont été dénormalisés. La table entity_subtypes a été supprimée et la colonne subtype dans la table entités contient simplement la représentation sous forme de chaîne du sous-type.

Par conséquent, toutes les API relatives à l’ajout et la mise à jour des sous-types et des classes d’entités ont été supprimées.

Les plugins peuvent désormais utiliser elgg_set_entity_class() et elgg_get_entity_class() pour enregistrer une classe d’entité personnalisée au moment de l’exécution (par exemple dans le gestionnaire d’initialisation du système).

Toutes les entités DOIVENT maintenant avoir un sous-type. Par défaut, les sous-types suivants sont ajoutés et réservés :

• user pour les utilisateurs

• group pour les groupes

• site pour les sites

Chargement de classe personnalisée

Elgg ne fournit plus de fonctions API pour enregistrer des classes personnalisées. Si vous avez besoin de classes personnalisées, vous pouvez utiliser des classes PSR-0 dans le dossier /classes de votre plugin ou utiliser composer pour charger automatiquement des classes supplémentaires.

Les fonctions suivantes liées à l’enregistrement des classes ont été supprimées :

• elgg_get_class_loader

• elgg_register_class

• elgg_register_classes

Conteneur d’injection de dépendance - DI = Dependency Injection

Les plugins peuvent maintenant définir leurs services et les attacher au conteneur public DI de Elgg en fournissant des définitions dans elgg-services.php dans la racine du répertoire de plugin.

elgg() ne renvoie plus une instance d’application Elgg, mais une instance de conteneur DI.

Modifications de la recherche

Nous avons ajouté un service de recherche dans le noyau, par conséquent, le plugin search fournit désormais uniquement une interface utilisateur pour afficher les formulaires et afficher les résultats de recherche. Beaucoup des vues du plugin search ont été affectées par ce changement.

Les indices FULLTEXT ont été supprimés sur différentes tables. Le plugin de recherche utilise désormais toujours une requête LIKE lors de l’exécution d’une recherche.

Voir la documentation Search Service et Search hooks pour des informations détaillées sur les nouvelles fonctionnalités de recherche.

Modifications liées aux formulaires et aux champs

• input/password : par défaut, ce champ n’affichera plus la valeur qui lui est transmise ; cela peut être remplacé en passant à la vue la variable always_empty définie sur false

• input/submit, input/reinit et input/button sont maintenant rendus avec un <button> au lieu de la balise <input>. Ces vues d’entrée acceptent également les paramètres text et icon.

• output/url définit maintenant la classe .elgg-anchor sur les éléments d’ancre et accepte le paramètre icon. Si aucun text n’est défini, le paramètre href est utilisé comme étiquette et sera limité à 100 caractères.

• output/url prend désormais en charge un paramètre badge, qui peut être utilisé lorsqu’un compteur, un badge ou autre est requis comme suffixe (principalement dans les éléments de menu qui ont des compteurs).

• output/tags n’utilise plus de balises <ul> avec des floats, et au lieu de cela s’appuie sur des éléments intrinsèquement en ligne inline tels que <span> et <a>

Modifications du menu des entités et de la rivière

Le menu Entity et le menu River affichent désormais tous les éléments d’une liste déroulante. Les actions sociales comme aimer ou commenter sont déplacées vers un menu alternatif appelé le menu social, qui est destiné aux actions sociales.

Bibliothèques supprimées

elgg_register_library et elgg_load_library ont été supprimées. Ces fonctions ont eu peu d’impact sur les performances (en particulier avec OPCache activé), et il a été difficile pour d’autres plugins de travailler avec les APIs contenues dans les bibliothèques. En outre, il était difficile pour les développeurs de savoir que les APIs étaient contenues dans une bibliothèque alors qu’il y a une autocomplétion par l’IDE.

Si vous êtes concerné par les performances, déplacez la logique vers les classes et laissez PHP les charger automatiquement au besoin, sinon utilisez require_once et exigez vos bibliothèques.

Gestionnaires de pages supprimés

• file/download

• file/search

• groupicon

• twitterservice

• collections/pickercallback

• discussion/reply : Voyez Les réponses aux discussions ont été converties en commentaires

• expages

• invitefriends : Utilisez friends/{username}/invite

• messages/compose : Utilisez messages/add

• reportedcontent

Actions supprimées

• file/download : Utilisez elgg_get_inline_url ou elgg_get_download_url

• file/delete : Utilisez l’action entity/delete

• import/opendd

• discussion/reply/save : Voyez Les réponses aux discussions ont été converties en commentaires

• discussion/reply/delete : Voyez Les réponses aux discussions ont été converties en commentaires

• comment/delete : Utilisez l’action entity/delete

• uservalidationbyemail/bulk_action : utilisez admin/user/bulk/validate ou admin/user/bulk/delete

• uservalidationbyemail/delete : utilisez admin/user/bulk/delete

• uservalidationbyemail/validate : utilisez admin/user/bulk/validate

• invitefriends/invite : utilisez friends/invite

Modifications de l’héritage

• ElggData (et donc la plupart des objets du domaine Elgg) n’implémente plus Exportable

• ElggEntity n’implémente plus Importable

• ElggGroup n’implémente plus Friendable

• ElggRelationship n’implémente plus Importable

• ElggSession n’implémente plus ArrayAccess

• Elgg\Application\Database n’étend plus Elgg\Database

APIs JavaScript supprimées

• admin.js

• elgg.widgets : Utilisez le module elgg/widgets. Les dispositions « widgets » chargent ce module automatiquement

• lightbox.js : Utilisez le module elgg/lightbox au besoin

• lightbox/settings.js : Utilisez le hook JS getOptions, ui.lightbox ou l’attribut data-colorbox-opts

• elgg.ui.popupClose : Utilisez le module elgg/popup

• elgg.ui.popupOpen : Utilisez le module elgg/popup

• elgg.ui.initAccessInputs

• elgg.ui.river

• elgg.ui.initDatePicker : Utilisez le module input/date

• elgg.ui.likesPopupHandler

• elgg.embed : Utilisez le module elgg/embed

• elgg.discussion : Utilisez le module elgg/discussion

• embed/custom_insert_js : Utilisez le hook JS embed, editor

• elgg/ckeditor.js : remplacé par elgg-ckeditor.js

• elgg/ckeditor/set-basepath.js

• elgg/ckeditor/insert.js

• jQuery.cookie : Utilisez elgg.session.cookie

• jquery.jeditable

• likes.js : Le module elgg/likes est chargé automatiquement

• messageboard.js

• elgg.autocomplete n’est plus défini.

• elgg.messageboard n’est plus défini.

• jQuery.fn.friendsPicker

• elgg.ui.toggleMenu n’est plus défini

• elgg.ui.toggleMenuItems : Utilisez l’attribut data-toggle lorsque vous enregistrez des éléments de menu basculables

• uservalidationbyemail/js.php : Utilisez le module elgg/uservalidationbyemail

• discussion.js : Voyez Les réponses aux discussions ont été converties en commentaires

Hooks/événements retirés

• Événement login, user : Utilisez login:before ou login:after. Notez que l’utilisateur n’est pas connecté pendant l’événement login:before

• Événement delete, annotations : Utilisez delete, annotation

• Événement pagesetup, system : Utilisez plutôt les hook de menu ou de coquille depage

• Événement upgrade, upgrade : Utilisez upgrade, system à la place

• Hook index, system : Remplacez la vue resources/index

• Hook object:notifications, <type> : Utilisez le hook send:before, notifications

• Hook output:before, layout : Utilisez view_vars, page/layout/<layout_name>

• Hook output:after, layout : Utilisez view, page/layout/<layout_name>

• Hook email, system : Utilisez les hooks plus granulaires <hook>, system:email

• Hook email:message, system : Utilisez le hook zend:message, system:email

• Hook members:list, <page> : Utilisez le hook de route ou votre propre gestionnaire de page

• Hook members:config, <page> : Utilisez register, menu:filter:members

• Hook profile_buttons, group : Utilisez register, menu:title

Formulaires/actions supprimés

• formulaire et action notificationsettings/save

• formulaire et action notificationssettings/groupsave

• formulaire et action discussion/reply/save

APIs qui n’acceptent plus qu’un tableau $options

• ElggEntity::getAnnotations

• ElggEntity::getEntitiesFromRelationship

• ElggEntity::getEntitiesFromRelationship

• ElggUser::getGroups

• ElggUser::getFriends (en tant que Friendable)

• ElggUser::getFriendsOf (dans le cadre de Friendable)

• ElggUser::getFriendsObjects (dans le cadre de Friendable)

• ElggUser::getObjects (dans le cadre de Friendable)

• find_active_users

• elgg_get_admin_notices

Fonctions plugin qui nécessitent maintenant un $plugin_id explicite

• elgg_get_all_plugin_user_settings

• elgg_set_plugin_user_setting

• elgg_unset_plugin_user_setting

• elgg_get_plugin_user_setting

• elgg_set_plugin_setting

• elgg_get_plugin_setting

• elgg_unset_plugin_setting

• elgg_unset_all_plugin_settings

Constructeurs de classes qui n’acceptent désormais qu’un objet stdClass ou null

• ElggAnnotation : N’accepte plus un ID d’annotation

• ElggGroup : N’accepte plus un GUID

• ElggMetadata : N’accepte plus un ID de métadonnées

• ElggObject : N’accepte plus un GUID

• ElggRelationship : N’accepte plus un ID de relation ni null

• ElggSite : N’accepte plus un GUID ni une URL

• ElggUser : N’accepte plus un GUID ni un nom d’utilisateur

• ElggPlugin : N’accepte plus un GUID ni un chemin. Utilisez ElggPlugin::fromId pour construire un plugin à partir de son chemin

Modifications d’API diverses

• ElggBatch : Vous ne pouvez accéder qu’aux propriétés publiques

• ElggEntity : Les propriétés tables_split et tables_loaded ont été supprimées

• ElggEntity : Les URL vides ne seront plus normalisées. Cela signifie que les entités sans URL ne vont plus avoir l’URL du site

• ElggGroup::removeObjectFromGroup nécessite de passer un ElggObject (n’accepte plus un GUID)

• ElggUser::$salt n’existe plus en tant qu’attribut, et n’est plus utilisé pour l’authentification

• ElggUser::$password n’existe plus en tant qu’attribut, et n’est plus utilisé pour l’authentification

• elgg_get_widget_types ne prend plus en charge $exact comme 2ème argument

• elgg_instanceof ne prend plus en charge le quatrième argument class

• elgg_view : Les 3ème et 4ème arguments (inutilisés) ont été supprimés. Si vous utilisiez l’argument $viewtype, vous devez mettre à jour votre utilisation.

• elgg_view_icon ne prend plus en charge true comme 2e argument

• elgg_list_entities ne prend plus en charge l’option view_type_toggle

• elgg_list_registered_entities ne prend plus en charge l’option view_type_toggle

• elgg_log n’accepte plus le niveau "DEBUG"

• elgg_dump n’accepte plus d’argument $to_screen.

• elgg_gatekeeper et elgg_admin_gatekeeper ne signalent plus login ou admin comme motif de redirection, mais 403

• Application::getDb() ne renvoie plus une instance de Elgg\Database, mais de Elgg\Application\Database

• $CONFIG n’est plus disponible en tant que variable locale dans les fichiers start.php des plugins.

• elgg_get_config('siteemail') n’est plus disponible. Utilisez elgg_get_site_entity()->email.

• ElggEntity::saveIconFromUploadedFile enregistre uniquement la taille master, les autres tailles sont créées sur demande par ElggEntity::getIcon() à partir de la taille master

• ElggEntity::saveIconFromLocalFile enregistre uniquement la taille master, les autres tailles sont créées sur demande par ElggEntity::getIcon() à partir de la taille master

• ElggEntity::saveIconFromElggFile enregistre uniquement la taille master`, les autres tailles sont créées sur demande par ElggEntity::getIcon() à partir de la taille master

• Les entités de groupe n’ont plus l’attribut magique username.

• Le gestionnaire de page ne détecte plus group:<guid> dans l’URL

• L’intervalle CRON reboot est supprimé.

• Les points de terminaison d’URL js/ et css/ ne sont plus pris en charge. Utilisez elgg_get_simplecache_url().

• L’action générique d’enregistrement de commentaire n’envoie plus la notification directement, cela a été déchargé vers le système de notification.

• Le script engine/start.php est supprimé.

• Les fonctions set_config, unset_config et get_config ont été dépréciées et remplacées par elgg_set_config, elgg_remove_config et elgg_get_config.

• Les valeurs de configuration path, wwwroot et dataroot ne sont pas lues dans la base de données. Les valeurs du fichier settings.php sont toujours utilisées.

• Les fonctions de configuration telles que elgg_get_config n’émondent plus - trim - les clefs.

• Si vous remplacez la vue navigation/menu/user_hover/placeholder, vous devez modifier la clef de configuration lazy_hover:menus en elgg_lazy_hover_menus.

• La valeur de configuration entity_types n’est plus présente ni utilisée.

• Les images téléchargées sont auto-pivotées en fonction de leurs métadonnées d’orientation.

• La vue object/widget/edit/num_display utilise désormais un champ input/number au lieu de input/select ; vous pourriez avoir besoin de mettre à jour vos vues de configuration des widgets en conséquence.

• Les noms d’annotation ne sont plus émondés - trim - lors de l’enregistrement

Le comportement d’extension des vues a été modifié

Une vue étendue recevra désormais tous les hooks classiques (comme le hook view_vars). Il est désormais également possible d’étendre les extensions de vue. Avec ce changement de comportement, tous les rendus de vue se comporteront de la même façon. Cela n’a plus d’importance si une vue est utilisée comme une extension ou non.

L’ordre d’appel des hooks JavaScript pourrait changer

Lors de l’enregistrement pour des hooks, le mot clef all pour la correspondance générique n’a plus aucun effet sur l’ordre dans lequel les gestionnaires sont appelés. Pour vous assurer que votre gestionnaire est appelé en dernier, vous devez lui donner la plus haute priorité de tous les gestionnaires correspondants, ou pour vous assurer que votre gestionnaire est appelé en premier, vous devez lui donner la plus faible priorité de tous les gestionnaires correspondants.

Si les gestionnaires ont été enregistrés avec la même priorité, ceux-ci sont appelés dans l’ordre où ils ont été enregistrés.

Pour émuler le comportement antérieur, les gestionnaires du noyau Elgg enregistrés avec le mot clé all ont été élevés en priorité. Certains de ces gestionnaires seront très probablement appelés dans un ordre différent.

Modifications liées à la disposition widget

L’utilisation de la disposition widget a été modifiée. Le contenu n’est plus rendu dans le cadre de la mise en page. Vous devez envelopper votre contenu dans une autre mise en page et utiliser la disposition widget comme contenu. Si vous souhaitez que du contenu spécial s’affiche s’il n’y a pas de widgets dans la mise en page, vous pouvez maintenant passer un paramètre spécial no_widgets (sous forme de chaîne ou de Closure).

Lors de l’enregistrement des widgets, vous ne pouvez plus omettre de passer un contexte car le contexte all n’est plus pris en charge. Vous devez explicitement passer les contextes pour lesquels le widget est destiné.

Routage

La gestion des pages à l’aide de elgg_register_page_handler() est devenue obsolète.

Nous avons ajouté une nouvelle API de routage utilisant elgg_register_route(), qui permet aux plugins de définir des routes nommées, en utilisant par la suite des noms de routes pour générer des URLs à l’aide de elgg_generate_url().

Pour plus d’informations, consultez les documentations sur le routage.

À la suite de cette modification, tous les gestionnaires de pages de base ont été supprimés et toute la logique contenue dans ces gestionnaires de pages a été déplacée vers les vues de ressources respectives.

elgg_generate_entity_url() a été ajouté comme raccourci pour générer des URLs à partir de routes nommées qui dépendent du type d’entité et du sous-type.

L’utilisation du paramètre handler dans les menus des entités a été dépréciée au profit des routes d’entités nommées.

Les fonctions Gatekeeper ont été refactorisées pour servir de middleware dans le processus de routage, et en tant que tel, elles ne retournent plus de valeurs. Ces fonctions lancent des exceptions HTTP qui sont ensuite acheminées vers des pages d’erreur et peuvent être redirigées vers d’autres pages via des hooks.

Nommage

Les conventions de nommage des entités et des collections ont changé pour se conformer aux nouveaux schémas de routage :

return [
   'item:object:blog' => 'Blog',
   'collection:object:blog' => 'Blogs',
   'collection:object:blog:all' => 'All site blogs',
   'collection:object:blog:owner' => '%s\'s blogs',
   'collection:object:blog:group' => 'Group blogs',
   'collection:object:blog:friends' => 'Friends\' blogs',
   'add:object:blog' => 'Add blog post',
   'edit:object:blog' => 'Edit blog post',
];

Ces conventions sont utilisées dans les systèmes de routage et de navigation, de sorte que les plugins sont invités à les suivre.

Filtrage des valeurs de la requête

set_input() et get_input() ne suppriment plus les espaces - trim - des valeurs.

Réponses des actions

Toutes les actions du noyau et des plugins du noyau utilisent maintenant toutes les nouvelles fonctions de Http Response comme elgg_ok_response et elgg_error_response au lieu de forward(). L’effet de ce changement est que dans la plupart des cas le hook “forward”, “system” n’est plus déclenché. Si vous souhaitez modifier les réponses, vous pouvez maintenant utiliser le hook “response”,”action:<name/of/action>”. Cela vous donne plus de contrôle sur la réponse et permet de cibler une action spécifique très facilement.

HtmLawed n’est plus un plugin

• N’appelez pas elgg_load_library('htmlawed').

• Dans les paramètres du hook pour 'config', 'htmlawed', le nom de la fonction hook_tag a changé.

Nouvelle approche des mises en page - layouts

Les dispositions one_column, one_sidebar, two_sidebar et content ont été supprimées - au lieu de cela, le rendu de la disposition a été centralisé dans default. La mise à jour de la disposition default permet de contrôler pleinement les éléments de mise en page via $vars. Pour obtenir une compatibilité descendante maximale, les appels à elgg_view_layout() avec ces noms de disposition donneront toujours la sortie attendue, mais les plugins doivent commencer à utiliser la disposition default avec un ensemble de paramètres mis à jour.

Les mises en page ont été découpées en éléments plus petits, ce qui devrait faciliter le ciblage d’éléments de mise en page spécifiques par les thèmes sans avoir à remplacer les dispositions en général.

À la suite de ces changements :

• toutes les dispositions sont cohérentes dans la façon dont elles gèrent les menus de titre et de filtre, le fil d’Ariane et les sous-vues de mise en page

• toutes les dispositions peuvent maintenant être facilement étendues pour avoir plusieurs onglets. Les plugins peuvent passer le paramètre filter_id qui permettra à d’autres plugins de s’accrocher au hook register, menu:filter:<filter_id> et d’ajouter de nouveaux onglets. Si aucun filter_id n’est fourni, le hook par défaut register, menu:filter peut être utilisé.

• les vues de mise en page et les sous-vues reçoivent désormais les identifier et segments de la page en cours de rendu

• les paramètres de mise en page sont disponibles pour les hooks de menu de titre et de filtre, ce qui permet aux ressources de fournir des informations de contexte supplémentaires, par exemple $entity dans cas d’une ressource pour le profil

Les plugins et thèmes devraient :

• Mettez à jour les appels à elgg_view_layout () pour utiliser la disposition default

• Mettez à jour et remplacez le paramètre nav dans les vues de disposition par le paramètre breadcrumbs

• Mettez à jour leur utilisation du paramètre filter dans les vues de disposition - layouts, soit en fournissant un ensemble par défaut d’onglets de filtre, soit en définissant un paramètre filter_id et en utilisant des hooks

• Supprimez la vue page/layouts/one_column

• Supprimez la vue page/layouts/one_sidebar

• Supprimez la vue page/layouts/two_sidebar

• Supprimez la vue page/layouts/content

• Mettez à jour leur utilisation de page/layouts/default

• Mettez à jour leur utilisation de page/layouts/error

• Mettez à jour leur utilisation de page/layouts/elements/filter

• Mettez à jour leur utilisation de page/layouts/elements/header

• Mettez à jour leur utilisation de page/layouts/elements/footer

• Mettez à jour leur utilisation de page/elements/title

• Mettez à jour leur utilisation de navigation/breadcrumb pour passer $vars ['breadcrumb'] à elgg_get_breadcrumbs()

• Mettez à jour les enregistrements du hook output:before, layout vers view_vars, page/layout/<layout_name>

• Mettez à jour les enregistrements du hook output:after, layout vers view, page/layout/<layout_name>

Plugin Likes

La fonctionnalité Likes n’utilise plus l’API de bascule « toggle » de Elgg, de sorte qu’un seul élément de menu likes est utilisé. Les actions d’ajout/suppression « add » et « remove » ne renvoient plus directement les valeurs Ajax, car les données d’état des mentions J’aime sont maintenant renvoyées avec chaque requête Ajax qui envoie un « guid ». Lorsque le nombre de mentions J’aime est nul, l’élément de menu likes_count est maintenant masqué en ajoutant .hidden à l’élément LI, au lieu de le faire sur l’ancre. De plus, l’élément de menu likes_count est un lien classique, et n’est plus créé par la vue likes/count.

Plugin Notifications

Le plugin Notifications a été réécrit en abandonnant de nombreuses vues et actions. Le but de cette réécriture était de mettre en œuvre une interface plus efficace, extensible et évolutive pour la gestion des préférences de notifications. Nous avons mis en œuvre un balisage beaucoup plus simple, supprimé les styles en excès et le javascript qui était nécessaire pour faire fonctionner l’ancienne interface.

Si votre plugin étend l’une des vues ou s’appuie sur des actions du plugin notifications, il doit être mis à jour.

Plugin Pages

Le sous-type page_top a été migré dans le sous-type page. Le sous-type page dispose de sa propre classe, à savoir ElggPage. Pour vérifier si une ElggPage est une page de premier niveau, la fonction de classe ElggPage->isTopPage() a été ajoutée.

Toutes les pages ont une valeur de métadonnée pour parent_guid, pour les pages de premier niveau celle-ci est 0.

Plugin Profile

Toutes les fonctionnalités liées au profil ont été déplacées hors du noyau dans ce plugin. Les plus remarquables sont l’utilitaire d’administration des champs de profil et le hook pour définir les données de configuration des champs de profil.

Vues de données « Plugin Data Views »

Le plugin Data Views n’est plus distribué avec le noyau.

Plugin de l’API Twitter

Le plugin twitter_api a été retiré du noyau de Elgg. Le plugin est toujours disponible sous forme de package Composer elgg/twitter_api. Pour l’installer, ajoutez ce qui suit à la section require de votre composer.json :

{
        "require": {
                "elgg/twitter_api": "~1.9"
        }
}

Plugin de support des URLs d’origine

Le plugin legacy_urls a été retiré du noyau de Elgg. Le plugin est toujours disponible sous la forme du package Composer elgg/legacy_urls. Pour l’installer, ajoutez ce qui suit à la section require de votre composer.json :

{
        "require": {
                "elgg/legacy_urls": "~2.3"
        }
}

Plugin de validation par e-mail de l’utilisateur

La vue qui liste les utilisateurs non validés a été déplacée du plugin vers le noyau de Elgg. Certaines actions génériques (par exemple valider et supprimer) ont également été déplacées vers le noyau de Elgg.

Expédition d’e-mail

Pour prévoir plus de granularité dans la gestion et la livraison des e-mails, le hook email, system a été supprimé. Le nouveau service de messagerie fournit plusieurs autres hooks de remplacement qui permettent aux plugins de contrôler le contenu, le format et l’agent de transport de messagerie utilisés pour la livraison.

elgg_set_email_transport() peut désormais être utilisé pour remplacer l’agent de transport Sendmail par défaut par une autre instance de \Zend\Mail\Transport\TransportInterface, par exemple SMTP, in-memory, ou le transport de fichiers. Notez que cette fonction doit être appelée tôt dans le processus de démarrage. Notez que si vous appelez cette fonction sur chaque requête, l’utilisation des paramètres du plugin pour déterminer la configuration de transport peut ne pas être très efficace - stockez ces paramètres sous forme de liste de données « datalist » ou dans les valeurs de configuration du site, de sorte qu’ils soient chargés à partir du cache de démarrage.

Changements de thème et de style

Le thème Aalborg n’est plus distribué avec Elgg. Le thème du noyau par défaut est maintenant basé sur Aalborg, mais avec des changements majeurs.

Évolutions notables dans les plugins :

• La barre supérieure -topbar-, la barre de navigation -navbar- et l’entête -header- ont été combinés en un seul composant de barre supérieure responsive - topbar

• La largeur intérieure par défaut est maintenant 1280px (80rem * 16px/1rem)

• L’unité de mesure préférée est maintenant rem et non px

• Le thème utilise un système de grille à 8 points <https://builttoadapt.io/intro-to-the-8-point-grid-system-d2573cde8632>

• Les menus, éléments de mise en page -layouts- et autres composants utilisent maintenant flexbox

• La réinitialisation se fait à l’aide d’un système de grille à 8 points <https://necolas.github.io/normalize.css/>

• Les requêtes multimédias ont été réécrites pour une expérience mobile-first

• Les éléments de formulaire (entrées de texte, boutons et sélecteurs) ont maintenant tous une hauteur identique de 2.5rem

• L’entête -header- de la disposition -layout- est maintenant positionné à l’extérieur des colonnes de la disposition, qui ont été enveloppées dans elgg-layout-columns

• les propriétés z-index ont été examinées et empilées avec une itération simple au lieu de 9999999 <https://hackernoon.com/my-approach-to-using-z-index-eca67feb079c>.

• Le schéma de couleurs a été modifié pour mettre en évidence les éléments exploitables et réduire l’abondance des nuances de gris

• le plugin de recherche n’étend plus page/elements/header, et au lieu de cela page/elements/topbar affiche la vue search/search_box

• .elgg-icon n’a plus de font-size, line-height ou color global : ces valeurs seront héritées des éléments parents

• Le support de .elgg-icon-hover a été abandonné

• Les icônes « hover » de l’utilisateur ne sont plus recouvertes par une icône « caret »

Pour en savoir plus au sujet des Principes de création de thèmes

Notez également que les vues CSS servies via les URL /cache sont pré-traitées à l’aide de CSS Crush <http://the-echoplex.net/csscrush/>. Si vous faites des références à des variables CSS ou à d’autres éléments, la définition doit être située dans la même vue d’affichage. Par exemple, une variable définie dans elgg.css ne peut pas être référencée dans un fichier CSS distinct comme colorbox.css.

Commentaires

L’envoi des commentaires est maintenant AJAXifié. Après un envoi réussi, la liste des commentaires sera mise à jour automatiquement.

Les modifications suivantes ont été apportées aux notifications des commentaires.

• Les clefs de traduction relatives aux notifications des commentaires ont changé. Vérifiez les clefs de traduction generic_comment:notification:owner:

• L’action de création d’un commentaire (action/comment/save) a été modifiée. Si votre plugin a remplacé cette action, vous devriez jeter un œil dessus afin d’éviter les doubles notifications

Vues de listing d’objets

• object/elements/full/body enveloppe maintenant l’ensemble du corps du listing dans un emballage -wrapper- .elgg-listing-full-body

• object/elements/full supporte désormais attachments et responses qui sont affichés après le corps du listing

• Dans les plugins du noyau, les vues des ressources n’affichent plus comments/replies - au lieu de cela, elles transmettent un indicateur show_responses à la vue de l’entité, ce qui génère les réponses et les transmet à la vue de la liste complète. Les plugins tiers devront mettre à jour leurs utilisations des vues object/<subtype> et ressources/<handler>/view.

• La vue de la discussion complète est désormais affichée en utilisant la vue object/elements/full

• object/file passe désormais la vue image (specialcontent) sous la forme d’une pièce jointe attachment à la vue listing complète

Modifications des menus

Le tri par défaut des éléments de menu a été modifié de text à priority.

Notez que les hooks register et prepare utilisent maintenant l’API des collections. Dans la majorité des cas, tous les hooks devraient continuer à fonctionner, tant qu’ils n’effectuent pas d’opérations complexes avec des tableaux.

La prise en charge des paramètres icon et badge a été ajoutée. Les plugins doivent commencer à utiliser ces paramètres et les préférer à un seul paramètre text. CSS devrait être utilisé pour contrôler la visibilité de l’étiquette, de l’icône et du badge, au lieu de conditions dans la préparation des éléments de menu.

Tous les menus sont maintenant enveloppés par nav.elgg-menu-container pour s’assurer que plusieurs sections de menu ont un unique élément parent, et peuvent être stylisés à l’aide de flexbox ou de floats.

Tous les éléments de menu sont maintenant identifiés avec l’attribut data-menu-item, les sections avec data-menu-section, et les conteneurs avec des attributs data-menu-name.

menu topbar :

• l’élément de menu account avec la priorité 800 ajouté à la section alt

• l’élément de menu site_notifications est désormais un enfant de account avec pour priorité 100

• l’élément de menu usersettings est désormais un enfant de account avec pour priorité 300

• l’élément de menu administration est désormais un enfant de account avec pour priorité 800

• l’élément de menu logout est désormais un enfant de account avec pour priorité 900

• l’élément de menu dashboard est désormais un enfant de account avec pour priorité 100

• Dans la section default (profile, friends, messages), les éléments de menu du noyau utilisent désormais le paramètre icon et utilisent CSS pour masquer l’étiquette. Les plugins qui enregistrent des éléments dans cette section et s’attendent à ce qu’une étiquette soit visible doive mettre à jour leur CSS.

• l’élément de menu profile est désormais un enfant de account

• l’élément de menu friends est désormais un enfant de account

menu entity :

• l’élément de menu access a été supprimé. L’information sur les accès est désormais affichée dans la signature (byline) de l’entité.

menu user_hover :

• Tous les éléments utilisent le paramètre icon.

• La disposition de la liste déroulante a été modifiée. Si vous avez modifié l’apparence de cette liste déroulante, vous devrez peut-être mettre à jour votre code HTML/CSS.

menu widget :

• l’élément de menu collapse a été supprimé et les CSS ont été mises à jour en conséquence

menu title :

Le plugin profile n’utilise plus la section actions du menu user_hover, mais enregistre des éléments de menu title classiques.

menu extras :

Ce menu a été supprimé de la mise en page. Les éléments de menu enregistrés pour ce menu ont été déplacés vers d’autres menus.

menu groups:my_status :

Ce menu a été supprimé de la page de profil du groupe.

menu site_notifications :

Ce menu a été supprimé. Les objets de notification de site utilisent désormais le menu de l’entité pour les actions.

menu site :

L’enregistrement d’un élément de menu personnalisé défini dans l’interface d’administrateur a été déplacé vers le hook register, menu:site. La vue navigation/menu/site a été supprimée. Le menu du site ajoute maintenant un élément de menu more directement dans la section default.

Icônes des entités

Les fichiers images des icônes par défaut ont été déplacés et re-mappés comme suit :

• Icônes par défaut : views/default/icon/default/$size.png

• Icônes utilisateur : views/default/icon/user/default/$size.gif

• Icônes de groupe : views/default/icon/group/default/$size.gif dans le plugin groups

Les fichiers d’icônes des groupes ont été déplacés de groups/<guid><size>.jpg relativement au répertoire du propriétaire du groupe dans le répertoire de fichiers, vers un emplacement indiqué par le service d’icône d’entité. Les plugins doivent cesser d’accéder directement aux fichiers du répertoire de fichiers et utiliser l’API de l’icône de l’entité. Le script de mise à niveau est disponible via l’interface d’administration.

La génération d’icônes des entités a été modifiée. Toutes les dimensions configurées ne seront plus générées lors de l’appel de l’une des fonctions de l’icône de l’entité (ElggEntity::saveIconFromUploadedFile, ElggEntity:::saveIconFromLocalFile ou ElggEntity::saveIconFromElggFile), mais seulement la taille master. Les autres dimensions configurées seront générées à partir de l’icône master lorsque cette dimension est demandée.

Glyphes d’icône

FontAwesome a été mis à niveau vers la version 5.0+. Il y a eu certains changements dans la façon dont les glyphes FontAwesome sont rendus. Le noyau s’occupera de la plupart des changements (par ex. mappage des anciens noms d’icônes à de nouveaux, et en utilisant le préfixe correct pour les icônes de marques et les icônes solides).

Auto-complétion / saisie automatique (sélecteurs d’utilisateurs et de contacts)

Le sélecteur de contacts « Friends Picker » est désormais affiché en utilisant input/userpicker.

Les plugins devraient :

• Mettre à jour le paramètre input/userpicker pour prendre en charge le nouveau paramètre only_friends

• Supprimer le CSS du sélecteur de contacts - « friends picker » - de leurs feuilles de style

Collections de Contacts

L’UI des collections de contacts a été déplacée vers son propre plugin - friends_collections.

Mise en page des éléments .elgg-body

Dans 3.0, ces éléments par défaut ne s’étirent plus pour remplir l’espace disponible dans un contexte de bloc. Ils continuent de supprimer les floats et permettent la césure des mots pour envelopper le texte.

Les modules du noyau et les mises en page qui reposaient sur le remplissage de l’espace ont été retravaillés pour Flexbox, et nous encourageons les développeurs à faire de même, plutôt que d’utiliser la technique problématique overflow:hidden.

Supprimer des éléments de la rivière

La fonction elgg_delete_river(), qui avait été dépréciée dans la version 2.3, a été rétablie. Des changements notables internes à cette fonction sont ;

• Elle accepte toutes les $options de elgg_get_river(), mais exige qu’au moins l’un des paramètres suivants soit défini : id(s), annotation_id(s), subject_guid(s), object_guid(s), target_guid(s) ou view(s)

• Étant donné que elgg_get_river a par défaut une limite sur le nombre d’éléments de la rivière qu’elle récupère, si vous souhaitez supprimer tous les éléments de la rivière, vous devez définir limit à false

• L’accès est ignoré lors de la suppression d’éléments de la rivière

• Les événements sont déclenchés juste avant et après qu’un élément de la rivière a été effacé

Les réponses aux discussions ont été converties en commentaires

Dans la mesure où les réponses aux discussion étaient quasiment une copie des commentaires, toutes les réponses aux discussions ont été migrées vers les commentaires. Toutes les actions, hooks, événements et clefs de traduction associés ont été supprimés.

Note

Les commentaires des discussions apparaîtront désormais dans la section Commentaires de la recherche, et plus dans la section Discussion.

Nettoyage des traductions

Tous les plugins ont été scannés pour des clefs de traduction inutilisées. Les clefs inutilisées ont été supprimées. S’il existait une traduction générique disponible pour la clef de traduction personnalisée, celles-ci ont également été mises à jour.

Journal système

L’API du journal système a été déplacée hors du noyau dans un plugin system_log. Les plugins logbrowser et logrotate ont été fusionnés dans le plugin system_log.

Journalisation des erreurs

L’affichage des messages d’erreur de elgg_log() et de PHP n’est plus désormais possible que via le paramètre « Afficher à l’écran » du plugin des développeurs. Consultez le fichier settings.example.php pour plus d’informations sur l’utilisation de $CONFIG->debug dans votre fichier settings.php. Le débogage doit généralement se faire via l’extension xdebug ou via tail -f /chemin/du/fichier/error.log sur votre serveur.

Le plugin des actifs de composer n’est plus requis

Les actifs sont maintenant chargés à partir de https://asset-packagist.org. Le plugin FXP composer n’est plus nécessaire lors de l’installation de Elgg ni lors de la mise à jour des dépendances de composer.

Journaux du Cron

Les journaux du Cron ne sont plus conservés dans la base de données, mais sur le système de fichiers (dans la racine du répertoire des données). Ceci va permettre de conserver des sorties plus longues. Un script de migration a été ajouté pour migrer les anciens paramètres de la base de données vers le nouvel emplacement et supprimer les anciennes valeurs de la base de données.

Clefs de traduction supprimées / modifiées

• Les clefs de traduction relatives aux notifications des commentaires ont changé. Vérifiez les clefs de traduction generic_comment:notification:owner:

Les nouvelles fonctionnalités du schéma MySQL ne sont pas appliquées

Les nouvelles installations 3.0 nécessitent MySQL 5.5.3 (ou plus) et utilisent le jeu de caractères utf8mb4 et les colonnes de contenu LONGTEXT (ce qui permet notamment le stockage d’un contenu plus long et des caractères étendus comme les emoji).

Changements divers

Les paramètres « Permettre aux visiteurs de s’inscrire » et « Restreindre les pages aux utilisateurs connectés » apparaissent désormais sur la page admin des paramètres de base - « Basic Settings ».

Plugin de l’API Twitter

Le plugin twitter_api n’est plus distribué avec Elgg.

Tests Unitaires et d’Intégration

L’amorçage du PHPUnit de Elgg peut désormais gérer à la fois les tests unitaires et d’intégration. Veuillez noter que vous ne devriez pas exécuter de test sur un site de production, car cela peut endommager l’intégrité des données. Pour éviter les pertes de données, vous devez spécifier les paramètres de la base de données via les variables d’environnement. Vous pouvez faire cela via le fichier d’amorçage phpunit.xml.

Les plugins peuvent désormais implémenter leurs propres tests PHPUnit en étendant les classes \Elgg\UnitTestCase et \Elgg\IntegrationTestCase. La suite de test plugins va automatiquement charger les tests PHPUnit depuis mod/<plugin_id>/tests/phpunit/unit et mod/<plugin_id>/tests/phpunit/integration.

Avant d’exécuter des tests d’intégration, vous devez activer les plugins que vous souhaitez tester en même temps que l’API du noyau.

\Elgg\IntegrationTestCase utilise le trait \Elgg\Seeding, qui peut être utilisé pour construire aisément de nouvelles entités et les enregistrer dans la base de données.

\Elgg\UnitTestCase n’utilise pas la base de données, mais fournit une interface de base de données factice, qui permet aux tests de définir des spécifications de requête avec des retours prédéfinis.

Par défaut, les tests unitaires et d’intégration seront exécutés à chaque fois que phpunit est appelé. Vous pouvez utiliser le drapeau --testsuite pour n’exécuter qu’une suite de tests spécifique : phpunit --testsuite unit ou phpunit --testsuite integration ou phpunit --testsuite plugins.

Pour que les tests d’intégration s’exécutent correctement, il est recommandé que les plugins ne placent aucune logique de fonctionnement dans la racine de start.php, et renvoient plutôt une Closure à la place. Ceci permet à la suite de test de construire une nouvelle instance Application sans perdre la logique d’initialisation du plugin.

Les plugins avec simpletests vont continuer à fonctionner comme précédemment. Cependant, les méthodes de signature dans la classe abstraite ElggCoreUnitTest ont changé et vous allez avoir besoin de mettre à jour vos tests en conséquence. En particulier, il est déconseillé d’utiliser des méthodes __construct et __destruct. setUp et tearDown ont été marquées comme privées et sont utilisées pour amorcer des tests cohérents et pour déclarer des conditions pre et post ; votre cas de test devrait utiliser les méthodes up et down à leur place.

Simpletests ne peut plus être exécuté depuis l’interface admin du plugin developers. Utilisez la commande Elgg cli : elgg-cli simpletest

De 2.2 à 2.3

Version de PHP

PHP 5.5 a atteint la date de fin de support en Juillet 2016. Afin de s’assurer que les sites Elgg soient sécurisés, nous exigeons désormais PHP 5.6 pour les nouvelles installations.

Les installations existantes peuvent continuer à utiliser PHP 5.5 jusqu’à Elgg 3.0.

Afin de mettre à niveau Elgg vers la version 2.3 en utilisant composer avec PHP 5.5, vous pouvez avoir besoin d’utiliser le drapeau --ignore-platform-reqs.

APIs dépréciées

• Enregistrement pour le hook to:object par le nom de l’extenseur : Utilisez les hooks to:object, annotation et to:object, metadata à la place.

• ajax_forward_hook() : N’est plus utilisé comme gestionnaire pour le hook “forward”,”all”`. La réponse Ajax est maintenant enveloppée par la ResponseFactory

• ajax_action_hook() : N’est plus utilisé comme gestionnaire pour le hook “action”,”all”. La mise en mémoire tampon de la sortie commence maintenant avant que le hook ne soit déclenché dans ActionsService

• elgg_error_page_handler() : N’est plus utilisé comme gestionnaire pour les hooks “forward”,<error_code>

• get_uploaded_file() : Utilisez la nouvelle API d’envoi de fichiers à la place

• get_user_notification_settings() : Utilisez ElggUser::getNotificationSettings()

• set_user_notification_setting() : Utilisez ElggUser::setNotificationSetting()

• événement pagesetup, system : Utilisez le menu ou les hooks de la coquille de la page - page shell - à la place.

• Le JavaScript elgg.walled_garden est obsolète : Utilisez le module AMD elgg/walled_garden à la place.

• elgg()->getDb()->getTableprefix() : Utilisez elgg_get_config('dbprefix').

• update_entity_last_action() est une fonction privée : Évitez de mettre à jour manuellement le timestamp de la dernière action.

• Définir un access_id non-public sur une métadonnée est obsolète. Voyez ci-dessous.

• get_resized_image_from_existing_file() : Utilisez elgg_save_resized_image().

• get_resized_image_from_uploaded_file() : Utilisez elgg_save_resized_image() en combinaison avec l’API d’envoi de fichier

• get_image_resize_parameters() sera supprimé.

• elgg_view_input() : Utilisez elgg_view_field(). Toutes nos excuses pour le changement d’API.

Vues obsolètes

• resources/file/world : Utilisez la vue resources/file/all.

• resources/pages/world : Utilisez la vue resources/pages/all.

• walled_garden.js : Utilisez le module elgg/walled_garden à la place.

Nouvelle API pour la gestion des pages et des actions

Les gestionnaires de pages et les fichiers de script d’action doivent maintenant renvoyer une instance de \Elgg\Http\ResponseBuilder. Les plugins devraient utiliser les fonctions suivantes pour créer des réponses :

• elgg_ok_response() envoie une réponse 2xx avec des données HTML (gestionnaire de page) ou JSON (actions)

• elgg_error_response() envoie une réponse 4xx ou 5xx sans contenu/donnée

• elgg_redirect_response() redirige silencieusement la requête

Nouvelle API pour travailler avec l’envoi de fichiers

• elgg_get_uploaded_files() - renvoie un tableau d’objets Symfony de fichiers téléchargés

• ElggFile::acceptUploadedFile() - déplace un fichier téléchargé dans le répertoire de fichiers de Elgg

Nouvelle API pour la manipulation d’images

Le nouveau service de manipulation d’images met en œuvre une approche plus efficace pour recadrer et redimensionner les images.

• elgg_save_resized_image() - recadre et redimensionne une image aux dimensions choisies

Nouvelle API pour les événements

• elgg_clear_event_handlers() - similaire à elgg_clear_plugin_hook_handlers cette fonction supprime tous les gestionnaires d’événements enregistrés

Nouvelle API pour la signature des URLs

Les URLs peuvent désormais être signées avec une clef HMAC SHA-256 et validées à tout moment avant l’expiration de l’URL. Cette fonctionnalité peut être utilisée pour tokenizer l’URL d’action dans les notifications par e-mail, ainsi que d’autres utilisations en dehors de l’installation Elgg.

• elgg_http_get_signed_url() - signe l’URL avec la clef HMAC

• elgg_http_validate_signed_url() - valide l’URL signée

• elgg_signed_request_gatekeeper() - gardien qui valide la signature de la requête en cours

Vues de formulaire extensibles

Le rendu du pied de page du formulaire peut maintenant être reporté jusqu’à ce que la vue du formulaire et ses extensions aient terminé le rendu. Cela permet aux plugins de collaborer sur les vues de formulaire sans casser la logique de balisage.

• elgg_set_form_footer() - définit le pied de page du formulaire pour un rendu différé

• elgg_get_form_footer() - renvoie le pied de page du formulaire actuellement défini

Métadonnées access_id

Il est maintenant obsolète de créer des métadonnées avec une valeur explicite de access_id autre que ACCESS_PUBLIC.

Dans Elgg 3.0, les métadonnées ne sont pas contrôlées et sont disponibles dans tous les contextes. Si votre plugin repose sur le contrôle d’accès des métadonnées, il serait sage de migrer le stockage vers des annotations ou des entités à la place.

Nouvelle API pour extraire des noms de classes à partir de tableaux

Semblable à elgg_extract(), elgg_extract_class() extrait la clef class (si elle est présente), la fusionne avec les noms de classe existants, et renvoie toujours un tableau.

Notifications

• Un hook de haut niveau 'prepare','notification' est maintenant déclenché pour les notifications instantanées et d’abonnement et peut être utilisé pour modifier les objets de notification quel que soit leur type.

• le hook 'format','notification:<method>' est maintenant déclenché pour les notifications instantanées et d’abonnement et peut être utilisé pour formater la notification (par ex. pour supprimer des balises HTML, envelopper le corps de la notification dans un modèle, etc.).

• Les notifications instantanées sont désormais traitées par le service de notifications, de sorte que la quasi-totalité des hooks applicables aux notifications d’abonnement s’appliquent également aux notifications instantanées.

• elgg_get_notification_methods() peut être utilisé pour obtenir les méthodes de notification enregistrées

• Ajout de ElggUser::getNotificationSettings() et ElggUser::setNotificationSetting()

Les fonctions de liste d’entités peuvent générer des tableaux

Dans des fonctions telles que elgg_list_entities($options), le rendu sous forme de tableau est possible en définissant $options['list_type'] = 'table' et en fournissant un tableau de colonnes de tableau dans $options['columns']. Chaque colonne est un objet Elgg\Views\TableColumn, généralement créé via des méthodes du service elgg()->table_columns.

Les plugins peuvent fournir ou modifier ces méthodes d’usine - factory methods (voir Elgg\Views\TableColumn\ColumFactory). Pour un exemple d’utilisation, consultez la vue admin/users/newest.

Composants d’onglets en ligne

Le composant des onglets en ligne peut désormais être rendu avec la vue page/components/tabs. Le composant permet de basculer entre pré-remplissage et chargement-par-ajax. Voir page/components/tabs dans les vues du noyau et theme_sandbox/components/tabs dans le plugin developers pour des instructions d’utilisation et des exemples.

API pour modifier l’URL d’inscription et de connexion

• elgg_get_registration_url() doit être utilisé pour obtenir l’URL d’inscription sur le site

• elgg_get_login_url() doit être utilisé pour obtenir l’URL de connexion du site

• le hook registration_url, site peut être utilisé pour modifier l’URL d’inscription par défaut

• le hook login_url, site peut être utilisé pour modifier l’URL de connexion par défaut

Prise en charge des jeux de champs - fieldsets - dans les formulaires

• elgg_view_field() remplace elgg_view_input(). Elle dispose d’une API similaire, mais accepte un seul tableau.

• elgg_view_field() prend en charge #type, #label, #help et #class, permettant l’envoi de versions non préfixées à la vue d’entrée $vars.

• La nouvelle vue input/fieldset peut être utilisée pour rendre un ensemble de champs, chacun rendu avec elgg_view_field().

Lightbox

• Le CSS de Lightbox n’est plus chargé en tant que fichier CSS externe. Le thème Lightbox étend maintenant elgg.css et admin.css

• La configuration de lightbox par défaut est maintenant définie via le hook 'elgg.data','site' côté serveur

De 2.1 à 2.2

APIs dépréciées

• Bibliothèque JavaScript elgg.ui.river : Supprimez les appels à elgg_load_js('elgg.ui.river') dans le code du plugin. Mettez à jour core/river/filter et forms/comment/save, s’ils sont remplacés, pour exiger des modules de composants AMD

• Méthodes elgg.ui.popupOpen() et elgg.ui.popupClose() dans la bibliothèque JS elgg.ui : Utilisez le module elgg/popup à la place.

• Bibliothèque lightbox.js : n’utilisez pas elgg_load_js('lightbox.js'); à moins que votre code ne référence l’espace de nom déprécié elgg.ui.lightbox. Utilisez plutôt le module AMD elgg/lightbox.

• Bibliothèque elgg.embed et objet elgg.embed : N’utilisez pas elgg_load_js('elgg.embed'). Utilisez plutôt le module AMD elgg/embed

• Accéder directement à la valeur de configuration icons_sizes : Utilisez elgg_get_icon_sizes()

• can_write_to_container() : Utilisez ElggEntity::canWriteToContainer()

Vues obsolètes

• elgg/ui.river.js est déprécié : ne vous fiez pas aux URLs de simplecache pour travailler.

• groups/js est déprécié : utilisez à la place le module AMD groups/navigation comme dépendance d’élément du menu pour les éléments de menu de mise en Une « feature » et de retrait de la Une « unfeature ».

• lightbox/settings.js est déprécié : utilisez l’attribut getOptions, ui.lightbox ou data-colorbox-opts du hook plugin JS.

• elgg/ckeditor/insert.js est déprécié : vous n’avez plus besoin de l’inclure, l’enregistrement des hooks a lieu dans le module elgg/ckeditor

• embed/embed.js est déconseillé : utilisez le module AMD elgg/embed.

Ajout du module elgg/popup

Le nouveau module elgg/popup peut être utilisé pour créer des interactions plus complexes de déclenchement de popup, y compris la liaison des types d’ancrage personnalisés et l’ouverture/fermeture programmatique de fenêtres contextuelles.

Ajout du module elgg/lightbox

Le nouveau module elgg/lightbox peut être utilisé pour ouvrir et fermer la lightbox de manière programmatique.

Ajout du module elgg/embed

Même s’il est rarement nécessaire, le module AMD elgg/embed peut être utilisé pour accéder aux méthodes d’intégration programmatiquement. Le module s’initialise lui-même si nécessaire et est peu susceptible de nécessiter une décoration supplémentaire.

Nouvelle API pour la manipulation des icônes d’entités

• ElggEntity implémente désormais l’interface \Elgg\EntityIcon

• elgg_get_icon_sizes() - renvoie les tailles d’icônes spécifiques au type/sous-type d’entité spécifié

• ElggEntity::saveIconFromUploadedFile() - crée des icônes à partir d’un fichier téléchargé

• ElggEntity::saveIconFromLocalFile() - crée des icônes à partir d’un fichier local

• ElggEntity::saveIconFromElggFile() - crée des icônes à partir d’une instance de ElggFile

• ElggEntity::getIcon() - renvoie une instance de ElggIcon qui pointe vers l’emplacement de l’icône de l’entité dans le répertoire de fichiers (il peut s’agir simplement d’un espace réservé, utilisez ElggEntity::hasIcon() pour vérifier si le fichier a effectivement été écrit)

• ElggEntity::deleteIcon() - supprime les icônes d’entité

• ElggEntity::getIconLastChange() - retourne la date de modification du fichier icône

• ElggEntity::hasIcon() - vérifie si une icône de la dimension donnée a bien été créée

• elgg_get_embed_url() - peut être utilisé pour retourner une URL afin d’intégrer l’icône d’une entité (servie via le gestionnaire /serve-icon)

Les avatars des utilisateurs sont désormais servis via le gestionnaire serve-file. Les plugins devraient commencer à utiliser elgg_get_inline_url() et noter que :

• le gestionnaire de page et la vue ressource``/avatar/view`` sont devenus obsolètes

• le fichier /mod/profile/icondirect.php est devenu obsolète

• profile_set_icon_url() n’est plus enregistré comme fonction de rappel -callback- pour le hook plugin "entity:icon:url","user"

Les avatars de groupe sont désormais servis via le gestionnaire serve-file. Les plugins devraient commencer à utiliser elgg_get_inline_url() et noter que :

• le gestionnaire de page groupicon (groups_icon_handler()) est devenu obsolète

• le fichier /mod/groups/icon.php est devenu obsolète

Les miniatures et les téléchargements sont désormais servis via le gestionnaire serve-file. Les plugins devraient commencer à utiliser elgg_get_inline_url() et elgg_get_download_url() et noter que :

• le gestionnaire de page et la vue ressource``file/download`` sont devenus obsolètes

• le fichier mod/file/thumbnail.php est devenu obsolète

• Plusieurs vues ont été mises à jour pour utiliser les nouvelles URLs de téléchargement, notamment :

  • mod/file/views/default/file/specialcontent/audio/default.php

  • mod/file/views/default/file/specialcontent/image/default.php

  • mod/file/views/default/resources/file/view.php

  • mod/file/views/rss/file/enclosure.php

APIs supprimées

Juste un avertissement pour indiquer que les fonctions de caches d’entité privée (par ex. _elgg_retrieve_cached_entity) ont été supprimées. Quelques plugins ont pu les utiliser. Les plugins ne devraient pas utiliser les API privées dans la mesure où elles seront plus souvent supprimées sans avertissement.

Un module elgg/ckeditor amélioré

le module elgg/ckeditor peut maintenant être utilisé pour ajouter un éditeur WYSIWYG à un textarea de manière programmatique avec elgg/ckeditor#bind.

De 2.0 à 2.1

APIs dépréciées

• ElggFile::setFilestore

• get_default_filestore

• set_default_filestore

• elgg_get_config('siteemail'): Utilisez elgg_get_site_entity()->email

• URLs commençant par /css/ et /js/ : Utilisez elgg_get_simplecache_url()

• elgg.ui.widgets L’objet JavaScript est déprécié par le module AMD elgg/widgets

Changements de Application::getDb()

Si vous utilisez cette API bas niveau, ne vous attendez pas à ce qu’elle renvoie une instance Elgg\Database dans Elgg 3.0. Elle renvoie maintenant un Elgg\Application\Database avec de nombreuses alertes de dépréciation. Ces méthodes n’ont jamais été destinées à devenir une API publique, mais nous ferons de notre mieux pour les prendre en charge dans les versions 2.x.

Ajout du module elgg/widgets

Si le code de votre plugin appelle elgg.ui.widgets.init(), utilisez le module elgg/widgets à la place.

De 1.x à 2.0

Elgg peut maintenant être installé en tant que dépendance composer au lieu d’être situé à la racine

Cela signifie qu’un site Elgg peut ressembler à ceci :

settings.php
vendor/
  elgg/
    elgg/
      engine/
        start.php
      _graphics/
        elgg_sprites.png
mod/
  blog
  bookmarks
  ...

elgg_get_root_path et $CONFIG->path vont renvoyer le chemin vers le répertoire racine de l’application, qui n’est pas nécessairement le même que le répertoire racine du noyau de Elgg (qui dans ce cas est vendor/elgg/elgg/).

N’essayez pas d’accéder directement au noyau de Elgg depuis votre plugin, car vous ne pouvez pas compter sur son emplacement dans le système de fichiers.

En particulier, n’essayez pas de charger engine/start.php.

// Don't do this!
dirname(__DIR__) . "/engine/start.php";

Pour démarrer Elgg manuellement, vous pouvez utiliser la classe Elgg\Application.

// boot Elgg in mod/myplugin/foo.php
require_once dirname(dirname(__DIR__)) . '/vendor/autoload.php';
\Elgg\Application::start();

Cependant, utilisez cette approche avec parcimonie. Préférez le routage Routage dans la mesure du possible, car cela permet de découpler vos URLs publiques et votre structure de système de fichiers.

En outre, n’essayez pas d’accéder directement aux fichiers _graphics.

readfile(elgg_get_root_path() . "_graphics/elgg_sprites.png");

Utilisez Vues à la place :

echo elgg_view('elgg_sprites.png');

Les vues pouvant être mises en cache doivent avoir une extension de fichier dans leur nom

Cette exigence nous permet de servir des actifs directement à partir du disque pour des raisons de performance, au lieu de les servir via PHP.

Il est également beaucoup plus facile d’explorer les ressources disponibles dans le cache en allant dans dataroot/views_simplecache et en naviguant à partir de là.

• Mauvais : my/cool/template

• Bon : my/cool/template.html

Nous mettons maintenant en cache des ressources par $viewtype/$view, et plus md5('$viewtype|$view'), qui entraînait des conflits entre les vues susceptibles d’être mises en cache qui n’avaient pas d’extension de fichier pour les distinguer des répertoires.

Abandon de jquery-migrate et mise à niveau de jquery vers ^2.1.4

l’API jQuery 2.x est compatible avec 1.x, mais abandonne la prise en charge de IE8-, que Elgg ne prenait déjà plus en charge depuis un certain temps de toutes façons.

Lisez http://jquery.com/upgrade-guide/1.9/ pour savoir comment se passer de jquery-migrate.

Si vous préférez le conserver, vous pouvez utiliser ce code dans l’initialisation de votre plugin :

elgg_register_js('jquery-migrate', elgg_get_simplecache_url('jquery-migrate.js'), 'head');
elgg_load_js('jquery-migrate');

Définissez également une vue jquery-migrate.js contenant le contenu du script.

JS et CSS ont été déplacés hors des répertoires js/ et css/

Ils ont également reçu des extensions .js et .css respectivement s’ils ne les avaient pas déjà :

Ancienne vue	Nouvelle vue
js/view	view.js
js/other.js	other.js
css/view	view.css
css/other.css	other.css
js/img.png	img.png

Le principal avantage que cela apporte est d’être en mesure de co-localiser les actifs connexes. Ainsi un modèle (view.php) peut avoir ses dépendances CSS/JS juste à côté (view.css, view.js).

Un grand soin a été pris pour rendre cette modification aussi rétro-compatible que possible, de sorte que vous ne devriez pas avoir besoin de mettre à jour les références des vues immédiatement. Cependant, vous êtes certainement encouragés à déplacer vos vues JS et CSS vers leurs nouveaux emplacements canoniques.

En pratique, ceci introduit quelques pièges :

Les hooks view_vars, $view_name et view, $view_name fonctionneront sur le nom canonique de la vue :

elgg_register_plugin_hook_handler('view', 'css/elgg', function($hook, $view_name) {
  assert($view_name == 'elgg.css') // not "css/elgg"
});

L’utilisation du hook view, all et la vérification des vues individuelles peuvent ne pas fonctionner comme prévu :

elgg_register_plugin_hook_handler('view', 'all', function($hook, $view_name) {
  // Won't work because "css/elgg" was aliased to "elgg.css"
  if ($view_name == 'css/elgg') {
    // Never executed...
  }

  // Won't work because no canonical views start with css/* anymore
  if (strpos($view_name, 'css/') === 0) {
    // Never executed...
  }
});

Merci de nous faire part de tous les autres problèmes de rétro-compatibilité que ce changement provoque. Nous aimerions en résoudre le plus grand nombre possible pour faciliter la transition.

fxp/composer-asset-plugin est maintenant nécessaire pour installer Elgg à partir de la source

Nous utilisons fxp/composer-asset-plugin pour gérer nos actifs de navigateur (js, css, html) avec Composer, mais il doit être installé globalement avant d’installer Elgg afin que les packages bower-asset/* soient reconnus. Pour l’installer, exécutez :

composer global require fxp/composer-asset-plugin

Si vous ne le faites pas avant d’exécuter composer install ou composer create-project, vous obtiendrez un message d’erreur :

[InvalidArgumentException]
Package fxp/composer-asset-plugin not found

Liste des vues dépréciées et des arguments d’une vue qui ont été supprimés

Nous avons abandonné la prise en charge des vues suivantes et/ou les avons supprimées :

• canvas/layouts/*

• categories

• categories/view

• core/settings/tools

• embed/addcontentjs

• footer/analytics (Utilisez page/elements/foot à la place)

• groups/left_column

• groups/right_column

• groups/search/finishblurb

• groups/search/startblurb

• input/calendar (Utilisez input/date)

• input/datepicker (Utilisez input/date à la place)

• input/pulldown (Utilisez input/select à la place)

• invitefriends/formitems

• js/admin (Utilisez AMD et elgg_require_js au lieu d’étendre les vues JS existantes)

• js/initialise_elgg (Utilisez AMD et elgg_require_js au lieu d’étendre les vues JS)

• members/nav

• metatags (Utilisez le hook plugin “head”, “page” à la place)

• navigation/topbar_tools

• navigation/viewtype

• notifications/subscriptions/groupsform

• object/groupforumtopic

• output/calendar (Utilisez output/date à la place)

• output/confirmlink (Utilisez output/url à la place)

• page_elements/contentwrapper

• page/elements/shortcut_icon (Utilisez le hook plugin “head”, “page” à la place)

• page/elements/wrapper

• profile/icon (Utilisez elgg_get_entity_icon)

• river/object/groupforumtopic/create

• settings/{plugin}/edit (Utilisez plugins/{plugin}/settings à la place)

• user/search/finishblurb

• user/search/startblurb

• usersettings/{plugin}/edit (Utilisez plugins/{plugin}/usersettings à la place)

• widgets/{handler}/view (Utilisez widgets/{handler}/content à la place)

Nous avons également abandonné les arguments suivants des vues :

• « value » dans output/iframe (Utilisez plutôt « src »)

• « area2 » et « area3 » dans page/elements/sidebar (utilisez plutôt « sidebar » ou l’extension de vue)

• « js » dans les vues des icônes (par exemple icon/user/default)

• Les « options » pour input/radio et input/checkboxes qui ne sont pas des paires de clef-valeur ne seront plus acceptées.

Tous les scripts ont été déplacés vers le bas de la page

Vous devriez tester votre plugin avec la console d’erreur JavaScript affichée. Pour des raisons de performance, Elgg ne prend plus en charge les éléments script dans l’élément head ou dans les vues HTML. elgg_register_js chargera désormais tous les scripts à la fin de l’élément body.

Vous devez convertir les scripts en ligne en modules AMD ou en scripts externes chargés avec elgg_load_js.

Tôt de la page, Elgg fournit un shim de la fonction RequireJS require() qui met simplement le code en file d’attente jusqu’à ce que les modules AMD elgg et jQuery soient définis. Cela fournit un moyen simple de convertir de nombreux scripts en ligne pour utiliser require().

Du code en ligne échouera car la pile n’est pas encore chargée :

<script>
$(function () {
    // code using $ and elgg
});
</script>

Ceci devrait fonctionner dans Elgg 2.0 :

<script>
require(['elgg', 'jquery'], function (elgg, $) {
    $(function () {
        // code using $ and elgg
    });
});
</script>

Le formateur d’attributs supprime les clefs avec des tirets bas

elgg_format_attributes() (et toutes les API qui l’utilisent) filtrent désormais les attributs dont le nom contient un tiret bas - underscore. Toutefois si l’attribut commence par data-, il ne sera pas supprimé.

Fil d’Ariane

L’affichage du fil d’Ariane supprime maintenant le dernier élément s’il ne contient pas de lien. Pour restaurer le comportement précédent, remplacez le gestionnaire de hook plugin elgg_prepare_breadcrumbs par le vôtre :

elgg_unregister_plugin_hook_handler('prepare', 'breadcrumbs', 'elgg_prepare_breadcrumbs');
elgg_register_plugin_hook_handler('prepare', 'breadcrumbs', 'myplugin_prepare_breadcrumbs');

function myplugin_prepare_breadcrumbs($hook, $type, $breadcrumbs, $params) {
    // just apply excerpt to titles
    foreach (array_keys($breadcrumbs) as $i) {
        $breadcrumbs[$i]['title'] = elgg_get_excerpt($breadcrumbs[$i]['title'], 100);
    }
    return $breadcrumbs;
}

Fonctions de rappel - Callbacks - dans les Requêtes

Assurez-vous d’utiliser uniquement des valeurs appelables - callable - valides pour l’argument/les options du « callback » dans l’API.

Les fonctions de requêtage lanceront désormais une RuntimeException si is_callable() renvoie false comme valeur pour la fonction de rappel donnée. Cela comprend des fonctions telles que elgg_get_entities(), get_data(), et bien d’autres.

Hook plugin des commentaires

Les plugins peuvent désormais renvoyer une chaîne vide depuis le hook 'comments',$entity_type afin de remplacer la vue du composant de commentaires par défaut. Pour forcer le composant de commentaires par défaut, votre plugin doit renvoyer false. Si vous utilisiez des chaînes vides pour forcer l’affichage des commentaires par défaut, vous devez mettre à jour vos gestionnaires de hooks pour qu’ils renvoient false.

Hook des permissions du conteneur

Le comportement du hook container_permissions_check a changé lorsqu’une entité est créée : avant la version 2.0, le hook était appelé deux fois si le conteneur de l’entité n’était pas le propriétaire. Lors du premier appel, le propriétaire de l’entité était transmis en tant que $params['container'], ce qui pouvait créer des confusion dans les gestionnaires.

Dans la version 2.0, lorsqu’une entité est créée dans un conteneur tel qu’un groupe, si le propriétaire est le même que l’utilisateur connecté (ce qui est presque toujours le cas), cette première vérification est contournée. Ainsi, le hook container_permissions_check sera presque toujours appelé une seule fois avec $params['container'] comme conteneur correct de l’entité.

La création ou la suppression d’une relation déclenche un seul événement

Les événements de relation « create » et « delete » sont désormais déclenchés une seule fois, avec "relationship" comme type d’objet.

Par ex. Écouter l’événement (ou les événements) "create", "member" ou "delete", "member" ne capturera plus les ajouts/suppressions d’appartenance au groupe. Utilisez les événements "create", "relationship" ou "delete", "relationship" events.

La fonction de discussion a été extraite des groupes vers son propre plugin

Le sous-type object, groupforumtopic a été remplacé par le sous-type object, discussion. Si votre plugin utilise ou modifie l’ancienne fonctionnalité de discussion, vous devez le mettre à niveau pour utiliser le nouveau sous-type.

Rien ne change du point de vue du propriétaire du groupe. La fonction de discussion est toujours disponible en tant qu’outil de groupe et toutes les anciennes discussions sont intactes.

Fonctionnalité de connexion via https abandonnée

Pour une meilleure sécurité et de meilleures performances, servez toutes les pages par HTTPS en changeant le protocole dans le wwwroot de votre site pour https dans http://yoursite.tld/admin/settings/advanced

Elgg a migré d’ext/mysql vers PDO MySQL

Elgg utilise désormais une connexion PDO_MYSQL et n’utilise plus de fonctions ext/mysql. Si vous utilisez les fonctions mysql_ *, en vous appuyant implicitement sur une connexion ouverte, celles-ci échoueront.

Si votre code utilise l’une des fonctions suivantes, lisez ce qui suit.

• execute_delayed_write_query()

• execute_delayed_read_query()

Si vous fournissez un objet $handler qui doit être appelé avec les résultats, votre gestionnaire recevra désormais un objet \Doctrine\DBAL\Driver\Statement. Auparavant, il s’agissait d’une ressource ext/mysql result.

L’ordre d’appel d’un événement/hook pourrait changer

Lors de l’enregistrement pour des événements/hooks, le mot-clef all pour la correspondance générique n’a plus aucun effet sur l’ordre dans lequel les gestionnaires sont appelés. Pour vous assurer que votre gestionnaire est appelé en dernier, vous devez lui donner la plus haute priorité de tous les gestionnaires correspondants, ou pour vous assurer que votre gestionnaire est appelé en premier, vous devez lui donner la plus basse priorité de tous les gestionnaires correspondants.

Si les gestionnaires ont été enregistrés avec la même priorité, ceux-ci sont appelés dans l’ordre où ils ont été enregistrés.

Pour émuler le comportement antérieur, les gestionnaires du noyau Elgg enregistrés avec le mot clé all ont été élevés en priorité. Certains de ces gestionnaires seront très probablement appelés dans un ordre différent.

Les URLs export/ ne sont plus disponibles

Elgg ne prend plus en charge ce point de terminaison pour exposer les données de ressources.

Icônes migrés vers Font Awesome

Les sprites de Elgg et la plupart des classes CSS commençant par elgg-icon- ont été supprimées.

L’utilisation de elgg_view_icon() est rétro-compatible, mais le HTML statique utilisant les classes elgg-icon devra être mis à jour vers le nouveau balisage.

Augmentation de la valeur de z-index dans la classe elgg-menu-site

La valeur de z-index dans la classe elgg-menu-site est passée de 1 à 50 pour permettre aux éléments de page de la zone de contenu d’utiliser la propriété z-index sans que le menu du site additionnel « More » s’affiche derrière ces éléments. Si votre plugin/thème remplace la classe elgg-menu-site ou les views/default/elements/navigation.css veuillez ajuster en conséquence la valeur de z-index dans votre fichier CSS modifié.

vue input/autocomplete

Les plugins qui remplacent la vue input/autocomplete devront inclure l’URL source dans l’attribut data-source de l’élément d’entrée, exiger le nouveau module AMD elgg/autocomplete et appeler sa méthode init. La bibliothèque javascript 1.x elgg.autocomplete n’est plus utilisée.

Introduction d’une bibliothèque tierce pour l’envoi d’e-mails

Nous utilisons l’excellente bibliothèque Zend\Mail pour envoyer des e-mails dans Elgg 2.0. Il y a probablement des cas particuliers que la bibliothèque gère différemment de Elgg 1.x. Prenez soin de tester attentivement vos notifications par e-mail lors de la mise à niveau vers 2.0.

Éléments d’étiquetage - label

Les vues suivantes ont reçu des éléments label autour de certains des champs d’entrée. Si votre plugin/thème remplace ces vues, veuillez vérifier le nouveau contenu.

• views/default/core/river/filter.php

• views/default/forms/admin/plugins/filter.php

• views/default/forms/admin/plugins/sort.php

• views/default/forms/login.php

Plugin de thème Aalborg

La vue page/elements/navbar utilise désormais une icône Font Awesome pour le sélecteur de menu mobile au lieu d’une image. L’image bars.png et les CSS correspondantes pour le rendu 1.12 ont été supprimées, aussi mettez à jour votre thème en conséquence.

Plugin Likes

Les objets ne peuvent plus être aimés - « likés » - par défaut. Pour qu’ils puissent être aimés, vous pouvez enregistrer un gestionnaire pour permettre l’annotation, ou plus simplement vous inscrire au hook ["likes:is_likable", "<type>:<subtype>"] et renvoyer true. Par ex.

elgg_register_plugin_hook_handler('likes:is_likable', 'object:mysubtype', 'Elgg\Values::getTrue');

Tout comme auparavant, le hook permissions_check:annotated est toujours appelé et peut être utilisé pour remplacer le comportement par défaut.

Plugin Messages

Si vous avez supprimé ou remplacé la fonction de gestionnaire messages_notifier pour masquer/modifier l’icône de la boîte de réception, vous devrez au lieu de cela faire de même pour le gestionnaire de menu de la barre supérieure - topbar - messages_register_topbar. messages_notifier n’est plus utilisé pour ajouter le lien de menu.

Les messages ne recevront plus les métadonnées “msg” pour les messages nouvellement créés. Cela signifie que vous ne pouvez plus compter sur l’existence de ces métadonnées.

Plugin Blog

Les pages de blog qui affichent les articles “Mine” - Moi - ou “Friends” - Contacts - ont été modifiés pour lister tous les articles de blog appartenant aux utilisateurs (y compris ceux créés dans les groupes).

Plugin des signets - Bookmarks

Les pages des signets qui affichent les listes de signets “Mine” - Moi - ou “Friends” - Contacts - ont été modifiées pour lister tous les signets appartenant aux utilisateurs (y compris ceux créés dans les groupes).

Plugin des fichiers - File

Les pages de fichiers qui affichent les listes de fichiers “Mine” - Moi - ou “Friends” - Contacts - ont été modifiées pour lister tous les fichiers appartenant aux utilisateurs (y compris ceux créés dans les groupes).

Classes supprimées

• ElggInspector

• Notable

• FilePluginFile : remplacez par ElggFile (ou chargez avec get_entity())

Clefs retirées disponibles via elgg_get_config()

• allowed_ajax_views

• dataroot_in_settings

• externals

• externals_map

• i18n_loaded_from_cache

• language_paths

• pagesetupdone

• registered_tag_metadata_names

• simplecache_enabled_in_settings

• translations

• viewpath

• views

• view_path

• viewtype

• wordblacklist

Notez également que les plugins ne devraient pas accéder à la variable globale $CONFIG à l’exception de settings.php.

Fonctions supprimées

• blog_get_page_content_friends

• blog_get_page_content_read

• count_unread_messages()

• delete_entities()

• delete_object_entity()

• delete_user_entity()

• elgg_get_view_location()

• elgg_validate_action_url()

• execute_delayed_query()

• extend_view()

• get_db_error()

• get_db_link()

• get_entities()

• get_entities_from_access_id()

• get_entities_from_access_collection()

• get_entities_from_annotations()

• get_entities_from_metadata()

• get_entities_from_metadata_multi()

• get_entities_from_relationship()

• get_filetype_cloud()

• get_library_files()

• get_views()

• is_ip_in_array()

• list_entities()

• list_entities_from_annotations()

• list_group_search()

• list_registered_entities()

• list_user_search()

• load_plugins()

• menu_item()

• make_register_object()

• mysql_*(): Elgg n’utilise plus ext/mysql

• remove_blacklist()

• search_for_group()

• search_for_object()

• search_for_site()

• search_for_user()

• search_list_objects_by_name()

• search_list_groups_by_name()

• search_list_users_by_name()

• set_template_handler()

• test_ip()

Méthodes supprimées

• ElggCache::set_variable()

• ElggCache::get_variable()

• ElggData::initialise_attributes()

• ElggData::getObjectOwnerGUID()

• ElggDiskFilestore::make_directory_root()

• ElggDiskFilestore::make_file_matrix()

• ElggDiskFilestore::user_file_matrix()

• ElggDiskFilestore::mb_str_split()

• ElggEntity::clearMetadata()

• ElggEntity::clearRelationships()

• ElggEntity::clearAnnotations()

• ElggEntity::getOwner()

• ElggEntity::setContainer()

• ElggEntity::getContainer()

• ElggEntity::getIcon()

• ElggEntity::setIcon()

• ElggExtender::getOwner()

• ElggFileCache::create_file()

• ElggObject::addToSite(): la fonction parente dans ElggEntity est toujours disponible

• ElggObject::getSites(): la fonction parente dans ElggEntity est toujours disponible

• ElggSite::getCollections()

• ElggUser::addToSite(): la fonction parente dans ElggEntity est toujours disponible

• ElggUser::getCollections()

• ElggUser::getOwner()

• ElggUser::getSites(): la fonction parente est toujours disponible dans ElggEntity

• ElggUser::listFriends()

• ElggUser::listGroups()

• ElggUser::removeFromSite(): la fonction parente est toujours disponible dans ElggEntity

Les arguments suivants ont également été abandonnés :

• ElggSite::getMembers() - 2: $offset

• elgg_view_entity_list() - 3: $offset - 4: $limit - 5: $full_view - 6: $list_type_toggle - 7: $pagination

Hooks plugin supprimés

• [display, view]: Voyez le nouvel hook plugin.

Actions supprimées

• widgets/upgrade

Vues supprimées

• forms/admin/plugins/change_state

Variables des Vues supprimées

Pendant le rendu, le système des vues ne les injecte plus dans le champ - scope :

• $vars['url'] : remplacez par elgg_get_site_url()

• $vars['user'] : remplacez par elgg_get_logged_in_user_entity()

• $vars['config'] : utilisez elgg_get_config() et elgg_set_config()

• $CONFIG: utilisez elgg_get_config() et elgg_set_config()

Plusieurs solutions de contournement pour des vues très anciennes ne sont plus effectuées. Effectuez ces modifications :

• Définissez $vars['full_view'] au lieu de $vars['full'].

• Définissez $vars['name'] au lieu de $vars['internalname'].

• Définissez $vars['id'] au lieu de $vars['internalid'].

Bibliothèques supprimées

• elgg:markdown : Elgg ne fournit plus d’implémentation de markdown. Vous devez fournir la vôtre.

Spécifier des Vues via les propriétés

La métadonnée $entity->view ne spécifie plus la vue utilisée pour l’affichage dans elgg_view_entity().

De même, la propriété $annotation->view n’a plus d’effet dans elgg_view_annotation().

Le type de vue est statique après l’appel initial elgg_get_viewtype()

elgg_set_viewtype() doit être utilisé pour définir le type de vue au moment de l’exécution. Bien que Elgg vérifie toujours l’entrée view et $CONFIG->view initialement, cela n’est fait qu’une fois par requête.

Dépréciations

Il est déprécié de lire ou d’écrire des clefs de métadonnées commençant par filestore:: sur les objets ElggFile. Dans Elgg 3.0, cette métadonnée sera supprimée si elle pointe vers le chemin d’accès racine actuel des données, aussi peu d’objets de fichiers devraient l’avoir. Les plugins ne doivent utiliser ElggFile::setFilestore que si les fichiers doivent être stockés dans un emplacement personnalisé.

Note

Ce n’est pas la seule dépréciation dans Elgg 2.0. Les développeurs de plugins devraient regarder leurs journaux d’erreurs de site.

De 1.10 à 1.11

Surlignage des commentaires

Si votre thème utilise le fichier views/default/css/elements/components.php, vous devez y ajouter les définitions de style suivantes pour activer la mise en surbrillance pour les commentaires et les réponses de discussion :

.elgg-comments .elgg-state-highlight {
        -webkit-animation: comment-highlight 5s;
        animation: comment-highlight 5s;
}
@-webkit-keyframes comment-highlight {
        from {background: #dff2ff;}
        to {background: white;}
}
@keyframes comment-highlight {
        from {background: #dff2ff;}
        to {background: white;}
}

De 1.9 à 1.10

Envois de fichiers

Si votre plugin utilise un bout de code copié à partir de l’action file/upload pour corriger les types mime détectés pour les formats zippés Microsoft, ce bout de code peut maintenant être supprimé en toute sécurité.

Si votre action de téléchargement effectue d’autres manipulations sur le type mime détecté et les types simples, il est recommandé de faire usage des hooks plugin disponibles :

• 'mime_type','file' pour filtrer les types mime détectés

• 'simple_type','file' pour filtrer les types simples analysés

De 1.8 à 1.9

Dans les exemples, nous mettons à niveau un plugin imaginaire Photos.

Seuls les changements de clefs sont inclus. Par exemple, certaines des fonctions dépréciées ne sont pas mentionnées ici séparément.

Chaque section comprendra des informations sur la rétro-compatibilité avec Elgg 1.8.

Le fichier manifest.xml

Aucun changement n’est nécessaire si votre plugin est compatible avec 1.8.

Il est toutefois recommandé d’ajouter l’étiquette <id>. Sa valeur devrait être le nom du répertoire du plugin à l’intérieur du répertoire mod/.

Si vous effectuez des modifications qui cassent la rétro-compatibilité arrière - ou « BC » pour « Backward Compatibility », vous devez mettre à jour la version du plugin et la distribution de Elgg requise.

Exemple (abrégé) d’une ancienne version :

<?xml version="1.0" encoding="UTF-8"?>
<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
    <name>Photos</name>
    <author>John Doe</author>
    <version>1.0</version>
    <description>Adds possibility to upload photos and arrange them into albums.</description>
    <requires>
        <type>elgg_release</type>
        <version>1.8</version>
    </requires>
</plugin_manifest>

Exemple de nouvelle version (raccourcie) :

<?xml version="1.0" encoding="UTF-8"?>
<plugin_manifest xmlns="http://www.elgg.org/plugin_manifest/1.8">
    <name>Photos</name>
    <id>photos</id>
    <author>John Doe</author>
    <version>2.0</version>
    <description>Adds possibility to upload photos and arrange them into albums.</description>
    <requires>
        <type>elgg_release</type>
        <version>1.9</version>
    </requires>
</plugin_manifest>

$CONFIG et $vars[“config”]

La variable globale $CONFIG et le paramètre $vars['config'] ont été dépréciés. Ils devraient être remplacés par la fonction elgg_get_config().

Exemple d’ancien code :

// Using the global $CONFIG variable:
global $CONFIG;
$plugins_path = $CONFIG->plugins_path

// Using the $vars view parameter:
$plugins_path = $vars['plugins_path'];

Exemple de nouveau code :

$plugins_path = elgg_get_config('plugins_path');

Note

Compatible avec 1.8

Note

Voyez comment le plugin community_plugins a été mis à jour : https://github.com/Elgg/community_plugins/commit/f233999bbd1478a200ee783679c2e2897c9a0483

Fichiers linguistiques

Dans Elgg 1.8, les fichiers linguistiques devaient utiliser la fonction add_translation(). En 1.9, il suffit de simplement renvoyer le tableau qui a été précédemment passé à la fonction en tant que paramètre. Le noyau de Elgg utilisera le nom du fichier (par ex. fr.php) pour déterminer quelle langue contient le fichier.

Exemple d’ancienne manière de faire dans languages/en.php :

$english = array(
    'photos:all' => 'All photos',
);
add_translation('en', $english);

Exemple de nouvelle manière de faire :

return array(
    'photos:all' => 'All photos',
);

Avertissement

Non compatible avec 1.8

Notifications

L’un des plus grands changements dans Elgg 1.9 est le système de notifications. Le nouveau système offre une manière plus flexible et évolutive d’envoyer des notifications.

Exemple d’ancienne manière de faire :

function photos_init() {
    // Tell core that we want to send notifications about new photos
    register_notification_object('object', 'photo', elgg_echo('photo:new'));

    // Register a handler that creates the notification message
    elgg_register_plugin_hook_handler('notify:entity:message', 'object', 'photos_notify_message');
}

/**
 * Set the notification message body
 *
 * @param string $hook    Hook name
 * @param string $type    Hook type
 * @param string $message The current message body
 * @param array  $params  Parameters about the photo
 * @return string
 */
function photos_notify_message($hook, $type, $message, $params) {
    $entity = $params['entity'];
    $to_entity = $params['to_entity'];
    $method = $params['method'];
    if (elgg_instanceof($entity, 'object', 'photo')) {
        $descr = $entity->excerpt;
        $title = $entity->title;
        $owner = $entity->getOwnerEntity();
        return elgg_echo('photos:notification', array(
            $owner->name,
            $title,
            $descr,
            $entity->getURL()
        ));
    }
    return null;
}

Exemple de la nouvelle manière de faire :

function photos_init() {
    elgg_register_notification_event('object', 'photo', array('create'));
    elgg_register_plugin_hook_handler('prepare', 'notification:publish:object:photo', 'photos_prepare_notification');
}

/**
 * Prepare a notification message about a new photo
 *
 * @param string                          $hook         Hook name
 * @param string                          $type         Hook type
 * @param Elgg_Notifications_Notification $notification The notification to prepare
 * @param array                           $params       Hook parameters
 * @return Elgg_Notifications_Notification
 */
function photos_prepare_notification($hook, $type, $notification, $params) {
    $entity = $params['event']->getObject();
    $owner = $params['event']->getActor();
    $recipient = $params['recipient'];
    $language = $params['language'];
    $method = $params['method'];

    // Title for the notification
    $notification->subject = elgg_echo('photos:notify:subject', array($entity->title), $language);

    // Message body for the notification
    $notification->body = elgg_echo('photos:notify:body', array(
        $owner->name,
        $entity->title,
        $entity->getExcerpt(),
        $entity->getURL()
    ), $language);

    // The summary text is used e.g. by the site_notifications plugin
    $notification->summary = elgg_echo('photos:notify:summary', array($entity->title), $language);

    return $notification;
}

Avertissement

Non compatible avec 1.8

Note

Voyez comment le plugin community_plugins a été mis à jour pour utiliser le nouveau système : https://github.com/Elgg/community_plugins/commit/bfa356cfe8fb99ebbca4109a1b8a1383b70ff123

Les notifications peuvent aussi être envoyées par la fonction notify_user().

Il a toutefois été mis à jour pour prendre en charge trois nouveaux paramètres optionnels passés à l’intérieur d’un tableau comme cinquième paramètre.

Les paramètres donnent aux plugins de notification plus de contrôle sur les notifications, de sorte qu’ils doivent être inclus dans la mesure du possible. Par exemple, le plugin site_notifications inclus ne fonctionnera pas correctement si les paramètres sont manquants.

Paramètres :

• object L’objet pour lequel nous envoyons une notification (par ex. ElggEntity ou ElggAnnotation). Ceci est nécessaire pour que les plugins de notification puissent fournir un lien vers l’objet.

• action Chaîne qui décrit l’action qui a déclenché la notification (par ex. « create », « update », etc.).

• summary Chaîne qui contient un résumé de la notification. (Elle devrait être plus informative que le sujet de notification, mais moins informative que le corps de la notification.)

Exemple d’ancienne manière de faire :

// Notify $owner that $user has added a $rating to an $entity created by him

$subject = elgg_echo('rating:notify:subject');
$body = elgg_echo('rating:notify:body', array(
        $owner->name,
        $user->name,
        $entity->title,
        $entity->getURL(),
));

notify_user($owner->guid,
                        $user->guid,
                        $subject,
                        $body
                );

Exemple de la nouvelle manière de faire :

// Notify $owner that $user has added a $rating to an $entity created by him

$subject = elgg_echo('rating:notify:subject');
$summary = elgg_echo('rating:notify:summary', array($entity->title));
$body = elgg_echo('rating:notify:body', array(
        $owner->name,
        $user->name,
        $entity->title,
        $entity->getURL(),
));

$params = array(
        'object' => $rating,
        'action' => 'create',
        'summary' => $summary,
);

notify_user($owner->guid,
                        $user->guid,
                        $subject,
                        $body,
                        $params
                );

Note

Compatible avec 1.8

Ajout d’éléments à la liste des Activités

add_to_river('river/object/photo/create', 'create', $user_guid, $photo_guid);

elgg_create_river_item(array(
    'view' => 'river/object/photo/create',
    'action_type' => 'create',
    'subject_guid' => $user_guid,
    'object_guid' => $photo_guid,
));

Vous pouvez également ajouter le paramètre facultatif target_guid qui indique la cible de l’action create.

Si la photo avait été ajoutée par exemple dans un album photo, nous pourrions l’ajouter en passant aussi :

'target_guid' => $album_guid,

Avertissement

Non compatible avec 1.8

Gestionnaires d’URL d’une entité

La fonction elgg_register_entity_url_handler() a été dépréciée. Dans 1.9, vous devez utiliser le hook plugin 'entity:url', 'object'.

Exemple d’ancienne manière de faire :

/**
 * Initialize the photo plugin
 */
my_plugin_init() {
    elgg_register_entity_url_handler('object', 'photo', 'photo_url_handler');
}

/**
 * Returns the URL from a photo entity
 *
 * @param ElggEntity $entity
 * @return string
 */
function photo_url_handler($entity) {
    return "photo/view/{$entity->guid}";
}

Exemple de la nouvelle manière de faire :

/**
 * Initialize the photo plugin
 */
my_plugin_init() {
    elgg_register_plugin_hook_handler('entity:url', 'object', 'photo_url_handler');
}

/**
 * Returns the URL from a photo entity
 *
 * @param string $hook   'entity:url'
 * @param string $type   'object'
 * @param string $url    The current URL
 * @param array  $params Hook parameters
 * @return string
 */
function photo_url_handler($hook, $type, $url, $params) {
    $entity = $params['entity'];

    // Check that the entity is a photo object
    if ($entity->getSubtype() !== 'photo') {
        // This is not a photo object, so there's no need to go further
        return;
    }

    return "photo/view/{$entity->guid}";
}

Avertissement

Non compatible avec 1.8

Web services

Dans Elgg 1.8, l’API des services Web a été incluse dans le noyau et les méthodes ont été exposées à l’aide de expose_function(). Pour activer la même fonctionnalité pour Elgg 1.9, activez le plugin Web services 1.9 et remplacez tous les appels à expose_function() par elgg_ws_expose_function().

1.7 vers 1.8

Elgg 1.8 est le plus grand bond en avant dans le développement de Elgg depuis la version 1.0. Pour cette raison, cela demande plus de travail pour mettre à jour le noyau et les plugins qu’avec les mises à niveau précédentes. Il y a eu un petit nombre de changements d’API et, suivant notre pratique standard, les méthodes que nous avons dépréciées ont été mises à jour pour travailler avec la nouvelle API. Les plus grands changements sont dans la normalisation des plugins et dans le système de vues.

Mettre à niveau le cœur

Supprimez les répertoires du noyau suivants (même niveau que _graphics et engine) :

• _css

• account

• admin

• dashboard

• entités

• friends

• search

• settings

• simplecache

• views

Avertissement

Si vous ne supprimez pas ces répertoires avant une mise à niveau, vous allez avoir des ennuis !

Mettre à jour les plugins

Utilisez le routage standard avec vos gestionnaires de pages

• Tout : /page_handler/all

• Publications de l’utilisateur : /page_handler/owner/:username

• Publications des contacts de l’utilisateur : /page_handler/friends/:username

• Entité seule : /page_handler/view/:guid/:title

• Ajout : /page_handler/add/:container_guid

• Modification : /page_handler/edit/:guid

• Liste des groupes : /page_handler/group/:guid/all

Incluez les scripts des gestionnaires de page à partir du gestionnaire de page

Presque tous les gestionnaires de page doivent avoir un script de gestionnaire de page. (Exemple : bookmarks/all => mod/bookmarks/pages/bookmarks/all.php)

• Appelez set_input() pour les guids d’entité dans le gestionnaire de page et utilisez get_input() dans les scripts du gestionnaire de page.

• Appelez gatekeeper() et admin_gatekeeper() dans la fonction du gestionnaire de page si nécessaire.

• L’URL d’un groupe doit utiliser le script pages/:handler/owner.php.

• Les gestionnaires de pages ne devraient pas contenir de HTML.

• Mettez à jour les URLs dans tout le plugin. (N’oubliez pas d’enlever /pg/ !)

Utilisez les gestionnaires de pages standardisés et les scripts

• Stockez les scripts du gestionnaire de page dans mod/:plugin/pages/:page_handler/:page_name.php

• Utilisez la disposition de page de contenu - content - dans les scripts du gestionnaire de pages :

  $content = elgg_view_layout('content', $options);
  

• Les scripts des gestionnaires de pages ne devraient pas contenir de HTML.

• Appelez elgg_push_breadcrumb() dans les scripts du gestionnaire de pages.

• Inutile de définir le propriétaire de la page si les URLs sont au format standard.

• Pour le contenu du groupe, vérifiez le conteneur container_guid en utilisant elgg_get_page_owner_entity().

La vue object/:subtype

• Assurez-vous qu’il existe bien des vues pour $vars['full_view'] == true et $vars['full_view'] == false. $vars['full_view'] a remplacé $vars['full].

• Vérifiez l’objet dans $vars['entity']. Utilisez elgg_instance_of() pour vous assurer qu’il s’agit du type d’entité que vous voulez.

• Renvoyez true pour court-circuiter la vue si l’entité est manquante ou erronée.

• Utilisez elgg_view('object/elements/summary', array('entity' => $entity)); et elgg_view_menu('entity', array('entity' => $entity)); pour faciliter le formatage. Vous devriez utiliser très peu de balisage dans ces vues.

Mettez à jour la structure de l’action

• Fichiers d’action et noms d’action de l’espace de noms (exemple : mod/blog/actions/blog/save.php => action/blog/save)

• Utilisez les URLs d’action suivantes :

  • Ajoutez : action/:plugin/save

  • Modifiez : action/:plugin/save

  • Supprimez : action/:plugin/delete

• Faites que l’action de suppression accepte action/:handler/delete?guid=:guid de sorte que le menu des métadonnées de l’entité ait la bonne URL par défaut.

Mettez à jour les fonctions obsolètes

• Les fonctions dépréciées en 1.7 produiront des erreurs visibles en 1.8.

• Vous pouvez également mettre à jour les fonctions dépréciées dans 1.8.

  • De nombreuses fonctions d’enregistrement ont simplement ajouté un préfixe elgg_ pour la cohérence, et devraient être faciles à mettre à jour.

  • Voyez /engine/lib/deprecated-1.8.php pour la liste complète.

  • Vous pouvez définir le niveau de débogage sur “warning” pour obtenir des rappels visuels des fonctions obsolètes.

Mettez à jour les vues widget

Voyez les widgets des plugins blog ou file pour des exemples.

Mettez à jour le module de profil de groupe

Utilisez les plugins blog ou file pour des exemples. Cela vous aidera à pouvoir appliquer un thème à votre plugin avec le nouveau framework CSS.

Mettez à jour les formulaires

• Déplacez les corps de formulaire vers la vue forms/:action pour utiliser le nouveau elgg_view_form d’Evan.

• Utilisez les vues d’entrée dans les corps de formulaire plutôt que du html. Cela aide à utiliser des thèmes et permet de préparer l’avenir.

• Ajoutez une fonction qui prépare le formulaire (voyez mod/file/lib/file.php pour un exemple)

• Rendez vos formulaires persistants (voir l’action de téléchargement du plugin file et la fonction de préparation du formulaire).

L’API des formulaires est discutée plus en détail dans Formulaires + Actions.

Nettoyez le CSS/HTML

Nous avons ajouté de nombreux modèles CSS au fichier CSS du noyau (modules, bloc avec une image, primitives d’espacement). Nous vous encourageons à utiliser ces modèles et ces classes dans la mesure du possible. Faire cela devrait :

1. Réduire les coûts de maintenance, car vous pouvez supprimer la plupart des CSS personnalisés.

2. Rendre votre plugin mieux compatible avec les thèmes de la communauté.

Recherchez des motifs qui peuvent être déplacés dans le noyau si vous avez besoin de CSS significatif.

Nous utilisons des traits d’union plutôt que des soulignements dans les classes/ids et vous encourageons à faire de même pour maintenir la cohérence globale.

Si vous avez besoin de votre propre CSS, vous devez utiliser votre propre espace de noms, plutôt que elgg-.

Mettez à jour manifest.xml

• Utilisez http://el.gg/manifest17to18 pour automatiser cette étape.

• N’utilisez pas la catégorie bundled avec vos plugins. Elle est réservée aux plugins distribués avec Elgg.

Mettez à jour les paramètres et les vues des paramètres utilisateur

• La vue pour les paramètres est maintenant plugins/:plugin/settings (auparavant settings/:plugin/edit).

• La vue pour les paramètres utilisateur est maintenant plugins/:plugin/usersettings (auparavant usersettings/:plugin/edit).

FAQs et autres Aides au dépannage

Ci-dessous quelques questions fréquemment posées à propos de Elgg.

Généralités

Voir aussi

Trouver de l’aide

« Le plugin ne peut pas démarrer et a été désactivé » - « Plugin cannot start and has been deactivated » ou « Ce plugin est invalide » - « This plugin is invalid »

Cette erreur est habituellement accompagnée par plus de détails qui expliquent pourquoi le plugin est invalide. Elle est généralement causée par un plugin mal installé.

Si vous installez un plugin appelé « test », il y aura un répertoire test dans le dossier mod. Dans ce dossier test il doit y avoir un fichier composer.json : /mod/test/manifest.xml.

Si ce fichier n’existe pas, cela peut être causé par :

• l’installation d’un plugin dans le mauvais répertoire

• la création d’un répertoire dans /mod qui ne contient pas un plugin

• un mauvais transfert FTP

• l’extraction d’un plugin dans un niveau de répertoire supplémentaire (myplugin.zip est extrait dans myplugin/myplugin)

• plugin incompatible

Si vous utilisez un hôte de type Unix et que les fichiers existent dans le bon répertoire, vérifiez les permissions. Elgg doit avoir accès en lecture + exécution sur les répertoires.

Page Blanche (WSOD)

Une page vide, blanche (souvent appelé « écran blanc de la mort » - « white screen of death » ou WSOD) signifie qu’il y a une erreur de syntaxe PHP. Il existe un certain nombre de causes possibles à cela :

• fichier corrompu - essayez de transférer à nouveau le code vers votre serveur

• un appel à un module php qui n’a pas été chargé - ceci peut se produire après que vous ayez installé un plugin qui requiert un module spécifique.

• mauvais plugin - tous les plugins n’ont pas été écrits avec le même niveau de qualité aussi vous devriez faire attention à ceux que vous installez.

Pour trouver l’origine de l’erreur, modifiez le fichier .htaccess pour afficher les erreurs dans le navigateur. Définissez display_errors à 1 et chargez la même page à nouveau. Vous devriez voir les erreurs PHP dans votre navigateur. Modifiez à nouveau ce paramètre une fois que vous avez résolu le problème.

Note

Si vous utilisez le plugin Developer’s Tools, allez dans sa page de configuration et assurez-vous que l’option « Afficher les erreurs PHP fatales » - « Display fatal PHP errors » - est bien activée.

Si l’écran blanc est dû à un mauvais plugin, retirez les derniers plugins que vous avez installé en supprimant leurs répertoires puis rechargez la page.

Note

Vous pouvez désactiver temporairement tous les plugins en créant un fichier vide dans mod/disabled. Vous pouvez ensuite désactiver le plugin responsable via les outils du panneau d’administration.

Si vous avez un WSOD quand vous effectuez une action, comme vous identifier ou publier un article de blog, mais qu’il n’y a pas de message d’erreur, le plus probable est que ce soit causé par des caractères non-imprimables dans le code du plugin. Vérifiez le plugin et supprimez les espaces vides et les nouvelles lignes situés après le tag de fin php (?>).

Page non trouvée

Si vous avez récemment installé votre site Elgg, la cause la plus probable d’une erreur de page non trouvée est que mod_rewrite n’est pas configuré correctement sur votre serveur. Il y a des informations dans la page Installation - Dépannage sur la manière de résoudre cela. La deuxième cause la plus probable est que l’URL de votre site dans votre base de données est incorrecte.

Si vous exécutez votre site depuis un certain temps et commencez soudainement à obtenir des erreurs de page non trouvées, vous devez vous demander ce qui a changé. Avez-vous ajouté des plugins ? Avez-vous modifié la configuration de votre serveur ?

Pour déboguer une erreur de page non trouvée « page not found » :

• Confirmez que le lien qui a mené à la page manquante est correct. S’il ne l’est pas, comment ce lien a-t-il été généré ?

• Confirmez que les règles de réécriture du .htaccess sont bien prises en compte.

Erreur de correspondance des jetons de connexion

Si vous devez vous connecter deux fois à votre site et que le message d’erreur après la première tentative indique qu’il y a eu une erreur de décalage de jeton, l’URL dans les paramètres de Elgg ne correspond pas à l’URL utilisée pour y accéder. La cause la plus fréquente est d’ajouter ou de supprimer le « www » lors de l’accès au site. Par exemple, www.elgg.org vs elgg.org. Cela pose un problème avec la gestion des sessions en raison de la façon dont les navigateurs Web enregistrent les cookies.

Pour résoudre ce problème, vous pouvez ajouter des règles de réécriture. Pour rediriger de www.elgg.org vers elgg.org dans Apache, les règles peuvent ressembler à :

RewriteCond %{HTTP_HOST} .
RewriteCond %{HTTP_HOST} !^elgg\.org
RewriteRule (.*) http://elgg.org/$1 [R=301,L]

La redirection de non-www vers www pourrait ressembler à ceci :

RewriteCond %{HTTP_HOST} ^elgg\.org
RewriteRule ^(.*)$ http://www.elgg.org/$1 [R=301,L]

Si vous ne savez pas comment configurer les règles de réécriture, demandez à votre hébergeur pour plus d’informations.

Il manque les champs __token ou __ts dans le formulaire. Veuillez recharger la page pour continuer

Toutes les actions Elgg requièrent un jeton de sécurité, et cette erreur se produit quand ce jeton est manquant. C’est un problème soit avec la configuration de votre serveur, soit avec un plugin tierce-partie.

Si vous rencontrez ce cas lors d’une nouvelle installation, assurez-vous que votre serveur est correctement configuré et que vos règles de réécriture sont correctes. Si vous en faites l’expérience sur une mise à niveau, assurez-vous d’avoir mis à jour vos règles de réécriture dans .htaccess (Apache) ou dans la configuration du serveur.

Si vous rencontrez ce cas, désactivez tous les plugins tiers et réessayez. Les très vieux plugins pour Elgg n’utilisent pas de jeton de sécurité. Si le problème disparaît lorsque les plugins sont désactivés, c’est dû à un plugin qui devrait être mis à jour par son auteur.

Mode de maintenance

Pour mettre temporairement votre site hors-ligne, allez dans Administration -> Utilitaires -> Mode de Maintenance. Complétez le formulaire et cliquez sur Enregistrer pour désactiver votre site pour tout le monde à l’exception des administrateurs.

E-mail manquant

Si vos utilisateurs signalent que les e-mails de validation ne s’affichent pas, demandez-leur de vérifier leur dossier de spam. Il est possible que les e-mails provenant de votre serveur sont marqués comme spam. Cela dépend de nombreux facteurs : si votre fournisseur d’hébergement a un problème avec les spammeurs, la manière dont est faite votre configuration e-mail de PHP, quel agent de transport de messagerie votre serveur utilise, ou encore si votre hébergement limite le nombre d’e-mails que vous pouvez envoyer en une heure.

Si personne ne reçoit d’e-mail du tout, il est très probable que votre serveur n’est pas configuré correctement pour le courrier électronique. Votre serveur a besoin d’un programme pour envoyer un e-mail (appelé agent de transfert de messagerie - MTA) et PHP doit être configuré pour utiliser le MTA.

Pour vérifier rapidement si PHP et un agent de transfert de mail - MTA « Mail Transfer Agent » - sont correctement configurés, créez un fichier sur votre serveur avec le contenu suivant :

<?php
$address = "your_email@your_host.com";

$subject = 'Test email.';

$body = 'If you can read this, your email is working.';

echo "Attempting to email $address...<br />";

if (mail($address, $subject, $body)) {
        echo 'SUCCESS!  PHP successfully delivered email to your MTA.  If you don\'t see the email in your inbox in a few minutes, there is a problem with your MTA.';
} else {
        echo 'ERROR!  PHP could not deliver email to your MTA.  Check that your PHP settings are correct for your MTA and your MTA will deliver email.';
}

Assurez-vous de remplacer « your_email@your_host.com » par votre adresse e-mail réelle. Prenez soin de garder des guillemets autour d’elle ! Lorsque vous accédez à cette page via votre navigateur Web, cela va tenter d’envoyer un e-mail de test. Ce test vous permettra de savoir si PHP et votre MTA sont correctement configurés. Si le test échoue - soit vous obtenez une erreur, soit vous ne recevez jamais l’e-mail - vous aurez besoin de faire plus de recherches et éventuellement de contacter votre fournisseur de services.

La configuration complète des fonctionnalités de messagerie d’un MTA et de PHP dépasse le cadre de cette FAQ, et vous devez rechercher plus de ressources sur Internet à ce sujet. Quelques informations de base sur les paramètres php peuvent être trouvées sur le site de PHP

Journaux du serveur

Il est probable que vous utilisiez Apache comme serveur Web. Les avertissements et les erreurs sont écrits dans un journal par le serveur Web et peuvent être utiles pour les problèmes de débogage. Vous verrez généralement deux types de fichiers journaux : les journaux d’accès et les journaux d’erreurs. Les informations de PHP et de Elgg sont inscrites dans le journal des erreurs du serveur.

• Linux – Le journal d’erreur est probablement dans /var/log/httpd ou /var/log/apache2.

• Windows - Il est probablement dans votre répertoire Apache.

• Mac OS - Le journal d’erreur est probablement dans /var/log/apache2/error_log

Si vous utilisez un hébergement partagé sans accès ssh, votre fournisseur d’hébergement peut fournir un mécanisme pour obtenir l’accès à vos journaux de serveur. Vous devrez leur poser vos questions à ce sujet.

Comment fonctionne l’inscription ?

Avec une installation par défaut, voici comment fonctionne l’inscription :

1. L’utilisateur renseigne le formulaire d’inscription et l’envoie

2. Le compte utilisateur est créé et désactivé jusqu’à sa validation

3. Un e-mail est envoyé à l’utilisateur afin de valider son compte

4. Quand l’utilisateur clique sur le lien, le compte est validé

5. L’utilisateur peut maintenant s’identifier

Les échecs durant ce processus comprennent l’utilisateur qui entre une adresse e-mail incorrecte, l’e-mail de validation marqué comme spam, ou un utilisateur qui ne prend jamais la peine de valider le compte.

Validation de l’utilisateur

Par défaut, tous les utilisateurs qui s’inscrivent doivent valider leur compte par e-mail. Si un utilisateur a des difficultés pour valider son compte, vous pouvez valider manuellement les utilisateurs en allant dans Administration -> Utilisateurs -> Non validés.

Vous pouvez supprimer cette exigence en désactivant le plugin User Validation by Email.

Note

La suppression de la validation a certaines conséquences : il n’y a aucun moyen de savoir si un utilisateur inscrit dispose d’une adresse e-mail fonctionnelle, et cela peut laisser votre système ouvert aux spammeurs.

Ajouter manuellement un utilisateur

Pour ajouter manuellement un utilisateur, dans la partie Administrer, accédez aux Utilisateurs. Là, vous verrez un lien « Ajouter un nouvel utilisateur ». Après avoir rempli les informations et soumis le formulaire, le nouvel utilisateur recevra un e-mail avec son nom d’utilisateur et son mot de passe, et un rappel pour changer le mot de passe.

Note

Elgg ne force pas l’utilisateur à changer le mot de passe.

Je suis en train de créer ou viens d’installer un nouveau thème, mais les images ou d’autres éléments ne fonctionnent pas

Assurez-vous que le thème est placé tout en bas de la liste des plugins.

Effacez le cache de votre navigateur et rechargez la page. Pour alléger la charge sur le serveur, Elgg demande rarement au navigateur de charger le fichier CSS. Un nouveau thème modifiera complètement le fichier CSS et un rafraîchissement devrait inciter le navigateur à demander à nouveau le fichier CSS.

Si vous créez ou modifiez un thème, assurez-vous d’avoir désactivé les caches simples et système. Cela peut être fait en activant le plugin Developer Tools, puis en naviguant vers Administration -> Outils de développement -> Paramètres. Une fois que les modifications vous conviennent, réactivez les caches ou les performances en souffriront.

Modification des champs du profil

Dans les paramètres d’administration de Elgg se trouve une page pour remplacer les champs de profil par défaut. Par défaut, Elgg propose deux choix à l’administrateur :

• Utilisez les champs de profil par défaut

• Remplacez les champs par défaut par un jeu de champs de profil personnalisés

Vous ne pouvez pas ajouter de nouveaux champs de profil aux champs par défaut. L’ajout d’un nouveau champ de profil via l’option de remplacement des champs de profil efface ceux par défaut. Avant de laisser les utilisateurs s’inscrire, il est préférable de déterminer quels champs de profil vous voulez, quels types de champ ils devraient être, et l’ordre dans lequel ils devraient apparaître. Vous ne pouvez pas modifier le type de champ ou réordonner ou supprimer les champs après leur création sans effacer l’intégralité du profil.

Plus de flexibilité peut être obtenue grâce à des plugins. Il y a au moins deux plugins sur le site communautaire qui vous permettent d’avoir plus de contrôle sur les champs de profil. Le plugin Profile Manager est devenu très populaire dans la communauté Elgg. Il vous permet d’ajouter de nouveaux champs de profil quand vous le souhaitez, de modifier leur ordre, de regrouper les champs de profil et de les ajouter au formulaire d’inscription.

Modification de l’inscription

Le processus d’inscription peut être modifié par un plugin. Tout ce qui concerne l’inscription peut être modifié : l’apparence du formulaire, des champs d’inscription différents, des validations additionnelles des champs, des étapes additionnelles, et ainsi de suite. Ces types de changements demandent quelques connaissances de base en HTML, CSS, PHP.

Une autre option est d’utiliser le plugin Profile Manager qui vous permet d’ajouter des champs à la fois aux profils des utilisateurs et au formulaire d’inscription.

Créez le squelette du plugin

Squelette du plugin

Modification de l’apparence de l’inscription

Surchargez la vue account/forms/register

Modification du gestionnaire de l’action d’inscription

Vous pouvez écrire votre propre action pour créer le compte utilisateur

Comment puis-je modifier les paramètres PHP en utilisant .htaccess ?

Vous pouvez modifier les paramètres php dans votre fichier .htaccess. Cela est particulièrement vrai si votre fournisseur d’hébergement ne vous donne pas accès au fichier php.ini du serveur. Les variables peuvent être associées aux limites de téléchargement de fichiers, à la sécurité, à la longueur de la session, ou à n’importe quel nombre d’autres attributs php. Pour des exemples sur comment faire cela, voyez la documentation PHP à ce sujet.

Connexion via HTTPS activée par erreur

Si vous avez activé la connexion HTTPS mais que vous n’avez pas configuré SSL, vous êtes maintenant bloqué hors de votre installation Elgg. Pour désactiver ce paramètre de configuration, vous devrez modifier votre base de données. Utilisez un outil comme phpMyAdmin pour afficher votre base de données. Sélectionnez la table config et supprimez la ligne qui a le nom https_login.

Utiliser un site de test

Il est recommandé de toujours tester les nouvelles versions ou les nouveaux plugins sur un site de test avant de les exécuter sur un site de production (un site avec des utilisateurs réels). La façon la plus simple de le faire est de maintenir une installation séparée de Elgg avec des comptes factices. Lors des tests, il est important d’utiliser des comptes factices qui ne sont pas des administrateurs pour tester ce que vos utilisateurs verront.

Un test plus réaliste consiste à refléter le contenu de votre site de production sur votre site de test. Suivez les instructions pour dupliquer un site. Assurez-vous ensuite d’empêcher l’envoi d’e-mails à vos utilisateurs. Vous pouvez écrire un petit plugin qui redirige tous les e-mails vers votre propre compte (soyez conscient des plugins qui comprennent leur propre code d’envoi d’e-mail personnalisé, car vous devrez modifier ces plugins). Une fois cela fait, vous pouvez afficher tout le contenu pour s’assurer que la mise à niveau ou le nouveau plugin fonctionne comme vous le souhaitez et ne casse rien. Si ce processus vous semble trop lourd, veuillez vous en tenir à l’exécution d’un site de test simple.

500 - Internal Server Error

Qu’est-ce que c’est ?

Une erreur interne du serveur 500 - Internal Server Error signifie que le serveur web a rencontré un problème en servant une requête.

Voir aussi

La page Wikipédia sur les codes de statut HTTP

Causes possibles

Configuration du serveur web

La cause la plus fréquente pour cela est un serveur mal configuré. Si vous avez modifié le fichier .htaccess et ajouté quelque chose d’incorrect, Apache renverra une erreur 500.

Permissions sur les fichiers

Il peut également s’agir d’un problème de permissions sur un fichier. Apache doit pouvoir lire les fichiers de Elgg. L’utilisation des autorisations 755 sur les répertoires et 644 sur les fichiers permettra à Apache de lire les fichiers.

Lorsque je télécharge une photo ou que je modifie ma photo de profil, j’obtiens un écran blanc

Il est fort probable que la bibliothèque PHP GD n’est pas installée ou configurée correctement. Vous pourriez avoir besoin de l’aide de l’administrateur de votre serveur.

CSS manquant

Mauvaise URL

Parfois, les gens installent Elgg de sorte que l’URL de base est localhost et essaient ensuite d’afficher le site à l’aide d’un nom d’hôte. Dans ce cas, le navigateur ne pourra pas charger le fichier CSS. Essayez d’afficher la source de la page Web et de copier le lien du fichier CSS. Collez-le dans votre navigateur. Si vous obtenez une erreur 404, il est probable que c’est votre problème. Vous devrez modifier l’URL de base de votre site.

Erreur de syntaxe

Elgg stocke ses CSS sous forme de code PHP pour fournir flexibilité et puissance. S’il y a une erreur de syntaxe, le fichier CSS servi au navigateur peut être vide. La désactivation des plugins tierce partie est la première étape recommandée.

Erreurs de règles de réécriture d’URL - Rewrite rules

Un mauvais fichier .htaccess peut également entraîner une erreur 404 lors de la requête du fichier CSS. Cela pourrait se produire lors d’une mise à niveau si vous oubliez de mettre également à niveau le fichier .htaccess.

Devrais-je modifier la base de données manuellement ?

Avertissement

Non, vous ne devriez jamais modifier manuellement la base de données !

Est-ce que modifier manuellement la base de données va casser mon site ?

Oui.

Est-ce que je peux ajouter des champs supplémentaires aux tables dans la base de données ?

(CÀD : Je ne comprends pas le modèle de données de Elgg donc je vais ajouter des colonnes. Est-ce que vous allez m’aider ?)

Non, c’est une mauvaise idée. Étudiez le modèle de données data model et vous verrez qu’à moins que ce soit une installation très spécifique et hautement personnalisée, vous pouvez faire tout ce que vous voulez avec le modèle de données actuel de Elgg.

Je veux supprimer des utilisateurs. Est-ce que je ne peux pas les supprimer directement de la table elgg_entities ?

Non, cela va corrompre votre base de données. Supprimez-les via le site.

Je veux supprimer du spam. Est-ce que je ne peux pas juste le rechercher et le supprimer dans la table elgg_entities ?

Non, cela va corrompre votre base de données. Supprimez-le via le site.

Quelqu’un sur le site communautaire m’a dit de modifier manuellement la base de données. Est-ce que je devrais le faire ?

Qui étais-ce ? Est-ce quelqu’un d’expérimenté avec Elgg, comme l’un des développeurs du noyau ou un auteur de plugins bien connu ? Est-ce qu’il ou elle vous a donné des instructions claires sur quoi modifier ? Si vous ne savez pas qui c’est, ou si vous ne comprenez pas ou n’êtes pas à l’aise avec ces instructions, ne modifiez pas la base de données manuellement.

Je connais PHP et MySQL et ai une raison légitime de modifier la base de données. Est-ce OK de modifier manuellement la base de données ?

Assurez-vous d’abord de bien comprendre le modèle de données de Elgg et le schéma. Faites un backup, modifiez avec soin, puis testez généreusement.

Problème de connexion d’Internet Explorer (IE)

URL canonique

IE n’aime pas travailler avec des sites qui utilisent à la fois http://example.org et http://www.example.org. Il stocke plusieurs cookies et cela cause des problèmes. Il est préférable d’utiliser une seule URL de base. Pour plus d’informations sur la façon de le faire, voyez l’erreur « Login token mismatch error » - erreur de correspondance des jetons de connexion.

Cadre Chrome

Utiliser le cadre Chrome au sein de IE peut rompre le processus d’authentification.

Les e-mails ne supportent pas les caractères non-latins

Pour prendre en charge les caractères non-latins, (tels que Cyrilliques ou Chinois) Elgg a besoin du support des chaînes de caractère multibyte multibyte string support soit compilé dans PHP.

Sur de nombreuses installations (par ex. Debian & Ubuntu), c’est activé par défaut. Si ce n’est pas le cas, vous devez l’activer (ou recompiler PHP pour l’inclure). Pour vérifier si votre serveur prend en charge les chaînes multioctets - multibyte -, vérifiez phpinfo.

Durée de session

La durée de la session est contrôlée par votre configuration php. Vous devrez d’abord localiser votre fichier php.ini. Dans ce fichier vous trouverez plusieurs variables de session. Une liste complète et ce qu’elles font peuvent être trouvée dans le manuel de php.

Un fichier n’a pas de propriétaire

Il y a trois causes à cette erreur. Vous pourriez avoir une entité dans votre base de données qui a un owner_guid de 0. Cela devrait être extrêmement rare et ne peut se produire que si votre base de données/serveur plante lors d’une opération d’écriture.

La deuxième cause serait une entité où le propriétaire n’existe plus. Cela peut se produire si un plugin désactivé a été impliqué dans la création de l’entité, puis que le propriétaire est supprimé, mais l’opération de suppression a échoué (parce que le plugin est désactivé). Si vous pouvez comprendre quelle entité est à l’origine de cette situation, regardez dans votre table entities et modifiez le owner_guid pour le vôtre, puis vous pouvez supprimer l’entité via Elgg.

Avertissement

Lisez la section « Devrais-je modifier la base de données manuellement ? ». Soyez très prudent lors de l’édition directe de la base de données. Cela peut briser votre site. Faites toujours une sauvegarde avant de faire cela.

Corrections

Le plugin Database Validator vérifiera votre base de données pour ces causes et vous fournira une option pour les corriger. Assurez-vous de sauvegarder la base de données avant d’essayer l’option de correction.

Pas d’image

Si des images de profil, des images de groupe ou d’autres fichiers ont cessé de fonctionner sur votre site, il est probable qu’il s’agit d’une mauvaise configuration, surtout si vous avez migré vers un nouveau serveur.

Ce sont les erreurs de configuration les plus courantes qui bloquent le fonctionnement des images et d’autres fichiers.

Mauvais chemin pour le répertoire des données

Assurez-vous que le chemin d’accès au répertoire des données est correct dans la zone d’administration du site. Il devrait avoir un slash à la fin.

Mauvaises permissions sur le répertoire des données

Vérifiez les permissions du répertoire des données. L’utilisateur du serveur web devrait pouvoir lire et écrire dans le répertoire des données.

Installation migrée avec un nouvel emplacement du répertoire des données

Si vous avez migré une installation et que vous devez modifier votre chemin d’accès au répertoire des données, assurez-vous de mettre à jour le SQL pour le répertoire de fichiers tel que documenté dans les instructions Dupliquer une installation.

Avertissements d’obsolescence

Si vous voyez de nombreux avertissements de dépréciation qui disent des choses comme

Deprecated in 1.7: extend_view() was deprecated by elgg_extend_view()!

alors vous utilisez un plugin qui a été écrit pour une ancienne version de Elgg. Cela signifie que le plugin utilise des fonctions qui vont être supprimées dans une future version de Elgg. Vous pouvez demander au développeur de plugin si le plugin sera mis à jour, ou vous pouvez mettre à jour le plugin vous-même. Si aucune de ces alternatives n’est susceptible de se produire, vous ne devriez pas utiliser ce plugin.

JavaScript ne fonctionne pas

Si le menu utilisateur qui apparaît au survol cesse de fonctionner ou si vous ne pouvez pas supprimer les messages système, cela signifie que JavaScript est cassé sur votre site. Ceci est généralement dû à un plugin ayant un mauvais code JavaScript. Vous devriez trouver le plugin à l’origine du problème et le désactiver. Vous pouvez le faire en désactivant les plugins tierce partie un par un jusqu’à ce que le problème disparaisse. Une autre approche consiste à désactiver tous les plugins tierce partie, puis à les activer un par un jusqu’à-ce que le problème se reproduise.

La plupart des navigateurs Web vous donneront un indice quant à ce qui casse le code JavaScript. Ils disposent souvent d’une console pour les erreurs JavaScript ou un mode avancé pour afficher les erreurs. Une fois que vous voyez le message d’erreur, il est plus facile de localiser le problème.

Les adresses IP dans les journaux sont incorrectes

Si votre installation Elgg est derrière un serveur proxy ou un équilibreur de charge, les adresses IP enregistrées dans les plugin des journaux système - System Log - peuvent être erronées. Elles pourraient n’indiquer que les adresses IP du serveur proxy.

Afin de résoudre ceci, vous pouvez configurer les adresses IP du serveur proxy comme adresses IP de confiance, ce qui permettra au système d’accéder aux bonnes IPs de vos utilisateurs.

Dans le fichier settings.php, vous pouvez configurer des paramètres pour $CONFIG->http_request_trusted_proxy_ips et $CONFIG->http_request_trusted_proxy_headers. Regardez dans le fichier settings.php pour plus d’information.

Sécurité

Est-ce que upgrade.php pose des soucis de sécurité ?

Upgrade.php est un fichier utilisé pour exécuter des mises à niveau du code et de la base de données. Il est placé à la racine de l’installation et il n’y a pas besoin d’un compte identifié pour y accéder. Sur un site totalement à niveau, l’exécution du fichier va seulement réinitialiser les caches et quitter, de sorte que ceci ne constitue pas un problème de sécurité.

SI cela vous préoccupe tout de même, vous pouvez supprimer, déplacer, ou modifier les permissions de ce fichier jusqu’à-ce que vous ayez besoin d’effectuer une mise à niveau.

Devrais-je supprimer install.php ?

Ce fichier est utilisé pour installer Elgg et n’a pas besoin d’être supprimé. Le fichier vérifie si Elgg est déjà installé et redirige l’utilisateur vers la première page si c’est le cas.

Filtrage

Le filtrage est utilisé dans Elgg pour rendre les attaques XSS plus difficiles. L’objectif du filtrage est de supprimer les JavaScript et autres entrées dangereuses envoyées par les utilisateurs.

Le filtrage est effectué via la fonction elgg_sanitize_input(). Cette fonction récupère une chaîne et renvoie une chaîne filtrée. Elle déclenche un event sanitize, input. Par défaut, Elgg est livré avec la bibliothèque de filtrage htmLawed sous forme de plugin. Les développeurs peuvent ajouter n’importe quel code de filtrage supplémentaire ou de remplacement via un plugin.

La fonction elgg_sanitize_input() est appelée pour chaque saisie utilisateur dès lors que la saisie est obtenue à travers un appel à get_input(). Si pour une raison quelconque un développeur souhaite ne pas appliquer le filtrage par défaut sur certaines saisies utilisateur, la fonction get_input() dispose d’un paramètre pour désactiver le filtrage.

Développement

Que devrais-je utiliser pour modifier le code php ?

Il existe deux options principales : l’éditeur de texte ou l”environnement de développement intégré (IDE).

Éditeur de texte

Si vous débutez dans le développement de logiciels ou n’avez pas beaucoup d’expérience avec les IDE, l’utilisation d’un éditeur de texte vous permettra d’être opérationnel le plus rapidement. Au minimum, vous voudrez un éditeur avec coloration syntaxique, qui rend le code plus facile à lire. Si vous pensez que vous pouvez soumettre des correctifs pour le suivi de bogues, vous voudrez vous assurer que votre éditeur de texte ne modifie pas les terminaisons de ligne. Si vous utilisez Windows, Notepad++ est un bon choix. Si vous êtes sur un Mac, TextWrangler est un choix populaire. Vous pouvez également essayer TextMate.

IDE - Environnement de Développement Intégré

Un IDE - EDI pour Environnement de Développement Intégré en français - fait exactement ce que son nom implique : il comprend un ensemble d’outils que vous utiliseriez normalement séparément. La plupart des IDE incluront le contrôle de code source qui vous permettra de valider et de mettre à jour directement votre code à partir de votre référentiel cvs. Il peut avoir un client FTP intégré pour faciliter le transfert de fichiers sur un serveur distant. Il disposera d’une vérification de syntaxe pour attraper les erreurs avant que vous essayiez d’exécuter le code sur un serveur.

Les deux IDE gratuits les plus populaires pour les développeurs PHP sont Eclipse et NetBeans. Eclipse dispose de deux plugins différents pour travailler avec le code PHP : PDT et PHPEclipse.

Je n’aime pas certaines traductions dans Elgg. Comment puis-je les changer ?

La meilleure façon de faire ceci est avec un plugin.

Créez le squelette du plugin

Squelette du plugin

Localisez la chaîne que vous voulez modifier

Toutes les chaînes qu’un utilisateur peut voir devraient être dans le répertoire /languages ou dans le répertoire des langues d’un plugin (/mod/<plugin name>/languages). Ceci est fait de sorte qu’il soit facile de changer la langue utilisée par Elgg. Pour plus d’informations à ce sujet, consultez la documentation développeur sur Internationalisation .

Pour trouver la chaîne, utilisez grep ou un éditeur de texte qui fournit la recherche dans les fichiers pour localiser la chaîne. (Un bon éditeur de texte pour Windows est Notepad++ ) Disons que nous voulons modifier la chaîne Ajouter un contact en Se faire un nouvel ami. La commande grep qui pemet de trouver cette chaîne serait grep -r "Ajouter un contact" *. Avec Notepad++ , vous utiliseriez la commande « Trouver dans les fichiers ». Vous recherchez la chaîne, définissez le filtre sur *.php, définissez le répertoire de recherche sur le répertoire racine de Elgg, et vous assurez qu’il recherche dans tous les sous-répertoires. Vous voudrez peut-être aussi définir que la recherche soit sensible à la casse.

Vous devriez placer la chaîne « Ajouter un contact » dans /languages/fr.php. Vous devriez voir quelque chose comme ceci dans le fichier :

'friend:add' => "Add friend",

Cela signifie que chaque fois que Elgg voit friend:add il le remplace par Ajouter un contact. Nous voulons changer la définition de friend:add.

Remplacement de la chaîne

Pour remplacer cette définition, nous ajouterons un fichier linguistique langues au plugin que nous avons construit dans la première étape.

1. Créez un nouveau répertoire : /mod/<your plugin name>/languages

2. Créer un fichier dans ce répertoire appelé fr.php

3. Ajoutez ces lignes à ce fichier

<?php

return array(
   'friend:add' => 'Make a new friend',
);

Assurez-vous que vous n’avez pas d’espace ou de retour à la ligne avant <?php.

Vous avez terminé maintenant et devriez être en mesure d’activer le plugin et de voir le changement. Si vous remplacez la langue d’un plugin, assurez-vous que votre plugin est chargé après celui que vous essayez de modifier. L’ordre de chargement est déterminé dans la page Administration des outils de la section Administrateur. Au fur et à mesure que vous trouverez d’autres choses à changer, vous pouvez continuer à les ajouter à ce plugin.

Comment puis-je trouver le code qui fait X ?

La meilleure façon de trouver le code qui fait quelque chose que vous souhaitez changer est d’utiliser grep ou un outil de recherche similaire. Si grep n’est pas intégré à votre système d’exploitation, vous voudrez installer un outil grep ou utiliser un éditeur de texte/IDE qui dispose d’un bonne recherche dans les fichiers. Notepad++ est un bon choix pour les utilisateurs de Windows. Eclipse avec PHP et NetBeans sont de bons choix pour n’importe quelle plateforme.

Exemple de chaîne - String

Supposons que vous souhaitez trouver où se trouve le code de la boîte de Connexion. Une chaîne de la zone Connexion qui devrait être suffisamment unique est Se souvenir de moi - « Remember me ». Faites un grep pour cette chaîne. Vous constaterez qu’elle n’est utilisée que dans le fichier fr.php - ou en.php pour la version d’origine - dans le répertoire /languages. Là, il est utilisé pour définir la chaîne Internationalisation user:persistent. Faites maintenant un grep pour cette chaîne. Vous la trouverez en deux endroits : le même fichier linguistique fr.php et dans /views/default/forms/login.php. Ce dernier emplacement définit le code html qui constitue la boîte Connexion.

Exemple d’Action

Supposons que vous souhaitez trouver le code qui s’exécute lorsqu’un utilisateur clique sur le bouton Enregistrer après avoir agencé les widgets sur une page de profil. Consultez la page du Profil d’un utilisateur de test. Utilisez Firebug pour inspecter le html de la page jusqu’à ce que vous trouviez l’action du formulaire de widgets de modification. Vous verrez que l’URL depuis la racine est action/widgets/move.

Faites un grep sur widgets/move et deux fichiers sont retournés. L’un est le code JavaScript pour les widgets : /js/lib/ui.widgets.js. L’autre, /engine/lib/widgets.php, est l’endroit où l’action est enregistrée à l’aide de elgg_register_action('widgets/reorder'). Vous ne connaissez peut-être pas cette fonction : dans ce cas, vous devriez consulter sa page dans la référence de l’API. Effectuez une recherche sur la fonction et cela renverra la documentation de la fonction. Cela vous indique que l’action se trouve à l’emplacement par défaut puisqu’un emplacement de fichier n’a pas été spécifié. L’emplacement par défaut des actions est /actions de sorte que vous trouverez le fichier dans /actions/widgets/move.php.

Mode de débogage

Durant le processus d’installation, vous avez peut-être remarqué une case à cocher qui contrôlait si le mode débogage était activé ou désactivé. Ce paramètre peut également être modifié dans la page Administration du site. Le mode de débogage écrit beaucoup de données supplémentaires dans votre journal php. Par exemple, lorsque vous utilisez ce mode, chaque requête dans la base de données est écrite dans vos journaux. Cela peut être utile pour le débogage d’un problème, mais peut produire une quantité énorme de données qui peuvent ne pas être liées du tout au problème recherché. Vous pouvez expérimenter avec ce mode pour comprendre ce qu’il fait, mais assurez-vous d’exécuter Elgg en mode normal sur un serveur de production.

Avertissement

En raison de la quantité de données enregistrées, il est préférable de ne pas l’activer sur un serveur de production car cela peut remplir les fichiers journaux très rapidement.

Que contient le journal en mode débogage ?

• Toutes les requêtes de base de données

• Profilage des requêtes de base de données

• Durée de génération de page

• Nombre de requêtes par page

• Liste des fichiers linguistiques du plugin

• Des erreurs/avertissements supplémentaires par rapport au mode normal (il est très rare que ces types d’erreurs soient liées à un problème que vous pourriez avoir)

À quoi ressemblent les données ?

[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results cached
[07-Mar-2009 14:27:20] SELECT guid from elggsites_entity where guid = 1 results cached
[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results cached
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results returned from cache
[07-Mar-2009 14:27:20] ** Sub part of GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggsites_entity where guid=1 results cached
[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] DEBUG: 2009-03-07 14:27:20 (MST): "Undefined index:  user" in file /var/www/elgg/engine/lib/elgglib.php (line 62)
[07-Mar-2009 14:27:20] DEBUG: 2009-03-07 14:27:20 (MST): "Undefined index:  pass" in file /var/www/elgg/engine/lib/elgglib.php (line 62)
[07-Mar-2009 14:27:20] ***************** DB PROFILING ********************
[07-Mar-2009 14:27:20] 1 times: 'SELECT * from elggentities where guid=1 and (  (access_id in (2) or (owner_guid = -1) or (access_id = 0 and owner_guid = -1)) and enabled='yes')'
...
[07-Mar-2009 14:27:20] 2 times: 'update elggmetadata set access_id = 2 where entity_guid = 1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggentities set owner_guid='0', access_id='2', container_guid='0', time_updated='1236461868' WHERE guid=1'
[07-Mar-2009 14:27:20] 1 times: 'SELECT guid from elggsites_entity where guid = 1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggsites_entity set name='3124/944', description='', url='http://example.org/' where guid=1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggusers_entity set prev_last_action = last_action, last_action = 1236461868 where guid = 2'
[07-Mar-2009 14:27:20] DB Queries for this page: 56
[07-Mar-2009 14:27:20] ***************************************************
[07-Mar-2009 14:27:20] Page /action/admin/site/update_basic generated in 0.36997294426 seconds

Quels événements sont déclenchés sur chaque chargement de page ?

Il y a 4 événements Elgg qui sont déclenchés sur chaque chargement de page :

1. plugins_boot, system

2. init, system

3. ready, system

4. shutdown, system

Les trois premiers sont déclenchés dans Elgg\Application::bootCore. shutdown, system est déclenché dans \Elgg\Application\ShutdownHandler après que la réponse a été envoyée au client. Ils sont tous documentés.

Il existe d’autres événements déclenchés par Elgg occasionnellement (par exemple lorsqu’un utilisateur se connecte).

Copie d’un plugin

Il y a beaucoup de questions posées sur la façon de copier un plugin. Disons que vous voulez copier le plugin blog afin d’exécuter un plugin appelé blog et un autre appelé poetry. Ce n’est pas difficile, mais cela demande beaucoup de travail. Vous auriez besoin de

• changer le nom du répertoire

• changer les noms de toutes les fonctions (avoir deux fonctions avec le même nom provoque un plantage de PHP)

• modifier le nom de chaque vue (afin de ne pas remplacer les vues du plugin d’origine)

• modifier tous les sous-types du modèle de données

• modifier le fichier linguistique

• changer tout le reste de ce qui était spécifique au plugin d’origine

Note

Si vous essayez de cloner le plugin groups, vous aurez la difficulté supplémentaire que le plugin de groupe ne définit pas de sous-type.

Généralités

Voir aussi

Trouver de l’aide

« Le plugin ne peut pas démarrer et a été désactivé » - « Plugin cannot start and has been deactivated » ou « Ce plugin est invalide » - « This plugin is invalid »

Cette erreur est habituellement accompagnée par plus de détails qui expliquent pourquoi le plugin est invalide. Elle est généralement causée par un plugin mal installé.

Si vous installez un plugin appelé « test », il y aura un répertoire test dans le dossier mod. Dans ce dossier test il doit y avoir un fichier composer.json : /mod/test/manifest.xml.

Si ce fichier n’existe pas, cela peut être causé par :

• l’installation d’un plugin dans le mauvais répertoire

• la création d’un répertoire dans /mod qui ne contient pas un plugin

• un mauvais transfert FTP

• l’extraction d’un plugin dans un niveau de répertoire supplémentaire (myplugin.zip est extrait dans myplugin/myplugin)

• plugin incompatible

Si vous utilisez un hôte de type Unix et que les fichiers existent dans le bon répertoire, vérifiez les permissions. Elgg doit avoir accès en lecture + exécution sur les répertoires.

Page Blanche (WSOD)

Une page vide, blanche (souvent appelé « écran blanc de la mort » - « white screen of death » ou WSOD) signifie qu’il y a une erreur de syntaxe PHP. Il existe un certain nombre de causes possibles à cela :

• fichier corrompu - essayez de transférer à nouveau le code vers votre serveur

• un appel à un module php qui n’a pas été chargé - ceci peut se produire après que vous ayez installé un plugin qui requiert un module spécifique.

• mauvais plugin - tous les plugins n’ont pas été écrits avec le même niveau de qualité aussi vous devriez faire attention à ceux que vous installez.

Pour trouver l’origine de l’erreur, modifiez le fichier .htaccess pour afficher les erreurs dans le navigateur. Définissez display_errors à 1 et chargez la même page à nouveau. Vous devriez voir les erreurs PHP dans votre navigateur. Modifiez à nouveau ce paramètre une fois que vous avez résolu le problème.

Note

Si vous utilisez le plugin Developer’s Tools, allez dans sa page de configuration et assurez-vous que l’option « Afficher les erreurs PHP fatales » - « Display fatal PHP errors » - est bien activée.

Si l’écran blanc est dû à un mauvais plugin, retirez les derniers plugins que vous avez installé en supprimant leurs répertoires puis rechargez la page.

Note

Vous pouvez désactiver temporairement tous les plugins en créant un fichier vide dans mod/disabled. Vous pouvez ensuite désactiver le plugin responsable via les outils du panneau d’administration.

Si vous avez un WSOD quand vous effectuez une action, comme vous identifier ou publier un article de blog, mais qu’il n’y a pas de message d’erreur, le plus probable est que ce soit causé par des caractères non-imprimables dans le code du plugin. Vérifiez le plugin et supprimez les espaces vides et les nouvelles lignes situés après le tag de fin php (?>).

Page non trouvée

Si vous avez récemment installé votre site Elgg, la cause la plus probable d’une erreur de page non trouvée est que mod_rewrite n’est pas configuré correctement sur votre serveur. Il y a des informations dans la page Installation - Dépannage sur la manière de résoudre cela. La deuxième cause la plus probable est que l’URL de votre site dans votre base de données est incorrecte.

Si vous exécutez votre site depuis un certain temps et commencez soudainement à obtenir des erreurs de page non trouvées, vous devez vous demander ce qui a changé. Avez-vous ajouté des plugins ? Avez-vous modifié la configuration de votre serveur ?

Pour déboguer une erreur de page non trouvée « page not found » :

• Confirmez que le lien qui a mené à la page manquante est correct. S’il ne l’est pas, comment ce lien a-t-il été généré ?

• Confirmez que les règles de réécriture du .htaccess sont bien prises en compte.

Erreur de correspondance des jetons de connexion

Si vous devez vous connecter deux fois à votre site et que le message d’erreur après la première tentative indique qu’il y a eu une erreur de décalage de jeton, l’URL dans les paramètres de Elgg ne correspond pas à l’URL utilisée pour y accéder. La cause la plus fréquente est d’ajouter ou de supprimer le « www » lors de l’accès au site. Par exemple, www.elgg.org vs elgg.org. Cela pose un problème avec la gestion des sessions en raison de la façon dont les navigateurs Web enregistrent les cookies.

Pour résoudre ce problème, vous pouvez ajouter des règles de réécriture. Pour rediriger de www.elgg.org vers elgg.org dans Apache, les règles peuvent ressembler à :

RewriteCond %{HTTP_HOST} .
RewriteCond %{HTTP_HOST} !^elgg\.org
RewriteRule (.*) http://elgg.org/$1 [R=301,L]

La redirection de non-www vers www pourrait ressembler à ceci :

RewriteCond %{HTTP_HOST} ^elgg\.org
RewriteRule ^(.*)$ http://www.elgg.org/$1 [R=301,L]

Si vous ne savez pas comment configurer les règles de réécriture, demandez à votre hébergeur pour plus d’informations.

Il manque les champs __token ou __ts dans le formulaire. Veuillez recharger la page pour continuer

Toutes les actions Elgg requièrent un jeton de sécurité, et cette erreur se produit quand ce jeton est manquant. C’est un problème soit avec la configuration de votre serveur, soit avec un plugin tierce-partie.

Si vous rencontrez ce cas lors d’une nouvelle installation, assurez-vous que votre serveur est correctement configuré et que vos règles de réécriture sont correctes. Si vous en faites l’expérience sur une mise à niveau, assurez-vous d’avoir mis à jour vos règles de réécriture dans .htaccess (Apache) ou dans la configuration du serveur.

Si vous rencontrez ce cas, désactivez tous les plugins tiers et réessayez. Les très vieux plugins pour Elgg n’utilisent pas de jeton de sécurité. Si le problème disparaît lorsque les plugins sont désactivés, c’est dû à un plugin qui devrait être mis à jour par son auteur.

Mode de maintenance

Pour mettre temporairement votre site hors-ligne, allez dans Administration -> Utilitaires -> Mode de Maintenance. Complétez le formulaire et cliquez sur Enregistrer pour désactiver votre site pour tout le monde à l’exception des administrateurs.

E-mail manquant

Si vos utilisateurs signalent que les e-mails de validation ne s’affichent pas, demandez-leur de vérifier leur dossier de spam. Il est possible que les e-mails provenant de votre serveur sont marqués comme spam. Cela dépend de nombreux facteurs : si votre fournisseur d’hébergement a un problème avec les spammeurs, la manière dont est faite votre configuration e-mail de PHP, quel agent de transport de messagerie votre serveur utilise, ou encore si votre hébergement limite le nombre d’e-mails que vous pouvez envoyer en une heure.

Si personne ne reçoit d’e-mail du tout, il est très probable que votre serveur n’est pas configuré correctement pour le courrier électronique. Votre serveur a besoin d’un programme pour envoyer un e-mail (appelé agent de transfert de messagerie - MTA) et PHP doit être configuré pour utiliser le MTA.

Pour vérifier rapidement si PHP et un agent de transfert de mail - MTA « Mail Transfer Agent » - sont correctement configurés, créez un fichier sur votre serveur avec le contenu suivant :

<?php
$address = "your_email@your_host.com";

$subject = 'Test email.';

$body = 'If you can read this, your email is working.';

echo "Attempting to email $address...<br />";

if (mail($address, $subject, $body)) {
        echo 'SUCCESS!  PHP successfully delivered email to your MTA.  If you don\'t see the email in your inbox in a few minutes, there is a problem with your MTA.';
} else {
        echo 'ERROR!  PHP could not deliver email to your MTA.  Check that your PHP settings are correct for your MTA and your MTA will deliver email.';
}

Assurez-vous de remplacer « your_email@your_host.com » par votre adresse e-mail réelle. Prenez soin de garder des guillemets autour d’elle ! Lorsque vous accédez à cette page via votre navigateur Web, cela va tenter d’envoyer un e-mail de test. Ce test vous permettra de savoir si PHP et votre MTA sont correctement configurés. Si le test échoue - soit vous obtenez une erreur, soit vous ne recevez jamais l’e-mail - vous aurez besoin de faire plus de recherches et éventuellement de contacter votre fournisseur de services.

La configuration complète des fonctionnalités de messagerie d’un MTA et de PHP dépasse le cadre de cette FAQ, et vous devez rechercher plus de ressources sur Internet à ce sujet. Quelques informations de base sur les paramètres php peuvent être trouvées sur le site de PHP

Journaux du serveur

Il est probable que vous utilisiez Apache comme serveur Web. Les avertissements et les erreurs sont écrits dans un journal par le serveur Web et peuvent être utiles pour les problèmes de débogage. Vous verrez généralement deux types de fichiers journaux : les journaux d’accès et les journaux d’erreurs. Les informations de PHP et de Elgg sont inscrites dans le journal des erreurs du serveur.

• Linux – Le journal d’erreur est probablement dans /var/log/httpd ou /var/log/apache2.

• Windows - Il est probablement dans votre répertoire Apache.

• Mac OS - Le journal d’erreur est probablement dans /var/log/apache2/error_log

Si vous utilisez un hébergement partagé sans accès ssh, votre fournisseur d’hébergement peut fournir un mécanisme pour obtenir l’accès à vos journaux de serveur. Vous devrez leur poser vos questions à ce sujet.

Comment fonctionne l’inscription ?

Avec une installation par défaut, voici comment fonctionne l’inscription :

1. L’utilisateur renseigne le formulaire d’inscription et l’envoie

2. Le compte utilisateur est créé et désactivé jusqu’à sa validation

3. Un e-mail est envoyé à l’utilisateur afin de valider son compte

4. Quand l’utilisateur clique sur le lien, le compte est validé

5. L’utilisateur peut maintenant s’identifier

Les échecs durant ce processus comprennent l’utilisateur qui entre une adresse e-mail incorrecte, l’e-mail de validation marqué comme spam, ou un utilisateur qui ne prend jamais la peine de valider le compte.

Validation de l’utilisateur

Par défaut, tous les utilisateurs qui s’inscrivent doivent valider leur compte par e-mail. Si un utilisateur a des difficultés pour valider son compte, vous pouvez valider manuellement les utilisateurs en allant dans Administration -> Utilisateurs -> Non validés.

Vous pouvez supprimer cette exigence en désactivant le plugin User Validation by Email.

Note

La suppression de la validation a certaines conséquences : il n’y a aucun moyen de savoir si un utilisateur inscrit dispose d’une adresse e-mail fonctionnelle, et cela peut laisser votre système ouvert aux spammeurs.

Ajouter manuellement un utilisateur

Pour ajouter manuellement un utilisateur, dans la partie Administrer, accédez aux Utilisateurs. Là, vous verrez un lien « Ajouter un nouvel utilisateur ». Après avoir rempli les informations et soumis le formulaire, le nouvel utilisateur recevra un e-mail avec son nom d’utilisateur et son mot de passe, et un rappel pour changer le mot de passe.

Note

Elgg ne force pas l’utilisateur à changer le mot de passe.

Je suis en train de créer ou viens d’installer un nouveau thème, mais les images ou d’autres éléments ne fonctionnent pas

Assurez-vous que le thème est placé tout en bas de la liste des plugins.

Effacez le cache de votre navigateur et rechargez la page. Pour alléger la charge sur le serveur, Elgg demande rarement au navigateur de charger le fichier CSS. Un nouveau thème modifiera complètement le fichier CSS et un rafraîchissement devrait inciter le navigateur à demander à nouveau le fichier CSS.

Si vous créez ou modifiez un thème, assurez-vous d’avoir désactivé les caches simples et système. Cela peut être fait en activant le plugin Developer Tools, puis en naviguant vers Administration -> Outils de développement -> Paramètres. Une fois que les modifications vous conviennent, réactivez les caches ou les performances en souffriront.

Modification des champs du profil

Dans les paramètres d’administration de Elgg se trouve une page pour remplacer les champs de profil par défaut. Par défaut, Elgg propose deux choix à l’administrateur :

• Utilisez les champs de profil par défaut

• Remplacez les champs par défaut par un jeu de champs de profil personnalisés

Vous ne pouvez pas ajouter de nouveaux champs de profil aux champs par défaut. L’ajout d’un nouveau champ de profil via l’option de remplacement des champs de profil efface ceux par défaut. Avant de laisser les utilisateurs s’inscrire, il est préférable de déterminer quels champs de profil vous voulez, quels types de champ ils devraient être, et l’ordre dans lequel ils devraient apparaître. Vous ne pouvez pas modifier le type de champ ou réordonner ou supprimer les champs après leur création sans effacer l’intégralité du profil.

Plus de flexibilité peut être obtenue grâce à des plugins. Il y a au moins deux plugins sur le site communautaire qui vous permettent d’avoir plus de contrôle sur les champs de profil. Le plugin Profile Manager est devenu très populaire dans la communauté Elgg. Il vous permet d’ajouter de nouveaux champs de profil quand vous le souhaitez, de modifier leur ordre, de regrouper les champs de profil et de les ajouter au formulaire d’inscription.

Modification de l’inscription

Le processus d’inscription peut être modifié par un plugin. Tout ce qui concerne l’inscription peut être modifié : l’apparence du formulaire, des champs d’inscription différents, des validations additionnelles des champs, des étapes additionnelles, et ainsi de suite. Ces types de changements demandent quelques connaissances de base en HTML, CSS, PHP.

Une autre option est d’utiliser le plugin Profile Manager qui vous permet d’ajouter des champs à la fois aux profils des utilisateurs et au formulaire d’inscription.

Créez le squelette du plugin

Squelette du plugin

Modification de l’apparence de l’inscription

Surchargez la vue account/forms/register

Modification du gestionnaire de l’action d’inscription

Vous pouvez écrire votre propre action pour créer le compte utilisateur

Comment puis-je modifier les paramètres PHP en utilisant .htaccess ?

Vous pouvez modifier les paramètres php dans votre fichier .htaccess. Cela est particulièrement vrai si votre fournisseur d’hébergement ne vous donne pas accès au fichier php.ini du serveur. Les variables peuvent être associées aux limites de téléchargement de fichiers, à la sécurité, à la longueur de la session, ou à n’importe quel nombre d’autres attributs php. Pour des exemples sur comment faire cela, voyez la documentation PHP à ce sujet.

Connexion via HTTPS activée par erreur

Si vous avez activé la connexion HTTPS mais que vous n’avez pas configuré SSL, vous êtes maintenant bloqué hors de votre installation Elgg. Pour désactiver ce paramètre de configuration, vous devrez modifier votre base de données. Utilisez un outil comme phpMyAdmin pour afficher votre base de données. Sélectionnez la table config et supprimez la ligne qui a le nom https_login.

Utiliser un site de test

Il est recommandé de toujours tester les nouvelles versions ou les nouveaux plugins sur un site de test avant de les exécuter sur un site de production (un site avec des utilisateurs réels). La façon la plus simple de le faire est de maintenir une installation séparée de Elgg avec des comptes factices. Lors des tests, il est important d’utiliser des comptes factices qui ne sont pas des administrateurs pour tester ce que vos utilisateurs verront.

Un test plus réaliste consiste à refléter le contenu de votre site de production sur votre site de test. Suivez les instructions pour dupliquer un site. Assurez-vous ensuite d’empêcher l’envoi d’e-mails à vos utilisateurs. Vous pouvez écrire un petit plugin qui redirige tous les e-mails vers votre propre compte (soyez conscient des plugins qui comprennent leur propre code d’envoi d’e-mail personnalisé, car vous devrez modifier ces plugins). Une fois cela fait, vous pouvez afficher tout le contenu pour s’assurer que la mise à niveau ou le nouveau plugin fonctionne comme vous le souhaitez et ne casse rien. Si ce processus vous semble trop lourd, veuillez vous en tenir à l’exécution d’un site de test simple.

500 - Internal Server Error

Qu’est-ce que c’est ?

Une erreur interne du serveur 500 - Internal Server Error signifie que le serveur web a rencontré un problème en servant une requête.

Voir aussi

La page Wikipédia sur les codes de statut HTTP

Causes possibles

Configuration du serveur web

La cause la plus fréquente pour cela est un serveur mal configuré. Si vous avez modifié le fichier .htaccess et ajouté quelque chose d’incorrect, Apache renverra une erreur 500.

Permissions sur les fichiers

Il peut également s’agir d’un problème de permissions sur un fichier. Apache doit pouvoir lire les fichiers de Elgg. L’utilisation des autorisations 755 sur les répertoires et 644 sur les fichiers permettra à Apache de lire les fichiers.

Lorsque je télécharge une photo ou que je modifie ma photo de profil, j’obtiens un écran blanc

Il est fort probable que la bibliothèque PHP GD n’est pas installée ou configurée correctement. Vous pourriez avoir besoin de l’aide de l’administrateur de votre serveur.

CSS manquant

Mauvaise URL

Parfois, les gens installent Elgg de sorte que l’URL de base est localhost et essaient ensuite d’afficher le site à l’aide d’un nom d’hôte. Dans ce cas, le navigateur ne pourra pas charger le fichier CSS. Essayez d’afficher la source de la page Web et de copier le lien du fichier CSS. Collez-le dans votre navigateur. Si vous obtenez une erreur 404, il est probable que c’est votre problème. Vous devrez modifier l’URL de base de votre site.

Erreur de syntaxe

Elgg stocke ses CSS sous forme de code PHP pour fournir flexibilité et puissance. S’il y a une erreur de syntaxe, le fichier CSS servi au navigateur peut être vide. La désactivation des plugins tierce partie est la première étape recommandée.

Erreurs de règles de réécriture d’URL - Rewrite rules

Un mauvais fichier .htaccess peut également entraîner une erreur 404 lors de la requête du fichier CSS. Cela pourrait se produire lors d’une mise à niveau si vous oubliez de mettre également à niveau le fichier .htaccess.

Devrais-je modifier la base de données manuellement ?

Avertissement

Non, vous ne devriez jamais modifier manuellement la base de données !

Est-ce que modifier manuellement la base de données va casser mon site ?

Oui.

Est-ce que je peux ajouter des champs supplémentaires aux tables dans la base de données ?

(CÀD : Je ne comprends pas le modèle de données de Elgg donc je vais ajouter des colonnes. Est-ce que vous allez m’aider ?)

Non, c’est une mauvaise idée. Étudiez le modèle de données data model et vous verrez qu’à moins que ce soit une installation très spécifique et hautement personnalisée, vous pouvez faire tout ce que vous voulez avec le modèle de données actuel de Elgg.

Je veux supprimer des utilisateurs. Est-ce que je ne peux pas les supprimer directement de la table elgg_entities ?

Non, cela va corrompre votre base de données. Supprimez-les via le site.

Je veux supprimer du spam. Est-ce que je ne peux pas juste le rechercher et le supprimer dans la table elgg_entities ?

Non, cela va corrompre votre base de données. Supprimez-le via le site.

Quelqu’un sur le site communautaire m’a dit de modifier manuellement la base de données. Est-ce que je devrais le faire ?

Qui étais-ce ? Est-ce quelqu’un d’expérimenté avec Elgg, comme l’un des développeurs du noyau ou un auteur de plugins bien connu ? Est-ce qu’il ou elle vous a donné des instructions claires sur quoi modifier ? Si vous ne savez pas qui c’est, ou si vous ne comprenez pas ou n’êtes pas à l’aise avec ces instructions, ne modifiez pas la base de données manuellement.

Je connais PHP et MySQL et ai une raison légitime de modifier la base de données. Est-ce OK de modifier manuellement la base de données ?

Assurez-vous d’abord de bien comprendre le modèle de données de Elgg et le schéma. Faites un backup, modifiez avec soin, puis testez généreusement.

Problème de connexion d’Internet Explorer (IE)

URL canonique

IE n’aime pas travailler avec des sites qui utilisent à la fois http://example.org et http://www.example.org. Il stocke plusieurs cookies et cela cause des problèmes. Il est préférable d’utiliser une seule URL de base. Pour plus d’informations sur la façon de le faire, voyez l’erreur « Login token mismatch error » - erreur de correspondance des jetons de connexion.

Cadre Chrome

Utiliser le cadre Chrome au sein de IE peut rompre le processus d’authentification.

Les e-mails ne supportent pas les caractères non-latins

Pour prendre en charge les caractères non-latins, (tels que Cyrilliques ou Chinois) Elgg a besoin du support des chaînes de caractère multibyte multibyte string support soit compilé dans PHP.

Sur de nombreuses installations (par ex. Debian & Ubuntu), c’est activé par défaut. Si ce n’est pas le cas, vous devez l’activer (ou recompiler PHP pour l’inclure). Pour vérifier si votre serveur prend en charge les chaînes multioctets - multibyte -, vérifiez phpinfo.

Durée de session

La durée de la session est contrôlée par votre configuration php. Vous devrez d’abord localiser votre fichier php.ini. Dans ce fichier vous trouverez plusieurs variables de session. Une liste complète et ce qu’elles font peuvent être trouvée dans le manuel de php.

Un fichier n’a pas de propriétaire

Il y a trois causes à cette erreur. Vous pourriez avoir une entité dans votre base de données qui a un owner_guid de 0. Cela devrait être extrêmement rare et ne peut se produire que si votre base de données/serveur plante lors d’une opération d’écriture.

La deuxième cause serait une entité où le propriétaire n’existe plus. Cela peut se produire si un plugin désactivé a été impliqué dans la création de l’entité, puis que le propriétaire est supprimé, mais l’opération de suppression a échoué (parce que le plugin est désactivé). Si vous pouvez comprendre quelle entité est à l’origine de cette situation, regardez dans votre table entities et modifiez le owner_guid pour le vôtre, puis vous pouvez supprimer l’entité via Elgg.

Avertissement

Lisez la section « Devrais-je modifier la base de données manuellement ? ». Soyez très prudent lors de l’édition directe de la base de données. Cela peut briser votre site. Faites toujours une sauvegarde avant de faire cela.

Corrections

Le plugin Database Validator vérifiera votre base de données pour ces causes et vous fournira une option pour les corriger. Assurez-vous de sauvegarder la base de données avant d’essayer l’option de correction.

Pas d’image

Si des images de profil, des images de groupe ou d’autres fichiers ont cessé de fonctionner sur votre site, il est probable qu’il s’agit d’une mauvaise configuration, surtout si vous avez migré vers un nouveau serveur.

Ce sont les erreurs de configuration les plus courantes qui bloquent le fonctionnement des images et d’autres fichiers.

Mauvais chemin pour le répertoire des données

Assurez-vous que le chemin d’accès au répertoire des données est correct dans la zone d’administration du site. Il devrait avoir un slash à la fin.

Mauvaises permissions sur le répertoire des données

Vérifiez les permissions du répertoire des données. L’utilisateur du serveur web devrait pouvoir lire et écrire dans le répertoire des données.

Installation migrée avec un nouvel emplacement du répertoire des données

Si vous avez migré une installation et que vous devez modifier votre chemin d’accès au répertoire des données, assurez-vous de mettre à jour le SQL pour le répertoire de fichiers tel que documenté dans les instructions Dupliquer une installation.

Avertissements d’obsolescence

Si vous voyez de nombreux avertissements de dépréciation qui disent des choses comme

Deprecated in 1.7: extend_view() was deprecated by elgg_extend_view()!

alors vous utilisez un plugin qui a été écrit pour une ancienne version de Elgg. Cela signifie que le plugin utilise des fonctions qui vont être supprimées dans une future version de Elgg. Vous pouvez demander au développeur de plugin si le plugin sera mis à jour, ou vous pouvez mettre à jour le plugin vous-même. Si aucune de ces alternatives n’est susceptible de se produire, vous ne devriez pas utiliser ce plugin.

JavaScript ne fonctionne pas

Si le menu utilisateur qui apparaît au survol cesse de fonctionner ou si vous ne pouvez pas supprimer les messages système, cela signifie que JavaScript est cassé sur votre site. Ceci est généralement dû à un plugin ayant un mauvais code JavaScript. Vous devriez trouver le plugin à l’origine du problème et le désactiver. Vous pouvez le faire en désactivant les plugins tierce partie un par un jusqu’à ce que le problème disparaisse. Une autre approche consiste à désactiver tous les plugins tierce partie, puis à les activer un par un jusqu’à-ce que le problème se reproduise.

La plupart des navigateurs Web vous donneront un indice quant à ce qui casse le code JavaScript. Ils disposent souvent d’une console pour les erreurs JavaScript ou un mode avancé pour afficher les erreurs. Une fois que vous voyez le message d’erreur, il est plus facile de localiser le problème.

Les adresses IP dans les journaux sont incorrectes

Si votre installation Elgg est derrière un serveur proxy ou un équilibreur de charge, les adresses IP enregistrées dans les plugin des journaux système - System Log - peuvent être erronées. Elles pourraient n’indiquer que les adresses IP du serveur proxy.

Afin de résoudre ceci, vous pouvez configurer les adresses IP du serveur proxy comme adresses IP de confiance, ce qui permettra au système d’accéder aux bonnes IPs de vos utilisateurs.

Dans le fichier settings.php, vous pouvez configurer des paramètres pour $CONFIG->http_request_trusted_proxy_ips et $CONFIG->http_request_trusted_proxy_headers. Regardez dans le fichier settings.php pour plus d’information.

Sécurité

Est-ce que upgrade.php pose des soucis de sécurité ?

Upgrade.php est un fichier utilisé pour exécuter des mises à niveau du code et de la base de données. Il est placé à la racine de l’installation et il n’y a pas besoin d’un compte identifié pour y accéder. Sur un site totalement à niveau, l’exécution du fichier va seulement réinitialiser les caches et quitter, de sorte que ceci ne constitue pas un problème de sécurité.

SI cela vous préoccupe tout de même, vous pouvez supprimer, déplacer, ou modifier les permissions de ce fichier jusqu’à-ce que vous ayez besoin d’effectuer une mise à niveau.

Devrais-je supprimer install.php ?

Ce fichier est utilisé pour installer Elgg et n’a pas besoin d’être supprimé. Le fichier vérifie si Elgg est déjà installé et redirige l’utilisateur vers la première page si c’est le cas.

Filtrage

Le filtrage est utilisé dans Elgg pour rendre les attaques XSS plus difficiles. L’objectif du filtrage est de supprimer les JavaScript et autres entrées dangereuses envoyées par les utilisateurs.

Le filtrage est effectué via la fonction elgg_sanitize_input(). Cette fonction récupère une chaîne et renvoie une chaîne filtrée. Elle déclenche un event sanitize, input. Par défaut, Elgg est livré avec la bibliothèque de filtrage htmLawed sous forme de plugin. Les développeurs peuvent ajouter n’importe quel code de filtrage supplémentaire ou de remplacement via un plugin.

La fonction elgg_sanitize_input() est appelée pour chaque saisie utilisateur dès lors que la saisie est obtenue à travers un appel à get_input(). Si pour une raison quelconque un développeur souhaite ne pas appliquer le filtrage par défaut sur certaines saisies utilisateur, la fonction get_input() dispose d’un paramètre pour désactiver le filtrage.

Développement

Que devrais-je utiliser pour modifier le code php ?

Il existe deux options principales : l’éditeur de texte ou l”environnement de développement intégré (IDE).

Éditeur de texte

Si vous débutez dans le développement de logiciels ou n’avez pas beaucoup d’expérience avec les IDE, l’utilisation d’un éditeur de texte vous permettra d’être opérationnel le plus rapidement. Au minimum, vous voudrez un éditeur avec coloration syntaxique, qui rend le code plus facile à lire. Si vous pensez que vous pouvez soumettre des correctifs pour le suivi de bogues, vous voudrez vous assurer que votre éditeur de texte ne modifie pas les terminaisons de ligne. Si vous utilisez Windows, Notepad++ est un bon choix. Si vous êtes sur un Mac, TextWrangler est un choix populaire. Vous pouvez également essayer TextMate.

IDE - Environnement de Développement Intégré

Un IDE - EDI pour Environnement de Développement Intégré en français - fait exactement ce que son nom implique : il comprend un ensemble d’outils que vous utiliseriez normalement séparément. La plupart des IDE incluront le contrôle de code source qui vous permettra de valider et de mettre à jour directement votre code à partir de votre référentiel cvs. Il peut avoir un client FTP intégré pour faciliter le transfert de fichiers sur un serveur distant. Il disposera d’une vérification de syntaxe pour attraper les erreurs avant que vous essayiez d’exécuter le code sur un serveur.

Les deux IDE gratuits les plus populaires pour les développeurs PHP sont Eclipse et NetBeans. Eclipse dispose de deux plugins différents pour travailler avec le code PHP : PDT et PHPEclipse.

Je n’aime pas certaines traductions dans Elgg. Comment puis-je les changer ?

La meilleure façon de faire ceci est avec un plugin.

Créez le squelette du plugin

Squelette du plugin

Localisez la chaîne que vous voulez modifier

Toutes les chaînes qu’un utilisateur peut voir devraient être dans le répertoire /languages ou dans le répertoire des langues d’un plugin (/mod/<plugin name>/languages). Ceci est fait de sorte qu’il soit facile de changer la langue utilisée par Elgg. Pour plus d’informations à ce sujet, consultez la documentation développeur sur Internationalisation .

Pour trouver la chaîne, utilisez grep ou un éditeur de texte qui fournit la recherche dans les fichiers pour localiser la chaîne. (Un bon éditeur de texte pour Windows est Notepad++ ) Disons que nous voulons modifier la chaîne Ajouter un contact en Se faire un nouvel ami. La commande grep qui pemet de trouver cette chaîne serait grep -r "Ajouter un contact" *. Avec Notepad++ , vous utiliseriez la commande « Trouver dans les fichiers ». Vous recherchez la chaîne, définissez le filtre sur *.php, définissez le répertoire de recherche sur le répertoire racine de Elgg, et vous assurez qu’il recherche dans tous les sous-répertoires. Vous voudrez peut-être aussi définir que la recherche soit sensible à la casse.

Vous devriez placer la chaîne « Ajouter un contact » dans /languages/fr.php. Vous devriez voir quelque chose comme ceci dans le fichier :

'friend:add' => "Add friend",

Cela signifie que chaque fois que Elgg voit friend:add il le remplace par Ajouter un contact. Nous voulons changer la définition de friend:add.

Remplacement de la chaîne

Pour remplacer cette définition, nous ajouterons un fichier linguistique langues au plugin que nous avons construit dans la première étape.

1. Créez un nouveau répertoire : /mod/<your plugin name>/languages

2. Créer un fichier dans ce répertoire appelé fr.php

3. Ajoutez ces lignes à ce fichier

<?php

return array(
   'friend:add' => 'Make a new friend',
);

Assurez-vous que vous n’avez pas d’espace ou de retour à la ligne avant <?php.

Vous avez terminé maintenant et devriez être en mesure d’activer le plugin et de voir le changement. Si vous remplacez la langue d’un plugin, assurez-vous que votre plugin est chargé après celui que vous essayez de modifier. L’ordre de chargement est déterminé dans la page Administration des outils de la section Administrateur. Au fur et à mesure que vous trouverez d’autres choses à changer, vous pouvez continuer à les ajouter à ce plugin.

Comment puis-je trouver le code qui fait X ?

La meilleure façon de trouver le code qui fait quelque chose que vous souhaitez changer est d’utiliser grep ou un outil de recherche similaire. Si grep n’est pas intégré à votre système d’exploitation, vous voudrez installer un outil grep ou utiliser un éditeur de texte/IDE qui dispose d’un bonne recherche dans les fichiers. Notepad++ est un bon choix pour les utilisateurs de Windows. Eclipse avec PHP et NetBeans sont de bons choix pour n’importe quelle plateforme.

Exemple de chaîne - String

Supposons que vous souhaitez trouver où se trouve le code de la boîte de Connexion. Une chaîne de la zone Connexion qui devrait être suffisamment unique est Se souvenir de moi - « Remember me ». Faites un grep pour cette chaîne. Vous constaterez qu’elle n’est utilisée que dans le fichier fr.php - ou en.php pour la version d’origine - dans le répertoire /languages. Là, il est utilisé pour définir la chaîne Internationalisation user:persistent. Faites maintenant un grep pour cette chaîne. Vous la trouverez en deux endroits : le même fichier linguistique fr.php et dans /views/default/forms/login.php. Ce dernier emplacement définit le code html qui constitue la boîte Connexion.

Exemple d’Action

Supposons que vous souhaitez trouver le code qui s’exécute lorsqu’un utilisateur clique sur le bouton Enregistrer après avoir agencé les widgets sur une page de profil. Consultez la page du Profil d’un utilisateur de test. Utilisez Firebug pour inspecter le html de la page jusqu’à ce que vous trouviez l’action du formulaire de widgets de modification. Vous verrez que l’URL depuis la racine est action/widgets/move.

Faites un grep sur widgets/move et deux fichiers sont retournés. L’un est le code JavaScript pour les widgets : /js/lib/ui.widgets.js. L’autre, /engine/lib/widgets.php, est l’endroit où l’action est enregistrée à l’aide de elgg_register_action('widgets/reorder'). Vous ne connaissez peut-être pas cette fonction : dans ce cas, vous devriez consulter sa page dans la référence de l’API. Effectuez une recherche sur la fonction et cela renverra la documentation de la fonction. Cela vous indique que l’action se trouve à l’emplacement par défaut puisqu’un emplacement de fichier n’a pas été spécifié. L’emplacement par défaut des actions est /actions de sorte que vous trouverez le fichier dans /actions/widgets/move.php.

Mode de débogage

Durant le processus d’installation, vous avez peut-être remarqué une case à cocher qui contrôlait si le mode débogage était activé ou désactivé. Ce paramètre peut également être modifié dans la page Administration du site. Le mode de débogage écrit beaucoup de données supplémentaires dans votre journal php. Par exemple, lorsque vous utilisez ce mode, chaque requête dans la base de données est écrite dans vos journaux. Cela peut être utile pour le débogage d’un problème, mais peut produire une quantité énorme de données qui peuvent ne pas être liées du tout au problème recherché. Vous pouvez expérimenter avec ce mode pour comprendre ce qu’il fait, mais assurez-vous d’exécuter Elgg en mode normal sur un serveur de production.

Avertissement

En raison de la quantité de données enregistrées, il est préférable de ne pas l’activer sur un serveur de production car cela peut remplir les fichiers journaux très rapidement.

Que contient le journal en mode débogage ?

• Toutes les requêtes de base de données

• Profilage des requêtes de base de données

• Durée de génération de page

• Nombre de requêtes par page

• Liste des fichiers linguistiques du plugin

• Des erreurs/avertissements supplémentaires par rapport au mode normal (il est très rare que ces types d’erreurs soient liées à un problème que vous pourriez avoir)

À quoi ressemblent les données ?

[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results cached
[07-Mar-2009 14:27:20] SELECT guid from elggsites_entity where guid = 1 results cached
[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results cached
[07-Mar-2009 14:27:20] ** GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggentities where guid=1 and ( (1 = 1)  and enabled='yes') results returned from cache
[07-Mar-2009 14:27:20] ** Sub part of GUID:1 loaded from DB
[07-Mar-2009 14:27:20] SELECT * from elggsites_entity where guid=1 results cached
[07-Mar-2009 14:27:20] Query cache invalidated
[07-Mar-2009 14:27:20] DEBUG: 2009-03-07 14:27:20 (MST): "Undefined index:  user" in file /var/www/elgg/engine/lib/elgglib.php (line 62)
[07-Mar-2009 14:27:20] DEBUG: 2009-03-07 14:27:20 (MST): "Undefined index:  pass" in file /var/www/elgg/engine/lib/elgglib.php (line 62)
[07-Mar-2009 14:27:20] ***************** DB PROFILING ********************
[07-Mar-2009 14:27:20] 1 times: 'SELECT * from elggentities where guid=1 and (  (access_id in (2) or (owner_guid = -1) or (access_id = 0 and owner_guid = -1)) and enabled='yes')'
...
[07-Mar-2009 14:27:20] 2 times: 'update elggmetadata set access_id = 2 where entity_guid = 1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggentities set owner_guid='0', access_id='2', container_guid='0', time_updated='1236461868' WHERE guid=1'
[07-Mar-2009 14:27:20] 1 times: 'SELECT guid from elggsites_entity where guid = 1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggsites_entity set name='3124/944', description='', url='http://example.org/' where guid=1'
[07-Mar-2009 14:27:20] 1 times: 'UPDATE elggusers_entity set prev_last_action = last_action, last_action = 1236461868 where guid = 2'
[07-Mar-2009 14:27:20] DB Queries for this page: 56
[07-Mar-2009 14:27:20] ***************************************************
[07-Mar-2009 14:27:20] Page /action/admin/site/update_basic generated in 0.36997294426 seconds

Quels événements sont déclenchés sur chaque chargement de page ?

Il y a 4 événements Elgg qui sont déclenchés sur chaque chargement de page :

1. plugins_boot, system

2. init, system

3. ready, system

4. shutdown, system

Les trois premiers sont déclenchés dans Elgg\Application::bootCore. shutdown, system est déclenché dans \Elgg\Application\ShutdownHandler après que la réponse a été envoyée au client. Ils sont tous documentés.

Il existe d’autres événements déclenchés par Elgg occasionnellement (par exemple lorsqu’un utilisateur se connecte).

Copie d’un plugin

Il y a beaucoup de questions posées sur la façon de copier un plugin. Disons que vous voulez copier le plugin blog afin d’exécuter un plugin appelé blog et un autre appelé poetry. Ce n’est pas difficile, mais cela demande beaucoup de travail. Vous auriez besoin de

• changer le nom du répertoire

• changer les noms de toutes les fonctions (avoir deux fonctions avec le même nom provoque un plantage de PHP)

• modifier le nom de chaque vue (afin de ne pas remplacer les vues du plugin d’origine)

• modifier tous les sous-types du modèle de données

• modifier le fichier linguistique

• changer tout le reste de ce qui était spécifique au plugin d’origine

Note

Si vous essayez de cloner le plugin groups, vous aurez la difficulté supplémentaire que le plugin de groupe ne définit pas de sous-type.

Feuille de route

Dans quelle direction va le projet ? Quelles nouvelles fonctionnalités passionnantes sont à venir bientôt ?

Nous ne publions pas de feuilles de route détaillées, mais il est possible d’avoir une idée de notre orientation générale en utilisant les ressources suivantes :

• Notre groupe de feedback et de planification feedback and planning group est utilisé pour accueillir des discussions préliminaires sur les travaux à venir.

• Nos jalons Github - « milestones » - représentent une orientation générale pour les futures versions de Elgg. C’est la chose la plus proche d’une feuille de route traditionnelle que nous avons.

• Les pull requests sur Github vous donneront une bonne idée de ce qui est en cours de développement, mais rien n’est sûr tant que la PR n’est pas effectivement enregistrée.

• Nous utilisons le developer blog pour publier les annonces de fonctionnalités qui ont récemment été ajoutées dans notre branche de développement, et qui donne l’indication la plus sûre sur quelles fonctionnalités seront disponibles dans la prochaine version.

Valeurs

Nous avons plusieurs objectifs/valeurs généraux qui affectent les orientations prises par Elgg. Les améliorations doivent généralement promouvoir ces valeurs afin d’être acceptées.

Accessibilité

Les sites basés sur Elgg devraient être utilisables par n’importe qui n’importe où. Cela signifie que nous nous efforcerons toujours de rendre Elgg :

• Indépendant de l’appareil - compatible mobile, tablette, ordinateur de bureau, etc.

• Multilingue – i18n, RTL, etc.

• Indépendant de la capacité – compatible tactile, clavier, lecteur d’écran

Testabilité

Nous voulons rendre les tests manuels inutiles pour les développeurs du noyau, les auteurs de plugins, et les administrateurs de sites en faisant la promotion et en permettant des tests rapides et automatisés à tous les niveaux de la pile Elgg.

Nous estimons que les API sont cassées si elles exigent des auteurs de plugins d’écrire du code non testable. Nous savons qu’il y a beaucoup de violations de ce principe dans le noyau actuellement et nous travaillons à les corriger.

Nous visons un monde dans lequel les développeurs du noyau n’ont pas besoin de faire de tests manuels pour vérifier la validité du code contribué à Elgg. De manière similaire, nous envisageons un monde dans lequel les administrateurs de site peuvent mettre à niveau et installer de nouveaux plugins avec la certitude que tout fonctionnera bien ensemble.

TODO : d’autres objectifs/valeurs ?

FAQ

Quand la fonctionnalité X sera-t-elle implémentée ?

Nous ne pouvons pas promettre quand les fonctionnalités seront mises en œuvre parce que les nouvelles fonctionnalités sont ajoutées dans Elgg seulement quand quelqu’un est suffisamment motivé pour implémenter la fonctionnalité et soumettre une demande de fusion. Le mieux que nous puissions faire est de vous dire de regarder pour quelles fonctionnalités les développeurs existants ont exprimé leur intérêt pour travailler dessus.

La meilleure façon de s’assurer qu’une fonctionnalité est implémentée est d’en discuter avec l’équipe du noyau et de la mettre en œuvre vous-même. Consultez notre guide Guides du contributeur si vous êtes intéressé. Nous adorons les nouveaux contributeurs !

Ne comptez pas sur les améliorations futures si vous hésitez à utiliser Elgg. Évaluez le logiciel compte tenu de l’ensemble de fonctionnalités existantes. Les fonctionnalités à venir ne se réaliseront certainement pas à temps dans votre calendrier.

Quand est-ce que la version X.Y.Z sera publiée ?

La prochaine version sera publiée lorsque l’équipe du noyau se sentira prête et aura le temps de publier la version. http://github.com/Elgg/Elgg/issues/milestones vous donnera une idée générale de la chronologie.

Politique de versions

À quoi s’attendre lors de la mise à niveau de Elgg.

Nous adhérons au versionnage sémantique.

Suivez le blog pour rester à jour sur les dernières versions.

Versions de correctifs/bugfix (2.1.x)

Toutes les deux semaines.

Les publications de correctifs sont effectuées régulièrement pour s’assurer que Elgg reste stable, sécurisé et exempt de bogues. Plus le troisième chiffre est élevé, plus la version est testée et stable.

Dans la mesure où les versions correctives de bogues se concentrent sur la correction des bogues et évitent d’apporter des changements majeurs, les thèmes et les plugins doivent fonctionner de version corrective en version corrective.

Versions mineures/fonctionnalités (2.x.0)

Tous les trois mois.

Chaque fois que nous introduisons de nouvelles fonctionnalités, nous incrémentons le numéro de version du milieu. Ces versions ne sont pas aussi matures que les correctifs, mais sont considérées comme stables et utilisables.

Nous faisons tous les efforts possibles pour être rétrocompatibles dans ces versions, de sorte que les plugins devraient fonctionner de version mineure en version mineure.

Toutefois, les plugins pourraient devoir être mis à jour pour utiliser les nouvelles fonctionnalités.

Versions Majeures / de rupture (x.0.0)

Chaque année.

Inévitablement, l’amélioration de Elgg nécessite des changements non rétro-compatibles et une nouvelle version majeure est alors publiée. Ces versions sont des occasions pour l’équipe de base d’apporter des changements stratégiques et de rupture à la plateforme sous-jacente. Les thèmes et les plugins des anciennes versions ne sont pas censés fonctionner sans modification sur les différentes versions majeures.

Nous pouvons supprimer des APIs obsolètes, mais nous ne supprimerons pas d’APIs sans les avoir d’abord dépréciées.

Les dépendances de Elgg peuvent être mises à niveau par leur version majeure ou supprimées entièrement. Nous ne supprimerons pas de dépendance avant une version majeure, mais nous ne rendons pas obsolète - « deprecate » - les dépendances ou ou n’émettons pas d’avertissement avant de les supprimer.

Votre package, plugin ou application doit déclarer ses propres dépendances directement afin que cela ne cause pas de problème.

Versions Alphas, Betas, et candidates RC - Release Candidates

Avant les versions majeures (et parfois avant les versions de fonctionnalités), l’équipe du noyau offrira une pré-version de Elgg pour obtenir des tests et des commentaires dans le monde réel sur la version. Ces versions sont destinées à des tests seulement et ne doivent pas être utilisées sur un site en production.

SemVer 2.0 ne définit pas de signification particulière pour les pré-versions, mais nous abordons les versions alpha, bêta et rc avec ces indications générales :

Une pré-version -alpha-X signifie qu’il y a encore des modifications de rupture prévues, mais l’ensemble des fonctionnalités de la version est gelé. Aucune nouvelle fonctionnalité ou modification de rupture ne peut être proposée pour cette version.

Une pré-version -beta.X signifie qu’il n’y a plus de modification de rupture connue à inclure, mais qu’il reste des régressions connues ou des bogues critiques à corriger.

Une pré-version -rc.X signifie qu’il n’y a plus de régression connue ou de bogue critique à corriger. Cette version pourrait devenir la version stable finale de Elgg si aucun nouveau blocage n’est signalé.

Rétro-compatibilité

Certaines parties du système ont besoin de clarifications supplémentaires si nous voulons être rétro-compatibles. Tout ce qui est considéré comme une API publique doit respecter les règles de rétro-compatibilité qui font partie du versionnage sémantique.

Classes et fonctions

Les classes et fonctions marquées @internal ne sont pas considérées comme faisant partie de l’API publique et peuvent être modifiées/supprimées à tout moment. Si une classe est marquée @internal, toutes les propriétés et méthodes de cette classe sont considérées comme une API privée et peuvent être modifiées/supprimées à tout moment.

Gestionnaires d’événements

Tous les rappels d’événement ne doivent jamais être appelés directement mais uniquement en déclenchant l’événement.

Le nom de la fonction de rappel est considéré comme une API dans le sens où les développeurs de plugins doivent être en mesure de compter sur le fait qu’ils peuvent (dé-)enregistrer une fonction de rappel. Ceci ne s’applique que si la fonction de rappel sert toujours le même but. Si une fonction de rappel devient obsolète, elle peut être supprimée du système.

Avertissement

Les exceptions à ces règles sont les fonctions de rappel liées aux événements system, ces fonctions de rappel peuvent être renommées / supprimées à tout moment.

• plugins_load

• plugins_boot

• init

• ready

• shutdown

• upgrade

Suite de tests

Les fichiers de la suite de tests Elgg PHPUnit ne sont pas considérés comme faisant partie de l’API publique et peuvent être modifiés/supprimés à tout moment.

Vues

• Les noms de vue sont des APIs.

• Les arguments de la vue (tableau $vars) sont des API.

• La suppression de vues ou le changement de nom de vues suit les stratégies de dépréciation de l’API.

• L’ajout de nouvelles vues nécessite une modification mineure de la version.

• La sortie des vues n’est pas une API et peut être modifiée entre deux versions de correctifs.

Politique de support

À partir de Elgg 2.0, chaque version mineure reçoit des corrections de bogue et de sécurité jusqu’à la prochaine version mineure.

Versions LTS supportées sur le long terme - Long Term Support

Au sein de chaque version majeure, la dernière version mineure est désignée pour le support à long terme (« LTS » pour Long Term Support) et recevra des correctifs de bogues jusqu’à 1 an après la sortie de la prochaine version majeure, et des correctifs de sécurité jusqu’à la 2ème version majeure suivante.

Par ex., 2.3 est la dernière version mineure dans les 2.x. Elle recevra des correctifs de bogues jusqu’à 1 an après que la version 3.0 a été publiée, et les correctifs de sécurité jusqu’à ce que la version 4.0 soit publiée.

Voir aussi

• Politique de versions

• Signaler des problèmes

Bugs

Lorsque des bogues sont trouvés, un effort de bonne foi sera fait pour corriger la publication de la version LTS, mais tous les correctifs ne seront pas rétro-portés. Par ex., certains correctifs peuvent dépendre de nouvelles API, rompre la rétro-compatibilité, ou nécessiter une refactorisation significative.

Important

Si un correctif risque de compromettre la stabilité de la branche LTS, il ne sera pas inclus.

Problèmes de sécurité

Lorsqu’un problème de sécurité est constaté, tous les efforts seront faits pour corriger la version LTS.

Attention

Veuillez signaler tout problème de sécurité à security @ elgg . org

Chronologie

Vous trouverez ci-dessous un tableau décrivant les détails de chaque version (les dates futures sont provisoires) :

Version	Première publication stable	Corrections de bogues à travers	Correctifs de sécurité à travers
1.12	Juillet 2015	Avril 2019	Avril 2019
2.0	Décembre 2015	Mars 2016
2.1	Mars 2016	Juin 2016
2.2	Juin 2016	Novembre 2016
2.3	Novembre 2016	Avril 2020	Septembre 2021
3.0	Avril 2019	Juillet 2019
3.1	Juillet 2019	Octobre 2019
3.2	Octobre 2019	Janvier 2020
3.3	Janvier 2020	Septembre 2022	Juin 2023
4.0	Septembre 2021	Janvier 2022
4.1	Janvier 2022	Avril 2022
4.2	Avril 2022	Juillet 2022
4.3 LTS	Juillet 2022	Juin 2024	Jusqu’à la 6.0
5.0	Juin 2023	Octobre 2023
5.1	Octobre 2023
6.0	A FAIRE

Historique

Le nom vient d’une ville en Suisse. Cela signifie aussi « élan » ou « orignal » en Danois.

Le financement initial de Elgg a été initié par une société appelée Curverider Ltd, qui a été lancée par David Tosh et Ben Werdmuller. En 2010, Curverider a été acquise par Thematic Networks et le contrôle du projet open-source a été confié à The Elgg Foundation. Aujourd’hui, Elgg est un projet open source communautaire avec une variété de contributeurs et de soutiens.