Skip to content

Commit 316a337

Browse files
coreationcoreation
committed
Added 5.12 docs
1 parent 05acbb7 commit 316a337

26 files changed

+1747
-3
lines changed

‎app/controllers/HomeController.php‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44

55
class HomeController extends BaseController
66
{
7-
87
public function handleRequest()
98
{
109

@@ -13,7 +12,7 @@ public function handleRequest()
1312

1413
// Default version of the documentation
1514
$page = 'introduction';
16-
$versions = array("4.0", "4.1", "4.2", "4.3", "4.6", "5.0", "5.6");
15+
$versions = array("4.0", "4.1", "4.2", "4.3", "4.6", "5.0", "5.6", "5.12");
1716
$version = end($versions);
1817

1918
// If not the root, then split the uri to find the content
@@ -32,7 +31,6 @@ public function handleRequest()
3231
$page = __DIR__ . '/docs/' . $version . '/' . $page . '.md';
3332

3433
if (file_exists($page)) {
35-
3634
$contents = file_get_contents($page);
3735
$sidebar = file_get_contents(__DIR__ . '/docs/' . $version . '/sidebar.md');
3836

‎app/controllers/docs/5.12/blueprints.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Blue prints
2+
3+
In this section you will learn
4+
5+
* [The big picture of the project](#project_setup)
6+
* [Our development cycles](#devcycle)
7+
8+
<a id='project_setup' class='anchor'></a>
9+
## The big picture
10+
11+
Our project's aim is to provide a tool that enables open data consumption in an easy, open and transparant way. This is achieved by providing an open source tool that can
12+
13+
* publish data in a RESTful way so that data consumers (e.g. app developers) don't have to download raw data files anymore but can get started right away
14+
* provide visualizations that makes it easy for civilians to interpret the data and gain information from it
15+
16+
Our repositories are divided by functionality on github, for example the documentation you're reading right now is managed on the [tdt/docs](https://github.com/tdt/docs) repository, this repository holds the documentation for all of The DataTank (tdt) repositories starting from version 4, and contains documentation about our previous versions. Our main [repository](https://github.com/tdt) holds several packages at this moment, the ones relevant to version 4+ are
17+
18+
* [core](https://github.com/tdt/core)
19+
* [input](https://github.com/tdt/input)
20+
* [docs](https://github.com/tdt/docs)
21+
22+
As of version 5.12 the input package is a part of the core package by default and provides an ETL for larger datasets.
23+
24+
The rest of the packages hosted in the tdt repository will become obsolete - from version 4 on - as most of them are either included in core, or are no longer relevant due to the migration to the [Laravel framework](http://laravel.com/) framework.
25+
26+
The core package contains the main component of The DataTank project and provides the basic functionality of publishing data in a RESTful way and making the data requestable in any raw webformat as well as visualizing the data (e.g. creating a map based on geographical properties in a CSV file).
27+
28+
The docs package contains all of the documentation relevant to our repository for packages from version 4 or higher. This documentation project is also created in the Laravel framework and consists of a list of markdown files. This makes it easy for non-technical people to change our documentation where they see fit.
29+
30+
<a id='devcycle' class='anchor'></a>
31+
## Development cycles
32+
33+
We currently work with bi-annual development cycles that provides releases on the 5th of december and the 5th of june.
34+
35+
Our versions are created following the [semantic versioning 2.0.0](http://semver.org/) specification. Our code base has a set of core developers, but as it is an open source project anyone can contribute in the form of pull-requests. Feature request, bugs, issues, questions and so on can be added to the corresponding repo using the github issue tracker.

‎app/controllers/docs/5.12/changelog.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Changelog
2+
3+
A list of each version's most important changes can be reviewed on our github [releases](https://github.com/tdt/core/releases) page, a full overview of closed and open issues can be reviewed on our [github issues tracker](https://github.com/tdt/core/issues).

‎app/controllers/docs/5.12/configuration.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Configuration
2+
3+
On this page you will learn how to configure:
4+
5+
* [A production environment](#production)
6+
* [Caching](#caching)
7+
* [A development environment](#development)
8+
* [Unit testing](#unittesting)
9+
10+
The configuration is entirely handled by the Laravel framework, if you encounter things that aren't covered on this page, visit the [Laravel configuration documentation](http://laravel.com/docs/4.2/configuration) or if that doesn't help you out, get in touch with us on [github](https://github.com/tdt).
11+
12+
> Ideally, you don't change any files in the app/config directory, but copy them into a folder you create under app/config and then edit as you see fit. This allows for proper configuration management and will make your overall configuration flow alot easier. For more info on this, check out the [configuration documentation](http://four.laravel.com/docs/configuration).
13+
14+
The sections below are a summary of what the important parts of the configuration are.
15+
16+
<a id='production' class='anchor'></a>
17+
## Production environment
18+
19+
You'll find that configuring an application through the Laravel framework is really easy and straightforward. Head to the root of the application and go to <em>app/config</em>. The explanation below is the same for environment configurations such as production. Simply create a folder under <em>app/config</em> called production and copy the files you want to change. This should also be explained thoroughly in the [configuration documentation](http://four.laravel.com/docs/configuration) of Laravel.
20+
21+
In the configuration folder you'll find a set of php files and folders that make up one or more configurations. The one that has to be changed is called <em>database.php</em>
22+
23+
The codebase has been tested against a MySQL database, it uses the Eloquent abstraction layer, so any database supported by Eloquent you should be able to use. As an example we'll use MySQL as a default so change the default property to <em>mysql</em> and fill in the mysql entry in the connections array in the <em>database.php</em> file. There's no need to throw away the other connection options or change anything else. This should make your database.php file look something like the following. Note that the comments that are present from a default Laravel installation have been deleted for the sake of simplicity.
24+
25+
<pre class='prettyprint'>
26+
return array(
27+
28+
'fetch' => PDO::FETCH_CLASS,
29+
30+
'default' => 'mysql',
31+
32+
'connections' => array(
33+
34+
'sqlite' => array(
35+
'driver' => 'sqlite',
36+
'database' => __DIR__.'/../database/production.sqlite',
37+
'prefix' => '',
38+
),
39+
40+
'mysql' => array(
41+
'driver' => 'mysql',
42+
'host' => 'localhost',
43+
'database' => 'datatank_db',
44+
'username' => 'foo',
45+
'password' => 'bar',
46+
'charset' => 'utf8',
47+
'collation' => 'utf8_unicode_ci',
48+
'prefix' => '',
49+
),
50+
51+
'pgsql' => array(
52+
'driver' => 'pgsql',
53+
'host' => 'localhost',
54+
'database' => 'database',
55+
'username' => 'root',
56+
'password' => '',
57+
'charset' => 'utf8',
58+
'prefix' => '',
59+
'schema' => 'public',
60+
),
61+
62+
'sqlsrv' => array(
63+
'driver' => 'sqlsrv',
64+
'host' => 'localhost',
65+
'database' => 'database',
66+
'username' => 'root',
67+
'password' => '',
68+
'prefix' => '',
69+
),
70+
71+
),
72+
...
73+
</pre>
74+
75+
That's all there is to it!
76+
77+
<a id='caching' class='anchor'></a>
78+
## Caching
79+
80+
The data request made to The DataTank are cached using the [Laravel caching mechanism](http://four.laravel.com/docs/cache). For the datatank we use the Memcached to cache all of our requests and internal flags. So be sure to have it running and configured in a way that PHP can reach it.
81+
82+
Head to the <em>cache.php</em> file and make sure that the default driver is set to memcached and fill in the necessary properties like so
83+
84+
<pre class="prettyprint">
85+
'enabled' => true,
86+
87+
'driver' => 'memcached',
88+
89+
...
90+
91+
'memcached' => array(
92+
93+
array('host' => '127.0.0.1', 'port' => 11211, 'weight' => 100),
94+
95+
), ...
96+
</pre>
97+
98+
<a id='development' class='anchor'></a>
99+
## Development environment
100+
101+
If you're planning on getting your hands dirty with The DataTank, you'll need to read up on how to configure environments in the [Laravel configuration documentation](http://four.laravel.com/docs/configuration#environment-configuration). In short, in order to load your database for development (e.g. localhost) only, you need to create a subfolder called <em>local</em> in the <em>app/config</em> folder, and make sure the environment is recognized by Laravel. This is done by adding your host name to the <em>$env</em> variable in the <em>bootstrap/start.php</em> file. Don't forget to add this file to the .gitignore file if you're using Git.
102+
103+
<a id='unittesting' class='anchor'></a>
104+
## Unit testing
105+
106+
If you want to run the unittests, to check if everything is still ok after adjustments or to test your own additional tests, go to the root of the application and perform the simple command:
107+
108+
$ phpunit
109+
110+
This will execute all of the tests located at the <em>app/tests</em> folder.
111+
112+
If you've never performed the unit tests before, you will probably stumble upon a large series of errors. This is because the testing environment hasn't been configured yet. It is however a fairly simple thing to do.
113+
114+
First you'll need to create a database that will be used by the unit tests. This can be configured in the <em>database.php</em> file inside the <em>app/config/testing</em> folder. Next you'll want to create the necessary tables in order to create a similar back-end as the application uses, in order to do this you'll need to perform the migration command, but with the testing environment as a parameter.
115+
116+
$ php artisan migrate --env=testing
117+
118+
Next, you'll have to migrate the extra package that we use for authentication purposes as well:
119+
120+
$ php artisan migrate --env=testing --package=cartalyst/sentry
121+
122+
After that, fill up the database with some basic users using our seeder:
123+
124+
$ php artisan db:seed --env=testing
125+
126+
That's it! You can perform the phpunit command now.

‎app/controllers/docs/5.12/consuming_data.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Consuming data
2+
3+
On this page you will learn how you can
4+
5+
* [Request data from The DataTank](#request)
6+
* [Add parameters to a request](#params)
7+
8+
<a id='request' class="anchor"></a>
9+
10+
## Requesting data
11+
12+
The DataTank makes data available through a REST interface. This means that data extracted from a certain data structure is available through HTTP. Just as any other operation of functionality, the discovery document shows us where to go!
13+
14+
<pre class="prettyprint linenums">
15+
{
16+
"protocol": "rest",
17+
"rootUrl": "http://foo",
18+
"resources": {
19+
"info": {
20+
"methods": {
21+
"get": {
22+
"httpMethod": "GET",
23+
"path": "/info",
24+
"description": "Get a list of all retrievable datasets published on this datatank."
25+
}
26+
}
27+
}
28+
}
29+
}
30+
</pre>
31+
32+
The discovery document shows that http://foo/info contains a document that has references to all available datasets, as stated before this list will be presented in a json format since it's part of the resources the datatank manages itself. If you haven't published any datasets so far, there will still be 1 entry in this info document, namely the <em>dcat</em> entry. This entry represents a document that lists information about the published datasets, much like the info resource does itself, but created from properties standardized in the [DCAT vocabulary](http://www.w3.org/TR/vocab-dcat/) and enriched with [dublin core](http://dublincore.org/documents/dcmi-terms/) properties.
33+
34+
<pre class="prettyprint linenums">
35+
{
36+
dcat: {
37+
description: "A DCAT document about the available datasets created by using the DCAT vocabulary.",
38+
uri: "http://foo/api/dcat"
39+
type: null
40+
},
41+
geo/csv: {
42+
description: "An example csv file with geographical properties.",
43+
uri: "http://foo/geo/csv",
44+
type: "CSV",
45+
parameters: {
46+
page: "Represents the page number if the dataset is paged, this parameter can be used together with page_size, which is default set to 500. Set this parameter to -1 if you don't want paging to be applied.",
47+
page_size: "Represents the size of a page, this means that by setting this parameter, you can alter the amount of results that are returned, in one page (e.g. page=1&page_size=3 will give you results 1,2 and 3).",
48+
limit: "Instead of page/page_size you can use limit and offset. Limit has the same purpose as page_size, namely putting a cap on the amount of entries returned, the default is 500. Set this parameter to -1 if don't want paging to be applied.",
49+
offset: "Represents the offset from which results are returned (e.g. ?offset=12&limit=5 will return 5 results starting from 12)."
50+
}
51+
}
52+
}
53+
</pre>
54+
55+
As you can see every entry has a description that is retrieved from the definition itself and contains the type of the data structure that holds the data represented by the uri. Furthermore we can see that some resources have a parameters entry. These represent optional request parameters that can be passed, in most cases this will be a duo of paging parameters, but can vary on the level of a single entry for these request parameters are configurable.
56+
57+
This is all you need to know in order to get a glimp of what datasources are available and on which uri they are retrievable.

0 commit comments

Comments
 (0)