Skip to content

Commit 382d29b

Browse files
committed
[FEAT] exemples et documentation
1 parent 8145939 commit 382d29b

File tree

6 files changed

+341
-83
lines changed

6 files changed

+341
-83
lines changed

README.md

Lines changed: 112 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ Il est recommandé de placer les fichiers dans cet ordre avant la balise fin de
1414

1515
```html
1616
<body>
17-
<script src="/path/to/c-scrollspy-callbacks.js"></script> <!-- optionnel -->
1817
<script src="/path/to/c-scrollspy.js"></script> <!-- obligatoire -->
18+
<script src="/path/to/c-scrollspy-callbacks.js"></script> <!-- optionnel -->
1919
</body>
2020
```
2121

@@ -44,13 +44,121 @@ https://cdn.jsdelivr.net/gh/ita-design-system/[email protected]/ui/js/c-scro
4444
```html
4545
<body>
4646
<!-- Exemple avec version la plus récente -->
47-
<script src="https://cdn.jsdelivr.net/gh/ita-design-system/c-scrollspy.js/ui/js/c-scrollspy-templates.min.js"></script>
4847
<script src="https://cdn.jsdelivr.net/gh/ita-design-system/c-scrollspy.js/ui/js/c-scrollspy.min.js"></script>
4948

5049
<!-- Exemple avec numéro de version -->
51-
<script src="https://cdn.jsdelivr.net/gh/ita-design-system/[email protected]/ui/js/c-scrollspy-templates.min.js"></script>
52-
<script src="https://cdn.jsdelivr.net/gh/ita-design-system/[email protected]/ui/js/c-scrollspy.min.js"></script>
50+
<script src="https://cdn.jsdelivr.net/gh/ita-design-system/[email protected]/ui/js/c-scrollspy.min.js"></script>
5351
</body>
5452
```
5553

5654
## Usage
55+
56+
c-scrollspy fonctionne avec [l'API de IntersectionObserver](https://developer.mozilla.org/fr/docs/Web/API/IntersectionObserver) et déclenche des callbacks selon les seuils de passages spécifiés dans la vue. Spécifier le nom du callback dans l'attribut `c-scrollspy="NAME_OF_THE_CALLBACK"`. c-scrollspy est livré avec un callback nommé `anchor` (le cas le plus courant). Il est possible de créer et d'utiliser vos propres callbacks.
57+
58+
**Chaque callback dispose de ses propres paramètres**
59+
60+
### Callback `anchor`
61+
62+
Avec le callback `anchor` (toujours inclus dans c-scrollspy.js), lorsque l'élément passe dans la fenêtre de visualisation, la classe des liens qui pointent vers cet élément est remplacée par "active".
63+
64+
**L'attribut id est obligatoire sur l'élément observé**
65+
66+
Il est possible de spécifier la classe de remplacement avec l'attribut `data-active-class="..."`
67+
68+
```html
69+
<a href="#section-description"
70+
class="classe-test-1 classe-test-2">
71+
Description
72+
</a>
73+
<a href="#section-livraison"
74+
class="autre-classe">
75+
Livraison
76+
</a>
77+
<a href="#section-financement">
78+
Financement
79+
</a>
80+
81+
<section id="section-description" c-scrollspy="anchors">
82+
<h2>Description</h2>
83+
<p>Par défaut, lorsque cet élément passe dans la vue, la classe des liens qui pointent vers celle-ci sont remplacées par "active".</p>
84+
</section>
85+
86+
<section id="section-livraison" c-scrollspy="anchors">
87+
<h2>Livraison</h2>
88+
<p>Défiler vers le bas pour visualiser les bascules de classes au passage des sections dans la vue.</p>
89+
<p>Par défaut, lorsque cette section passe dans la vue, la classe des liens qui pointent vers celle-ci sont remplacées par "active".</p>
90+
</section>
91+
92+
<section id="section-financement"
93+
c-scrollspy="anchors"
94+
data-active-class="active-2 active-3">
95+
<h2>Financement</h2>
96+
<p>Section avec classes personnalisées. Lorsque cette section est dans la vue, la classe des liens qui pointent vers celle-ci sont remplacées par la valeur de l'attribut data-active-class. Ici "active-2 active-3"</p>
97+
</section>
98+
```
99+
100+
### Callback personnalisé
101+
102+
cScrollspyCallbacks object is available when c-scrollspy.js is set on the document. Write your own callbacks to fit your needs.
103+
104+
Exemple de callback vierge: [démo](https://ita-design-system.github.io/c-scrollspy.js/content/custom-callback.html)
105+
106+
```javascript
107+
// Minimal
108+
cScrollspyCallbacks.myCustomCallbackName = {
109+
/**
110+
* CALLBACK
111+
* CALLBACK METHOD
112+
* @arg {(object)} data event data returned by intersectonObserver
113+
*/
114+
callback: function(data) {
115+
console.log('myCustomCallbackName', data);
116+
// Your own stuff here
117+
}
118+
}
119+
```
120+
121+
Exemple de callback simple avec options personnalisées: [démo](https://ita-design-system.github.io/c-scrollspy.js/content/custom-callback.html)
122+
123+
```javascript
124+
// Simple callback avec thresholds personnalisés
125+
// Arrière-plan variable
126+
cScrollspyCallbacks.multipleThesholds = {
127+
options: {
128+
threshold: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1]
129+
},
130+
/**
131+
* CALLBACK
132+
* CALLBACK METHOD
133+
* @arg {(object)} data event data returned by intersectonObserver
134+
*/
135+
callback: function(data) {
136+
data.forEach(function(obj) {
137+
// console.log('multipleThesholds', obj.intersectionRatio);
138+
obj.target.style.transition = 'background-color 200ms';
139+
obj.target.style.backgroundColor = 'rgba(180, 200, 220, '+obj.intersectionRatio+')';
140+
})
141+
}
142+
}
143+
```
144+
145+
## Méthodes
146+
147+
### `update()`
148+
149+
Indispensable pour démarrer l'application, instancie les IntersectionObserver, s'exécute automatiquement sur le `DOMReady` et peut être invoqué à tout moment, à chaque changement de DOM.
150+
151+
```javascript
152+
cScrollspy.update();
153+
```
154+
155+
## API
156+
157+
Toutes les instances de c-scrollspy sont placées dans `cScrollspy.instances[ID_DE_L_INSTANCE]`. `ID_DE_L_INSTANCE` est l'id de l'élément s'il est présent, s'il est absent, c-scrollspy applique un id préfixé de `cspy_` suivi de l'index de l'instance.
158+
159+
```javascript
160+
// Élément DOM traqué
161+
cScrollspy.instances[ID_DE_L_INSTANCE].el;
162+
// Méthodes IntersectionObserver
163+
cScrollspy.instances[ID_DE_L_INSTANCE].io;
164+
```

_config.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,8 +185,8 @@ playground:
185185
# Relative URL from site root starting with slash /
186186
# Absolute URL starting with 'http'
187187
scripts_body: # Javascript files near </body>. Can be either relative URL from site root, absolute URL starting with 'http'
188-
- /ui/js/c-scrollspy-callbacks.js
189188
- /ui/js/c-scrollspy.js
189+
- /ui/js/c-scrollspy-callbacks.js
190190
# - /js/my-toggle-native.js
191191
# - /js/my-tabs-options.js
192192
# - /js/my-tabs-native.js

content/custom-callback.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Callbacks personnalisés
3+
description: Exemples c-scrollspy avec callbacks personnalisés
4+
layout: libdoc/page-split
5+
category: Exemples
6+
order: 10
7+
---
8+
9+
```html
10+
<section c-scrollspy="mostSimple">
11+
<h2>Callback personnalisé mostSimple</h2>
12+
<p>Ce callback personnalisé appelé "mostSimple" retourne un simple console.log(data) de l'IntersectionObserver (voir la console).</p>
13+
<p>Si les options ne sont pas spécifiées, comme sur cet exemple, cScrollspy utilise les options du callback anchor.</p>
14+
</section>
15+
16+
<section c-scrollspy="multipleThesholds">
17+
<h2>Callback personnalisé multipleThesholds</h2>
18+
<p>Ce callback personnalisé appelé "multipleThesholds" modifie la couleur de l'arrière-plan à chaque seuil.</p>
19+
</section>
20+
21+
<section c-scrollspy="multipleThesholds">
22+
<h2>Callback personnalisé multipleThesholds seconde instance</h2>
23+
<p>Modifie la couleur de l'arrière-plan à chaque seuil.</p>
24+
</section>
25+
26+
<!-- DEMO ONLY -->
27+
<style>
28+
body {
29+
padding: var(--ita-spacing-4);
30+
color: var(--ita-color-primary-800);
31+
font-family: var(--ita-font-family-mono);
32+
font-size: 1rem;
33+
line-height: 1.5rem;
34+
padding-bottom: 150vh;
35+
}
36+
nav {
37+
display: flex;
38+
flex-wrap: wrap;
39+
position: fixed;
40+
top: 0;
41+
left: 0;
42+
width: 100%;
43+
background-color: var(--ita-color-primary-500);
44+
}
45+
nav a {
46+
color: var(--ita-color-neutral-100);
47+
padding: 1em 2em;
48+
font-size: var(--ita-font-size-4);
49+
text-transform: uppercase;
50+
text-decoration: none;
51+
}
52+
a.active {
53+
color: var(--ita-color-primary-900);
54+
}
55+
a.active-2 {
56+
color: var(--ita-color-support-warning-500);
57+
}
58+
a.active-3 {
59+
color: var(--ita-color-support-danger-500);
60+
}
61+
section {
62+
height: 130vh;
63+
padding: 3em;
64+
background-color: var(--ita-color-primary-100);
65+
margin-bottom: 3em;
66+
scroll-margin-top: 40px;
67+
}
68+
</style>
69+
```
70+
{:.playground title="Exemple de callbacks personnalisés"}

content/index.html

Lines changed: 78 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,64 @@
33
permalink: index.html
44
unlisted: true
55
---
6-
<nav class="">
7-
<a href="#section-description" class="c-btn mod-tab">Description</a>
8-
<a href="#section-reprise" class="c-btn mod-tab">Reprise</a>
9-
<a href="#section-financement" class="c-btn mod-tab">financement</a>
10-
<a href="#section-livraison" class="c-btn mod-tab">Livraison</a>
11-
<a href="#section-avis" class="c-btn mod-tab">Avis</a>
6+
<nav>
7+
<a href="#section-description"
8+
class="classe-test-1 classe-test-2">
9+
Description
10+
</a>
11+
<a href="#section-reprise"
12+
class="classe-test-1">
13+
Reprise
14+
</a>
15+
<a href="#section-financement"
16+
class="classe-test-2">
17+
Financement
18+
</a>
19+
<a href="#section-livraison"
20+
class="classe-test-5">
21+
Livraison
22+
</a>
23+
<a href="#section-avis"
24+
class="classe-test-1 classe-test-2">
25+
Avis
26+
</a>
1227
</nav>
13-
<section id="section-description"><h2>Description</h2></section>
14-
<section id="section-reprise"><h2>Reprise</h2></section>
15-
<section id="section-financement" c-scrollspy="anchors"><h2>financement</h2></section>
16-
<section id="section-livraison"><h2>livraison</h2></section>
17-
<section id="section-avis"><h2>avis</h2></section>
28+
<section id="section-description"
29+
c-scrollspy="anchors">
30+
<h2>Description</h2>
31+
<p>Défiler vers le bas pour visualiser les bascules de classes au passage des sections dans la vue.</p>
32+
<p>Par défaut, lorsque cette section passe dans la vue, la classe des liens qui pointent vers celle-ci sont remplacées par "active".</p>
33+
<a href="#section-reprise">Reprise</a>
34+
</section>
35+
36+
<section id="section-reprise"
37+
c-scrollspy="anchors">
38+
<h2>Reprise</h2>
39+
<a href="#section-financement">Financement</a>
40+
</section>
41+
42+
<section id="section-financement"
43+
c-scrollspy="anchors"
44+
data-active-class="active-2">
45+
<h2>Financement</h2>
46+
<p>Section avec classes personnalisées. Lorsque cette section est dans la vue, la classe des liens qui pointent vers celle-ci sont remplacées par la valeur de la chaine de caractères de l'attribut personnalisé data-active-class. Ici "active-2"</p>
47+
<a href="#section-livraison">Livraison</a>
48+
</section>
49+
50+
<section id="section-livraison"
51+
c-scrollspy="anchors"
52+
data-active-class="active-3 test foobar">
53+
<h2>Livraison</h2>
54+
<p>Section avec classes personnalisées. Lorsque cette section est dans la vue, la classe des liens qui pointent vers celle-ci sont remplacées par la valeur de la chaine de caractères de l'attribut personnalisé data-active-class. "active-3 test foobar"</p>
55+
<a href="#section-avis">Avis</a>
56+
</section>
57+
58+
<section id="section-avis"
59+
c-scrollspy="anchors">
60+
<h2>Avis</h2>
61+
<a href="#">Retour vers le haut</a>
62+
</section>
63+
1864
<!-- DEMO ONLY -->
1965
<style>
2066
body {
@@ -23,9 +69,11 @@
2369
font-family: var(--ita-font-family-mono);
2470
font-size: 1rem;
2571
line-height: 1.5rem;
26-
padding-bottom: 50vh;
72+
padding-bottom: 150vh;
2773
}
2874
nav {
75+
display: flex;
76+
flex-wrap: wrap;
2977
position: fixed;
3078
top: 0;
3179
left: 0;
@@ -34,11 +82,25 @@
3482
}
3583
nav a {
3684
color: var(--ita-color-neutral-100);
85+
padding: 1em 2em;
86+
font-size: var(--ita-font-size-4);
87+
text-transform: uppercase;
88+
text-decoration: none;
89+
}
90+
a.active {
91+
color: var(--ita-color-primary-900);
92+
}
93+
a.active-2 {
94+
color: var(--ita-color-support-warning-500);
95+
}
96+
a.active-3 {
97+
color: var(--ita-color-support-danger-500);
3798
}
3899
section {
39-
height: 150vh;
40-
padding-top: 100px;
41-
background-color: var(--ita-color-primary-200);
42-
margin-bottom: 100px;
100+
height: 130vh;
101+
padding: 3em;
102+
background-color: var(--ita-color-primary-100);
103+
margin-bottom: 3em;
104+
scroll-margin-top: 40px;
43105
}
44106
</style>

ui/js/c-scrollspy-callbacks.js

Lines changed: 35 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,39 @@
1-
// cpreview Templates
2-
let cScrollspyCallbacks = {
1+
/**
2+
* Custom callbacks for c-scrollspy
3+
* Demo purpose only
4+
*/
5+
6+
// Most simple callback (blank)
7+
cScrollspyCallbacks.mostSimple = {
8+
// options: {
9+
// threshold: [0, 0.2, 0.8, 1]
10+
// },
311
/**
4-
* CUSTOM TEMPLATE FOR "REMOVE ALL" FILES BUTTON
5-
* @param {Object} data
6-
* @param {Object} data.el_target_container DOM element if the file item
7-
* @param {String} data.id input type file id to reset
8-
*/
9-
myCallback: {
10-
options: {
11-
threshold: [0, 0.2, 0.8, 1]
12-
},
13-
/**
14-
* CALLBACK
15-
* CALLBACK METHOD
16-
* @arg {(object)} data event data returned by intersectonObserver
17-
*/
18-
callback: function(data) {
19-
}
12+
* CALLBACK
13+
* CALLBACK METHOD
14+
* @arg {(object)} data event data returned by intersectonObserver
15+
*/
16+
callback: function(data) {
17+
console.log('mostSimple', data[0].intersectionRatio, data)
18+
}
19+
}
2020

21+
// Simple callback avec thresholds personnalisés
22+
// Arrière-plan variable
23+
cScrollspyCallbacks.multipleThesholds = {
24+
options: {
25+
threshold: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1]
26+
},
27+
/**
28+
* CALLBACK
29+
* CALLBACK METHOD
30+
* @arg {(object)} data event data returned by intersectonObserver
31+
*/
32+
callback: function(data) {
33+
data.forEach(function(obj) {
34+
// console.log('multipleThesholds', obj.intersectionRatio);
35+
obj.target.style.transition = 'background-color 200ms';
36+
obj.target.style.backgroundColor = 'rgba(180, 200, 220, '+obj.intersectionRatio+')';
37+
})
2138
}
2239
}

0 commit comments

Comments
 (0)