De 1.8 à 1.9

Contenu

Le fichier manifest.xml
$CONFIG et $vars[“config”]
Fichiers linguistiques
Notifications
Ajout d’éléments à la liste des Activités
Gestionnaires d’URL d’une entité
Web services

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().

De 1.8 à 1.9

Le fichier manifest.xml

$CONFIG et $vars[“config”]

Fichiers linguistiques

Notifications

Ajout d’éléments à la liste des Activités

Gestionnaires d’URL d’une entité

Web services

Le fichier manifest.xml 

Fichiers linguistiques 

Notifications 

Ajout d’éléments à la liste des Activités 

Gestionnaires d’URL d’une entité 

Web services 