Skip to content

Commit 30f9b7c

Browse files
nico3333frnico3333fr
authored
A real readme now !
1 parent 6b85d98 commit 30f9b7c

File tree

1 file changed

+169
-2
lines changed

1 file changed

+169
-2
lines changed

‎README.md

+169-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,169 @@
1-
# van11y-accessible-tab-panel-aria
2-
ES2015 accessible tabs panel system, using ARIA
1+
# Van11y accessible tabs panel system, using ARIA
2+
3+
<img src="https://van11y.net/layout/images/logo-van11y.svg" alt="Van11y" width="300" />
4+
5+
This script will transform a simple list of anchors to contents into a fantastic-shiny accessible tabpanel system, using ARIA.
6+
7+
The demo is here: https://van11y.net/downloads/tab-panel/demo/index.html
8+
9+
Website is here: https://van11y.net/accessible-tab-panel/
10+
11+
La page existe aussi en français : https://van11y.net/fr/onglets-accessibles/
12+
13+
## How it works
14+
15+
__ARIA is coming__
16+
17+
The script adds all needed attributes to your tabs controls and panels (```role="tab/tablist/etc."```,```aria-selected/controls="…"```).
18+
19+
__Then a bit of styling classes__
20+
21+
Then it will generate some classes for you, to allow styling your tabs as you want.
22+
23+
__And JavaScript does the rest__
24+
25+
Some listeners for keyboard and mouse interactions are added, when you activate one, it will updates attributes and manage keyboard interations.
26+
27+
## How to use it
28+
29+
__Download the script__
30+
31+
You may also use npm command: ```npm i van11y-accessible-tab-panel-aria```.
32+
33+
You may also use bower: ```bower install van11y-accessible-tab-panel-aria```.
34+
35+
__Conventions__
36+
37+
Then, follow the conventions given in this minimal example (in bold).
38+
39+
- use classes needed (```js-tabs```, ```js-tablist```, ```js-tablist__item```, ```js-tablist__link```, ```js-tabcontent```)
40+
- be careful to use the convention in the links ```a href="#id_first" id="label_id_first"```
41+
- check that your anchors are working.
42+
- for accessibility purposes (for VoiceOver), the plugin has to give focus to ```hx``` (```h2```, ```h3```, ```h4```, etc.) in tab contents.
43+
44+
For ```Hx```, you have two cases:
45+
46+
- There aren’t any in your ```js-tabcontent```’s, so specify in ```data-hx``` attribute (will be added with ```class="invisible"```, which means visually hidden);
47+
- There are some, just tell it to the plugin using ```data-existing-hx``` attribute.
48+
49+
Example without ```hx```:
50+
```
51+
<div class="js-tabs">
52+
<ul class="js-tablist" data-hx="h2">
53+
<li class="js-tablist__item">
54+
<a href="#id_first" id="label_id_first" class="js-tablist__link">1st tab</a>
55+
</li>
56+
<li class="js-tablist__item">
57+
<a href="#id_second" id="label_id_second" class="js-tablist__link">2nd tab</a>
58+
</li>
59+
</ul>
60+
<div id="id_first" class="js-tabcontent">
61+
here the content of 1st tab
62+
</div>
63+
<div id="id_second" class="js-tabcontent">
64+
here the content of 2nd tab
65+
</div>
66+
</div>
67+
```
68+
Example with ```hx```:
69+
```
70+
<div class="js-tabs">
71+
<ul class="js-tablist" data-existing-hx="h2">
72+
<li class="js-tablist__item">
73+
<a href="#id_first" id="label_id_first" class="js-tablist__link">1st tab</a>
74+
</li>
75+
<li class="js-tablist__item">
76+
<a href="#id_second" id="label_id_second" class="js-tablist__link">2nd tab</a>
77+
</li>
78+
</ul>
79+
<div id="id_first" class="js-tabcontent">
80+
<h2>title</h2>
81+
here the content of 1st tab
82+
</div>
83+
<div id="id_second" class="js-tabcontent">
84+
<h2>other title</h2>
85+
here the content of 2nd tab
86+
</div>
87+
</div>
88+
```
89+
90+
## Keyboard shortcuts
91+
92+
If you focus on the tabs “buttons”:
93+
94+
- use Up/Left to see previous tab,
95+
- use Down/Right to see next tab
96+
- use Home to see first tab (wherever you are in tab buttons)
97+
- use End to see last tab (wherever you are in tab buttons)
98+
99+
If you focus on a tab content:
100+
101+
- use Ctrl Up/Left to set focus on the tab button for the currently displayed tab
102+
- use Ctrl PageUp to set focus on the previous tab button for the currently displayed tab
103+
- use Ctrl PageDown to set focus on the next tab button for the currently displayed tab
104+
105+
Warning: Ctrl+PageUp/PageDown combination could activate for some browsers a switch of browser tabs. Nothing to do for this, as far as I know (if you have a solution, let me know).
106+
107+
## Logic of styling classes
108+
109+
__Before Javascript__
110+
111+
Once you set up the code with your content, style it before activating JavaScript: so it will be nice even if there is no JavaScript.
112+
113+
For example, just imagine you are on poor mobile connexion, and the JavaScript hasn’t (yet) loaded. Or it can be disabled.
114+
115+
__After Javascript__
116+
117+
You should add classes to the source, and use them this way:
118+
```
119+
[role="tablist"].my-style {…}
120+
```
121+
Basically, you should rely on ARIA attributes, so styles will be applied only if JavaScript is loaded and well-executed.
122+
Namespaced generated classes
123+
124+
The plugin has another feature: if you don’t like styling on role attributes, it can generate classes for you only for styling tabs when they are activated.
125+
126+
Here is an example:
127+
```
128+
<ul … data-tabs-prefix-class="last-tabs">
129+
```
130+
The ```data-tabs-prefix-class``` will add classes on each elements:
131+
```
132+
<ul … class="… last-tabs-tabs__list">
133+
<li … class="… last-tabs-tabs__item">
134+
<a … class="… last-tabs-tabs__link">…
135+
```
136+
So with ```data-tabs-prefix-class="last-tabs"``` you have:
137+
138+
- ```last-tabs-tabs__list``` for styling the ```ul```;
139+
- ```last-tabs-tabs__item``` for styling the ```li```;
140+
- ```last-tabs-tabs__link``` for styling the ```a```;
141+
- ```last-tabs-tabs__content``` for styling each tab panel.
142+
143+
## Bonuses
144+
145+
__Anchor added in URL__
146+
147+
As you may notice (or not), now the script adds a fragment in the URL when you click or select a tab using the keyboard. It is cool when you want to copy/paste the link of the page you are reading, and the opened tab will be the good one!
148+
Anchor on a tab panel
149+
150+
If you need to make a link on your page to a id that is on a tab panel, the script will detect it and display the good tab, only for you.
151+
152+
If you want to test, open a new window, and copy/paste this:
153+
https://van11y.net/downloads/tab-panel/demo/index.html#id_third
154+
155+
__Anchor in a tab panel__
156+
157+
If you need to make a link on your page to a id that is in a tab panel, the script will detect it and display the good tab, only for you.
158+
159+
If you want to test, open a new window, and copy/paste this:
160+
https://van11y.net/downloads/tab-panel/demo/index.html#cool-anchor
161+
162+
__“In-page” link to a tab panel__
163+
164+
If you need to create in your current page a link to a tab (inside or outside), it is possible:
165+
166+
- Create the link to the content you want to target: ```<a href="#link-to-tab">link to tab option</a>```
167+
- Add the class ```class="js-link-to-tab"``` to it;
168+
- And that’s all. The plugin will make it work.
169+

0 commit comments

Comments
 (0)