Skip to content

Commit 63b9855

Browse files
ktquezktquez
committed
Add documentation
1 parent 1de7169 commit 63b9855

File tree

15 files changed

+19659
-8839
lines changed

15 files changed

+19659
-8839
lines changed

‎README.md

Lines changed: 35 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
1-
# vue-announcer
1+
# Introduction
22

3-
Imagine browsing pages (routes), receiving alerts and notifications, having a countdown timer on the page, a progress bar or a loading, among others. Now imagine all this happening to people who have visual disabilities and who use screen readers.
3+
Imagine browsing pages (routes), receiving alerts and notifications, having a countdown timer on the page, a progress bar, a loading or a change of route in a SPA. Now imagine all this happening to people who have visual disabilities and who use screen readers.
4+
5+
The [vue-announcer](https://github.com/vue-a11y/vue-announcer) provides an easy way to really tell what’s going on in your application to people using screen readers.
46

5-
The idea of this plugin is to tell the screen reader what is happening and primarily if you use single-page application.
67
Inspired by others in the community like:
7-
https://haltersweb.github.io/Accessibility/spa.html *(Example of how creating an accessible single-page application)*
8-
https://github.com/ember-a11y/a11y-announcer *(Ember A11y community)*
8+
- [Example of how creating an accessible single-page application](https://haltersweb.github.io/Accessibility/spa.html)
9+
- [Ember A11y community](https://github.com/ember-a11y/a11y-announcer)
10+
11+
### Links
912

13+
- [Documentation](https://announcer.vue-a11y.com/)
14+
- [Demos](https://announcer.vue-a11y.com/demos/)
1015

1116
## Install package
1217
#### NPM
@@ -20,8 +25,22 @@ yarn add vue-announcer
2025
```
2126
---
2227

23-
## How to use
24-
In your `main.js`
28+
# Installation
29+
30+
## Package
31+
32+
#### NPM
33+
```shell
34+
npm install -S vue-announcer
35+
```
36+
37+
#### Yarn
38+
```shell
39+
yarn add vue-announcer
40+
```
41+
42+
## Basic usage
43+
2544
```javascript
2645
import Vue from 'vue'
2746
import VueAnnouncer from 'vue-announcer'
@@ -30,98 +49,18 @@ Vue.use(VueAnnouncer)
3049
```
3150

3251
In your `App.vue`
33-
Example using `vue-toasted`
3452
```vue
3553
<template>
36-
<div id="app">
54+
<div>
3755
<vue-announcer />
38-
39-
<h2>App page</h2>
40-
41-
<button type="button" data-va="toasted" @click="notify">
42-
trigger notification
43-
</button>
56+
<!-- header code -->
57+
<!-- router-view -->
58+
<!-- footer code -->
4459
</div>
4560
</template>
46-
<script>
47-
export default {
48-
name: 'app'
49-
methods: {
50-
notify () {
51-
let message = `Hi, it's a toasted notification`
52-
this.$toasted.success(message)
53-
this.$announcer.set(message) // Sets the message that will be read by the screen reader automatically.
54-
}
55-
}
56-
}
57-
</script>
58-
```
59-
See this example:
60-
[Example link](https://github.com/vue-a11y/vue-announcer/blob/master/example/src/pages/About.vue)
61-
62-
## Announce route changes
63-
For page changes (routes) to be announced automatically, you only need to pass the router object as a parameter at the time of installation.
64-
65-
```javascript
66-
import Vue from 'vue'
67-
import router from './router'
68-
import VueAnnouncer from 'vue-announcer'
69-
70-
Vue.use(VueAnnouncer, {}, router)
7161
```
7262

73-
### Options
74-
Key | Data Type | default |
75-
------------------ | ---------- | ------------ |
76-
`complementRoute` | String | `has loaded` |
77-
78-
79-
Example:
80-
```javascript
81-
Vue.use(VueAnnouncer, {
82-
complementRoute: 'ha cargado' // e.g. in spanish
83-
}, router)
84-
```
85-
86-
### Methods
87-
**Note: These methods are registered on the `$announcer` property injected into the Vue instance**
88-
89-
#### `$announcer.setComplementRoute(complementRoute)`
90-
91-
If you need to set the `complementRoute` option dynamically without reloading the application, for example if you're
92-
dynamically loading translations, you can use this method to update it.
93-
94-
```javascript
95-
export default {
96-
onTranslationsUpdated (translations) {
97-
this.$announcer.setComplementRoute(translations.complementRouteKey /* = 'ha cargado' */)
98-
}
99-
}
100-
```
101-
102-
### Custom message to each page (optional)
103-
You can set a property on the meta object, which will serve as information to get the message that will be announced to the screen reader on each page. e.g.:
104-
```javascript
105-
{
106-
name: 'home',
107-
path: '/',
108-
component: Home,
109-
meta: {
110-
announcer: 'Página de inicio'
111-
}
112-
}
113-
```
114-
115-
When the page loads, the screen reader user will hear:
116-
```shell
117-
Página de inicio ha cargado
118-
```
119-
120-
121-
122-
**Note:**
123-
- The plugin checks whether it was defined in the meta object, otherwise, without any problems, the title of the page being loaded will be used.
124-
- The vue-announcer uses the global after hooks `router.afterEach` to announce the route changes.
63+
[see more in the documentation](https://announcer.vue-a11y.com/)
12564

12665
## Check live demo
12766
https://vue-announcer.surge.sh/
@@ -130,18 +69,18 @@ https://vue-announcer.surge.sh/
13069
```shell
13170
git clone https://github.com/vue-a11y/vue-announcer.git vue-announcer
13271

133-
// Run plugin
72+
# Run plugin
13473
cd vue-announcer
13574
npm install
13675
npm run dev
13776

138-
// Run example
77+
# Run example
13978
cd examples
14079
npm install
14180
npm run dev
14281
cd ..
14382

144-
// Run Cypress testing
83+
# Run Cypress testing
14584
npm run test
14685
```
14786

@@ -155,6 +94,7 @@ After the commands just access the http://localhost:8080/
15594

15695

15796
## Contributing
97+
- From typos in documentation to coding new features;
15898
- Check the open issues or open a new issue to start a discussion around your feature idea or the bug you found;
15999
- Fork repository, make changes and send a pull request;
160100

‎docs/.vuepress/config.js

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
module.exports = {
2+
title: 'Vue announcer',
3+
description: '',
4+
serviceWorker: true,
5+
themeConfig: {
6+
home: false,
7+
repo: 'vue-a11y/vue-announcer',
8+
docsDir: 'docs',
9+
locales: {
10+
'/': {
11+
editLinkText: 'Edit this page on GitHub',
12+
nav: [
13+
{
14+
text: 'Guide',
15+
link: '/guide/'
16+
},
17+
{
18+
text: 'How to',
19+
link: '/demos/'
20+
}
21+
],
22+
sidebar: [
23+
'/',
24+
{
25+
title: 'Guide',
26+
collapsable: false,
27+
children: [
28+
'/guide/',
29+
'/guide/announcer.md',
30+
'/guide/announcer-router.md',
31+
'/guide/accessibility.md',
32+
'/guide/support.md',
33+
]
34+
},
35+
{
36+
title: 'How to',
37+
collapsable: false,
38+
children: [
39+
'/demos/',
40+
'/demos/nuxt.md',
41+
'/demos/vuepress.md'
42+
]
43+
}
44+
]
45+
}
46+
}
47+
}
48+
}

‎docs/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Introduction
2+
3+
Imagine browsing pages (routes), receiving alerts and notifications, having a countdown timer on the page, a progress bar, a loading or a change of route in a SPA. Now imagine all this happening to people who have visual disabilities and who use screen readers.
4+
5+
The [vue-announcer](https://github.com/vue-a11y/vue-announcer) provides an easy way to really tell what’s going on in your application to people using screen readers.
6+
7+
Inspired by others in the community like:
8+
- [Example of how creating an accessible single-page application](https://haltersweb.github.io/Accessibility/spa.html)
9+
- [Ember A11y community](https://github.com/ember-a11y/a11y-announcer)

‎docs/demos/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Use in Vue
2+
3+
### Coming soon

‎docs/demos/nuxt.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Use in Nuxt.js
2+
3+
### Coming soon

‎docs/demos/vuepress.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Use in Vuepress
2+
3+
### Coming soon

‎docs/guide/README.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Installation
2+
3+
## Package
4+
5+
#### NPM
6+
```shell
7+
npm install -S vue-announcer
8+
```
9+
10+
#### Yarn
11+
```shell
12+
yarn add vue-announcer
13+
```
14+
15+
## Basic usage
16+
17+
```javascript
18+
import Vue from 'vue'
19+
import VueAnnouncer from 'vue-announcer'
20+
21+
Vue.use(VueAnnouncer)
22+
```
23+
24+
In your `App.vue`
25+
```vue
26+
<template>
27+
<div>
28+
<vue-announcer />
29+
<!-- header code -->
30+
<!-- router-view -->
31+
<!-- footer code -->
32+
</div>
33+
</template>
34+
```

‎docs/guide/accessibility.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# ARIA live regions
2+
3+
> Using JavaScript, it is possible to dynamically change parts of a page without requiring the entire page to reload — for instance, to update a list of search results on the fly, or to display a discreet alert or notification which does not require user interaction. While these changes are usually visually apparent to users who can see the page, they may not be obvious to users of assistive technologies. ARIA live regions fill this gap and provide a way to programmatically expose dynamic content changes in a way that can be announced by assistive technologies.
4+
--- [ARIA live regions - Accessibility | MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)
5+
6+
## Politeness settings
7+
8+
You can use the options `polite`, `assertive` and `off`, if no configuration is defined, the default is `off`.
9+
10+
### polite
11+
It is used in most situations that present new information to users.
12+
The notification will take place at the next available point, without interruptions.
13+
14+
::: tip Note
15+
In the [vue-announcer plugin](https://github.com/vue-a11y/vue-announcer/blob/master/src/index.js#L8) the default is `polite`
16+
:::
17+
18+
### assertive
19+
It is used in situations where the notification is important enough to communicate it immediately, for example, error messages or alerts.
20+
21+
22+
23+
```javascript
24+
this.$announcer.set('My notification error', 'assertive')
25+
```
26+
27+
### off
28+
Is the default and prevent assistive technology from keeping up with changes.
29+
30+
31+
## Referencies
32+
33+
- [ARIA live regions - Accessibility | MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)
34+
- [Using aria-live - Bitsofcode](https://bitsofco.de/using-aria-live/)

0 commit comments

Comments
 (0)