Bonnes pratiques : AJAX et WordPress

Introduction

Voilà une demande qui se fait souvent, comment faire proprement de l’ajax dans une installation WordPress,que se soit dans un plugin, dans l’admin ou dans sur le front.

Heureusement, WordPress propose une toute petit API pour faire de l’ajax très facilement et profiter de toutes les fonctionnalités de WordPress dans son PHP.

Les actions

WordPress proposant son APi pour faire de l’ajax, nous avons deux actions disponibles :

'wp_ajax_'
'wp_ajax_nopriv_'

Pour que WordPress comprenne bien ces actions, il faut tout simplement lui signifier l’action que nous voulons effectuer :

[pastacode provider= »manual » lang= »php »]

add_action( 'wp_ajax_getPost', 'get_the_posts' );

[/pastacode]

ou

[pastacode provider= »manual » lang= »php »]

add_action( 'wp_ajax_nopriv_getPost' , 'get_the_posts' );

[/pastacode]

Comme on peut le voir, j’ai ajouté ‘getPost’ à la fin des noms des actions, c’est le nom de l’action que nous voulons faire. Mais il y a aussi une nuance, le petit ‘no_priv’ à la fin de l’action.

Que signifient-ils ? Tout simplement qui si on ajoute pas le ‘nopriv’ dans le nom de notre action, la fonction appelée par l’action ne sera active que pour les utilisateurs non connectés. Si vous faites un plugin qui s’adresse aux deux types d’utilisateurs ou alors un plugin qui ne fait de l’ajax que dans l’admin ces actions peuvent appeler des fonctions totalement différentes.

Cas d’étude

Nous allons faire un tout petit script qui va mettre en évidence les deux actions. Nous voulons mettre en bas d’article un lien qui donne accès à des informations supplémentaires mais qui ne sont affichées qu’aux utilisateurs connectés. Notre plugin se composera d’un fichier php et d’un fichier javascript qui va gérer la requête ajax.

Le code PHP

Ajouter le lien en bas d’article

Ajoutons donc un lien en fin d’article, pour que se soit très propre nous allons le faire avec le filtre sur ‘the_content’.

[pastacode provider= »manual » lang= »php »]

add_filter( 'the_content', 'add_content_ajax_link' );

function add_content_ajax_link( $content ) {
	$content .= '

';
	return $content;

}

[/pastacode]

Nous venons juste d'ajouter à notre article un lien qui ne renvoie vers rien mais qui nous permettra de faire notre petit javascript.

Ajouter l'action et la réponse

Pour que WordPress comprenne notre demande nous devons faire une requête spécifiquement vers une url, la ajaxurl. Si vous regardez bien dans l'admin avec la source, il y a des variables javascript dans le header :

Cette variable est la même pour tous les blogs et se base su l'url de l'admin, mais n'est pas dans les variables javascript dans le front. Il faut que nous l'ajoutions manuellement pour que le code puisse fonctionner même si l'url du site change.

Ajout de l'action ajax

Quelle que soit l'action ajax que vous allez faire, il faut faire un die ou un exit à la fin de votre script ou WordPress le fera pour vous, mais accompagnera votre résultat d'un 0, ce qui ne vous arrangeras pas forcément.

[pastacode provider="manual" lang="php"]

// Action pour l'utilisateur connecté
add_action( 'wp_ajax_ajaxLink', 'a_ajaxLink' );
function a_ajaxLink(){
	echo __( 'The date is ' ).date( 'd m Y' );
	die();
}

// Action pour l'utilisateur non connecté
add_action( 'wp_ajax_nopriv_ajaxLink', 'an_ajaxLink' );
function an_ajaxLink(){
	echo __( 'You have to be logged in for more infos.' );
	die();
}

[/pastacode]

Nous avons donc deux résultats différents pour chaque action ajax envoyée, j'ai préfixé les fonctions d'un 'a' pour l'appel ajax connecté et d'un 'an' pour l'appel en nopriv.

Nous allons maintenant devoir ajouter le javascript et la variable vers l'API ajax de WordPress dont nous avons parlé plus tôt.

Ajout du javascript et de la variable

Nous allons ajouter ce code dans le fichier functions.php:

[pastacode provider="manual" lang="php"]

// Ajoutons le script dans le wp_head
add_action( 'init', 'add_ajax_script' );
function add_ajax_script() {
	if( !is_single() )
		return false;

	wp_enqueue_script( 'ajax_link', template_url().'/js/ajax_link.js', array( 'jquery'  ), '1.0', true );
	wp_localize_script( 'ajax_link', 'aLink', array( 'ajaxurl' => admin_url( '/admin-ajax.php' )  )  );

}

[/pastacode]

La fonction wp_enqueue_script accepte 5 paramètres:

1.  l'identifiant unique du script pour WordPress
2. L'url du script à importer
3. La dépendance du script, ici il faut jQuery pour que ça marche car nous allons utiliser le jquery de WordPress
4. La version de notre script ( utile pour le cache en cas de mise à jour )
5. Forcer le script à s'ajouter dans le footer. Cette valeur est à false pas défaut, en la mettant à true le script sera ajouté au moment du wp_footer.

1. L'identifiant du script qui utilise la variable
2. Le nom de la variable javascript qui sera créée
3. Un tableau de clé/valeurs qui vous permettent de passer des variables PHP très facilement, ou des chaînes traduites !

Le javascript

[pastacode provider="manual" lang="javascript"]

jQuery( function() {
	jQuery( '.ajax_link_wrapper' ).on('click', 'a.ajax_link', function( event ){
		event.preventDefault();
		var _self = jQuery( this ),
		parent = jQuery( this ).closest( 'div' );
		if( !parent.hasClass( 'ajaxing' ) ) {
			jQuery.ajax( {
				url: aLink.ajaxurl,
				type: "POST",
				data: { action : 'ajaxLink' },
				beforeSend: function() {
					parent.addClass( 'ajaxing' );
				},
				success: function( response ) {
					parent.removeClass( 'ajaxing' );
					response.appendTo( parent );
				}
			} );
		}
	});
});

[/pastacode]

Dans ce javascript tout simple, nous faisons une requête vers notre API de WordPress avec le "aLink.ajaxurl", et pour éviter de lancer plusieurs fois notre action ajax nous ajoutons la classe "ajaxing" à notre parent que nous retirons lors de la fin de notre requête.
Maintenant en cliquant sur notre lien, nous allons faire une requête ajax et ajouter le résultat dans notre parent.

Le script final

Le PHP

[pastacode provider="manual" lang="php"]

add_filter( 'the_content', 'add_content_ajax_link' );
function add_content_ajax_link( $content ) {
	$content .= '

';
	return $content;
}

// Action pour l'utilisateur connecté
add_action( 'wp_ajax_ajaxLink', 'a_ajaxLink' );
	function a_ajaxLink() {
	echo _( 'The date is ' ).date( 'd m Y' );
	die();
}

// Action pour l'utilisateur non connecté
add_action( 'wp_ajax_nopriv_ajaxLink', 'an_ajaxLink' );
	function a_ajaxLink() {
	echo _( 'You have to be logged in for more infos.' );
	die();
}

// Ajoutons le script dans le wp_head
add_action( 'init', 'add_ajax_script' );
function add_ajax_script() {
	// Testons si nous sommes bien dans un article seul
	if( !is_single() )
	return false;

	wp_enqueue_script( 'ajax_link', template_url().'/js/ajax_link.js', array( 'jquery'  ), '1.0', true );
	wp_localize_script( 'ajax_link', 'aLink', array( 'ajaxurl' => admin_url( '/admin-ajax.php' )  )  );
}

[/pastacode]

Le Javascript

[pastacode provider="manual" lang="javascript"]

jQuery( function() {
	jQuery( '.ajax_link_wrapper' ).on( 'click' , 'a.ajax_link', function( event ){
		event.preventDefault();
		var _self = jQuery( this ),
		parent = jQuery( this ).closest( 'div' );
		if( !parent.hasClass( 'ajaxing' ) ) {
			jQuery.ajax( {
				url: aLink.ajaxurl,
				type: "POST",
				data: { action : 'ajaxLink' },
				beforeSend: function() {
					parent.addClass( 'ajaxing' );
				},
				success: function( response ) {
					parent.removeClass( 'ajaxing' );
					response.appendTo( parent );
				}
			} );
		}
	});
});

[/pastacode]

Conclusion

Faire de l'ajax dans WordPress est très aisé, mais il faut garder en tête que chaque actions que vous allez laisser à votre utilisateur doit être testée et vérifiée.
Il faut que si vous permettez des actions, que ces actions ne puissent pas laisser une personne mal intentionnée de casser votre site.

Pour aller plus loin

Une classe existe pour ajouter facilement des actions ajax juste en formattant vos méthodes avec des 'a_' ou des 'an_'.
Elle se présente de la manière suivante :

[pastacode provider="manual" lang="php"]

class WP_Ajax {
        function __construct( $ajax_prefix = 'a', $nopriv_prefix = 'n' ) {
                $regex = "/^($ajax_prefix)?($nopriv_prefix)?_|^($nopriv_prefix)?($ajax_prefix)?_/";
                $methods = get_class_methods( $this );
                foreach ( $methods as $method ) {
                        if ( preg_match( $regex, $method, $matches ) ) {
                                if ( count( $matches ) > 1 ) {
                                        $action = preg_replace( $regex, '', $method );
                                        if ( count( $matches ) == 3 ) {
                                                add_action( "wp_ajax_$action", array( $this, $method ) );
                                                add_action( "wp_ajax_nopriv_$action", array( $this, $method ) );
                                        } else {
                                                if ( $matches[1] == $ajax_prefix ) {
                                                        add_action( "wp_ajax_$action", array( $this, $method ) );
                                                } else {
                                                        add_action( "wp_ajax_nopriv_$action", array( $this, $method ) );
                                                }
                                        }
                                }
                        }
                }
        }
}

[/pastacode]

Si vous voulez faire de l'ajax très rapidement elle est parfaite, elle ajoute automatiquement les différentes actions, mais il faut développer avec des classes.