# AJAX avec jQuery

jQuery propose plusieurs fonctions pour effectuer des requêtes AJAX. La principale est `jQuery.ajax()`, mais il existe des raccourcis et des options supplémentaires.

## Fonction passe-partout

La fonction passe-partout `jQuery.ajax()` s'utilise avec deux paramètres : l'URL (`string`) et la configuration (`JSON`).

Voici un exemple de requête AJAX dans son contexte :

```js
$('#login-button').on('click', function() {
    $.ajax('/user/login', {
        method : 'POST',
        data : {
            username : $('#username').val(),
            password : $('#password').val()
        },
        success : function(response) {
            $('#message').text("Vous vous êtes connecté·e avec succès")
        },
        fail : function() {
            $('#message').text("Il y a eu un problème lors de la connexion")
        }
    })
})
```

Le code ci-dessus nécessite quelques explications :

- La requête AJAX est lancée lorsqu'on clique sur un bouton. En général, on place les requêtes AJAX dans des évènements, car s'il s'agit de récupérer des données dès le chargement de la page, pourquoi ne pas les envoyer directement avec le code initial ?
- AJAX va demander la page `/user/login`. On ne précise pas plus, puisqu'on va effectuer une requête vers le même site. L'adresse réellement appelée sera `https ://site-sur-lequel-on-se-trouve.com/user/login`.
- La fonction `$.ajax` prend, comme second paramètre, un JSON contenant 4 attributs : `method`, `data`, `success`, `fail`. Il y a en tout 34 attributs possibles, détaillés sur la page de documentation [jQuery.ajax](http ://api.jquery.com/jQuery.ajax/). Sachez que tous ces attributs sont facultatifs car ils possèdent tous une valeur par défaut.
  - `method` indique que la méthode HTTP à utiliser pour la requête est `POST`.
  - `data` contient, sous la forme d'un JSON, les données nécessaires au server afin de réaliser l'action demandée. En l'occurrence, pour la page `/user/login`, le serveur a besoin d'un `username` et d'un `password`. Les valeurs envoyées sont directement tirées des champs correspondants.
  - `success` est la fonction qui sera appelée lorsque le serveur aura répondu avec un code "200 OK" (tout s'est bien passé). Le paramètre `response` est la réponse de celui-ci.
  - `fail` est la fonction qui sera appelée lorsque le serveur aura répondu avec un code "4xx" ou "5xx" (erreur côté client ou côté serveur).

## Méthodes raccourcies pour GET et POST

jQuery propose deux méthodes raccourcies pour l'utilisation d'AJAX en GET et en POST : `$.get` et `$.post`.

Voici le code ci-dessus, traduit avec ce raccourci :

```js
$('#login-button').on('click', function() {
    $.post('/user/login', {
        username : $('#username').val(),
        password : $('#password').val(),
    }, function(response) {
        $('#message').text("Vous vous êtes connecté·e avec succès")
    }).fail(function() {
        $('#message').text("Il y a eu un problème lors de la connexion")
    })
})
```

La fonction prend trois paramètres :

- une chaine de caractères représentant l'URL à contacter (obligatoire)
- un JSON contenant les données à envoyer (facultatif)
- une fonction à appeler lorsque tout s'est bien passé (facultatif)

La fonction à appeler lors d'erreur n'est pas incluse dans cet alias raccourci et doit être ajoutée ainsi : `$.post(...).fail(...)`.

**NOTE :** la fonction `$.get` fonctionne exactement de la même manière, mais envoie une requête avec la méthode GET.

# Charger des données directement dans un élément

jQuery possède un raccourci encore plus court pour faire une opération très répandue : charger du contenu distant dans un élément du DOM. Il utilise pour ceci la fonction `.load`.

**NOTE :** il s'agit bien de la fonction `.load` et non `$.load`, ce qui signifie qu'elle s'applique à un élément du DOM.

Voici un exemple d'utilisation :

```js
$('#a-propos').load('/about')
```

Cette fonction va chercher le contenu (HTML) de la page `/about` et va l'insérer comme contenu de l'élément `#a-propos`.

La fonction `.load` peut prendre un second paramètre contenant d'éventuelles données nécessaires au serveur. Voici un autre exemple qui l'utilise :

```js
$('.article').load('/article/show', {
    id : $(this).data('id')
})
```

Pour plus d'information sur `.data`, lisez la [page de documentation](https ://api.jquery.com/data) 😉 !

# Exercice

En utilisant l'API de *prevision-meteo.ch*, effectuez une boite de recherche qui affiche des informations météorologiques sur un lieu.

L'URL de l'API est : `https ://www.prevision-meteo.ch/services/json/ :q`, ` :q` étant la requête (le lieu recherché).

Le résultat doit être le suivant :

![Résultat de la recherche](../img/resultat-meteo.png)

## Explications de ce qui est affiché

Lorsqu'on fait une recherche :

1. La ville recherchée est transformée en *slug* :
   - `Le Locle` devient `le-locle`
   - `Neuchâtel` devient `neuchatel` (vous pouvez aussi vous simplifier la vie et taper *Neuchatel* sans accent)
   - `La Chaux-de-Fonds` devient `la-chaux-de-fonds`
2. Une requête est envoyée à l'API
3. Les données sont récupérées en brut
4. On ajoute à la page les données reçues, sans supprimer les données précédentes (dans l'exemple ci-dessus, 3 requêtes ont été faites).

Cherchez les informations parmi celles récupérées de l'API afin de pouvoir afficher les conditions météorologiques courantes.