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.

TODO : Capture d’écran

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 teoutes 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 drapeux 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 focntionner correctement dans le panneau d’édition d’un widget.

Enregistrez le widget

Une fois que vous avez créé vos pages de modification et d’affichage, vous devez initialiser le widget plugin. Cela se fait dans 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'),
]);

Note

Le seul attribut requis est l”id.

Widgets multiples

Il est possible d’ajouter plusieurs widgets pour un plugin. Vous initialisez seulement 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'),
 ]);

 // Add a second file widget
elgg_register_widget_type([
     'id' => 'filerepo2',
     'name' => elgg_echo('widgets:filerepo2:name'),
     'description' => elgg_echo('widgets:filerepo2:description'),
 ]);

 // Add a third file widget
elgg_register_widget_type([
     'id' => 'filerepo3',
     'name' => elgg_echo('widgets:filerepo3:name'),
     'description' => elgg_echo('widgets:filerepo3:description'),
 ]);

Assurez-vous que vous avez les répertoires correspondants suivants au sien de 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 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 spécifier le contexte dans lequel il peut être utilisé (partout, uniquement sur le profil, sur le tableau de bord, etc.). Si vous ne spécifiez pas de contexte, ils seront disponibles pour tous les contextes.

elgg_register_widget_type([
    'id' => 'filerepo',
    'context' => ['profile', 'dashboard', 'other_context'],
]);

Autorisez plusieurs widgets 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 plusieurs widgets du même type sur la page, vous pouvez spécifier ceci quand vous enregistrez le widget :

elgg_register_widget_type([
    'id' => 'filerepo',
    'multiple' => true,
]);

Enregistrez 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($hook, $type, $return, $params) {
    if (!elgg_is_active_plugin('file')) {
        return;
    }

    $return[] = \Elgg\WidgetDefinition::factory([
        'id' => 'filerepo',
    ]);

    return $return;
}

Modifiez les propriétés du 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($hook, $type, $return, $params) {
    foreach ($return as $key => $widget) {
        if ($widget->id === 'filerepo') {
            $return[$key]->multiple = false;
        }
    }

    return $return;
}

Widgets par défaut

Si votre plugin utilise le canvas widgets, vous pouvez enregistrer le support d’un widget par défaut avec le noyau d’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');

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 admin.

• widget_context - Le contexte depuis lequel la page widgets est appelée. (Si non défini explicitement, ce sera l’id de votre plugin.)

• widget_columns - Combien de colonnes la page widgets va utiliser.

• event - L’événement Elgg pour lequel créer de nouveaux widgets. C’est habituellement create.

• 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.

Quand un objet déclenche un événement qui correspond aux paramètres passés event, entity_type, et entity_subtype, le noyau d’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.

function my_plugin_default_widgets_hook($hook, $type, $return, $params) {
    $return[] = array(
        'name' => elgg_echo('my_plugin'),
        'widget_context' => 'my_plugin',
        'widget_columns' => 3,

        'event' => 'create',
        'entity_type' => 'user',
        'entity_subtype' => ELGG_ENTITIES_ANY_VALUE,
    );

    return $return;
}