1# Generator framework based on Jinja template engine
2
3!!! warning
4
5    This framework is implemented in
6    [textX-jinja](https://github.com/textX/textX-jinja) project.
7    You have to install it with `pip install textX-jinja` to be able to use it.
8
9
10You can roll your own code generation approach with textX but sometimes it is
11good to have a predefined framework which is easy to get started with and only
12if you need something very specific later you can create your own code
13generator.
14
15Here, we describe a little framework based on
16[Jinja](https://jinja.palletsprojects.com/) template engine.
17
18The idea is simple. If you want to generate a set of files from your textX
19model(s) you create a folder which resembles the outline of the file tree you
20want to generate. Each file in your template folder can be a Jinja template
21(with `.jinja` extension, e.g. `index.html.jinja`), in which case target file
22will be created by running the template through the Jinja engine. If the file
23doesn't end with `.jinja` extension it is copied as is to the target folder.
24
25To call Jinja generator you use `textx_jinja_generator` function:
26
27```python
28...
29from textxjinja import textx_jinja_generator
30...
31
32@generator('mylang', 'mytarget')
33def mygenerator(metamodel, model, output_path, overwrite, debug):
34    "Generate MyTarget from MyLang model."
35
36    # Prepare config dictionary
37    config = {}
38    config['some_param'] = "Some value"
39
40    template_folder = os.path.join(THIS_FOLDER, 'template')
41
42    # Run Jinja generator
43    textx_jinja_generator(template_folder, output_path, config, overwrite)
44```
45
46In this example we have our templates stored in `template` folder.
47
48You can use variables from `config` dict in your templates as usual, but also
49you can use them in filenames. If file name has a variable name in the format
50`__<variablename>__` it will be replaced by the value of the variable from the
51`config` dict. If variable by the given name is not found the `variablename` is
52treated as literal filename. For example
53[\_\_package__](https://github.com/textX/textX-dev/tree/master/textxdev/scaffold/template)
54in the template file names will be replaced by package name from `config` dict.
55
56Boolean values in file names are treated specially. If the value is of a bool
57type the file will be skipped entirely if the value is `False` but will be used
58if the value is `True`. This makes it easy to provide templates/files which
59should be generated only under certain conditions (for example see `__lang__`
60and `__gen__` variable usage in [template
61names](https://github.com/textX/textX-dev/tree/master/textxdev/scaffold/template))
62
63!!! note
64
65    It is planned to support iterable in `config` dict. If a variable is
66    iterable then a file will be generated for each element of the iterable. This
67    is still not implemented.
68
69To see a full example of using `textX-jinja` you can take a look at the
70implementation of `startproject` textX command in
71[textX-dev](https://github.com/textX/textX-dev) project. This textX command will
72run a questionnaire based on [the Questionnaire
73DSL](https://github.com/textX/textx-lang-questionnaire) and with run a project
74scaffolding generation by [calling
75textx\_jinja\_generate](https://github.com/textX/textX-dev/blob/master/textxdev/scaffold/__init__.py#L46)
76with [the templates for the
77project](https://github.com/textX/textX-dev/tree/master/textxdev/scaffold/template).
78