Eaternity Database Docs
The Eaternity Database is a collection of files and tools.
- File Structure: Ingredient data is stored in the JSON data format in a non-public GitHub repository. There is one .json file per ingredient.
- Jekyll-DB: Jekyll-DB is used to display an overview of all ingredients to the user. The user can search for keywords and select the file to edit.
- Prose: Data is edited in Prose. Thus, the full advantage of GitHub's versioning system is offered to the users.
1. File Structure
Every ingredient is stored in the JSON data format in its own .json file. The files are basically flat, i.e. there is no nested, hierarchical structure inside each file. Yet, the files are not exactly 100% compliant to the JSON specification: Additionally to containing fully valid JSON, in the beginning and the end of each file a YAML-frontmatter header and footer string ("---") is added. Example:
---
{
"ID": "8",
"Name_Deutsch": "Sesamöl",
"Std_Herkunft": "Schweiz",
"kg_CO2": "2.67",
...
}
---
Each file therefore serves a double purpose. Interpreted as a JSON file, it can be processed by JSON parsers. At the same time, it can be processed by Jekyll's frontmatter parsers (which accepts both YAML and JSON equally).
Furthermore, all files are placed in a _data/edbs/ subdirectory. As per Jekyll v2.1.0 all YAML- or JSON-files placed in such a subdirectory can be accessed and looped over via Liquid templates like this: {% for edb in site.data.edbs %} ...do something... {% endfor %}. (Attention: On the 9th July 2014 the datafiles examples in the linked documentation contained errors, for more info see here.) edb[0] will contain the filename (without leading path and without file ending), whereas edb[1] will contain the key/value-pairs specified in YAML or JSON. It is now easy to build a HTML page containing a list of all ingredients with selected attributes:
...
<ul>
{% for edb in site.data.edbs %}
<li>Filename: {{ edb[0] }}.json; Name_Deutsch: {{ edb[1].Name_Deutsch }}</li>
{% endfor %}
</ul>
...
(Attention: On the 9th July 2014 GitHub Pages was still running Jekyll 1.5.1. The datafiles feature is therefore currently not available on GitHub pages. To use it, a Jekyll server instance with version >= 2.1.0 must be run.)
2. Jekyll-DB
Jekyll-DB is an open source and easy-to-use tool based on List.js to index, filter, search, sort and display html tables and lists. Basically, Jekyll-DB allows to index YAML- (or JSON-) frontmatter of (markdown or html) posts placed in the _posts folder. It builds an adaptable display table that can be searched and filtered by keywords and sorted by columns. It is also possible to place links in the display table e.g. to a open a given post item in a GitHub or Prose editor. Data columns can be specified, as can the number of displayed items.
Although the official documentation does not state it explicitly, Jekyll-DB not only works with files placed inside a _posts directory, but also with files in a _data/edbs/ subdirectory. If a _posts/ directory is used, in Liquid templates frontmatter data can be accessed directly, e.g. {% for post in site.posts %} ...{{ post.myFrontmatterKey }}... {% endfor %}. For _data/edbs/ subdirectories, additionally indices must be used to differentiate between filename at index 0 and frontmatter content at index 1: {% for edb in site.data.edbs %} ...{{ edb[1].myFrontmatterKey }}... {% endfor %}.
If JSON files inside a _data subdirectory should be indexed, a Jekyll server instance >= v.2.1.0 is required. Indexing frontmatter only in a _posts directory also works with older Jekyll server instances.
3. Prose
Whereas Jekyll-DB allows to display data, Prose can be used to actually edit the underlying data. Prose is an open-source editor built on top of GitHub pages. There is a free-to-use online instance running at the given link, but it is also possible to run one's own Prose in any YAML-aware webserver such as Jekyll or a Node.js web server. Because as stated above all files are also valid frontmatter files,
There are currently two alternatives how to use Prose: either edit data in Prose's metadata editor, or use an adapted version of Prose running on one's own server instance. Both have their advantages and disadvantages.
Using Prose's metadata editor
Advantages:
- No redundancy between data and frontmatter - all data is stored as only frontmatter.
- Prose's online version can be used. No need to run Prose on one's own server.
- No need for coding, all required metadata editor fields can be configured in a
prosesection in a_config.ymlor in a_prose.yml.
Disadvantages:
- Apparently, JSON frontmatter is changed into YAML, i.e. curly brackets and commas are dropped as soon as the metadata is saved. (TODO: Try this out. An alternative would be to keep all files in the YAML format right from the start. YAML is actually a superset of JSON. For the difference, see this thread.)
- Data in textareas is not displayed and saved properly. (On the 09th of July 2014, this bug has been known for 11 months, yet no patch has been provided by the developers so far. There are two provisional solutions to this problem: First, instead of textareas textfields are used. Unfortunately, they don't preserve line breaks and display only little data. Second, there is a "Raw Values" input field for all non-specified frontmatter key/value-pairs. TODO: Figure out what happens to line breaks in this case.)
- Metadata editor input fields too small?
Using an adapted version of Prose
Advantages:
- Prose can be adapted to one's need. JSONForm can be used to create good-looking forms for data editing.
Disadvantages:
- Redundancy of data and frontmatter. (TODO: Figure out whether JSONForm could be applied for editing frontmatter data.)
- Requires running one's own server instance.
- Need to maintain one's own adapted version of Prose.