diff --git a/templating/README.md b/templating/README.md index f76051a5b..eb30a7742 100644 --- a/templating/README.md +++ b/templating/README.md @@ -21,13 +21,13 @@ options, type ``python build.py --help``. Developing ---------- -## Sections and Units +### Sections and Units Batesian is built around the concept of Sections and Units. Sections are strings which will be inserted into the provided document. Every section has a unique key name which is the template variable that it represents. Units are arbitrary python data. They are also represented by unique key names. -## Adding template variables +### Adding template variables If you want to add a new template variable e.g. `{{foo_bar}}` which is replaced with the text `foobar`, you need to add a new Section: @@ -35,13 +35,14 @@ with the text `foobar`, you need to add a new Section: - Add a new function to `MatrixSections` called `render_foo_bar`. The function name after `render_` determines the template variable name, and the return value of this function determines what will be inserted. + ```python def render_foo_bar(self): return "foobar" ``` - - Run `build.py`! + - Run `build.py` with a file which has `{{foo_bar}}` in it. -## Adding data for template variables +### Adding data for template variables If you want to expose arbitrary data which can be used by `MatrixSections`, you need to add a new Unit: @@ -49,6 +50,7 @@ need to add a new Unit: - Add a new function to `MatrixUnits` called `load_some_data`. Similar to sections, the function name after `load_` determines the unit name, and the return value of this function determines the value of the unit. + ```python def load_some_data(self): return { @@ -60,15 +62,26 @@ need to add a new Unit: - You can now call `self.units.get("some_data")` to retrieve the value you returned. -## Using Jinja templates +### Using Jinja templates Sections can use Jinja templates to return text. Batesian will attempt to load all templates from `matrix_templates/templates/`. These can be accessed in Section code via `template = self.env.get_template("name_of_template.tmpl")`. At this point, the `template` is just a standard `jinja2.Template`. In fact, `self.env` is just a `jinja2.Environment`. -## Debugging +### Debugging If you don't know why your template isn't behaving as you'd expect, or you just want to add some informative logging, use `self.log` in either the Sections class or Units class. You'll need to add `-v` to `build.py` for these lines to -show. \ No newline at end of file +show. + +About +----- + +Batesian was designed to be extremely simple and just use Python as its language +rather than another intermediary language like some other templating systems. +This provides a **lot** of flexibility since you aren't contrained by a +templating language. Batesian provides a thin abstraction over Jinja which is +very useful when you want to do random bits of processing then dump the output +into a Jinja template. Its name is derived from Batesian mimicry due to how the +templating system uses Python as its language, but in a harmless way.