Changes for doc/client.md: 87 added lines, 0 removed lines.
Original line number
Diff line number
Diff line
# Partie client en Javascript
UnicaenVue dispose d'un module Javascript conçu pour être utilisé sur la partie front des applications.
Il est accessible depuis un composant Vue aussi bien que depuis n'importe quel autre script Javascript sans avoir à utiliser `import` : il est préchargé et directement utilisable.
Pour y accéder, il suffit d'utiliser `window.unicaenVue` ou tout simplement `unicaenVue`.
Ce module propose deux choses pour le moment :
- une méthode url
- une instance augmentée d'Axios
## Gestion des Urls
Il est souvent nécessaire de devoir construire des URLs avec des paramètres de route et/ou des paramètres GET.
La méthode `unicenVue.url` fonctionne de la même manière que l'aide de vue url de Laminas : elle prend une route
en premier paramètre, un objet de paramètres en tant que paramètres de routes, puis éventuellement un second objet de paramètres pour le GET.
A partir de ça, elle va construire une URL sur le modèle suivant :
URL = page Home de l'application + route avec remplacement des variables par les paramètres de route + ? + paramètres GET (s'il y en a)
En voici quelques exemples d'utilisation :
```javascript
$(()=>{
// Dans ces exemple, la page home sera sur /
// Dans les routes transmises, il ne faut du coup jamais commenter par "/".
Lorsqu'il reçoit une réponse du serveur, si cette dernière comporte des messages issus du flashMessenger, il va les afficher sous formes d'alertes.
Les alertes sont personnalisées selon qu'il s'agit de success, warning, info ou error. Elles sont affichées pendant 5 secondes, sauf les erreurs qu'il faut fermer
manuellement afin d'avoir le temps de lire le message et de le traiter.
Changes for doc/serveur.md: 369 added lines, 0 removed lines.
Original line number
Diff line number
Diff line
# Utiliser UnicaenVue depuis le serveur en PHP
## Instancier un composant Vue depuis une action de contrôleur
Depuis une action de contrôleur, vous pouvez renvoyer directement un `VueModel`, qui va se charger
d'instancier un composant Vue directement sans avoir à passer par une `view` en PHP.
Le fonctionnement est très proche du `ViewModel` de Laminas, à ceci près que :
- Les variables transmises sont converties en JSON pour être passées au client. Il est donc impossible de passer un service ou autre.
Vous pouvez passer en revanche des entités ou des tableaux, des variables telles que des entiers, flotants, chaines, dates (`\DateTime`).
La convertion en Json se fait à l'aide de l'[AxiosExtractor](#axiosextractor). Pour avoir la liste précise des types des données gérés rendez-vous [ci-dessous](#axiosextractor), donc.
- Le template fourni est en fait un chemin pointant vers un composant Vue. La syntaxe est très proche de celle des templates utilisés pour
les `view` : `chemin/vers/le/composant/nom-du-composant`, en kebab-case donc!
Exemple pour un composant `MonTest` dont le fichier est placé dans `front/Exemple/MonTest.vue` : `exemple/mon-test`
Exemple :
```php
Dansuncontrôleur:
// On utilise VueModel
useUnicaenVue\View\Model\VueModel;
...
// Action qui va charger le composant MonTest
publicfunctiontestAction()
{
$data=[
'monId'=>50,
];
// On crée un VueModel et on lui transmet des données par défaut
$vm=newVueModel($data);
// On lui donne un template, c'est-à-dire le chemin et le nom du composant à utiliser
// Le composant s'appelle MonTest se trouvera dans le fichier front/Exemple/MonTest.vue
// Notez qu'on utilise par convention une syntaxe kebab-case pour le template et CamelCase pour les répertoires, & noms de composants Vue.
$vm->setTemplate('exemple/mon-test');
// On retourne le VueModel
return$vm;
}
...
```
## Instancier un composant Vue depuis une vue
Lorsque c'est nécessaire, il est aussi possible d'intégrer un composant Vue à une `view` existante.
L'aide de vue `vue` est là pour ça.
En voici un exemple :
```php
// instancie le composant Liste placé dans le fichier front/Mission/Liste.vue
echo$this->vue('mission/liste',[
// on lui passe un entier en ID, ce qui va permettre de récupérer l'ensemble des données de l'intervenant plus tard gràce à Axios
'intervenant'=>$intervenant->getId(),
// Et on lui transmet aussi un booleen
'canAddMission'=>$canAddMission,
]);
```
Autre exemple, si vous voulez afficher plusieurs composants Vue d'affilée :
```php
// on démarre une vue-app
echo$this->vue()->begin();
// affichage des composants
echo$this->vue()->component('monPremierComposant',[/* tableau de propriétés */]);
echo$this->vue()->component('monSecondComposant',[/* tableau de propriétés */]);
// on termine la vue-app
echo$this->vue()->end();
```
## Utilisation d'Axios
### Récupération de données en POST
Lorsqu'au niveau du client on lance `axios.post` les données ne sont pas récupérables avec le plugin de contrôleur `params`,
car Axios encode les données en `application/x-www-form-urlencoded`.
Un plugin de contrôleur spécifique nommé... `axios` a donc été mis en place.
Avec Axios, donc, plutôt que
```php
$inputData=$this->params()->fromPost();
```
utilisez à la place
```php
$inputData=$this->axios()->fromPost();
```
### Envoi de données via Axios
Les données renvoyées doivent être encalsupées dans un `AxiosModel`.
Ce dernier va :
- utiliser [AxiosExtractor](#axiosextractor) pour convertir les données
- collecter les éventuels messages issus du `flashMessenger`
- convertir le tout en Json pour envoi au client
Voici un exemple d'action de contrôleur qui envoie des données au client en mode Ajax vers Axios :
```php
useUnicaenVue\View\Model\AxiosModel;
...
// exemple d'une action de contrôleur renvoyant des données au client suite à une requête Axios
publicfunctiontestDataAction(){
// on récupère les données sur la base de l'ID récupéré
$contacts=[
50=>[
['nom'=>'monNom','prenom'=>'monPrenom'],
['nom'=>'monNom2','prenom'=>'monPrenom2'],
['nom'=>'monNom3','prenom'=>'monPrenom3'],
],
];
// Petit msg d'info
$this->flashMessenger()->addSuccessMessage('Tout va bien!');
// Et on retourne un AxiosModel qui présente le tout au client
returnnewAxiosModel($contacts[$monId]);
// Si on exporte un objet ou un tableau d'objets, on peut aussi fournir une lisye de propriétés, cf. ExiosExtractor
// $proprietes = [/* liste des propriétés à exporter */];
// => return new AxiosModel($monObjet, $proprietes);
}
```
## AxiosExtractor
L'AxiosExtractor est chargé de convertir des données en PHP issues du serveur afin de pouvoir les réexploiter sur le client, en Javascript.
Il n'a pas besoin d'être appelé explicitement, hors cas d'usage spécifique.
Il est appelé en arrière-plan lorsque vous retournez un `AxiosModel`, un `VueModel` ou faites appel à l'aide de vue `vue`.
Au besoin, il faudra appeler la méthode globale `\UnicaenVue\Axios\AxiosExtractor::extract`.
### Types simples
Il peut gérer les types de données simples et des types plus complexes comme les entités ou même des `query` Doctrine.
En revanche, il ne sera pas en mesure de traiter des services ou autres objets non utilisables hors du contexte serveur.
Les types de données simples sont supportés, et une fois récupérés sur le client, le typage est préservé c'est-à-dire qu'un entier reste un entier, un boolean reste un booléen, etc.
Les propriétés doivent avoir des accesseurs, par exemple pour la propriété age, l'entité doit avoir une fonction parmis les suivantes :
- age()
- getAge()
- isAge()
- hasAge()
Pour l'adresse, comme il s'agit d'une entité, on doit fournir un tableau ayany deux valeurs : `['nom de la propriété', [...liste des propriétés de la sous-entité]]`.
#### Extraction sur un objet implémentant AxiosExtractorInterface
Si des propriétés sont explicitement transmises en second paramètre d'extract, alors elles sont utilisées en priorité.
A défaut, AxiosExtractor peut extraire la liste des propriétés si les objets implémentent UnicaenVue\Axios\AxiosExtractorInterface
Cela peut être utile pour des objets dont nous avons toujours besoin de renvoyer les mêmes propriétés.
A l'exemple ci-dessus, on ajoute à la classe Adresse :