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 design/actions et du Cache simple (Simplecache).

Identifiant d’URL et ségments¶

Après avoir supprimé l’URL du site, Elgg découpe le chemin d’accès 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://exemple.com/elgg/, l’URL http://exemple.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 vides.

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.

Gestionnaire de page¶

Pour gérer toutes les URLs qui commencent par un identificateur particulier, vous pouvez enregistrer une fonction pour agir en tant que Gestionnaire de page (gestionnaire de page). Lorsque le gestionnaire est appelé, le tableau de segments est transmis comme premier argument.

Le code suivant enregistre un gestionnaire de page pour les URL « blog » et montre comment on peut acheminer la requête vers une vue de ressource.

elgg_register_page_handler('blog', 'blog_page_handler');

function blog_page_handler(array $segments) {
     // if the URL is http://example.com/elgg/blog/view/123/my-blog-post
     // $segments contains: ['view', '123', 'my-blog-post']

     $subpage = elgg_extract(0, $segments);
     if ($subpage === 'view') {

         // use a view for the page logic to allow other plugins to easily change it
         $resource = elgg_view_resource('blog/view', [
             'guid' => (int)elgg_extract(1, $segments);
         ]);

         return elgg_ok_response($resource);
     }

     // redirect to a different location
     if ($subpage === '') {
         return elgg_redirect_response('blog/all');
     }

     // send an error page
     if ($subpage === 'owner' && !elgg_entity_exists($segments[1])) {
         return elgg_error_response('User not found', 'blog/all', ELGG_HTTP_NOT_FOUND);
     }

     // ... handle other subpages
}

Le Hook Plugin `route`¶

Le hook plugin route est déclenché avant que les gestionnaires de page ne soient appelés. L’identificateur d’URL est donné comme type de hook. Ce hook peut être utilisé pour ajouter une certaine logique avant que la requête soit traitée ailleurs, ou prendre complètement en charge le rendu de page.

En général, les développeurs doivent plutôt utiliser un gestionnaire de page, à moins qu’ils n’aient besoin d’affecter une seule page ou une plus grande variété d’URLs.

Le code suivant donne lieu à des requêtes dans /blog/all entièrement traitées par le gestionnaire de hook de plugin. Pour ces demandes, le gestionnaire de page blog n’est jamais appelé.

function myplugin_blog_all_handler($hook, $type, $returnvalue, $params) {
    $segments = elgg_extract('segments', $returnvalue, array());

    if (isset($segments[0]) && $segments[0] === 'all') {
        $title = "We're taking over!";
        $content = elgg_view_layout('one_column', array(
            'title' => $title,
            'content' => "We can take over page rendering completely"
        ));
        echo elgg_view_page($title, $content);

        // in the route hook, return false says, "stop rendering, we've handled this request"
        return false;
    }
}

elgg_register_plugin_hook_handler('route', 'blog', 'myplugin_blog_all_handler');

Note

À compter de 2.1, la modification de la route doit être effectuée dans le hook route:rewrite.

Le hook de plugin `route:rewrite`¶

Pour la réécriture de l’URL, le hook route:rewrite (avec des arguments similaires à route) est déclenché très tôt, et permet de modifier le chemin d’accès de l’URL de requête (par rapport au site Elgg).

Ici, nous réécrivons les requêtes de news/* vers blog/* :

function myplugin_rewrite_handler($hook, $type, $value, $params) {
    $value['identifier'] = 'blog';
    return $value;
}

elgg_register_plugin_hook_handler('route:rewrite', 'news', 'myplugin_rewrite_handler');

Avertissement

Le hook doit être enregistré directement dans le start.php de votre plugin (l’événement [init, system] est trop tardif).

Aperçu du routage¶

Pour les pages standard, le flux de programme d’Elgg est quelque chose comme ceci :

Un utilisateur demande http://exemple.com/news/owner/jane.
Les plugins sont initialisés.
Elgg analyse l’URL pour identificateur news et les ségments ['owner', 'jane'].
Elgg déclenche le hook plugin route:rewrite, news (voir ci-dessus).
Elgg déclenche le hook plugin route, blog (a été réécrit dans le hook de réécriture).
Elgg trouve un gestionnaire de page enregistré (voir ci-dessus) pour blog, et appelle la fonction, en lui passant les segments.
La fonction de gestionnaire de page détermine qu’elle doit rendre le blog d’un seul utilisateur. Elle appelle elgg_view_resource('blog/owner', $vars) où $vars contient le nom d’utilisateur.
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 comme elgg_view_layout() et elgg_view_page() pour créer la page HTML entière.
Le gestionnaire de page génère l’affichage HTML et renvoie true pour indiquer qu’il a géré la requête.
PHP invoque la séquence d’arrêt d’Elgg.
L’utilisateur reçoit une page complète.

Les normes de codage d’Elgg suggèrent une disposition d’URL particulière, mais il n’y a pas de syntaxe obligatoire.