|
|
|
# Fonctions
|
|
|
|
|
|
|
|
Les fonctions présentées ci-après sont définies dans les scripts [api.js](https://gitlab.liris.cnrs.fr/lex-game/balex2ff/-/blob/main/src/utils/api.js) et [definitions.js](https://gitlab.liris.cnrs.fr/lex-game/balex2ff/-/blob/main/src/utils/definitions.js).
|
|
|
|
|
|
|
|
#### `callApi`
|
|
|
|
Fonction utilitaire qui centralise l'exécution des requêtes vers l'API. Elle gère la configuration des entêtes, la méthode (GET/POST), le corps de la requête et le traitement de la réponse.
|
|
|
|
|
|
|
|
Fonction utilitaire qui centralise l'exécution des requêtes vers l'API. Elle gère la configuration des entêtes, la méthode (GET/POST), le corps de la requête et le traitement de la réponse.\
|
|
|
|
**Paramètres d'entrée** :
|
|
|
|
|
|
|
|
- `url` (string) : l’adresse complète de l’API à appeler
|
|
|
|
- `authToken` (string|null) : le token d’authentification, s’il existe, pour ajouter un header `Authorization`.
|
|
|
|
- `method` (string, optionnel, par défaut `'GET'`) : la méthode HTTP à utiliser
|
|
|
|
- `data` (object|null, optionnel) : un objet qui sera converti en JSON et envoyé dans le corps de la requête pour les méthodes qui en nécessitent
|
|
|
|
|
|
|
|
**Données manipulées** :
|
|
|
|
Les en-têtes nécessaires aux requêtes contiennent :
|
|
|
|
`Content-Type: application/json`
|
|
|
|
`Authorization: Bearer <authToken>`
|
|
|
|
**Données manipulées** :\
|
|
|
|
Les en-têtes nécessaires aux requêtes contiennent :\
|
|
|
|
`Content-Type: application/json`\
|
|
|
|
`Authorization: Bearer <authToken>`\
|
|
|
|
Pour le corps de la requête, `data`est transformé en JSON avec `JSON.stringify(data)` et assigné à `fetchOptions.body`.
|
|
|
|
|
|
|
|
**Traitement de la réponse** :
|
|
|
|
**Traitement de la réponse** :\
|
|
|
|
La fonction attend la réponse de `fetch(url, fetchOptions)`. Si la réponse n'est pas `ok`, elle lève une exception avec un message d'erreur (code de statut + statut textuel). Sinon, elle retourne le résultat parsé en JSON avec `await response.json()`. La sortie attendue est donc un objet au format JSON représentant la réponse de l'API (ou exception si erreur).
|
|
|
|
|
|
|
|
#### `getLexicons`
|
|
|
|
Cette fonction récupère les lexiques (et les informations les concernant) de l'utilisateur. Le paramètre d'entrée est `authToken` pour autoriser la requête. La fonction appelle `callApi` en fournissant l'URL de la requête et le token.
|
|
|
|
Le point de terminaison utilisé est : `api/lexicon/search`
|
|
|
|
|
|
|
|
Cette fonction récupère les lexiques (et les informations les concernant) de l'utilisateur. Le paramètre d'entrée est `authToken` pour autoriser la requête. La fonction appelle `callApi` en fournissant l'URL de la requête et le token.\
|
|
|
|
Le point de terminaison utilisé est : `api/lexicon/search`\
|
|
|
|
Les **données récupérées** sont :
|
|
|
|
|
|
|
|
```
|
|
|
|
[
|
|
|
|
{
|
| ... | ... | @@ -36,28 +41,35 @@ Les **données récupérées** sont : |
|
|
|
}
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
#### `getLexiconsEntries`
|
|
|
|
Cette fonction récupère les entrées d'un lexique spécifique. Elle attend en entrée `authToken`et `lexiconId` qui est l'identifiant (`id`) du lexique dont on souhaite récupérer les entrées.
|
|
|
|
Le point de terminaison est : `api/lexicon/entries/{lexiconId}`
|
|
|
|
|
|
|
|
Cette fonction récupère les entrées d'un lexique spécifique. Elle attend en entrée `authToken`et `lexiconId` qui est l'identifiant (`id`) du lexique dont on souhaite récupérer les entrées.\
|
|
|
|
Le point de terminaison est : `api/lexicon/entries/{lexiconId}`\
|
|
|
|
La sortie attendue est un tableau d'entrées pour le lexique spécifié. Chaque entrée a un `id` et une `graphy`.
|
|
|
|
|
|
|
|
#### `getAllLexiconWords`
|
|
|
|
Cette fonction récupère toutes les graphies de l'ensemble des lexiques de l'utilisateur. Elle utilise `getLexicons` puis itère sur chaque lexique avec `getLexiconEntries` pour obtenir les entrées. Les mots sont ensuite regroupés dans un objet dont les clés sont des libellés uniques. Pour un lexique de catégorie `User`, le libellé est construit comme : `Lexique personnel (<pseudo de l'utilisateur | Inconnu>) [<id>]`. Pour la catégorie `Group`, le libellé est : `Lexique de groupe (<nom du groupe | Inconnu>) [<id>].
|
|
|
|
|
|
|
|
Cette fonction récupère toutes les graphies de l'ensemble des lexiques de l'utilisateur. Elle utilise `getLexicons` puis itère sur chaque lexique avec `getLexiconEntries` pour obtenir les entrées. Les mots sont ensuite regroupés dans un objet dont les clés sont des libellés uniques. Pour un lexique de catégorie `User`, le libellé est construit comme : `Lexique personnel (<pseudo de l'utilisateur | Inconnu>) [<id>]`. Pour la catégorie `Group`, le libellé est : \`Lexique de groupe (\<nom du groupe | Inconnu\>) \[\].
|
|
|
|
|
|
|
|
#### `getWiktionaryDefinition`
|
|
|
|
Cette fonction récupère la définition d'un mot depuis le Wiktionnaire. Le paramètre d'entrée est `word` (string). L'URL utilisée est : `https://fr.wiktionary.org/w/api.php?action=query&format=json&origin=*&prop=extracts&exintro=true&titles=<word>`
|
|
|
|
|
|
|
|
Cette fonction récupère la définition d'un mot depuis le Wiktionnaire. Le paramètre d'entrée est `word` (string). L'URL utilisée est : `https://fr.wiktionary.org/w/api.php?action=query&format=json&origin=*&prop=extracts&exintro=true&titles=<word>`\
|
|
|
|
Cette fonction a été utilisée dans une première version de l'extension mais a été remplacée par une fonction utilisant l'API de BaLex.
|
|
|
|
|
|
|
|
#### `AddWord`
|
|
|
|
Cette fonction ajoute le mot sélectionné dans un ou plusieurs lexiques.
|
|
|
|
|
|
|
|
Cette fonction ajoute le mot sélectionné dans un ou plusieurs lexiques.\
|
|
|
|
**Paramètres d'entrée** :
|
|
|
|
|
|
|
|
- `authToken`
|
|
|
|
- `selectedWord` (string)
|
|
|
|
- `lexiconIds` (tableau de nombres) : liste des identifiants des lexiques dans lesquels le mot doit être ajouté.
|
|
|
|
- `force` (boolean, optionnel, par défaut `false`) : Un flag pour forcer l’ajout. _Si `force = true`, l'entrée est créée même si le mot n'est pas trouvé dans le Wiktionnaire, mais uniquement dans le lexique des nouveaux mots_ (cf. documentation API BaLex).
|
|
|
|
|
|
|
|
**Données manipulées** :
|
|
|
|
**Données manipulées** :\
|
|
|
|
Le corps de la requête est un objet JSON constitué de :
|
|
|
|
|
|
|
|
- `graphy` : le mot à ajouter
|
|
|
|
- `force`
|
|
|
|
- `target_lex` : le tableau des identifiants des lexiques cibles
|
| ... | ... | @@ -67,28 +79,23 @@ Le point de terminaison est `api/entry/create` et la méthode est `POST`. |
|
|
|
La sortie attendue est la réponse JSON de l'API après l'ajout du mot, ou bien une exception en cas d'erreur (absence de token d'authentification, mot vide, aucun lexique sélectionné).
|
|
|
|
|
|
|
|
#### `fetchLexiconDefinitions`
|
|
|
|
Cette fonction récupère les définitions d'un mot dans les lexiques de l'utilisateur. Après avoir récupéré les lexiques, la fonction effectue une requête pour rechercher le mot dans le lexique ciblé.
|
|
|
|
Le point de terminaison utilisé est : `api/entry/search` et l'URL construite est : `api/entry/search?graphy=<word>&language=<language>&target_lex=<lex.id>`
|
|
|
|
|
|
|
|
Pour chaque entrée, elle vérifie si une propriété `Sense?.Definitions` existe, et si la propriété `Def` est présente.
|
|
|
|
Cette fonction récupère les définitions d'un mot dans les lexiques de l'utilisateur. Après avoir récupéré les lexiques, la fonction effectue une requête pour rechercher le mot dans le lexique ciblé. Le point de terminaison utilisé est : `api/entry/search` et l'URL construite est : `api/entry/search?graphy=<word>&language=<language>&target_lex=<lex.id>`
|
|
|
|
|
|
|
|
Pour chaque entrée, elle vérifie si une propriété `Sense?.Definitions` existe, et si la propriété `Def` est présente.\
|
|
|
|
La sortie attendue est un tableau d'objets : `{ source: <nom_du_lexique>, text: <texte_de_la_définition>, lexiconId: <id> }`
|
|
|
|
|
|
|
|
#### `wikiApiResponse`
|
|
|
|
|
|
|
|
Cette fonction récupère les définitions du Wiktionnaire via l'API de BaLex plutôt qu'un appel direct au Wiktionnaire (fonction `getWiktionaryDefinition` précédente). Le point de terminaison utilisé est : `api/wiktionary/search?graphy=<word>&language=fr`. Les données JSON contenant les informations brutes du mot sont retournées par l'API.
|
|
|
|
|
|
|
|
# Fonctionnalités
|
|
|
|
|
|
|
|
Ces requêtes à l'API de BaLex ont permis la mise en place des fonctionnalités suivantes :
|
|
|
|
- **Vérifier si le mot est présent dans le lexique de l'utilisateur** : `api/lexicon/search` pour récupérer les identifiants des lexiques de l'utilisateur, puis `api/lexicon/entries/{id}` où `id` est le numéro d'identifiant du lexique.
|
|
|
|
|
|
|
|
- **Vérifier si le mot est présent dans le lexique de l'utilisateur** : `api/lexicon/search` pour récupérer les identifiants des lexiques de l'utilisateur, puis `api/lexicon/entries/{id}` où `id` est le numéro d'identifiant du lexique.
|
|
|
|
- **Afficher dans quel(s) lexique(s) le mot est présent** : `api/lexicon/search` pour récupérer les lexiques de l'utilisateur, puis recherche du mot dans chaque lexique grâce à `api/entry/search?graphy=<word>&language=<language>&target_lex=<lex.id>`. La fonction `searchInLexicons` permet ensuite de construire une map des lexiques où le mot a été trouvé
|
|
|
|
|
|
|
|
- **Obtenir une définition** : Si l'utilisateur n'est pas connecté, il peut accéder à la définition issue du Wiktionnaire (sans passer par l'API de BaLex) via `https://fr.wiktionary.org/w/api.php?action=query&format=json&origin=*&prop=extracts&exintro=true&titles=${encodeURIComponent(word)}`. Si l'utilisateur est connecté, il a accès aux définitions issues de ses lexiques, et issues du Wiktionnaire via l'API de BaLex (`api/wiktionary/search?graphy=<word>&language=fr`).
|
|
|
|
|
|
|
|
- **Surlignage des mots présents dans le(s) lexique(s)** : Chaque lexique récupéré via `api/lexicon/search` est interrogé pour obtenir ses entrées contenant les mots à surligner `api/lexicon/entries/{lexiconId}`.
|
|
|
|
|
|
|
|
- **Ajout manuel d'un mot dans le(s) lexique(s) de l'utilisateur** : `api/entry/create` via la fonction `AddWord` (pour l'instant l'ajout d'un mot est disponible uniquement pour le français)
|
|
|
|
|
|
|
|
|
|
|
|
- **Ajout automatique d'un mot dans le(s) lexique(s) personnel (user) de l'utilisateur** : `api/entry/create` via la fonction `AddWord` après détection du dépassement de seuil défini (voir script `pyodide_worker.js`)
|
|
|
|
|
|
|
|
|
|
|
|
- **Ajout automatique d'un mot dans le(s) lexique(s) personnel (user) de l'utilisateur** : `api/entry/create` via la fonction `autoAddWord`après détection du dépassement de seuil défini (voir script `pyodide_worker.js`) |
|
|
\ No newline at end of file |
