@edugouvfr/ngx-dsfr - Readme

NgxDsfr est un portage Angular des éléments d'interface du 🇫🇷 Système de Design de l'État Français (DSFR).

Cette bibliothèque est développée, maintenue et gérée par une équipe de développement du Ministère de l'Éducation Nationale basée à Grenoble et pilotée par les sous-directions "socle numérique" (SOCLE1) et "services numériques" (SN2) de la Direction du Numérique pour l'Éducation (DNE).

Dépendances

Notre package s'appuie actuellement ur la version 1.10.1 du DSFR.

Nous développons avec Angular 14 mais notre bibliothèque est compatible Angular 15 et 16.

Licence et droit d'utilisation

Le contenu de ce projet est placé sous licence EUPL 1.2.

Pour rappel, l'usage du DSFR est réservé aux sites Internet de l'État, se référer aux cf. CGU du DSFR.

Installation

• Installer la dépendance vers le module NPM dans votre projet Angular

  npm install @edugouvfr/ngx-dsfr

  La dépendance transitive vers @gouvfr/dsfr sera installée automatiquement.

• Référencer les feuilles de style et le script DSFR dans votre fichier angular.json ou project.json :

  "styles": [
    "projects/app-demo/src/styles.scss",
    "./node_modules/@gouvfr/dsfr/dist/dsfr/dsfr.css",
    "./node_modules/@gouvfr/dsfr/dist/utility/utility.css",
  ],
  "scripts": [
    "./node_modules/@gouvfr/dsfr/dist/dsfr/dsfr.module.js"
  ]

• Ajouter les meta tag du dsfr dans le fichier index.html.

Exemple: Prise en main

Utilisation

• Dans votre module, importer le module du composant que vous souhaitez utiliser :

  import { DsfrButtonModule } from "@edugouvfr/ngx-dsfr"
  
  @NgModule({
    imports: [
      CommonModule,
      DsfrButtonModule,
      ...
    ]
  })
  export class MonModule {}

• Puis utiliser le composant dans votre template html :

  <dsfr-button>...</dsfr-button>

Documentation

Se référer au Storybook de la version que vous utilisez :

https://foad.phm.education.gouv.fr/edugouvfr/ngx-dsfr/

Icônes de la documentation :

• 👆 Remarque
• 📌 Note
• 🔥 Point d'attention
• 👓 Accessibilité

Code source

Le code source de cette bibliothèque de composants est publié sur mim-libre :

https://gitlab.mim-libre.fr/men/transverse/dsmen/ngx-dsfr-components.git

Fonctionnement

Gestion des liens

Certains composants permettent de naviguer vers d'autres pages web ou d'autres parties de votre site/application web.

Pour produire un hyperlien "classique" avec une une url (absolue ou relative) passer par la propriété link du composant.

Si vous souhaitez plutôt exécuter une navigation Angular (via le Router) voici comment procéder :

Navigation gérée programmatiquement via router#navigate

• Renseigner la propriété route en input du composant
• Mettez-vous à l'écoute de l'output routeSelect
• L'événement (routeSelect) est émis avec la valeur de route et l'événement natif n'est pas propagé
• Vous pouvez alors exécuter router#navigate

Navigation gérée via une directive routerLink (si supporté par le composant)

• Renseigner la propriété routerLink
• Cela va intégrer une directive routerLink au niveau du lien de navigation interne au composant
• routerLinkExtras vous permet d'ajouter les paramètres optionnels tels les queryParams
• Ou de laisser la gestion de façon externe au composant en utilisant l'attribut route. Dans ce cas, .

Gestion des icônes

Une propriété icon est :

• soit une classe du DSFR, exemple fr-icon-home-4-fill,
• soit l'identifiant du référentiel d'icônes Remix, exemple : ri-home-4-fill.

Gestion des libellés

Dans de nombreux composants, il vous est possible de fournir certains contenus de deux façons :

• soit via un point d'injection (ng-content) prévu à cet effet :

  • Ex.: <dsfr-link link="#bottom">Bas de page</dsfr-link>

• soit via une propriété (input) :

  • Ex.: <dsfr-link link="#bottom" label="Bas de page"></dsfr-link>

Si les deux (slot+input) sont renseignés c'est l'input qui sera utilisé en priorité

L'input ne supporte pas le format HTML, si vous avez besoin de formater votre contenu vous devez obligatoirement passer par le slot

Exemple de composants supportant cette possibilité :

• forms : checkbox, input, select, toggle, radio(legend)
• accordion(content, heading)
• table(caption)
• tile(description)

Internationalisation

Les libellés des composants sont disponibles en 2 langues, fr par défaut et en. Le changement de langue, pour les composants de la librairie, est géré par le composant translate. Il n'y a pas besoin de faire un setLang() quelque part.

Vous pouvez aussi ajouter un fichier pour une nouvelle langue.

• messages.<code-lang>.json est le nom par défaut du fichier,
• /assets/i18n/ est le répertoire par défaut de ce fichier.

Le répertoire par défaut peut être modifié à l'import du module :

@NgModule({
imports: [
  DsfrConfigModule.forRoot({i18nMessagesPath: '<votre path>>'})
]
})

Contact

• Liste de diffusion de l'équipe de développement dsmen-core@ldiff.forge.education.gouv.fr

• Canal Mattermost (interne forge Éduc. Nat.)

Demander une évolution ou signaler une anomalie

Équipes internes Éduc. Nat.

• Passer par les issues du Gitlab Forge

Autres ministères ou délégations de service public

• Passer par les issues Gitlab Mim-Libre

Contribuer

Voir le guide de contribution.