first commit:
- we have a static astro website under /website. It has the implementation docs of the homepage/gaufre templates, and it handles the few API endpoints (the gaufre js, backgrounds, logos) - we have a vite app under /packages/integration. It has the react components generating the homepage and the gaufre button, and their css. Its used to generate an npm package
This commit is contained in:
Emmanuel Pelletier
6
website/src/content/config.ts
Normal file
6
website/src/content/config.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
import { defineCollection } from "astro:content"
|
||||
import { docsSchema } from "@astrojs/starlight/schema"
|
||||
|
||||
export const collections = {
|
||||
docs: defineCollection({ schema: docsSchema() }),
|
||||
}
|
||||
103
website/src/content/docs/guides/gaufre.mdx
Normal file
103
website/src/content/docs/guides/gaufre.mdx
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: La Gaufre
|
||||
sidebar:
|
||||
order: 30
|
||||
---
|
||||
|
||||
import { Aside } from "@astrojs/starlight/components"
|
||||
import assetGaufre from "./gaufre.png"
|
||||
import { Code } from "@astrojs/starlight/components"
|
||||
import gaufreHtml from "@gouvfr-lasuite/integration/dist/html/gaufre.html?raw"
|
||||
|
||||
|
||||
|
||||
Le bouton "Gaufre" est un élément d'interface commun à tous les services de La Suite numérique. Il
|
||||
permet aux internautes de facilement passer d'un service de La Suite à un autre.
|
||||
|
||||
Pour intégrer la Gaufre, il y a trois étapes :
|
||||
|
||||
- intégrer le HTML du bouton
|
||||
- ajouter le fichier CSS nécessaire
|
||||
- ajouter le fichier JS chargeant le widget au clic du bouton
|
||||
|
||||
:::note
|
||||
|
||||
Ce guide est à suivre pour intégrer la Gaufre sur toute page autre que
|
||||
[votre page d'accueil](../homepage). Le gabarit de page d'accueil inclut déjà le bouton.
|
||||
|
||||
:::
|
||||
|
||||
## Règles d'utilisation
|
||||
|
||||
Le bouton Gaufre est destiné à être présent dans le coin supérieur droit de la page de votre page
|
||||
web afin d'être toujours placé au même endroit quelque soit le service.
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. HTML
|
||||
|
||||
#### Avec React
|
||||
|
||||
Si vous utilisez React, utilisez le composant `Gaufre` fourni par le paquet :
|
||||
|
||||
```jsx
|
||||
import { Gaufre } from "@gouvfr-lasuite/integration"
|
||||
|
||||
function MonComposant() {
|
||||
return <Gaufre />
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
Même en utilisant React, vous devrez charger le CSS et le JS manuellement. Ce petit travail
|
||||
supplémentaire est fait pour vous donner plus de contrôle sur le chargement des assets suivant votre
|
||||
stack technique.
|
||||
|
||||
:::
|
||||
|
||||
#### Sans React
|
||||
|
||||
Si vous n'utilisez pas React, utilisez le HTML présent dans le paquet :
|
||||
|
||||
<Code code={gaufreHtml} lang="html" title="@gouvfr-lasuite/integration/dist/html/gaufre.html" />
|
||||
|
||||
### 2. CSS
|
||||
|
||||
Le CSS nécessaire est présent dans `@gouvfr-lasuite/integration/dist/css/gaufre.css`. Il est à
|
||||
inclure dans votre projet comme n'importe quel fichier CSS.
|
||||
|
||||
Suivant votre stack technique, vous pouvez peut-être inclure directement le CSS depuis les
|
||||
dépendances. Par exemple avec _vite_ :
|
||||
|
||||
<Code
|
||||
code={`@import "@gouvfr-lasuite/integration/dist/css/gaufre.css";`}
|
||||
lang="css"
|
||||
title="vos/styles/globaux/app.css"
|
||||
/>
|
||||
|
||||
Si vous n'utilisez pas de _bundler_ particulier et que avez plutôt décidé à l'installation de
|
||||
[copier les assets](/guides/getting-started/#gestion-des-assets), vous pouvez inclure le CSS
|
||||
directement via une balise `link` comme tout fichier CSS.
|
||||
|
||||
### 3. JS
|
||||
|
||||
Après avoir ajouté le bouton, il est nécessaire de le faire fonctionner. Pour ça, chargez ce fichier
|
||||
JS externe qui s'occupe d'afficher le widget au clic du bouton. Vous pouvez ajouter ce code dans
|
||||
votre `<head>` :
|
||||
|
||||
<Code
|
||||
code={`<script id="lasuite-gaufre-script" async defer src="${import.meta.env.PUBLIC_LASUITE_API_URL}/api/v1/gaufre.js"></script>`}
|
||||
lang="html"
|
||||
/>
|
||||
|
||||
:::note
|
||||
|
||||
Pour que le script fonctionne il est nécessaire qu'il ait un id `lasuite-gaufre-script`. Ne
|
||||
l'enlevez pas en copiant l'exemple !
|
||||
|
||||
:::
|
||||
|
||||
## Exemple
|
||||
|
||||
[La Gaufre : exemple HTML](/examples/gaufre/html).
|
||||
BIN
website/src/content/docs/guides/gaufre.png
Normal file
BIN
website/src/content/docs/guides/gaufre.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
103
website/src/content/docs/guides/getting-started.mdx
Normal file
103
website/src/content/docs/guides/getting-started.mdx
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: Démarrer
|
||||
sidebar:
|
||||
order: 0
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from "@astrojs/starlight/components"
|
||||
|
||||
Utilisez les composants d'interface prêt-à-l'emploi pour votre service de La Suite numérique.
|
||||
|
||||
## Présentation
|
||||
|
||||
Nous mettons à disposition plusieurs composants.
|
||||
|
||||
### Gabarit de page d'accueil
|
||||
|
||||
|
||||
|
||||
Le gabarit de page d'accueil permet de rapidement intégrer dans le code de votre service une page
|
||||
d'accueil suivant un visuel commun avec tous les autres services de La Suite.
|
||||
|
||||
### _La Gaufre_, le bouton des services
|
||||
|
||||
|
||||
|
||||
Le bouton de La Suite numérique permet aux internautes de facilement passer d'un service de La Suite
|
||||
à un autre.
|
||||
|
||||
Tous ces éléments sont disponibles via :
|
||||
|
||||
- des gabarits HTML, utilisables au choix via des **composants React** ou directement via des
|
||||
**fichiers .html**,
|
||||
- **du CSS** nécessaire à afficher correctement les gabarits HTML,
|
||||
- et une **API web** exposant plusieurs _endpoints_.
|
||||
|
||||
## Installation
|
||||
|
||||
### Via NPM
|
||||
|
||||
Le plus simple pour accéder au code est d'installer le paquet npm avec votre gestionnaire de paquets
|
||||
préféré :
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="npm">
|
||||
|
||||
```sh
|
||||
npm install @gouvfr-lasuite/integration
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Yarn">
|
||||
|
||||
```sh
|
||||
yarn add @gouvfr-lasuite/integration
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
|
||||
```sh
|
||||
pnpm add @gouvfr-lasuite/integration
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Manuellement
|
||||
|
||||
À la place d'utiliser npm, vous pouvez télécharger directement les fichiers depuis le dépôt sur
|
||||
GitHub :
|
||||
|
||||
@TODO
|
||||
|
||||
### Gestion des assets
|
||||
|
||||
Quand vous voudrez utiliser les assets fournis par le paquet, vous aurez peut-être besoin de copier
|
||||
les assets dans un dossier accessible par votre serveur web, suivant votre stack technique.
|
||||
|
||||
Tous les fichiers exposés par le paquet npm sont dans son dossier `dist/`.
|
||||
|
||||
Si vous utilisez déjà _webpack_, _vite_ ou alternative, vous pourrez importer les fichiers CSS
|
||||
directement depuis votre code comme tout autre CSS venant des dépendances. Par exemple avec _vite_ :
|
||||
|
||||
```js
|
||||
// dans un fichier JS :
|
||||
import '@gouvfr-lasuite/integration/dist/gaufre.css';
|
||||
// ou dans un fichier CSS :
|
||||
@import "@gouvfr-lasuite/integration/dist/gaufre.css";
|
||||
```
|
||||
|
||||
Si vous n'utilisez pas de bundler, une façon simple de rendre accessible le code du paquet est
|
||||
d'avoir un script qui copie pour vous les fichiers nécessaires dans un dossier accessible par votre
|
||||
serveur web. Par exemple, rajouter ceci dans votre `package.json` copiera les fichiers du paquet
|
||||
dans un dossier `public/@gouvfr-lasuite/integration` après chaque installation :
|
||||
|
||||
```diff lang="json"
|
||||
"scripts": {
|
||||
+ "copy-lasuite-assets": "cp -r node_modules/@gouvfr-lasuite/integration/dist/ public/@gouvfr-lasuite/integration",
|
||||
+ "postinstall": "npm run copy-lasuite-assets"
|
||||
}
|
||||
```
|
||||
|
||||
Une fois les fichiers installés, vous êtes prêt à utiliser les composants fournis par le paquet !
|
||||
29
website/src/content/docs/guides/homepage-generator.mdx
Normal file
29
website/src/content/docs/guides/homepage-generator.mdx
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Générateur de page d'accueil
|
||||
sidebar:
|
||||
order: 20
|
||||
---
|
||||
|
||||
import HomepageGenerator from "@/components/HomepageGenerator.tsx"
|
||||
|
||||
Après avoir [installé le JS et le CSS nécessaires de la page d'accueil](../homepage), vous pouvez
|
||||
utiliser ce formulaire pour générer facilement la partie HTML.
|
||||
|
||||
Séléctionnez votre service dans la liste pour automatiquement générer le template prévu. Vous pouvez
|
||||
aussi générer un template sans service pré-défini si besoin.
|
||||
|
||||
:::caution
|
||||
|
||||
Dans les exemples fournis, toutes les parties marquées <code>\~\~replace\~\~</code> sont à remplacer
|
||||
avec vos données !
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
Le logo à afficher en entête peut être récupéré dans le dossier `dist/logos` du paquet npm si
|
||||
besoin.
|
||||
|
||||
:::
|
||||
|
||||
<HomepageGenerator client:load />
|
||||
159
website/src/content/docs/guides/homepage.mdx
Normal file
159
website/src/content/docs/guides/homepage.mdx
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Gabarit de page d'accueil
|
||||
sidebar:
|
||||
order: 10
|
||||
---
|
||||
|
||||
import { Image } from "astro:assets"
|
||||
import { Code, Tabs, TabItem } from "@astrojs/starlight/components"
|
||||
import assetHomepage from "./homepage.png"
|
||||
import homepageHtml from "@gouvfr-lasuite/integration/dist/html/homepage.html?raw"
|
||||
|
||||
<p>
|
||||
<a href={assetHomepage.src} target="_blank">
|
||||
<Image
|
||||
src={assetHomepage}
|
||||
alt="Voir le gabarit de page d'accueil en grand (nouvelle fenêtre)"
|
||||
/>
|
||||
</a>
|
||||
</p>
|
||||
|
||||
Le gabarit de page d'accueil vous permet de rapidement intégrer dans le code de votre service une
|
||||
page d'accueil suivant un visuel commun avec tous les autres services de La Suite.
|
||||
|
||||
## Règles d'utilisation
|
||||
|
||||
Le gabarit de page d'accueil est un guide à utiliser pour intégrer votre page d'accueil de service.
|
||||
Si pour des raisons techniques quelconques vous ne pouvez pas reprendre les templates proposés à la
|
||||
lettre, voici les points importants à retenir :
|
||||
|
||||
- la page d'accueil doit contenir [le bouton Gaufre](../gaufre) dans son coin supérieur droit,
|
||||
- elle doit présenter le nom de votre service à travers une phrase d'accroche suivant un minimum le
|
||||
visuel proposé,
|
||||
- elle doit permettre à l'utilisateur de se connecter à votre application,
|
||||
- elle doit afficher en fond de page
|
||||
[une des photos communes de La Suite](/reference/api#background)
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. CSS
|
||||
|
||||
Le gabarit se base sur une partie du [DSFR](https://www.systeme-de-design.gouv.fr/). Suivant que
|
||||
vous l'utilisiez déjà ou non dans votre projet, un fichier CSS différent est à charger.
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Vous n'utilisez pas le DSFR">
|
||||
Le fichier CSS à utiliser est :
|
||||
|
||||
```
|
||||
@gouvfr-lasuite/integration/dist/css/homepage-gaufre-dsfr.css
|
||||
```
|
||||
|
||||
Si durant l'installation vous avez décidé de
|
||||
[copier les assets](../getting-started/#gestion-des-assets), assurez-vous que la police de
|
||||
caractères Marianne a bien été copiée en suivant le chemin noté dans le CSS.
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Vous utilisez déjà le DSFR">
|
||||
Le fichier CSS à utiliser est :
|
||||
|
||||
```
|
||||
@gouvfr-lasuite/integration/dist/css/homepage-gaufre.css
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### 2. JS
|
||||
|
||||
Pour faire fonctionner le bouton Gaufre présent en haut à droite de la page, il est nécessaire de
|
||||
charger un fichier JS externe qui s'occupe d'afficher le widget au clic du bouton.
|
||||
|
||||
Vous pouvez ajouter ce code dans le `<head>` de votre page d'accueil uniquement, ou dans le `<head>`
|
||||
commun à toutes vos pages si vous décidez d'intégrer [La Gaufre](../gaufre) de façon globale sur
|
||||
votre site :
|
||||
|
||||
<Code
|
||||
code={`<script id="lasuite-gaufre-script" async defer src="${import.meta.env.PUBLIC_LASUITE_API_URL}/api/v1/gaufre.js"></script>`}
|
||||
lang="html"
|
||||
/>
|
||||
|
||||
:::note
|
||||
|
||||
Pour que le script fonctionne il est nécessaire qu'il ait un id `lasuite-gaufre-script`, ne
|
||||
l'enlevez pas !
|
||||
|
||||
:::
|
||||
|
||||
### 3. HTML
|
||||
|
||||
:::tip
|
||||
|
||||
Pour facilement générer le code nécessaire, utilisez
|
||||
[le générateur de gabarit de page d'accueil](../homepage-generator).
|
||||
|
||||
Sinon, suivez les conseils ci-dessous.
|
||||
|
||||
:::
|
||||
|
||||
#### Avec React
|
||||
|
||||
Si vous utilisez React, utilisez le composant `Homepage` fourni par le paquet. Il faut lui passer
|
||||
plusieurs _props_ pour adapter le contenu à votre service. Et lui passer en enfant le contenu à
|
||||
afficher dans la partie droite de la page d'accueil.
|
||||
|
||||
Plusieurs composants prêt-à-l'emploi sont disponibles pour vous aider à construire rapidement ce
|
||||
contenu :
|
||||
|
||||
- `HomepageEmail` affiche un bloc contenant un formulaire de connexion par e-mail,
|
||||
- `HomepageEmailOrProconnect` affiche un bloc contenant un formulaire de connexion par e-mail et un
|
||||
bouton Proconnect,
|
||||
- `HomepageProconnect` affiche un bloc contenant un bouton de connexion par Proconnect,
|
||||
|
||||
Tous les composants sont typés avec TypeScript avec des props commentées. En attendant une
|
||||
documentation plus complète, vous pouvez vous aider de l'autocomplétion de votre éditeur pour en
|
||||
savoir plus sur chaque composant.
|
||||
|
||||
##### Traduction
|
||||
|
||||
Si vous utilisez les composants React et que vous avez besoin de traduire votre page d'accueil,
|
||||
vous pouvez envelopper les composants avec le provider `LaSuiteTranslationsProvider` provenant du
|
||||
paquet, et lui passer en props vos `translations`. Les traductions françaises sont exportées en
|
||||
tant que `frTranslations`.
|
||||
|
||||
#### Sans React
|
||||
|
||||
Si vous n'utilisez pas React, utilisez le HTML présent dans
|
||||
`@gouvfr-lasuite/integration/dist/html/homepage.html` :
|
||||
|
||||
<details>
|
||||
<summary>Voir le code HTML</summary>
|
||||
<Code
|
||||
code={homepageHtml}
|
||||
lang="html"
|
||||
title="@gouvfr-lasuite/integration/dist/html/homepage.html"
|
||||
/>
|
||||
</details>
|
||||
|
||||
Remplacez le contenu de la div `.lasuite-homepage__form-inner` par le contenu propre à votre page
|
||||
d'accueil. Vous pouvez utiliser du HTML prêt à l'emploi pour construire rapidement ce contenu :
|
||||
|
||||
- `@gouvfr-lasuite/integration/dist/html/email.html` affiche un bloc contenant un formulaire de
|
||||
connexion par e-mail,
|
||||
- `@gouvfr-lasuite/integration/dist/html/email-or-proconnect.html` affiche un bloc contenant un
|
||||
formulaire de connexion par e-mail et un bouton Proconnect,
|
||||
- `@gouvfr-lasuite/integration/dist/html/proconnect.html` affiche un bloc contenant un bouton de
|
||||
connexion par Proconnect.
|
||||
|
||||
:::caution
|
||||
|
||||
Dans les gabarits HTML fournis, toutes les parties `~~replace~~` sont à remplacer avec vos données !
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
Vous pouvez récupérer le logo de votre service au format svg dans le paquet npm :
|
||||
`@gouvfr-lasuite/integration/dist/logos`.
|
||||
|
||||
:::
|
||||
BIN
website/src/content/docs/guides/homepage.png
Normal file
BIN
website/src/content/docs/guides/homepage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 220 KiB |
18
website/src/content/docs/index.mdx
Normal file
18
website/src/content/docs/index.mdx
Normal file
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: Intégrations de La Suite numérique
|
||||
description:
|
||||
Intégrez facilement les interfaces utilisateurs communes des services de La Suite numérique.
|
||||
template: splash
|
||||
hero:
|
||||
tagline:
|
||||
Intégrez facilement les interfaces utilisateurs communes des services de <a style="color:
|
||||
var(--sl-color-text-accent)" href="https://lasuite.numerique.gouv.fr">La Suite numérique</a>.
|
||||
image:
|
||||
file: ../../assets/lasuite-logo.svg
|
||||
alt: ""
|
||||
actions:
|
||||
- text: Commencer
|
||||
link: /guides/getting-started
|
||||
icon: right-arrow
|
||||
variant: primary
|
||||
---
|
||||
90
website/src/content/docs/reference/api.md
Normal file
90
website/src/content/docs/reference/api.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Endpoints de l'API web
|
||||
---
|
||||
|
||||
L'API d'intégration de La Suite expose plusieurs endpoints facilitant l'usage des UI communes.
|
||||
|
||||
## URL de l'API
|
||||
|
||||
```
|
||||
https://integration.lasuite.numerique.gouv.fr
|
||||
```
|
||||
|
||||
C'est par exemple l'URL à passer comme `lasuiteApiUrl` aux composants React.
|
||||
|
||||
## Fond d'écran de page d'accueil
|
||||
|
||||
```text "{id}" "{avif,jpg}"
|
||||
https://integration.lasuite.numerique.gouv.fr/api/backgrounds/v1/{id}.avif
|
||||
https://integration.lasuite.numerique.gouv.fr/api/backgrounds/v1/{id}.jpg
|
||||
```
|
||||
|
||||
- Méthode : GET
|
||||
- Retourne : une image en AVIF ou JPG en 1920x1080
|
||||
- Passer l'[id d'un service](#liste-des-services-de-la-suite) à la place de `{id}`.
|
||||
💡 Si votre service n'est pas (encore) supporté, vous pouvez utiliser l'id `default`.
|
||||
|
||||
Les photos d'arrière-plan de chaque page d'accueil de service changent plusieurs fois par mois à
|
||||
travers tous les services.
|
||||
|
||||
Pour que ce changement se fasse sans avoir à mettre à jour le code des pages d'accueil
|
||||
régulièrement, un service peut requêter une photo d'arrière-plan avec son identifiant. L'image
|
||||
exposée sur cette URL change régulièrement.
|
||||
|
||||
Les photos sont disponibles à la fois en avif et en jpeg.
|
||||
|
||||
### Exemple d'usage
|
||||
|
||||
Avec le service Resana :
|
||||
|
||||
```html
|
||||
<picture>
|
||||
<source
|
||||
srcset="https://integration.lasuite.numerique.gouv.fr/api/backgrounds/v1/resana.avif"
|
||||
type="image/avif"
|
||||
/>
|
||||
<img
|
||||
src="https://integration.lasuite.numerique.gouv.fr/api/backgrounds/v1/resana.jpg"
|
||||
alt=""
|
||||
width="1920"
|
||||
height="1080"
|
||||
/>
|
||||
</picture>
|
||||
```
|
||||
|
||||
<picture>
|
||||
<source
|
||||
srcset="https://integration.lasuite.numerique.gouv.fr/api/backgrounds/v1/resana.avif"
|
||||
type="image/avif"
|
||||
/>
|
||||
<img
|
||||
src="https://integration.lasuite.numerique.gouv.fr/api/backgrounds/v1/resana.jpg"
|
||||
alt=""
|
||||
width="1920"
|
||||
height="1080"
|
||||
/>
|
||||
</picture>
|
||||
|
||||
## Widget La Gaufre
|
||||
|
||||
```
|
||||
https://integration.lasuite.numerique.gouv.fr/api/v1/gaufre.js
|
||||
```
|
||||
|
||||
- Méthode : GET
|
||||
- Retourne : le JavaScript s'occupant d'afficher la popup listant les services de La Suite au clic
|
||||
sur le bouton [Gaufre](/guides/gaufre)
|
||||
|
||||
## Liste des services de La Suite
|
||||
|
||||
`https://integration.lasuite.numerique.gouv.fr/api/v1/services.json`
|
||||
|
||||
Retourne un tableau JSON listant les services de La Suite numérique. Chaque service a cette
|
||||
structure :
|
||||
|
||||
- `id` l'identifiant du service, utilisé par d'autres APIs,
|
||||
- `name` le nom du service,
|
||||
- `url` l'url de la page d'accueil du service.
|
||||
|
||||
Ce endpoint sert principalement à retrouver l'`id` correspondant à un service et est là plutôt à
|
||||
titre informatif.
|
||||
Reference in New Issue
Block a user