forked from benkeen/generatedata
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdeveloper.html
444 lines (396 loc) · 19.5 KB
/
developer.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
<!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="#intro"><i class="icon-chevron-right"></i> Introduction</a></li>
<li><a href="#modules"><i class="icon-chevron-right"></i> Module Types</a></li>
<li><a href="#code"><i class="icon-chevron-right"></i> Code Architecture</a></li>
<li><a href="#i18n"><i class="icon-chevron-right"></i> Translations / I18N</a></li>
<li><a href="#sasssss"><i class="icon-chevron-right"></i> SASS</a></li>
<li><a href="#bundling"><i class="icon-chevron-right"></i> Minification and Bundling</a></li>
</ul>
</div>
<div class="span9">
<section id="intro">
<div class="hero-unit">
<h1>Developer Doc</h1>
<p>
This document explains more than you ever wanted to know about the Data Generator:
how it works, how it's structured, and how to extend it. May the thrills commence.
</p>
</div>
<h2>Introduction</h2>
<p>
If you haven't already done so check out the <a href="http://www.generatedata.com" target="_blank">script
online</a> and generate some data. You should have a general sense about what the script does
before you bother reading any further.
</p>
<p>
Version 3.0.0 of the Data Generator was a complete redesign of the script to make it properly <i>modular</i>:
now it's primarily an <i>engine</i> that includes an interface, installation script, user account
system, and a standardized way for plugins to be integrated with the script. The really interesting part
is the plugins themselves: they provide all the functionality of the script. And that's where you come in.
</p>
<p>
The Developer Doc focuses on how you, as a developer, can write new modules. Different module types require
degrees of technical knowledge: providing new translations is very basic; providing new country plugins is
fairly simple, but requires basic PHP; creating new Export and Data Types are complicated and will require
both JS and PHP expertise. But I'm getting ahead of myself... let's start with an overview to the
module types.
</p>
</section>
<hr size="1" />
<section id="modules">
<h2>Module Types</h2>
<p class="alert alert-info">
Note: the words <b>plugin</b> and <b>module</b> are used synonymously.
</p>
<p>
The Data Generator accommodates the following types of module:
</p>
<table class="table table-bordered table-striped">
<tr>
<td width="120"><a href="dataTypes.html">Data Types</a></td>
<td>
<p>
These govern what kind of data can be generated through the interface. You get a huge amount of control and
customizability out of these suckers. For example:
</p>
<ul>
<li>They can generate anything you want - strings, numbers, URLs, images, binary data, code, ascii art, you
name it.</li>
<li>They can display any arbitrary settings to allow in-row configuration by the user, customizing the
particular output for the Data Type row.</li>
<li>You can add custom JS validation to ensure the values are well formed.</li>
<li>They can access and depend on other Data Types in the generated result sets to customize their output.</li>
<li>They can generate different content depending on the selected Export Type (HTML, CSV, XML, etc.)
and the export target (in-page, prompt to download, new tab).
</ul>
<a href="dataTypes.html" class="btn btn-primary btn-small">More about Data Types »</a>
</td>
</tr>
<tr>
<td><a href="exportTypes.html">Export Types</a></td>
<td>
<p>
Export Types are the formats in which the data is actually generated: XML, HTML, CSV, JSON, etc.
</p>
<a href="exportTypes.html" class="btn btn-primary btn-small">More about Export Types »</a>
</td>
</tr>
<tr>
<td><a href="countryPlugins.html">Country Plugins</a></td>
<td>
<p>
In order to generate realistic-looking human-related data, you need to actually provide the
data set to pull from. The Country plugins let you do just this: you provide some data
country, regions and cities for a particular country. This allows various Data Types to intelligently
generate rows of data with regions, cities and postal codes that match the country selected. These are
very simple plugins to create.
</p>
<a href="countryPlugins.html" class="btn btn-primary btn-small">More about Country Data »</a>
</td>
</tr>
<tr>
<td><a href="translations.html">Translations</a></td>
<td>
<p>The entire Data Generator interface is translatable. At the top right of the interface, there's a dropdown
that lists all available languages. The default languages other than English were auto-generated with
Google Translate. As such, they're in need of proper translations! Click the button below to learn more
about translations and how to provide your own / update the existing ones.</p>
<a href="translations.html" class="btn btn-primary btn-small">More about Translations »</a>
</td>
</tr>
</table>
</section>
<hr size="1" />
<section id="code">
<h2>Code Architecture</h2>
<p>
A few words on how the code is organized, to give you a sense of how it all fits together.
</p>
<h3>PHP</h3>
<p>
The <code>settings.php</code> found in the root folder contains the unique settings for the current
installation - MySQL database settings, and so on. This file is automatically created by
the installation script. <i>This is the only file that contains custom information for
the installation</i>.
</p>
<p>
The PHP codebase is <b>object-oriented</b>, with all core classes found in <code>/resources/classes/</code>.
The <code>library.php</code> file - again found in the root - is used as the main entry point: all code
that needs access to the core codebase just needs to include that single file.
</p>
<h4>Core.class.php</h4>
<p>
The <code>Core.class.php</code> file is special. It's a static class (or would be if PHP permitted it!)
that acts as the global namespace for the backend code. When <code>Core::init()</code> is run, it does
all the stuff you need to run the script, namely:
</p>
<ul>
<li>Parses the <code>settings.php</code> file and stores all the custom settings for the environment.</li>
<li>Makes a connection to the database.</li>
<li>Automatically handles serious errors like database connection problems, or Smarty not being able to generate
the page due to permission errors.</li>
<li>Loads up all Data Types, Export Types and Country plugins and renders them appropriately on the screen.</li>
<li>Loads the current language file.</li>
<li>Lots of other nagging juicy stuff.</li>
</ul>
<p>
It also contains numerous helper functions. Check out the source code for more details.
</p>
<h4>Smarty Templates</h4>
<p>
<i>So... where the hell's the markup?</i> If you're anything like me, you hate examining a new codebase to find
you can't even track down the HTML. I know, it's annoying. Check out <code>/resources/templates/</code>. That contains the bulk of the HTML used to generate
webpages. You can read more about Smarty <a href="http://smarty.net" target="_blank">on their website</a>. The script
uses version 3.
</p>
<h4>Custom Smarty Functions</h4>
<p>
When you look through the templates, you may notice the occasional non-standard Smarty function, like
<code>{country_plugins}</code>. These are all found in <code>/resources/libs/smarty/plugins/</code>. That's actually
the same folder as all the default Smarty modules and functions. If you're not familiar with Smarty, it's worth
fishing through that folder to get an idea of how those files map to actual functions and modifies that you can
use in the Smarty templates.
</p>
<h3>JavaScript</h3>
<p>
The client-side code is built around <a href="http://requirejs.org/" target="_blank">requireJS</a>. All the
JS module code works the same way, regardless of whether the code is the Core, for a Data Type or Export
Type. Country plugins are entirely PHP - no JS required.
</p>
<ul>
<li>Each module is sandboxed by RequireJS, to ensure it doesn't pollute the global namespace.</li>
<li>Modules interact with one another using <b>publish / subscribe messages</b>, not by calling one another
directly.</li>
<li>All modules register themselves with the <b>Manager</b>, which is found here: <code>/resources/scripts/manager.js</code>.
The Manager handles all pub/sub messaging and ensuring that the module being registered contains all the
required functions in order to integrate with the script.</li>
<li>All save/load functionality for a Data Type and Export Type is done via the JS module. When the user saves
or loads a data set via the interface, the core script calls all appropriate module's JS module files that
serialize the data for database storage, or are passed the information to re-populate the page data. It's
actually pretty simple once you see it in action: see the <a href="dataTypes.html">Data Types</a> or
<a href="exportTypes.html">Export Types</a> pages for more information.</li>
</ul>
<p>
The pub/sub messages can be viewed right in the Data Generator by going to the <code>Settings</code> tab and
choosing which information you want to see in your browser console through the <code>Developer</code> section.
</p>
<p>
See the appropriate module documentation section for more info on how all this works from a practical
viewpoint.
</p>
</section>
<hr size="1" />
<section id="i18n">
<h2>Translations / I18N</h2>
<p>
The Data Generator has built-in multi-language support; a user can easily change the UI language via a dropdown
and the page automatically redraws with the new language. This means all language strings for the Core and all
plugins need to be extracted and placed
</p>
<p>
After a lot of humming and hawing, I decided to use a simple PHP array to store the language strings.
The Core language strings are found in <code>/resources/lang/</code>. There you'll see there's a separate file
for each language. The Data Types and Export Types all have their own language files which need to be stored in a
<code>/plugins/[data-or-export-type-folder]/lang/</code> folder. When the user picks a language through the interface,
the Core script automatically figures out what language files are present and attempts to load the right one. If it
can't find it, it will load the default English one (yes, an <code>en.php</code> language file is required for
Data and Export Type modules).
</p>
<h3>Google Translate auto-translations</h3>
<p>
The base translation is provided by Google Translate. It's pretty poor, but it's better than nothing.
I'd LOVE people to help improve the translations! For more info on that, see the
<a href="translations.html">Translations</a> page.
</p>
</section>
<hr size="1" />
<section id="sasssss">
<h2>SASS</h2>
<p>
In the unlikely event of you needing to tweak the CSS for the Core script, bear in mind it's auto-generated
based on SASS templates so updating the CSS is the wrong way to go about it. You'll need to edit the
SASS files at <code>/resources/themes/[theme]/sass/</code>.
</p>
<p>
Check out <a href="http://sass-lang.com/">sass-lang.com</a> for more information.
</p>
</section>
<hr size="1" />
<section id="bundling">
<h2>Resource Minification and Bundling</h2>
<p>
In version 3.0.7, I added optional CSS and JS minification and bundling to speed up load times. I figure
in most scenarios you won't much care about this, since it'll be running in a local environment
and will be pretty speedy to load anyway. But if you <i>do</i> want to improve page load times and
reduce the total bandwidth for the script, here's how to go about it. Please bear in mind I really
only added this for the sake of the <a href="http://www.generatedata.com">public website</a>, so
it's not as simple as the rest of the script to get going. Apologies.
</p>
<h4>How to set up</h4>
<ol>
<li>
To create the minified and bundled files, you need to have Node installed. Download it from
<a href="http://nodejs.org/">nodejs.org/</a>. It runs on all platforms.
</li>
<li>
After installing it, in Terminal / the Windows command prompt, navigate to the generatedata
folder and type the following command: <code>npm install</code>. If node is configured, it
will download all the necessary files.
</li>
<li>
Next, type <code>npm install -g grunt-cli</code>. That installs the grunt command line tools
so you can run grunt from the command line.
</li>
<li>
In Generate Data, click on the "Reset Plugins" button on the Settings tab.
</li>
<li>
On the command line, type <code>grunt</code>. That should create all the new files.
</li>
<li>
In your <code>settings.php</code> file, add the following line: <code>$useMinifiedResources = true;</code>
</li>
</ol>
<p>
And that should be it. It should have created a number of different files in your /cache folder
(CSS and JS), which should now be linked to in the script's webpages.
</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>