forked from benkeen/generatedata
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcountryPlugins.html
494 lines (439 loc) · 18.1 KB
/
countryPlugins.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
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
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Data Generator</title>
<link href="assets/css/bootstrap.css" rel="stylesheet">
<link href="assets/css/bootstrap-responsive.css" rel="stylesheet">
<link href="assets/css/docs.css" rel="stylesheet">
<link href="assets/js/google-code-prettify/prettify.css" rel="stylesheet">
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body data-spy="scroll" data-target="#pagenav">
<div class="navbar navbar-inverse navbar-fixed-top">
<div class="navbar-inner">
<div class="container-fluid">
<ul class="nav">
<li id="mainTitle">
<button id="mobileNavLink" data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar" type="button">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a href="index.html"></a>
</li>
<li>
<ul id="mainNav" class="nav">
<li><a href="index.html">User Doc</a></li>
<li class="active dropdown">
<a href="developer.html" class="dropdown-toggle" data-toggle="dropdown">Developer Doc <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="developer.html">Introduction</a></li>
<li class="divider"></li>
<li class="nav-header">Module Types</li>
<li><a href="dataTypes.html">Data Types</a></li>
<li><a href="exportTypes.html">Export Types</a></li>
<li><a href="countryPlugins.html">Country Plugins</a></li>
<li class="divider"></li>
<li><a href="translations.html">Translations</a></li>
</ul>
</li>
<li><a href="api.html">API</a></li>
<li><a href="contribute.html">Contributing</a></li>
<li><a href="scriptsUsed.html">Scripts Used</a></li>
</ul>
<ul id="tabletNav" class="nav">
<li class="dropdown">
<a href="developer.html" class="dropdown-toggle" data-toggle="dropdown">Menu <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="index.html">User Documentation</a></li>
<li><a href="install.html">How to Install</a></li>
<li class="divider"></li>
<li class="nav-header">Developer Documentation</li>
<li><a href="developer.html">Introduction</a></li>
<li class="divider"></li>
<li class="nav-header">Module Types</li>
<li><a href="dataTypes.html">Data Types</a></li>
<li><a href="exportTypes.html">Export Types</a></li>
<li><a href="countryPlugins.html">Country Plugins</a></li>
<li class="divider"></li>
<li><a href="translations.html">Translations</a></li>
<li class="divider"></li>
<li><a href="contribute.html">How to Contribute / Contact Me</a></li>
<li><a href="scriptsUsed.html">Scripts Used</a></li>
</ul>
</li>
</ul>
<ul id="mobileNav" class="nav">
<li class="dropdown">
<div class="nav-collapse collapse">
<ul class="dropdown-menu">
<li><a href="index.html">User Documentation</a></li>
<li><a href="install.html">How to Install</a></li>
<li class="divider"></li>
<li class="nav-header">Developer Documentation</li>
<li><a href="developer.html">Introduction</a></li>
<li class="divider"></li>
<li class="nav-header">Module Types</li>
<li><a href="dataTypes.html">Data Types</a></li>
<li><a href="exportTypes.html">Export Types</a></li>
<li><a href="countryPlugins.html">Country Plugins</a></li>
<li class="divider"></li>
<li><a href="translations.html">Translations</a></li>
<li class="divider"></li>
<li><a href="contribute.html">How to Contribute / Contact Me</a></li>
<li><a href="scriptsUsed.html">Scripts Used</a></li>
</ul>
</div>
</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="span3 bs-docs-sidebar" id="pagenav">
<ul class="nav nav-list bs-docs-sidenav" data-spy="affix">
<li class="active"><a href="#overview"><i class="icon-chevron-right"></i> Overview</a></li>
<li><a href="#limitations"><i class="icon-chevron-right"></i> Limitations</a></li>
<li><a href="#add_your_own"><i class="icon-chevron-right"></i> Add your own</a></li>
<li><a href="#extended_data"><i class="icon-chevron-right"></i> Extended Data</a></li>
<li><a href="#contribute"><i class="icon-chevron-right"></i> Contribute your plugin</a></li>
</ul>
</div>
<div class="span9">
<section id="overview">
<div class="page-header">
<h1>Country Plugins</h1>
</div>
<p class="lead">
Allow the script to generate more realistic, country-specific data.
</p>
</section>
<section>
<h2>Overview</h2>
<p>
The primary purpose of the script is to generate <i>realistic-looking</i> fake/test data. So when it comes
to human-centric geographical information, it needs the actual raw data - city and region names - in
order to do its job. That's where the Country plugins come in: they let you provide the following information
about any country:
</p>
<ol>
<li>High-level geographical political groupings: regions / provinces / states / territories, etc.</li>
<li>City / town names for those regions</li>
<li>
<b>Extended Data</b> - as of 3.0.6, Country plugins may now contain an optional extended data section
that contains whatever additional information may be needed by any Data Types. This currently
includes zip codes and phone numbers. You can choose to make that data generic for the country as a whole,
or make it overridable per region. For example, some Country plugins define custom zip code formats
for each region; others define custom area codes for phone numbers. But the idea is that it's a generic
data structure that can be appended to over time without changing the structure of the Country class.
</li>
</ol>
</section>
<hr size="1" />
<section id="limitations">
<h2>Limitations</h2>
<p>
The Country plugins are currently pretty basic. Right now, all they're used for is to try to keep the data across a single
generated row looking as consistent as possible. So if the generated row contains "Canada" for the <code>Country</code>
field, it will pick a Canadian province for any <code>Region</code> fields, and any cities within that region for any
<code>City</code> fields. A few more interesting caveats:
</p>
<ul>
<li>If the user didn't select the "Limit countries to those selected above" for a <code>Country</code> row, it will randomly
pick any country from the list (200 or so). If the country being outputted for a row doesn't have a corresponding
Country-plugin, it will arbitrarily pick any region, city and postal/zip code (since it won't know any better!)</li>
<li>If the data set being generated doesn't contain a <code>Country</code> or <code>Region</code> field, the cities
will just be arbitrarily chosen.</li>
</ul>
</section>
<hr size="1" />
<section id="add_your_own">
<h2>Add your own</h2>
<p>
Adding your own country-plugin is very simple. Knowing a little PHP would help a lot, but with common
sense and a bit of patience, you can probably get by just fine. But before we get into the details, remember
this:
</p>
<p class="alert alert-info">
<b>Important</b>: the purpose of a Country plugin isn't to provide a 100% accurate, 100% complete
list of regions and cities for a country: it's to provide <i>enough</i> information so that the
generated data looks valid.
</p>
<p>
If you were to add in every region and every city/town within a country, the data set could get
extremely large, which could slow down the data generation.
</p>
<p>
Now that's over with, here's how to create a
</p>
<ol>
<li>
In the <code>/plugins/countries</code> folder, create a new folder for your country. The folder name
should be the country name with no spaces, and camel-case - i.e. an upper case letter for each word
in the country name, like <code>PapuaNewGuinea</code>.
</li>
<li>Create a single file in that folder called <code>PapuaNewGuinea.class.php</code> (where PapuaNewGuinea
is the name of the folder you just created) and add in the following PHP.</li>
</ol>
<pre class="prettyprint linenums">
<?php
/**
* @package Countries
*/
class Country_PapuaNewGuinea extends CountryPlugin {
protected $countryName = "Papua New Guinea";
protected $countrySlug = "papuanewguinea";
protected $regionNames = "Papua New Guinean Provinces";
protected $continent = "oceania";
protected $countryData = array(
array(
"regionName" => "Province Name 1",
"regionShort" => "PN1",
"regionSlug" => "province_name_1",
"weight" => 1,
"cities" => array(
"City Name 1", "City Name 2"
)
),
array(
"regionName" => "Province Name 2",
"regionShort" => "PN2",
"regionSlug" => "province_name_2",
"weight" => 1,
"cities" => array(
"City Name 3", "City Name 4"
)
)
);
public function install() {
return CountryPluginHelper::populateDB(
$this->countryName,
$this->countrySlug,
$this->countryData
);
}
}
</pre>
<ol start="3">
<li>Now edit that file for your own country data. Here's the important stuff.
<ul>
<li>
<b>First line</b>. On this line, all you need to do is change the class name to end with
<code>_YourCountry</code>. e.g.
<pre class="prettyprint">class Country_YourCountry extends CountryPlugin {</pre>
</li>
<li><b>$countryName</b>. This is your country name. </li>
<li><b>$countrySlug</b>. This is the country name without any spaces or non a-Z characters.</li>
<li><b>$regionNames</b>. Different countries subdivide their political geographic regions in
different ways. For example, Canada has provinces, the US has states, the UK has counties and
so on. Just enter a string like "UK Counties"; this is used in the interface of the Region
Data Type to let users know what data they want to generate.
</li>
<li><b>$continent</b>. This is the name of the continent. The following options are
available (note: these must be entered <i>exactly</i> as written, otherwise your
plugin won't show up: <code>africa</code>, <code>asia</code>, <code>europe</code>,
<code>central_america</code>, <code>north_america</code>, <code>oceania</code>,
<code>south_america</code>.
</li>
<li>
<b>$countryData</b>. The regions and cities/towns are all stored in a single data
structure, grouped by region. Hopefully it's pretty self-explanatory from looking at the
example above, but there are a couple of things to note:
<ul>
<li><b>regionShort</b>. This is whatever form of abbreviation is use for the region.
e.g. US States have a single two-letter code for states, as do Canadian provinces. If
your country doesn't use abbreviations for the region, just enter the full region name again.</li>
<li><b>weight</b>. This field lets you optionally weight the region to increase / decrease the
likelihood of random data being pulled from this region. If, say, one of your regions contained
90% of the population, you could enter "90" for this value, then have the rest of the regions
add up to 10. Note: the weights don't need to add up to any particular value. They simply
reflect the <i>relative</i> weights.
</ul>
</li>
</ul>
</li>
<li>
Lastly, to get your Country plugin to show up, go to the Settings tab in the generator and
click the "Reset Plugins" button.
</li>
</ol>
<p>
And that's it!
</p>
</section>
<hr size="1" />
<section id="extended_data">
<h2>Extended Data</h2>
<p>
You may have noticed that in the <code>PapuaNewGuinea</code> example above, there was no Zip / Postal code
data or Phone Number formats added for the country. Country plugins are designed to be flexible enough to
add <i>any</i> country- or region-specific format.
</p>
<p>
The basic pattern to adding extended data is to create two things:
</p>
<ol>
<li>
an <code>$extendedData</code>` protected member variable in the class that contains the default values
for the extended data.
</li>
<li>
Inside each region inside <code>$countryData</code>, define whatever region-specific data is needed.
</li>
<li>
Inside the Data Type, parse and interpret that data.
</li>
</ol>
<p>
Here's a couple of existing Data Types that use this feature.
</p>
<h3>Postal/Zip & Phone-Regional Data Types</h3>
<p>
At the time of writing, the only two Data Types that make use of country extended data
is the Postal/Zip and Phone-Regional data types. They both generate as appropriate a
value as they can, based on the selected countries and the value for the Country and
Region field in the data set.
</p>
<p>
Here's the first few lines of the Costa Rica Country Data Type. Take a look at
the <code>$extendedData</code> variable.
</p>
<pre class="prettyprint linenums">
<?php
/**
* @package Countries
*/
class Country_CostaRica extends CountryPlugin {
protected $continent = "central_america";
protected $countryName = "Costa Rica";
protected $countrySlug = "CR";
protected $regionNames = "Costa Rican Provinces";
protected $extendedData = array(
"zipFormat" => array(
"format" => "ZYxYx",
"replacements" => array(
"Z" => "1234567",
"Y" => "01",
"x" => "0123456789"
)
),
"phoneFormat" => array(
"displayFormats" => array(
"xxxxxxxx",
"xxxx-xxxx"
)
)
);
// ...
</pre>
<p>
The <code>$extendedData</code> variable can store whatever information is needed. For the zip format
it stores a general zip format for the whole country and a list of replacement values that are used
to generate the zip. The phone number needs a list (one is fine) of possible display formats for the
phone number. These are selectable via the UI.
</p>
<p class="alert alert-info">
Note: the Data Types are what handles all the actual data generation. The developers of those plugins
decide the structure of the extended data (for that section) and what info needs to be supplied. As a
Country plugin developer you just need to follow the pattern set out in other Country plugins.
</p>
<p>
To provide region-specific data, you'll need to include an <code>extendedData</code> key in the
region's data section, like as followed:
</p>
<pre class="prettyprint linenums">
protected $countryData = array(
array(
"regionName" => "Alajuela",
"regionShort" => "A",
"regionSlug" => "alajuela",
"weight" => 20,
"cities" => array(
"Alajuela", "Quesada", "San José de Alajuela", "San Rafael"
),
"extendedData" => array(
"zipFormat" => array(
"format" => "2zxYx",
"replacements" => array(
"z" => "01",
"Y" => "01",
"x" => "0123456789"
)
),
"phoneFormat" => array(
"format" => "24xxxxxx"
)
)
),
array(
// ...
</pre>
<p>
That will be used by the various data types to override the default values and provide more realistic
data for the country.
</p>
<p>
To keep your Country plugin up to date with whatever extended data is generally used, I'd suggest looking
through the various existing Country plugins and seeing what's defined. Extended data <i>should</i>
be optional, but naturally you'll want to make your plugin as compatible with as many Data Types
as possible.
</p>
</section>
<hr size="1" />
<section id="contribute">
<h2>Contribute your plugin</h2>
<p>
Sharing is much appreciated! To contribute your plugin, please just
<a href="https://github.com/benkeen/generatedata" target="_blank">fork
the project</a> on github and submit your changes via a pull request. This is certainly
the preferred method to contribute code, but if you don't think you're up for it you can
always <a href="mailto:[email protected]">email me</a> and I'll manually add it in. Please note,
all contributions will be expected to be available under the GPL license and released along with the
rest of the code. I'll be sure to add in your name as a contributor.
</p>
</section>
</div>
</div>
</div>
<script src="assets/js/jquery.js"></script>
<script src="assets/js/google-code-prettify/prettify.js"></script>
<script src="assets/js/bootstrap-transition.js"></script>
<script src="assets/js/bootstrap-alert.js"></script>
<script src="assets/js/bootstrap-modal.js"></script>
<script src="assets/js/bootstrap-dropdown.js"></script>
<script src="assets/js/bootstrap-scrollspy.js"></script>
<script src="assets/js/bootstrap-tab.js"></script>
<script src="assets/js/bootstrap-tooltip.js"></script>
<script src="assets/js/bootstrap-popover.js"></script>
<script src="assets/js/bootstrap-button.js"></script>
<script src="assets/js/bootstrap-collapse.js"></script>
<script src="assets/js/bootstrap-carousel.js"></script>
<script src="assets/js/bootstrap-typeahead.js"></script>
<script src="assets/js/bootstrap-affix.js"></script>
<script>$(function() { prettyPrint(); });</script>
<footer>
<div class="container">
<div class="row">
<div class="span12">
</div>
</div>
</div>
</footer>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-41026944-1', 'benkeen.github.io');
ga('send', 'pageview');
</script>
</body>
</html>