From 4342dd84fc1fd8ae02dc58817e3502b5f30b451d Mon Sep 17 00:00:00 2001 From: Cyrill Schumacher Date: Sun, 15 Feb 2015 10:01:58 +1100 Subject: [PATCH] Update Dynamic Content docs --- docs/content/extras/dynamiccontent.md | 192 ++++++++++++++------------ 1 file changed, 107 insertions(+), 85 deletions(-) diff --git a/docs/content/extras/dynamiccontent.md b/docs/content/extras/dynamiccontent.md index 7727279d4..ca9c59b92 100644 --- a/docs/content/extras/dynamiccontent.md +++ b/docs/content/extras/dynamiccontent.md @@ -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: + + -``` - -``` ### 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. -``` - - - - - - - - - - {{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }} - {{ $sep := "," }} - {{ range $i, $r := getCsv $sep $url }} - - - - - - {{ end }} - -
NamePositionSalary
{{ index $r 0 }}{{ index $r 1 }}{{ index $r 2 }}
-``` + + + + + + + + + + {{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }} + {{ $sep := "," }} + {{ range $i, $r := getCsv $sep $url }} + + + + + + {{ end }} + +
NamePositionSalary
{{ index $r 0 }}{{ index $r 1 }}{{ index $r 2 }}
+ +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" }} + -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.