Pour tout problème contactez-nous par mail : support@froggit.fr | La FAQ :grey_question: | Rejoignez-nous sur le Chat :speech_balloon:

Skip to content
Snippets Groups Projects
Commit 33bbd9fd authored by Christophe Chaudier's avatar Christophe Chaudier :rocket:
Browse files

Merge branch '73-doc-improve-a-component' into 'master'

Resolve "doc: improve a component"

Closes #73

See merge request !46
parents 7016374a 35d73087
No related branches found
No related tags found
1 merge request!46Resolve "doc: improve a component"
Pipeline #5115 canceled
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
Docusaurus étant un Framework de la librairie React, on y retrouve la même logique. Docusaurus étant un Framework de la librairie React, on y retrouve la même logique.
L'affichage d'une page web est un ensemble de composants réutilisables, que l'on peux assembler. L'affichage d'une page web est un ensemble de composants réutilisables, que l'on peut assembler.
Nous allons nous appuyer sur l'utilisation de ces Composants pour créer nos différentes sections d'affichage, notamment pour gérer le rendu visuel de la page d'accueil du site `index.js`. Nous allons nous appuyer sur l'utilisation de ces Composants pour créer nos différentes sections d'affichage, notamment pour gérer le rendu visuel de la page d'accueil du site `index.js`.
...@@ -16,12 +16,10 @@ Pour l'exemple, nous allons expliquer comment nous avons créer la section charg ...@@ -16,12 +16,10 @@ Pour l'exemple, nous allons expliquer comment nous avons créer la section charg
Dans le dossier `src/components/`, nous avons créé un fichier React `HomepageFeatures.js`. Dans le dossier `src/components/`, nous avons créé un fichier React `HomepageFeatures.js`.
Nous avons choisi de nommer notre fichier `HomepageFeatures`, en [PascalCase](https://techlib.fr/definition/pascalcase.html), car ce composent est destiné à être affiché, dans la `Homepage` (page d'Accueil) et doit afficher les `Features` (fonctionnalités) de Froggit. Nous avons choisi de nommer notre fichier `HomepageFeatures`, en [PascalCase](https://techlib.fr/definition/pascalcase.html), car ce composent est destiné à être affiché, dans la `Homepage` (page d'Accueil) et doit afficher les `Features` (fonctionnalités) de Froggit.
Ce fichier est composé de 3 parties: Ce fichier est composé de 3 parties:
- une pour gérer les données de notre section ; - une pour gérer les données de notre section ;
- une pour définir les comportements que nous attendons en utilisant différentes fonctions ; - une pour définir les comportements que nous attendons en utilisant différentes fonctions ;
- une pour définir l'affichage. Nous utilisons le JSX pour cette partie, voir l' [introduction au JSX](https://fr.reactjs.org/docs/introducing-jsx.html) sur la doc de React pour des explications sur cette extension syntaxique du JavaScript. - une pour définir l'affichage. Nous utilisons le JSX pour cette partie, voir l' [introduction au JSX](https://fr.reactjs.org/docs/introducing-jsx.html) sur la doc de React pour des explications sur cette extension syntaxique du JavaScript.
...@@ -29,6 +27,7 @@ Ce fichier est composé de 3 parties: ...@@ -29,6 +27,7 @@ Ce fichier est composé de 3 parties:
### Les données de notre section ### Les données de notre section
Nous allons créer un tableau d'objets JavaScript pour définir les données à afficher dans notre section. Il y a 3 objets pour chaque élément du tableau : Nous allons créer un tableau d'objets JavaScript pour définir les données à afficher dans notre section. Il y a 3 objets pour chaque élément du tableau :
1. Un titre, de type `chaîne de charactère` (_String_), donc entouré de guillements simples `'` ou doubles `"`). 1. Un titre, de type `chaîne de charactère` (_String_), donc entouré de guillements simples `'` ou doubles `"`).
2. Une description, que nous définissons en tant qu' `Element JSX`. Nous pouvons ainsi lui donner un _template_ de rendu comme valeur, avec les balises HTML de notre choix, juste un paragraphe dans notre cas. Pour cela, nous devons définir sa valeur entre des parenthèses et à l'intérieur d' une balise parent, pouvant être une `div`, ou comme nous utilisons ci-dessous, avec une simple balise vide. 2. Une description, que nous définissons en tant qu' `Element JSX`. Nous pouvons ainsi lui donner un _template_ de rendu comme valeur, avec les balises HTML de notre choix, juste un paragraphe dans notre cas. Pour cela, nous devons définir sa valeur entre des parenthèses et à l'intérieur d' une balise parent, pouvant être une `div`, ou comme nous utilisons ci-dessous, avec une simple balise vide.
3. Une image, que nous définissons en tant que `Composant React`, afin de simplifier la syntaxe de notre code dans les prochaines étapes notemment pour définir notre affichage. Comme cette image est un composant, nous la nommons `Svg` en PascalCase. 3. Une image, que nous définissons en tant que `Composant React`, afin de simplifier la syntaxe de notre code dans les prochaines étapes notemment pour définir notre affichage. Comme cette image est un composant, nous la nommons `Svg` en PascalCase.
...@@ -79,6 +78,94 @@ const FeatureList = [ ...@@ -79,6 +78,94 @@ const FeatureList = [
Notre section affichera les 4 éléments, chacune avec un titre, une description et une image en Svg. Notre section affichera les 4 éléments, chacune avec un titre, une description et une image en Svg.
### Les paramètres d'un composant
On peut passer des paramètres au composant grâce :
- au propriété de la balise ;
- au texte entre les balises ouvrante et fermantes.
Pour notre exemple on va créer le compostant `TextRight` avec deux paramètres :
1. une image
2. un bloc de texte
On va utiliser ce composant depuis un fichier MDX.
Le fichier `TextRight.js` se trouve dans le répertoire des composants : `src/components`. Comme on a du CSS exclusif à ce composant on crée un fichier avec la même base de nom :`TextRight.module.css`. Le `.module.css` signifie qu'il apportera des modifications uniquement au fichier `.js` pourtant le même nom, et pas les autres page du site.
#### Le composant
```jsx
// src/components/TextRight.js
import React from "react";
import styles from "./TextRight.module.css";
import useBaseUrl from '@docusaurus/useBaseUrl';
export default function TextRight({children, img}) {
return (
<>
<div className="row">
<div className="col col--6">
<img src={useBaseUrl(img)} />
</div>
<div className="col col--6">
{children}
</div>
</div>
</>
);
}
```
D'abord on fait ses imports : React, le module css, et un useBaseUrl.
On utilise `useBaseUrl` pour obtenir l'URL de base du site et pouvoir avoir renvoyer les bonnes URL au HTML sui sera généré. Voir la doc de [Docusaurus](https://docusaurus.io/fr/docs/static-assets#in-jsx).
On exporte la fonction (qui sera importée ensuite dans le fichier mdx). Cette fonction possède deux paramètres :
1. `children`, reprenant les propriétés des "parents" pour les renvoyer en sortie, c'est ce qui se trouve entre les deux balises du composant React.
2. `img` qui contient le chemin relatif de notre image depuis le répertoire` static/` et qui sera passé dans les propriété de la balise ouvrante de notre composant au moment de l'appel.
La fonction génère du HTML, se qui se trouve dans `return` :
- Des "blocks" (`div`) avec des `className` (ou des class en html).
- Pour l'image on utilise le fonction `useBaseUrl` qui renvois l'URL finale de notre `img` (en paramètre).
- Pour notre texte il est contenu dans le paramètre children.
Dans le dossier `static/` : mettre l'image en veillant à bien choisir son nom.
#### L'appel du composant
Dans le dossier `src/pages` : on à un fichier [MDX](https://docusaurus.io/fr/docs/markdown-features/react), `communaute.mdx` dans notre exemple.
Dans notre fichier MDX il faut :
- Importer la fonction `TextRight` depuis le chemin du composant.
- Utiliser le composant avec la nouvelle balise créé `<TextRight>` et `</TextRight>`
Comme par exemple :
```markdown
import TextRight from '@site/src/components/TextRight';
<TextRight img="/img/mon_image.png">
# Mon Titre
Mon texte
</TextRight>
```
### Attention au multiples CSS
⚠️ **Remarque: veiller aux erreurs dans les fichiers `custom.css` et `.module.css`.**
Nous avons constaté que si une classe reçoit des attribues dans le fichier `mon_composant.module.css` et le fichier `custom.css` alors il sera retenu en priorité ce qui se trouve dans le fichier `custom.css` qui est le fichier général de style.
Nous n'avons pas de réponse à la question :
> Est-ce que ce qui se trouve dans le fichier `mon_composant.module.css` s'ajoute à ce qui se trouve dans le fichier `custom.css` ?
### Affichage ### Affichage
...@@ -118,10 +205,9 @@ Ainsi, notre composant va renvoyer notre Svg en image, le titre en `h3` et la de ...@@ -118,10 +205,9 @@ Ainsi, notre composant va renvoyer notre Svg en image, le titre en `h3` et la de
Nous devons également importer certains utilitaires, selon nos besoins (la librairie React, les modules CSS), puis exporter notre composant, pour qu'il puisse être réutilisé. Nous devons également importer certains utilitaires, selon nos besoins (la librairie React, les modules CSS), puis exporter notre composant, pour qu'il puisse être réutilisé.
Il est nécessaire d'utiliser le système d'import/export de [modules JavaScript](https://javascript.info/import-export). Il est nécessaire d'utiliser le système d'import/export de [modules JavaScript](https://javascript.info/import-export).
### Définition des Comportements
### Définition des Comportements Nous itérons sur chaque élément de notre tableau, en utilisant la méthode JavaScript `.map`, qui est très souvent utilisé dans les Composants React.
Nous itérons sur chaque élément de notre tableau, en utilisant la méthode JavaScript `.map`, qui est très souvent utilisé dans les Composants React.
La méthode map() crée un nouveau tableau avec les résultats de chaque élément du tableau. [Voici un tutoriel expliquant cette méthode](https://www.freecodecamp.org/news/javascript-map-how-to-use-the-js-map-function-array-method/). La méthode map() crée un nouveau tableau avec les résultats de chaque élément du tableau. [Voici un tutoriel expliquant cette méthode](https://www.freecodecamp.org/news/javascript-map-how-to-use-the-js-map-function-array-method/).
...@@ -172,11 +258,12 @@ export default function Home() { ...@@ -172,11 +258,12 @@ export default function Home() {
} }
``` ```
Entre nos balises `Layout`, nous retrouvons 3 composants enfants, d'abord l'entête (_header_) nommé <HomepageHeader /> qui a été créé à l'intérieur même de ce composant. Entre nos balises `Layout`, nous retrouvons 3 composants enfants, d'abord l'entête (_header_) nommé `<HomepageHeader />` qui a été créé à l'intérieur même de ce composant.
Puis nous retrouvons 2 Composants, qui ont été importé depuis le dossier `src/components/`:
Puis nous retrouvons 2 Composants, qui ont été importé depuis le dossier `src/components/`: 1. `<HomepagePromises />` pour la section des promesses
1. <HomepagePromises />, pour la section des promesses 2. `<HomepageFeatures />` pour la section des fonctionnalités
2. <HomepageFeatures />, pour la section des fonctionnalités
## Feuille de style CSS ## Feuille de style CSS
......
...@@ -13,3 +13,35 @@ html[data-theme='dark'] .menu__link { ...@@ -13,3 +13,35 @@ html[data-theme='dark'] .menu__link {
``` ```
Pour les couleurs, **Infima** utilise un nuancier sur [Colorbox](https://colorbox.io/). Pour les couleurs, **Infima** utilise un nuancier sur [Colorbox](https://colorbox.io/).
## Le Swizzling
Docusaurus propose une méthode pour personnaliser le thème : c'est le [Swizzling](https://docusaurus.io/fr/docs/swizzling).
On échange un composant de thème généré par Docusaurus, par le notre.
Il en existe deux types :
1. **Éjection** : créer une copie du composant de thème à personnaliser.
2. **Enveloppement** : on améliorer le composant de thème existant.
### Éjection
**Pour procéder à l'éjection, on lance dans son terminal la commande suivante :**
```sh
npm run swizzle [nom du thème] [nom du composant] -- --eject
```
### Enveloppement
**Pour l'enveloppement, procéder comme suit :**
```sh
npm run swizzle [theme name] [component name] -- --wrap
```
En exemple, de notre Footer :
En lançant la commande de l'enveloppement, il nous crée le répertoire `theme/Footer`.
Le fichier `index.js` s'y trouvant est notre nouveau Footer.
Nous avons enveloppé notre Footer avec de nouveaux éléments.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment