github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-21 20:46:30 -05:00
Code Issues Projects Releases Packages Wiki Activity

Update doc

Browse source
This commit is contained in:
Cyrill Schumacher 2015-02-13 17:21:26 +11:00 committed by spf13
parent 47b7cfeb44
commit 48a6d44786
1 changed files with 133 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

158
docs/content/extras/dynamiccontent.md
View file

@ -13,50 +13,158 @@ weight: 91
Dynamic content with a static site generator? Yes it is possible! Dynamic content with a static site generator? Yes it is possible!
Besides the [data files](/extras/datafiles/) available from Hugo, you can specify your own custom data that can be accessed via templates or shortcodes. Besides the [data files](/extras/datafiles/) feature, we have also implemented the feature "Dynamic Content"
which lets you load any [JSON](http://www.json.org/) or [CSV](http://en.wikipedia.org/wiki/Comma-separated_values)
file from nearly any resource.
Hugo supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/), and [TOML](https://github.com/toml-lang/toml) files located in the `data` directory. "Dynamic Content" consists at the moment of two functions `getJson` and `getCsv` which are available in
**all template files**.
**It even works with [LiveReload](/extras/livereload/).** ## Implementation details
## The Data Folder ### Calling the functions with an URL
As explained in [Source Organization](/overview/source-directory/), the `data` folder is where you can store additional data for Hugo to use when generating your site. These files must be YAML, JSON or TOML files (using either the `.yml`, `.yaml`, `.json` or `toml` extension) and the data will be accessible as a `map` in `.Site.Data`. In any template file call the functions like:
**The keys in this map will be a dot chained set of _path_, _filename_ and _key_ in file (if applicable).** ```
{{ $dataJ := getJson "url" }}
{{ $dataC := getCsv "separator" "url" }}
```
This is best explained with an example: or if you use a prefix or postfix for the URL the functions
accepts [variadic arguments](http://en.wikipedia.org/wiki/Variadic_function):
## The Future: getSQL ```
{{ $dataJ := getJson "url prefix" "arg1" "arg2" "arg n" }}
{{ $dataC := getCsv "separator" "url prefix" "arg1" "arg2" "arg n" }}
```
The separator for `getCsv` must be put on the first position and can be only one character long.
All passed arguments will be joined to the final URL, example:
```
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJson $urlPre "/users/GITHUB_USERNAME/gists" }}
```
will resolve internally to:
```
{{ $gistJ := getJson "https://api.github.com/users/GITHUB_USERNAME/gists" }}
```
Eventually you can range or the map/array/slice. This example will output the first 5 Github gists for a user:
```
<ul>
{{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJson $urlPre "/users/GITHUB_USERNAME/gists" }}
{{range first 5 $gistJ }}
{{ if .public }}
<li><a href="{{ .html_url }}" target="_blank">{{.description}}</a></li>
{{ end }}
{{end}}
</ul>
```
### Example for CSV files
For `getCsv` the one character long separator must be placed on the first position followed by the URL.
```
<table>
<thead>
<tr>
<th>Name</th>
<th>Position</th>
<th>Salary</th>
</tr>
</thead>
<tbody>
{{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
{{ $sep := "," }}
{{ range $i, $r := getCsv $sep $url }}
<tr>
<td>{{ index $r 0 }}</td>
<td>{{ index $r 1 }}</td>
<td>{{ index $r 2 }}</td>
</tr>
{{ end }}
</tbody>
</table>
```
### Caching of URLs
Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`. The variable `$TMPDIR` will be
resolved to your system dependent temporary directory.
With the command line flag `--cacheDir` you can specify any folder on your system as a caching directory.
If you don't like caching at all you can fully disabled to read from the cache with the command line
flag `--ignoreCache`. But hugo will still write on each build of the site to the cache folder (silent backup).
### Authentication when using REST URLs
At the moment you can only use those authentication methods which can be put into an URL.
OAuth or other stuff is not implemented.
### Loading local files
To load local files with the two functions `getJson` and `getCsv` the source files must reside within
Hugos working directory. The file extension does not matter but the content.
It applies the same logic as in the topic: *Calling the functions with an URL*.
## Live reload
There is not chance to trigger a [LiveReload](/extras/livereload/) when the content of an URL changes.
But when a local JSON/CSV file changes then of course a live reload will be triggered. Symlinks not supported.
**URLs and Live reload**: If you change any local file and the live reload got trigger Hugo will
either read the URL content from the cache or if you have disabled the cache Hugo will re-download the content.
This can create a huge traffic and also you may reach API limits quickly.
As downloading of content takes a while Hugo stops with processing your markdown files until the content
has been downloaded.
## The Future:
### YAML and TOML
If the community demands the implementation of *getYaml* [YAML](http://yaml.org/) or
*getToml* [TOML](https://github.com/toml-lang/toml) these functions will for sure follow.
### getSql
The outlook to support more sources is of course implementing SQL support. The outlook to support more sources is of course implementing SQL support.
Maybe adding two new CLI switches: Maybe adding a new CLI option:
--sqlDriver=mysql|postres|mssql --sqlSource=path/to/filename.ext
--sqlSource=string|filename
#### `--sqlDriver`
specifies the driver to use which can be one from [https://github.com/golang/go/wiki/SQLDrivers](https://github.com/golang/go/wiki/SQLDrivers)
#### `--sqlSource` #### `--sqlSource`
You can either provide the connection string on the command file OR an existing file which contains the connection string. The file must start with `[mysql|postres|mssql|...]_whatever.ext`
The part until the first underscore specifies the driver to use which can be one
from [https://github.com/golang/go/wiki/SQLDrivers](https://github.com/golang/go/wiki/SQLDrivers).
The file itself contains only the connection string and no other comments or characters.
How the connection string looks like depends heavily on the used driver. For MySQL: How the connection string looks like depends heavily on the used driver. For MySQL:
hugo --sqlDriver=mysql \ hugo --sqlSource=path/to/mysql_Credentials.txt
--sqlSource=username:password@protocol(address)/dbname?param=value
or with a file name:
hugo --sqlDriver=mysql --sqlSource=path/to/myCredentials.txt
The file myCredentials.txt contains the connection string: `username:password@protocol(address)/dbname?param=value` and nothing more!
The file `mysql_Credentials.txt` contains the connection string:
`username:password@protocol(address)/dbname?param=value` and nothing more!
In your template you can process as with the `getCsv` function:
``` ```
$data := getSQL "SELECT id,artist,genre,title from musicTable" $data := getSql "SELECT id,artist,genre,title from musicTable"
``` ```
Abusing `getSql` with [DML](http://en.wikipedia.org/wiki/Data_manipulation_language) or
[DDL](http://en.wikipedia.org/wiki/Data_definition_language) statements is up to you.