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