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 Dynamic Content docs

Browse source
This commit is contained in:
Cyrill Schumacher 2015-02-15 10:01:58 +11:00 committed by spf13
parent 48a6d44786
commit 4342dd84fc
1 changed files with 107 additions and 85 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -13,12 +13,14 @@ 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/) feature, we have also implemented the feature "Dynamic Content" Besides the [data files](/extras/datafiles/) feature, we have also
which lets you load any [JSON](http://www.json.org/) or [CSV](http://en.wikipedia.org/wiki/Comma-separated_values) implemented the feature "Dynamic Content" which lets you load
file from nearly any resource. any [JSON](http://www.json.org/) or
[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) file
from nearly any resource.
"Dynamic Content" consists at the moment of two functions `getJson` and `getCsv` which are available in "Dynamic Content" consists at the moment of two functions `getJson`
**all template files**. and `getCsv` which are available in **all template files**.
## Implementation details ## Implementation details
@ -26,119 +28,129 @@ file from nearly any resource.
In any template file call the functions like: In any template file call the functions like:
```
{{ $dataJ := getJson "url" }} {{ $dataJ := getJson "url" }}
{{ $dataC := getCsv "separator" "url" }} {{ $dataC := getCsv "separator" "url" }}
```
or if you use a prefix or postfix for the URL the functions or if you use a prefix or postfix for the URL the functions
accepts [variadic arguments](http://en.wikipedia.org/wiki/Variadic_function): accepts [variadic arguments](http://en.wikipedia.org/wiki/Variadic_function):
```
{{ $dataJ := getJson "url prefix" "arg1" "arg2" "arg n" }} {{ $dataJ := getJson "url prefix" "arg1" "arg2" "arg n" }}
{{ $dataC := getCsv "separator" "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. 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: All passed arguments will be joined to the final URL, example:
```
{{ $urlPre := "https://api.github.com" }} {{ $urlPre := "https://api.github.com" }}
{{ $gistJ := getJson $urlPre "/users/GITHUB_USERNAME/gists" }} {{ $gistJ := getJson $urlPre "/users/GITHUB_USERNAME/gists" }}
```
will resolve internally to: will resolve internally to:
```
{{ $gistJ := getJson "https://api.github.com/users/GITHUB_USERNAME/gists" }} {{ $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: Eventually you can range over the array. 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>
```
<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 ### Example for CSV files
For `getCsv` the one character long separator must be placed on the first position followed by the URL. For `getCsv` the one character long separator must be placed on the
first position followed by the URL.
``` <table>
<table> <thead>
<thead> <tr>
<tr> <th>Name</th>
<th>Name</th> <th>Position</th>
<th>Position</th> <th>Salary</th>
<th>Salary</th> </tr>
</tr> </thead>
</thead> <tbody>
<tbody> {{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
{{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }} {{ $sep := "," }}
{{ $sep := "," }} {{ range $i, $r := getCsv $sep $url }}
{{ range $i, $r := getCsv $sep $url }} <tr>
<tr> <td>{{ index $r 0 }}</td>
<td>{{ index $r 0 }}</td> <td>{{ index $r 1 }}</td>
<td>{{ index $r 1 }}</td> <td>{{ index $r 2 }}</td>
<td>{{ index $r 2 }}</td> </tr>
</tr> {{ end }}
{{ end }} </tbody>
</tbody> </table>
</table>
``` The expression `{{index $r number}}` must be used to output the nth-column from
the current row.
### Caching of URLs ### Caching of URLs
Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`. The variable `$TMPDIR` will be Each downloaded URL will be cached in the default folder `$TMPDIR/hugo_cache/`.
resolved to your system dependent temporary directory. 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. 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 If you don't like caching at all you can fully disable to read from the
flag `--ignoreCache`. But hugo will still write on each build of the site to the cache folder (silent backup). cache with the command line flag `--ignoreCache`. But hugo will always
write, on each build of the site, to the cache folder (silent backup).
### Authentication when using REST URLs ### Authentication when using REST URLs
At the moment you can only use those authentication methods which can be put into an URL. At the moment you can only use those authentication methods which can
OAuth or other stuff is not implemented. be put into an URL. OAuth or other stuff is not implemented.
### Loading local files ### Loading local files
To load local files with the two functions `getJson` and `getCsv` the source files must reside within To load local files with the two functions `getJson` and `getCsv` the
Hugos working directory. The file extension does not matter but the content. 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*. It applies the same output logic as in the topic: *Calling the functions with an URL*.
## Live reload ## Live reload
There is not chance to trigger a [LiveReload](/extras/livereload/) when the content of an URL changes. There is no chance to trigger a [LiveReload](/extras/livereload/) when
But when a local JSON/CSV file changes then of course a live reload will be triggered. Symlinks not supported. 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 **URLs and Live reload**: If you change any local file and the live reload
either read the URL content from the cache or if you have disabled the cache Hugo will re-download the content. got trigger Hugo will either read the URL content from the cache or if
This can create a huge traffic and also you may reach API limits quickly. you have disabled the cache Hugo will re-download the content.
This can creates 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 As downloading of content takes a while Hugo stops with processing
has been downloaded. your markdown files until the content has been downloaded.
## The Future: ## Examples
- Photo gallery JSON powered: [https://github.com/pcdummy/hugo-lightslider-example](https://github.com/pcdummy/hugo-lightslider-example)
- Github Starred Repositories [in a posts](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) with the related [short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html).
- more?
## The Future
### YAML and TOML ### YAML and TOML
If the community demands the implementation of *getYaml* [YAML](http://yaml.org/) or If the community demands the implementation of *getYaml*
*getToml* [TOML](https://github.com/toml-lang/toml) these functions will for sure follow. [YAML](http://yaml.org/) or *getToml* [TOML](https://github.com/toml-lang/toml)
these functions will for sure follow.
### getSql ### 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. The following description is an initial idea and may change.
Maybe adding a new CLI option: Maybe adding a new CLI option:
@ -146,25 +158,35 @@ Maybe adding a new CLI option:
#### `--sqlSource` #### `--sqlSource`
The file must start with `[mysql|postres|mssql|...]_whatever.ext` The file must start with `[mysql|postres|mssql|...]_[\w]+.ext`
The part until the first underscore specifies the driver to use which can be one The part until the first underscore specifies the driver to use which can
from [https://github.com/golang/go/wiki/SQLDrivers](https://github.com/golang/go/wiki/SQLDrivers). 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. 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 --sqlSource=path/to/mysql_Credentials.txt hugo --sqlSource=path/to/mysql_credentials.txt
The file `mysql_Credentials.txt` contains the connection string: The file `mysql_credentials.txt` contains the connection string:
`username:password@protocol(address)/dbname?param=value` and nothing more! `username:password@protocol(address)/dbname?param=value` and nothing more!
In your template you can process as with the `getCsv` function: In your template you can process `getSql` the same way as with
the `getJson` function:
``` {{ $rows := getSql "SELECT id,artist,genre,title from musicTable" }}
$data := getSql "SELECT id,artist,genre,title from musicTable" <ul>
``` {{range first 5 $rows }}
<li>#{{ .id }} {{.artist}}</a></li>
{{end}}
</ul>
Abusing `getSql` with [DML](http://en.wikipedia.org/wiki/Data_manipulation_language) or Queries with `SELECT * from table` are of course also possible.
[DDL](http://en.wikipedia.org/wiki/Data_definition_language) statements is up to you. Returned **values** will be converted to **strings**.
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.