mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
Update Dynamic Content docs
This commit is contained in:
Cyrill Schumacher
spf13
parent
48a6d44786
commit
4342dd84fc
1 changed files with 107 additions and 85 deletions
|
|
@ -13,12 +13,14 @@ weight: 91
|
|||
|
||||
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"
|
||||
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.
|
||||
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.
|
||||
|
||||
"Dynamic Content" consists at the moment of two functions `getJson` and `getCsv` which are available in
|
||||
**all template files**.
|
||||
"Dynamic Content" consists at the moment of two functions `getJson`
|
||||
and `getCsv` which are available in **all template files**.
|
||||
|
||||
## Implementation details
|
||||
|
||||
|
|
@ -26,119 +28,129 @@ file from nearly any resource.
|
|||
|
||||
In any template file call the functions like:
|
||||
|
||||
```
|
||||
|
||||
{{ $dataJ := getJson "url" }}
|
||||
{{ $dataC := getCsv "separator" "url" }}
|
||||
```
|
||||
{{ $dataC := getCsv "separator" "url" }}
|
||||
|
||||
|
||||
or if you use a prefix or postfix for the URL the functions
|
||||
accepts [variadic arguments](http://en.wikipedia.org/wiki/Variadic_function):
|
||||
|
||||
```
|
||||
{{ $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.
|
||||
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" }}
|
||||
```
|
||||
{{ $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:
|
||||
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
|
||||
|
||||
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>
|
||||
<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>
|
||||
```
|
||||
<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>
|
||||
|
||||
The expression `{{index $r number}}` must be used to output the nth-column from
|
||||
the current row.
|
||||
|
||||
### 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.
|
||||
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.
|
||||
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).
|
||||
If you don't like caching at all you can fully disable to read from the
|
||||
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
|
||||
|
||||
At the moment you can only use those authentication methods which can be put into an URL.
|
||||
OAuth or other stuff is not implemented.
|
||||
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.
|
||||
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*.
|
||||
It applies the same output 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.
|
||||
There is no 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.
|
||||
**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 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
|
||||
has been downloaded.
|
||||
As downloading of content takes a while Hugo stops with processing
|
||||
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
|
||||
|
||||
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.
|
||||
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. The following description is an initial idea and may change.
|
||||
|
||||
Maybe adding a new CLI option:
|
||||
|
||||
|
|
@ -146,25 +158,35 @@ Maybe adding a new CLI option:
|
|||
|
||||
#### `--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
|
||||
from [https://github.com/golang/go/wiki/SQLDrivers](https://github.com/golang/go/wiki/SQLDrivers).
|
||||
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.
|
||||
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!
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
$data := getSql "SELECT id,artist,genre,title from musicTable"
|
||||
```
|
||||
{{ $rows := 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
|
||||
[DDL](http://en.wikipedia.org/wiki/Data_definition_language) statements is up to you.
|
||||
Queries with `SELECT * from table` are of course also possible.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue