README.md 9.97 KB
Newer Older
Bastien Le Querrec's avatar
Bastien Le Querrec committed
1
2
3
4
# ParlementairesJS - Display information about MPs and engage your audience to contact them

ParlementairesJS displays a simple frame to show phone numbers, email addresses, Twitter accounts and Facebook links about MPs. Filters can be configured to match campaign's requirements.

Bastien Le Querrec's avatar
Bastien Le Querrec committed
5
Demo: https://parlementairesjs.eu.org/demo.html
Bastien Le Querrec's avatar
Bastien Le Querrec committed
6

Bastien Le Querrec's avatar
Bastien Le Querrec committed
7
8
## Usage

9
10
### Javascript (recommended)

Bastien Le Querrec's avatar
Bastien Le Querrec committed
11
12
13
1. In the `<head>` section, you must include the script and its CSS:

```html
Bastien Le Querrec's avatar
Bastien Le Querrec committed
14
15
<script src="https://parlementairesjs.eu.org/parlementaires.js"></script>
<link rel='stylesheet' href='https://parlementairesjs.eu.org/parlementaires.css' type='text/css' media='all' />
Bastien Le Querrec's avatar
Bastien Le Querrec committed
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
```

You can download a copy of the `parlementaires.js` and `parlementaires.css` and load your local copy.

2. You need to add a `<div>` element in your web page, where the frame will be displayed. This `<div>` must have an ID.

3. Add the following code at the end of your web page, before the `</body>`:

```html
<script>
    ParlementairesJS({
        dataset: "/json/an.json",
        datasetConfig: "/json/an-config.json"
    }).display('id-of-your-div');
</script>
```

You must set at least the `dataset` and `datasetConfig` values. Change the `id-of-your-div` with the ID of your `<div>` you added in stage 2.

35
### Options
Bastien Le Querrec's avatar
Bastien Le Querrec committed
36
37
38
39
40
41
42
43

| Option             | Mandatory? | Description                                                                               | Default               |
| ------------------ | ---------- | ----------------------------------------------------------------------------------------- | --------------------- |
| `dataset`          | true       | URL of the MPs' dataset.                                                                  | N/A                   |
| `datasetConfig`    | true       | URL of the dataset's configuration.                                                       | N/A                   |
| `commissionFilter` | false      | Display MPs that are in the specified commission.                                         | No filter is applied. |
| `writeHTML`        | false      | Write the HTML in the `<div>`. Disable this if you want to change the current stylesheet. | `true`                |
| `photoInImg`       | false      | Put the image in a `<img>` instead of in a `<div>`.                                       | `false`               |
Bastien Le Querrec's avatar
typo    
Bastien Le Querrec committed
44
45
| `phoneFilter`      | false      | Display phone numbers that start with this value.                                         | No filter is applied. |
| `mailFilter`       | false      | Display emails with the specified domain name.                                            | No filter is applied. |
Bastien Le Querrec's avatar
Bastien Le Querrec committed
46
47
| `twitter`          | false      | Display Twitter link.                                                                     | `true`                |
| `facebook`         | false      | Display Facebook link.                                                                    | `true`                |
48
| `download`         | false      | Display a link to download data as a CSV file.                                            | `true`                |
49
| `hiddenGroups`     | false      | Do not display MPs in on of the specified parliamentary group.                            | `[]`                  |
Bastien Le Querrec's avatar
Bastien Le Querrec committed
50

51
52
53
54
55
56
57
## Iframe (fallback)

If you are unable to add a script to your web page, you can fallback to the iframe method. Please note that you cannot have a custom CSS nor options by doing this. Datasets available are limited to those [listed bellow](#datasets-and-their-configuration).

Without a filter:

```html
Bastien Le Querrec's avatar
Bastien Le Querrec committed
58
<iframe src="https://parlementairesjs.eu.org/iframe.html#dataset" frameborder="1" width="100%" height="640px">
59
60
61
62
63
```

With a filter:

```html
Bastien Le Querrec's avatar
Bastien Le Querrec committed
64
<iframe src="https://parlementairesjs.eu.org/iframe.html#dataset-filter" frameborder="1" width="100%" height="640px">
65
66
```

Bastien Le Querrec's avatar
Bastien Le Querrec committed
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
## Generated HTML

The following HTML is generated:

```html
<div id="id-of-your-div">
    <div id="parlementairesjs_introphone_wrapper">
        <p class="parlementairesjs_introphone">
            Au hasard parmi les <span id="parlementairesjs_mp_total">576</span> député·es de
            <select id="parlementairesjs_select_group">
                <option value="0">tous les groupes</option>
            </select>
            <br> et de
            <select id="parlementairesjs_select_county">
                <option value="0">toutes les circonscription</option>
            </select>
        </p>
    </div>
    <div id="parlementairesjs_mp_photo_info_wrapper">
        <div id="parlementairesjs_mp_photo_wrapper">
            <div id="parlementairesjs_mp_photo" style="width: 150px; height: 192px; background-image: url('http://localhost:8000//images/an/334116.jpg');"></div>
        </div>
        <div id="parlementairesjs_mp_info" style="display: block;">
            <p id="parlementairesjs_mp_name_wrapper">
                <span id="parlementairesjs_mp_first_name">John</span> <span id="parlementairesjs_mp_last_name">Doe</span>
            </p>
93
94
            <p id="parlementairesjs_mp_group">Some Group</p>
            <p id="parlementairesjs_mp_county">Some county</p>
Bastien Le Querrec's avatar
Bastien Le Querrec committed
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
            </p>
            <div id="parlementairesjs_mp_phone">
                <p>
                    <a class="parlementairesjs_mp_phone_child" href="tel:+33123456789">01 23 45 67 89</a>
                    <a class="parlementairesjs_mp_phone_child" href="tel:+33600000000">+33600000000</a>
                </p>
            </div>
            <div id="parlementairesjs_mp_mail">
                <p>
                    <a class="parlementairesjs_mp_mail_child" href="mailto:john.doe@example.org">john.doe@example.org</a>
                    <a class="parlementairesjs_mp_mail_child" href="mailto:john.doe2@example.org">john.doe2@example.org</a>
                </p>
            </div>
            <p id="parlementairesjs_mp_twi">
                <a class="parlementairesjs_mp_twi_child" href="https://twitter.com/SommeTwitterAccount" target="_blank">@SommeTwitterAccount</a>
            </p>
            <p id="parlementairesjs_mp_fb">
                <a class="parlementairesjs_mp_fb_child" href="https://www.facebook.com/SomeFacebookLink" target="_blank">SomeFacebookLink</a>
            </p>
        </div>
    </div>
    <div id="parlementairesjs_mp_next_wrapper">
        <p id="parlementairesjs_mp_next">Député·e suivant·e &gt;</p>
    </div>
119
120
121
    <div id="parlementairesjs_csv_wrapper">
        <p id="parlementairesjs_csv">Télécharger les données au format CSV</p>
    </div>
Bastien Le Querrec's avatar
Bastien Le Querrec committed
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
</div>
```

You can override CSS style using those HTML classes and IDs.

If you set `writeHTML` to `false`, your HTML must have the following elements:

- `parlementairesjs_mp_total`
- `parlementairesjs_select_group`
- `parlementairesjs_mp_photo` (if `photoToImg` is `false`)
- `parlementairesjs_mp_photo_img` (if `photoToImg` is `true`)
- `parlementairesjs_mp_first_name`
- `parlementairesjs_mp_last_name`
- `parlementairesjs_mp_group`
- `parlementairesjs_mp_county`
- `parlementairesjs_mp_phone`
- `parlementairesjs_mp_mail`
- `parlementairesjs_mp_twi`
- `parlementairesjs_mp_fb`
- `parlementairesjs_mp_info`
- `parlementairesjs_mp_next`
143
- `parlementairesjs_csv` (if `download` is `true`)
Bastien Le Querrec's avatar
Bastien Le Querrec committed
144
145
146
147
148
149
150

## Datasets and their configuration

Datasets must be shipped with their configuration. Datasets contain MPs, configurations contain information about formatting.

Available datasets:

Bastien Le Querrec's avatar
Bastien Le Querrec committed
151
152
153
154
| Name                         | ID      | Description               | Data's source                                                                                |
| ---------------------------- | ------- | ------------------------- | -------------------------------------------------------------------------------------------- |
| Assemblée nationale (France) | `an`    | French national assembly. | Chamber's open data + additional listing for phone numbers (see `scripts/an.sh` for details) |
| Sénat (France)               | `senat` | French Senate.            | Chamber's open data (see `scripts/senat.sh` for details)                                     |
Bastien Le Querrec's avatar
Bastien Le Querrec committed
155

Bastien Le Querrec's avatar
Bastien Le Querrec committed
156
Datasets are available at `https://parlementairesjs.eu.org/json/<dataset>.json` and their configuration at `https://parlementairesjs.eu.org/json/<dataset>-config.json`.
Bastien Le Querrec's avatar
Bastien Le Querrec committed
157
158
159
160
161

You can generate a dataset with `make <dataset-id>`.

## Create your dataset

Bastien Le Querrec's avatar
Bastien Le Querrec committed
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
Generated datasets are located at `data/<id>/dataset.json` and their configuration is at `data/<id>/config.json`. Each dataset must be generated by a script located at `scripts/<id>.sh`. If you need to have other data in the git tree to include in the generation process, put it in the `misc/<id>/` folder.

Generated datasets are a JSON array like this:

```json
[
  {
    "id": "XXXXXX",
    "last_name": "John",
    "first_name": "Doe",
    "group": "Some group",
    "county": "Some county",
    "commissions": [
      "A first commission",
      "Another commission"
    ],
    "phone": [
      "0123456789",
      "+33600000000"
    ],
    "email": [
      "john.doe@example.org",
      "john.doe2@example.org"
    ],
    "twitter": "SommeTwitterAccount",
    "facebook": "SomeFacebookLink",
    "photo": "XXXXXX"
  },
  {
    "id": "YYYYYY",
    "last_name": "John",
    "first_name": "Doe",
    "group": "Some group",
    "county": "Some county",
    "commissions": [
      "A first commission",
      "Another commission"
    ],
    "phone": [
      "0123456789",
      "+33600000000"
    ],
    "email": [
      "john.doe@example.org",
      "john.doe2@example.org"
    ],
    "twitter": "SommeTwitterAccount",
    "facebook": "SomeFacebookLink",
    "photo": "YYYYYY"
  }
]
Bastien Le Querrec's avatar
Bastien Le Querrec committed
213
214
```

Bastien Le Querrec's avatar
Bastien Le Querrec committed
215
Mandatory fields are `last_name`, `first_name`.
Bastien Le Querrec's avatar
Bastien Le Querrec committed
216
217
218

Configuration files must follow that format:

Bastien Le Querrec's avatar
Bastien Le Querrec committed
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
```json
{
  "designation": {
    "singular": "député·e",
    "plural": "député·es"
  },
  "phone": {
    "local_prefix": "33",
    "separator": " ",
    "group_size": 2
  },
  "img": {
    "baseURL": "/data/gen/an/images/",
    "width": "150px",
    "height": "192px"
  }
}
Bastien Le Querrec's avatar
Bastien Le Querrec committed
236
237
238
239
240
241
242
```

All fields are mandatory. `baseURL` can be a relative URL or with a FQDN. For privacy issues, you should get a copy of MPs' photos in `images/<id>/` and use a relative `baseURL`.

## License

Source code is MIT licensed. Data may have a different license.