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,
]);

Enregistrer des widgets dans un hook

Si, par exemple, vous souhaitez enregistrer des widgets de manière conditionnelle, vous pouvez utiliser un hook pour enregistrer des widgets.

function my_plugin_init() {
    elgg_register_plugin_hook_handler('handlers', 'widgets', 'my_plugin_conditional_widgets_hook');
}

function my_plugin_conditional_widgets_hook(\Elgg\Hook $hook) {
    if (!elgg_is_active_plugin('file')) {
        return;
    }

    $return = $hook->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 changer les contextes autorisés pour un widget déjà enregistré, vous pouvez faire cela en ré-enregistrant le widget avec elgg_register_widget_type, ce qui va remplacer une définition de widget existante. Si vous voulez encore plus de contrôle vous pouvez également utiliser le hook handlers, widgets pour changer la définition du widget.

function my_plugin_init() {
    elgg_register_plugin_hook_handler('handlers', 'widgets', 'my_plugin_change_widget_definition_hook');
}

function my_plugin_change_widget_definition_hook(\Elgg\Hook $hook) {
    $return = $hook->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 déclarer le support d’un widget par défaut dans votre plugin, enregistrez le hook plugin get_list, default_widgets :

elgg_register_plugin_hook_handler('get_list', 'default_widgets', 'my_plugin_default_widgets_hook');

function my_plugin_default_widgets_hook(\Elgg\Hook $hook) {
    $return = $hook->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 du hook plugin, poussez un tableau dans la valeur de retour, qui définit le support de votre widget par défaut et quand créer les widgets par défaut. Les tableaux doivent définir les clefs 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 que des widgets soient créés, vous devez enregistrer le hook de plug-in suivant :

elgg_register_plugin_hook_handler('create', '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.