API day : TYPO3 et les liens (typolink)

L’API TYPO3 regroupe un nombre impressionnant de fonctionnalités dont certaines ne sont pas très connues.
Voici, par exemple, la gestion des liens dans les plugins Frontend avec le CMS TYPO3.

Les liens sont des éléments importants dans la navigation sur un site internet et dans TYPO3 les liens peuvent avoir plusieurs formes.

A) Principe des urls dans TYPO3

Par exemple, pour une url vers la page « 29  » (titre « ma page »), au format pdf (type=123), avec une variable dont la valeur est 12 :

• Sans réécriture : /index.php?id=29&type=123&tx_monext_pi1[variable]=12
• Réécriture du nom de la page : /mapage.html?type=123&tx_monext_pi1[variable]=12
• Réécriture de la page et de la variable : /mapage/12.html?type=123
• Réécriture de la page, de la variable et du type : /mapage/12.pdf : réécriture complète

Dans le cadre d’un développement de plugin, et pour ne pas avoir à réinventer la roue, l’API TYPO3 fournie plusieurs fonctions permettant de mettre en forme les liens.

De manière générique (via l’objet cObj) :

• $this->cObj->currentPageUrl()
• $this->cObj->typoLink_URL()
• $this->cObj->getTypoLink_URL()

Dans le cas d’un plugin qui hérite de pibase :

• $this->pi_getPageLink()
• $this->pi_linkTP_keepPIvars_url()

Pour les développements qui utilisent correctement ces fonctions, la mise en place (ou la désactivation) d’un système de réécriture d’url ne posera aucun problème car l’url aura le même formatage que partout ailleurs dans le site.

Ensuite le lien généré respecte les droits d’accès aux pages, ce qui fait que si une page est cachée, supprimée, ou que l’internaute n’a pas les droits nécessaires pour consulter la page, alors le lien sera désactivé.

Enfin, si la page est renommée ou déplacée dans l’arborescence, le lien réécrit sera automatiquement mis à jour, il ne sera pas nécessaire de modifier quoi que ce soit.

B) De manière générique (via la classe « tslib_cObj » )

1) Fonction currentPageUrl()

Elle permet de faire rapidement un lien vers la page actuelle ou une page précise dans TYPO3 en lui passant si besoin des paramètres à rajouter dans l’url.

Elle accepte 2 paramètres :
– un tableau de paramétres à ajouter dans l’url
– une page de destination à utiliser en remplacement de l’ID de la page actuelle

  //id page destination
$idPage=18;
  //tableaux des parametres a inserer dans le lien
$urlParameters=array(
  'etape'=>'details',
  'idDetail'=>12
);
  //generation de l'url
$url = $this->cObj->currentPageUrl($urlParameters, $idPage);

L’url simple sera : /index.php?id=18&etape=details&idDetail=12

2) fonction typoLink_URL()

c’est un peu la même fonction que currentPageUrl() sauf que les paramètres doivent être passé sous forme de tableau.

Dans le tableau, la case « parameter » est la page de destination et la case « addionalParams » est une chaîne de caractères qui sera ajoutée dans l’url.

  //id page destination
$idPage=18;
  //tableaux des parametres a inserer dans le lien
$confLink=array(
  'parameter' => $idPage,
  'additionalParams' => '&etape=details&idDetail=12'
);
  //generation de l'url
$url = $this->cObj->typoLink_URL($confLink);

L’url simple sera : /index.php?id=18&etape=details&idDetail=12

3) fonction getTypoLink_URL()

c’est un peu la même fonction que currentPageUrl() sauf que la page de destination est obligatoire et que l’ordre des paramètres est inversé.

Elle accepte 3 paramètres :
– la page de destination du lien
– un tableau de paramètres à ajouter dans l’url
– la target (mais pas utilisée puisqu’on ne génère que l’url, donc on ne l’utilise pas)

  //id page destination
$idPage=18;
  //tableaux des parametres a inserer dans le lien
$urlParameters=array(
  'etape'=>'details',
  'idDetail'=>12
);
  //generation de l'url
$url = $this->cObj->getTypoLink_URL($idPage, $urlParameters);

L’url simple sera : /index.php?id=18&etape=details&idDetail=12

C) Les plugins héritant de la classe « tslib_pibase »

1) fonction  $this->pi_getPageLink()

c’est un raccourci vers la fonction $this->cObj->getTypoLink_URL(), seul l’ordre des paramètres change.

Elle accepte 3 paramètres :
– la page de destination du lien
– la target (mais pas utilisée puisqu’on ne génère que l’url, donc on laissera vide)
– un tableau de paramètres à ajouter dans l’url

  //id page destination
$idPage=18;
  //tableaux des paramatres a inserer dans le lien
$urlParameters=array(
  'etape'=>'details',
  'idDetail'=>12
);
  //generation de l'url
$url = $this->pi_getPageLink ($idPage, '', $urlParameters);

L’url simple sera : /index.php?id=18&etape=details&idDetail=12

2) function pi_linkTP_keepPIvars_url()

Cette fonction permet de faire un lien mais avec une reprise automatique des pivars existants.

Les « pivars » sont les variables spécifiques à un plugin qui, dans leur forme brute dans une url, peuvent être identifiées car ils sont de la forme : &tx_+nomplugin+[+nom_variable+].

Dans les plugins, ils ont accessibles simplement et automatiquement via la variable « $this->piVars[+nom_variable+] ».

Cette fonction accepte 4 paramètres :
– un tableau permettant de remplacer les pivars actuels
– un booléen permettant de préciser le mode de mise en cache (avec ou sans cache)
– un booléen permettant de forcer la suppression des pivars actuels
– la page de destination du lien

  //id page destination
$idPage=18;
  //tableau des variables de remplacement des pivars actuel
$piVars=array(
 'etape'=>'details',
 'idDetail'=>12
);
  //generation de l'url
$url = $this->pi_linkTP_keepPIvars_url($piVars,1,0,$idPage);

Si l’url actuelle est :
/index.php?id=18&tx_monext[etape]=liste&tx_monext[message]=OK
Alors l’url simple sera :
/index.php?id=18&tx_monext[etape]=details&tx_monext[idDetail]=12&tx_monext[message]=OK
Avec :
– le pivars « etape » qui passe de « liste » à « details » (remplacement du pivars),
– ajout du pivars « idDetail »
– et conservation (automatique) du pivar « message ».

D) les autres types de liens

Nous avons vu la génération de lien vers une page interne à TYPO3, mais il est tout aussi simple de générer un lien vers n’importe quel autre élément comme par exemple :

• un fichier (dans le site TYPO3)
• une url externe
• un email

Il suffit pour cela de mettre le lien dans la variable pour laquelle nous avions mis, précédemment, un ID de page.
TYPO3 se chargera tout seul de détecter le type du lien avec les règles suivantes :

• le lien contient un @ et est éventuellement préfixé de « mailto: » => alors c’est un email
• le lien contient http:// (ou équivalent) et ce n’est pas un fichier du site => alors c’est un lien vers une url externe
• le lien contient une chaine de texte correspondant à un fichier du site => alors c’est un lien interne vers un fichier
• sinon => c’est un lien interne vers une page

En fonction de chaque type de lien, TYPO3 suivra la configuration demandée pour adapter le lien comme par exemple la fonctionnalité de « jumpurl » ou l’encryption d’email.

Exemple de lien vers un email :

  //email a la place
$idPage='email@domaine.tld';
  //tableaux des parametres a inserer dans le lien
$confLink=array(
  'parameter' => $idPage
);
  //generation de l'url
$url = $this->cObj->typoLink_URL($confLink);

L’url simple sera : mailto:email@domaine.tld (l’email sera automatiquement encodé si le paramétrage typoscript demande l’encryption de l’email)

Exemple de lien vers un fichier :

  //url vers un fichier dans fileadmin
$idPage='fileadmin/user_uploads/monfichier.doc';
  //tableaux des parametres a inserer dans le lien
$confLink=array(
  'parameter' => $idPage
);
  //generation de l'url
$url = $this->cObj->typoLink_URL($confLink);

L’url simple sera : fileadmin/user_uploads/monfichier.doc (le lien sera automatiquement adpaté si la configuration jumpurl est activée ou éventuellement préfixée en fonction de la configuration TYPO3/typoscript)

Exemple de lien vers une url externe:

  //url vers un fichier dans fileadmin
$idPage='http://www.google.fr/';
  //tableaux des parametres a inserer dans le lien
$confLink=array(
  'parameter' => $idPage
);
  //generation de l'url
$url = $this->cObj->typoLink_URL($confLink);

L’url simple sera : http://www.google.fr/ (le lien sera automatiquement adpaté si la configuration jumpurl est activée).

E) Et le reste du lien alors?

Nous avons vu les fonctions pour générer l’url du lien, mais il est possible de générer le lien complet aussi simplement.
On peut retrouver les fonctions génériques (via l’objet cObj) :

• $this->cObj->typoLink
• $this->cObj->getTypoLink

Ou dans le cas des plugins héritant de piBase :

• $this->pi_linkToPage (correspondant à $this->pi_getPageLink())
• $this->pi_linkTP_keepPIvars()

Chaque fonction agit de la même manière que la fonction générant l’url seule mais en prenant en compte du chaine de texte autour de laquelle construire le lien, ainsi que l’ensemble des autres attributs de la balise du lien.

Le principe est que le paramètre du lien (appelé « $idPage » au dessus) ne contient pas obligatoirement que le lien (exemple l’uid d’une page)  mais peut contenir plusieurs informations à savoir :

• l’url du lien (l’ID de la page ou le lien complet)
• la « target » du lien
• la classe CSS à mettre en place
• le titre spécifique du lien
• les paramètres supplémentaires du lien

Si l’une des 4 dernières informations contient « – » elle est considérée comme vide.

Exemple d’appel à la fonction typolink

  //le texte du lien
$texte='texte du lien';
  //parametres complet du lien
  // avec idPage 18 + pas de target + classe css "maClasseCSS" + pas de titre spécifique + des parametres supplementaires pour le lien
$idPage='18 - maClasseCSS - &etape=details&idDetail=12';
  //tableaux des parametres a inserer dans le lien
$confLink=array(
  'parameter' => $idPage,
);
  //generation de l'url
$lien = $this->cObj->typoLink($texte, $confLink);

Le lien complet sera : <a href= »/index.php?id=18&etape=details&idDetail=12″ class= »maClasseCSS »>texte du lien</a>

F) Encore… Encore…

Il existe d’autres possibilités pour faire des liens depuis un plugin, comme par exemple l’utilisation de FLUID.

Ce moteur de template (qui ressemble à SMARTY), étroitement lié au typoscript et aux fonctionnalités du noyau de TYPO3, permet de faire des liens via des marqueurs spécifiques dans un template HTML.

Un article a été rédigé pour présenter l’utilisation de FLUID dans les développements PHP.

G) Conclusion

Il est important de toujours utiliser les fonctionnalités de l’API dans le but d’avoir un fonctionnement stable sur le long terme, mais surtout la garantie que les urls mises en place reflètent le fonctionnement du site dans son ensemble.

En utilisant ces fonctions il est possible de mettre en place des urls propres, utilisable par exemple :

• pour fournir un lien pour passer d’un écran à un autre
• pour rediriger l’internaute sur une page précise après la création d’un enregistrement en base de données
• pour gérer les différents liens d’une navigation multi-page sans avoir à surveiller l’ensemble des paramètres de l’url
• proposer le téléchargement d’un document
• fournir un lien vers un site exterieur
• etc….

Alors, toujours envie de construire vos liens à la main?