Commit c06deaa4 authored by Laurent Lecluse's avatar Laurent Lecluse
Browse files

doc

parent 1e0c5d52
Loading
Loading
Loading
Loading
Loading

doc/client.md

0 → 100644
+87 −0
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 "/".

    const url1 = unicaenVue.url('exemple/test');
    // affiche /exemple/test
    console.log(url1);

    const url2 = unicaenVue.url('exemple/test/:monId', {monId: 50});
    // affiche /exemple/test/50
    console.log(url2);

    const url3 = unicaenVue.url('exemple/test', {}, {monId: 50});
    // affiche /exemple/test?monId=50
    console.log(url3);

    const url4 = unicaenVue.url('exemple/test/:monId', {monId: 50}, {monCode: 'cinquante'});
    // affiche /exemple/test/50?monCode=cinquante
    console.log(url4);

})
```


## Axios

UnicaenVue fournit une instance personnalisée d'Axios.
Axios permet de faire de la communication Ajax entre le serveur et le navigateur.
Il peut être utilsé depuis des composants Vue, mai aussi ailleurs dans l'application.

UnicaenVue propose un Axios augmenté des possibilités suivantes :

- Une partie serveur d'Axios, intégrée au mode de fonctionnement de Laminas permettant de
  - traiter des données pour envoi au client avec un système d'extraction présenté ci-dessous
  - récupérer les messages du flashMessenger pour les exposer au client.

- Une partie client qui ajoute à l'existant la récupération des messages du flashMessenger envoyés par le serveur
  et les afficher sur la page sous formes d'alertes.

Pour le reste, [l'usage standard d'Axios](https://axios-http.com/fr/docs/intro) reste de mise

L'instance d'Axios est récupérable en appelant `unicaenVue.axios`.


Voici un exemple d'utilisation d'axios:

```javascript

unicaenVue.axios.get(
    // on construit l'Url nécessaire pour intérroger le serveur
    unicaenVue.url("exemple/test-data/:monId", {monId: this.monId})
).then(response => {
    // response.data contient les données
    console.log(response.data);
});
```

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.
+18 −0
Changes for doc/doc.md: 18 added lines, 0 removed lines.
Original line number Diff line number Diff line
# Documentation du module Unicaen/Vue

[Procédure d'installation](install.md)

[Premier tuto](tuto1.md)

[Partie client Javascript](client.md)

[Partie serveur PHP](serveur.md)

Pour aller plus loin :

- [Doc d'introduction à VueJS de Stéphane](https://git.unicaen.fr/bouvry/presentation-dev/-/blob/master/src/vuejs.md)

Sites officiels :

- [Vue.js](https://vuejs.org/)
- [Vite](https://vitejs.dev)
- [BootstrapVue](https://bootstrap-vue.org/)
- [Axios](https://axios-http.com/)
 No newline at end of file
+1 −0
Changes for doc/install.md: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -50,6 +50,7 @@ Voici un exemple complet de fichier package.json :

Lancez `npx npm update` depuis le répertoire racine de votre application.


## 3. Vite

Un fichier de configuration pour Vite est également à ajouter dans le répertoire racine du projet, dans le fichier `vite.config.js`.

doc/serveur.md

0 → 100644
+369 −0
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

Dans un contrôleur :

// On utilise VueModel 
use UnicaenVue\View\Model\VueModel;
...

    // Action qui va charger le composant MonTest
    public function testAction()
    {
        $data = [
            'monId' => 50,
        ];

        // On crée un VueModel et on lui transmet des données par défaut
        $vm = new VueModel($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
use UnicaenVue\View\Model\AxiosModel;
...

    // exemple d'une action de contrôleur renvoyant des données au client suite à une requête Axios
    public function testDataAction(){
        // 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
        return new AxiosModel($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.

```php
$data = 15;
$extracted = \UnicaenVue\Axios\AxiosExtractor::extract($data);
var_dump($extracted); // => int 15
// idem pour string, bool, float
```

Pour les dates, les données de type \DateTime sont converties en chaînes de caractère au standard ISO 8601 ('Y-m-d\TH:i:s.u\Z') préconisé pour HTML5.

```php
$data = new \DateTime();
$extracted = \UnicaenVue\Axios\AxiosExtractor::extract($data);
var_dump($extracted); // => string '2023-03-29T15:58:19.368432Z'
```

### Tableaux

Les tableaux PHP sont également gérés et transformés en objets JSON (`{k1: 'v1', k2: 'v2'}`) ou en listes JSON `['v1','v2']`.
Ils sont parcourus de manière récursive et ne doivent bien entendu pas intégrer de données ayant des types non gérables.

côté PHP :
```php
$data = [
    'nom' => 'Dupont',
    'prenom' => 'Robert',
    'adresse' => [
        'numéro' => 1,
        'rue' => 'Allée des mésanges',
        'cp' => 14000,
        'ville' => 'Caen',
        'france' => true,
    ],
];
$extracted = \UnicaenVue\Axios\AxiosExtractor::extract($data);
var_dump($extracted); // $extracted = $data
```
côté JS :
```javascript
    const result = <?= json_encode($extracted) ?>;
    console.log(result);
    /* renvoie (idem dans response.data d'Axios) :
    { 
        nom: "Dupont", 
        prenom: "Robert", 
        adresse: {
            cp: 14000
            france: true
            "numéro": 1
            rue: "Allée des mésanges"
            ville: "Caen"
        } 
    }
    
    */
})
```

### Entités & objets

Les Entités ou autres objets portant des données sont également gérables. Leur extraction est, contrairement aux types simples, paramétrable.

Prenons les deux entités suivantes en exemple :

```php
class Adresse {
    protected int $numero = 1;
    protected string $rue = 'Allée des mésanges';
    protected int $cp = 14000;
    protected string $ville = 'Caen';

    public function getNumero(): int
    {
        return $this->numero;
    }

    public function getRue(): string
    {
        return $this->rue;
    }

    public function getCp(): int
    {
        return $this->cp;
    }

    public function getVille(): string
    {
        return $this->ville;
    }


}

class Personne
{
    protected string $nom = 'Dupont';
    protected string $prenom = 'Robert';
    protected int $age = 42;
    protected Adresse $adresse;

    public function __construct()
    {
        $this->adresse = new Adresse();
    }

    public function getNom(): string
    {
        return $this->nom;
    }

    public function getPrenom(): string
    {
        return $this->prenom;
    }

    public function getAge(): int
    {
        return $this->age;
    }

    public function getAdresse(): Adresse
    {
        return $this->adresse;
    }

    public function isMajeur(): bool
    {
        return $this->age >= 18;
    }
}

$personne = new Personne;
```

#### Extraction avec des propriétées données explicitement

Et voici une première extraction de données :

On précise ici les données à exporter en listant les propriétés concernées.

```php
$personne = new Personne();

$properties = ['nom', 'prenom', 'isMajeur', ['adresse', ['cp', 'ville']]];
$extracted = \UnicaenVue\Axios\AxiosExtractor::extract($personne,$properties);
var_dump($extracted);
// Renvoie :
// array (size=4)
//  'nom' => string 'Dupont' (length=6)
//  'prenom' => string 'Robert' (length=6)
//  'isMajeur' => boolean true
//  'adresse' => array (size=2)
//      'cp' => int 14000
//      'ville' => string 'Caen' (length=4)
```

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 :

```php
class Adresse implements \UnicaenVue\Axios\AxiosExtractorInterface
{
   ...

    public function axiosDefinition(): array
    {
        // par défaut, les extractions de Adresse auront donc les deux propriétés co et ville
        return ['cp', 'ville'];
    }
}
```

Et toujours en reprenant l'exemple ci-dessus, avec cette modification, le code suivant fonctionnera :

```php
$personne = new Personne();

$properties = ['nom', 'prenom', 'isMajeur', 'adresse'];
$extracted = \UnicaenVue\Axios\AxiosExtractor::extract($personne,$properties);
var_dump($extracted);
// Renvoie :
// array (size=4)
//  'nom' => string 'Dupont' (length=6)
//  'prenom' => string 'Robert' (length=6)
//  'isMajeur' => boolean true
//  'adresse' => array (size=2)
//      'cp' => int 14000
//      'ville' => string 'Caen' (length=4)
```

### Depuis Doctrine

@todo
 No newline at end of file
+3 −1
Changes for doc/tuto1.md: 3 added lines, 1 removed line.
Original line number Diff line number Diff line
@@ -14,6 +14,7 @@ use UnicaenVue\View\Model\VueModel;
...

    // Action qui va charger le composant MonTest
    // route exemple/test à ajouter à votre config
    public function testAction()
    {
        $data = [
@@ -35,6 +36,7 @@ use UnicaenVue\View\Model\VueModel;


    // Action qui envoie des données au composant
    // route exemple/test-data/:monId à ajouter à votre config
    public function testDataAction()
    {
        $monId = $this->params()->fromRoute('monId');
@@ -100,7 +102,7 @@ export default {
        // on utilise l'axios adapté d'UnicaenVue
        unicaenVue.axios.get(
            // unicaenVue.url permet de créer une URL à partir d'une route et de paramètres d'URL
            unicaenVue.url("mission/test-data/:monId", {monId: this.monId})
            unicaenVue.url("exemple/test-data/:monId", {monId: this.monId})
        ).then(response => {
            // response.data contient les données, on met à jour les contacts avec...
            this.contacts = response.data;
Loading