diff --git a/docs/content/extras/dynamiccontent.md b/docs/content/extras/dynamiccontent.md index 60bf336dd..7727279d4 100644 --- a/docs/content/extras/dynamiccontent.md +++ b/docs/content/extras/dynamiccontent.md @@ -13,50 +13,158 @@ weight: 91 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: + +``` + +``` + +### Example for CSV files + +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 }}
+``` + +### 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. -Maybe adding two new CLI switches: +Maybe adding a new CLI option: - --sqlDriver=mysql|postres|mssql - --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=path/to/filename.ext #### `--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: - hugo --sqlDriver=mysql \ - --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! + hugo --sqlSource=path/to/mysql_Credentials.txt +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.