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

Resolve "doc: improve a component"

Merged Julie Thezenas requested to merge 73-doc-improve-a-component into master
Files
2
+ 58
35
@@ -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`.
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:
- 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 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:
### 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 :
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.
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,17 +78,26 @@ const FeatureList = [
Notre section affichera les 4 éléments, chacune avec un titre, une description et une image en Svg.
### Ajouter une image dans un fichier MDX, et la passer en paramètre dans un composant.js
### Les paramètres d'un composant
#### Afin d'utiliser une image.png ou une image.jpg dans un fichier MDX, procéder comme suit :
On peut passer des paramètres au composant grâce :
- Dans le **dossier src/static/img** : mettre l'image en veillant à bien choisir son nom.
- au propriété de la balise ;
- au texte entre les balises ouvrante et fermantes.
- Dans le **dossier src/components** : créer un fichier **TextRight.js** et son css du même nom comme **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).
Pour notre exemple on va créer le compostant `TextRight` avec deux paramètres :
À présent, penchant nous un instant sur le **composant** :
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';
@@ -108,41 +116,56 @@ export default function TextRight({children, img}) {
</>
);
}
```
D'abord on fait ses imports : React, le module css, et un useBaseUrl.
On utilise **useBaseUrl** pour résoudre des problèmes liés à ce que le navigateur interprète. Cet import permettra d'éviter les erreurs de chemin lors de l'import d'images. Voir https://docusaurus.io/fr/docs/static-assets section ***Référencement de votre ressource static en JSX.***
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 : **children**, reprenant les propriétés des "parents" pour les renvoyer en sortie, et **img** notre image. Ce qui sera afficher se trouve dans **return** :
On exporte la fonction (qui sera importée ensuite dans le fichier mdx). Cette fonction possède deux paramètres :
- Des "blocks" (div) avec des className (ou des class en html).
- Pour imbriquer l'image, on modifie la source avec notre ***useBaseUrl*** contenant notre img en paramètre.
- Pour imbriquer notre texte, elle se récupére par le paramètre children.
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.
#### Dans le dossier src/pages : créer sa nouvelle_page.mdx
La fonction génère du HTML, se qui se trouve dans `return` :
**Importer la fonction *TextRight* et le chemin du composant.**
- 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.
**Inclure l'image et son chemin :**
Dans le dossier `static/` : mettre l'image en veillant à bien choisir son nom.
- En haut du fichier mdx, on importe la fonction ***TextRight*** ainsi que son chemin :
#### 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';
```
- Puis on dispose l'image selon sa convenance dans le fichier mdx :
```
<TextRight img="/img/cheatsheet_cover.png">
<TextRight img="/img/mon_image.png">
# Mon Titre
Mon texte
</TextRight>
```
On lui dit alors : l'image qu'on passe en paramètre et faisant référence à TextRight EST img cheatsheet.
***Remarque: veiller aux erreurs dans les fichiers custom.css et .module.css.***
Il a été vu que si par exemple une class button reçoit des attribus dans le fichier.module.css, et que le fichier custom.css possède lui aussi des modification dans ce même class button, il sera retenu en priorité ce qui se trouve dans le fichier custom.css (le fichier général de style).
À ce jour, nous nous questionnons : est-ce que ce qui se trouve dans la class button du fichier.module.css se retrouvera AJOUTÉ dans la class button du fichier custom.css ?
Ou bien est-ce que class button du fichier.module.css sera simplement abandonné ? À confirmer.
### 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
@@ -182,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é.
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/).
@@ -236,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
2. <HomepageFeatures />, pour la section des fonctionnalités
1. `<HomepagePromises />` pour la section des promesses
2. `<HomepageFeatures />` pour la section des fonctionnalités
## Feuille de style CSS
Loading