Installation

Il existe deux méthodes pour intégrer SipaUI à votre projet :

  1. La plus simple : appeler la version distante directement via un CDN.
  2. La plus efficace : récupérer l’intégralité du code grâce à npm pour l’intégrer dans votre propre projet et compiler le tout.

Méthode 1 : le CDN

La méthode la plus simple (il n’y a rien à installer) est d’appeler la librairie dans vos pages depuis le CDN (Content Delivery Network) du groupe SIPA. Toutefois, cette méthode ne vous permet pas de choisir vos composants, ni de créer un thème. Vous aurez donc l’intégralité du framework chargé, avec le thème standard (Ouest-France) ou éventuellement un des thèmes maintenu ici.

Import de la toute dernière version livrée

Permet d’être toujours à jour, au risque de recevoir une version majeur avec de potentiels changements non rétro-compatibles…

<link rel="stylesheet" href="https://cdn.sipaof.fr/sipaui/latest/css/main-sipaui.css" type="text/css" media="screen"/>

<script async src="https://cdn.sipaof.fr/sipaui/latest/js/sipaui.min.js"></script>

N. B. – La balise script est bien sûr à appeler en bas du <body>.

Import d’une version majeure spécifique

Permet d’être toujours à jour sur une version majeur sans risquer de changements non rétro-compatibles…

Pour changer de version majeure, il suffit de remplacer 7 par le numéro de version majeur voulu.

<link rel="stylesheet" href="https://cdn.sipaof.fr/sipaui/7/css/main-sipaui.css" type="text/css" media="screen"/>

<script async src="https://cdn.sipaof.fr/sipaui/7/js/sipaui.min.js"></script>

Import d’une version figée

Oblige à faire les changements de version à la main.

Il suffit de remplacer 7.0.54 par le numéro de version détaillé voulu.

<link rel="stylesheet" href="https://cdn.sipaof.fr/sipaui/7.0.54/css/main-sipaui.css" type="text/css" media="screen"/>

<script async src="https://cdn.sipaof.fr/sipaui/7.0.54/js/sipaui.min.js"></script>

Import d’une version majeure spécifique dans un thème

Pour appeler par exemple le thème Voiles et Voiliers de la version 7, ajouter le diminutif -vv au nom du fichier CSS.

<link rel="stylesheet" href="https://cdn.sipaof.fr/sipaui/7/css/main-sipaui-vv.css" type="text/css" media="screen"/>

<script async src="https://cdn.sipaof.fr/sipaui/7/js/sipaui.min.js"></script>

Méthode 2 : npm

La méthode la plus efficace est d’inclure la librairie dans votre projet pour qu’elle en fasse partie intégrante et qu’elle soit compilée avec celui-ci. Cette méthode vous permettra de choisir les composants à intégrer (et donc le poids de SipaUI dans votre projet) ainsi que de personnaliser votre thème si nécessaire (via un thème SipaUi ou via votre propre thème). Toutefois, pour utliser cette méthode, vous devrez maîtriser un exécuteur de tâches (comme Gulp) et utiliser un préprocesseur SASS (fichiers SCSS au lieu de CSS). Par ailleurs, si vous voulez filtrer les composants, faites attention aux dépendances ! (Certains composants sont dépendants d’autres pour s’afficher correctement.)

SipaUI est hébergé sur un dépôt NPM : https://www.npmjs.com/package/sipa-ui. On appelle cela un paquet. Pour l’installer, il faut l’appeler avec un gestionnaire de paquets que vous devrez installer sur votre machine si vous n’en avez pas : NPM, Yarn…

Méthodologie standard

Les lignes de commande ci-dessous sont pour le gestionnaire de paquet standard NPM… À vous de les adapter à votre gestionnaire si vous en utilisez un autre.

1. Récupérer le projet SipaUI en l’installant dans votre propre projet.

Via un terminal :

npm install sipa-ui

Cela installera une dépendance à SipaUI et aux paquets dont il a besoin dans votre dossier « node_modules » à la racine de votre projet sous le nom de sipa-ui.

2. Pour les CSS.

Importer dans vos fichiers SCSS l’intégralité de ceux de notre framework ou bien juste les composants nécessaires (attention au dépendances). Vous pouvez le faire en appelant directement les fichiers présents dans /node_modules/sipa-ui :

  • Pour l’intégralité de SipaUI :
@import "../node_modules/sipa-ui/src/core/scss/main-sipaui";
  • Pour un composant (p. ex. : le bouton plus sa dépendance aux classes d’aide) :
@import "../node_modules/sipa-ui/src/core/scss/main";
@import "../node_modules/sipa-ui/src/fondations/scss/Helpers/main";
@import "../node_modules/sipa-ui/src/composants/Inputs/Buttons/main";
  • Pour le même composant sans la librairie de reset CSS normalize si vous avez déjà un reset CSS dans votre projet :
@import "../node_modules/sipa-ui/src/core/scss/main-no-normalize";
@import "../node_modules/sipa-ui/src/fondations/scss/Helpers/main";
@import "../node_modules/sipa-ui/src/composants/Inputs/Buttons/main";

Autre possibilité, vous pouvez aussi choisir de copier avec votre exécuteur de tâches tous les fichiers de SipaUI présents dans « node_modules » vers vos propres assets et appeler ensuite ceux-ci dans vos fichiers SCSS.

3. Pour le JS.

Si vous ne souhaitez pas minifier le JS de SipaUI avec le vôtre, vous pouvez simplement utiliser la méthode du CDN ci-dessus. Dans le cas contraire, appliquez la même logique que pour les CSS.

4. Configurer le préprocesseur de votre projet pour gérer la compilation…

Méthodologie avec un thème déjà créé à importer

SipaUi intègre aujourd’hui des thèmes supplémentaires déjà réalisés, comme celui de Voiles & voiliers (cf. Les thèmes pour en savoir plus). De nouveaux thèmes peuvent être créés au besoin.

Pour utiliser un thème particulier dans votre projet, au point 2 de la méthode standard, appelez le main-sipaui de ce thème. L’identifiant du thème de Voiles & voiliers étant vv, cela donne :

@import "../node_modules/sipa-ui/src/core/scss/main-sipaui-vv";

Si vous filtrez les composants, faites comme pour le thème standard et ajoutez les variables du thème :

@import "../node_modules/sipa-ui/src/core/scss/main";
@import "../node_modules/sipa-ui/src/core/scss/themes/variables-theme-vv";
@import "../node_modules/sipa-ui/src/fondations/scss/Helpers/main";
@import "../node_modules/sipa-ui/src/composants/Inputs/Buttons/main";

Méthodologie avec votre propre thème

Si vous connaissez le SCSS, vous pouvez utiliser les composants de SipaUI en créant votre propre thème ! Le principe de base est assez simple, il suffit de surcharger chaque variable par défaut qui doit changer par les valeurs de votre choix. Cela peut être fait dans le fichier ../node_modules/sipa-ui/src/core/scss/themes/variables-theme-perso. Il vous suffit ensuite d’appeler ce fichier :

@import "../node_modules/sipa-ui/src/core/scss/main";
@import "../node_modules/sipa-ui/src/core/scss/themes/variables-theme-perso";
@import "../node_modules/sipa-ui/src/fondations/scss/Helpers/main";
@import "../node_modules/sipa-ui/src/composants/Inputs/Buttons/main";

La complexité réside dans le fait que les variables sont très nombreuses et peu documentées. Vous pouvez toujours consulter cette documentation pour en savoir (un peu) plus.

Initialisation des composants

Quelle que soit la méthode d’importation des assets de SipaUI que vous choisirez, il reste une action à faire avant d’utiliser des copposants : vous aurez besoin d’une classe sipaui au-dessus des éléments qui doivent être à la charte SipaUI. La place la plus logique est donc sur le <body> de votre page…

<body class="sipaui">

Le code a bien été copié !