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.