Improve cuddly #1
1 changed files with 38 additions and 31 deletions
update and improve documentation
commit
d9713da6fd
69
README.md
69
README.md
|
|
@ -1,6 +1,6 @@
|
|||
# Cuddly
|
||||
|
||||
Generate HTML and PDF from KDL structured data.
|
||||
Generate HTML and PDF files, with HTML and Jinja templates, from KDL structured data.
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ python -m venv env
|
|||
env/bin/pip install .
|
||||
```
|
||||
|
||||
## Usage
|
||||
## Basic Usage
|
||||
|
||||
### Example
|
||||
|
||||
|
|
@ -32,15 +32,25 @@ Generating both at the same time, with short options:
|
|||
env/bin/cuddly -t samples/cv/cv.template.html -i samples/cv.kdl -o samples/cv.pdf -o samples/cv.html
|
||||
```
|
||||
|
||||
### Template usage
|
||||
### Samples
|
||||
|
||||
The template language used is [Jinja](https://jinja.palletsprojects.com/en/3.0.x/), source template need to be a single HTML template file.
|
||||
* `samples/cv/cv.template.html`: Template to generate a CV, see `samples/cv.kdl` for the input data.
|
||||
* `samples/facture/facture.template.html`: Template to generate a French invoice, see `samples/facture.kdl` for the input data.
|
||||
|
||||
#### Base URL
|
||||
|
||||
When generating the PDF the base URL is set to the source template directory. All relative links to other resources (for example CSS and images) must be relative to that directory.
|
||||
## Template usage
|
||||
|
||||
#### Accessing nodes values and attributes
|
||||
The source template need to be a single HTML template file.
|
||||
|
||||
- The template language is [Jinja](https://jinja.palletsprojects.com/en/3.0.x/).
|
||||
- For PDFs, the resulting HTML is run through [Weasyprint](https://weasyprint.org/).
|
||||
- The data language is [KDL](https://kdl.dev/) (2.0.0).
|
||||
|
||||
### Base URL
|
||||
|
||||
When generating a PDF, the base URL is set to the source template directory. All relative links to other resources (for example CSS and images) must be relative to that directory.
|
||||
|
||||
### Accessing nodes values and attributes
|
||||
|
||||
Nodes are available as global variables in the template. The rendered value of a node is the first value that has been assigned to the node. This value can also be accessed using the `value` property. The list of values can be accessed using the `values` property.
|
||||
|
||||
|
|
@ -62,7 +72,23 @@ something
|
|||
something, other thing
|
||||
```
|
||||
|
||||
Accessing children nodes can be done using properties of the children names.
|
||||
Attributes of a node can be accessed through the `attributes` property:
|
||||
|
||||
```kdl
|
||||
my_node version=42 "something"
|
||||
```
|
||||
|
||||
```jinja
|
||||
{{ my_node.attributes.version }}
|
||||
```
|
||||
renders to
|
||||
```
|
||||
42
|
||||
```
|
||||
|
||||
### Accessing children nodes
|
||||
|
||||
Children nodes can be accessed using the children names.
|
||||
|
||||
```kdl
|
||||
my_node {
|
||||
|
|
@ -79,7 +105,7 @@ renders to
|
|||
test
|
||||
```
|
||||
|
||||
If a node has multiple children of a same node type, then directly accessing the children properties will fail, a loop will be needed. Note that, on the other hand, looping on the children always work, even if there is only one child of the given type.
|
||||
If a node has multiple children of a same node type, you’ll need to use a loop (directly accessing the children properties will fail). Note that, on the other hand, looping on the children always work, even if there is only one child of the given type.
|
||||
|
||||
```kdl
|
||||
my_node {
|
||||
|
|
@ -101,25 +127,11 @@ first
|
|||
second
|
||||
```
|
||||
|
||||
Attributes of a node can be accessed through the `attributes` property:
|
||||
### Using components to template nodes
|
||||
|
||||
```kdl
|
||||
my_node version=42 "something"
|
||||
```
|
||||
You can define node specific templates inside the `components` tag in the HTML template file. Nodes can then be rendered using those micro-templates using the `render` filter.
|
||||
|
||||
```jinja
|
||||
{{ my_node.attributes.version }}
|
||||
```
|
||||
renders to
|
||||
```
|
||||
42
|
||||
```
|
||||
|
||||
#### Templating nodes
|
||||
|
||||
Node specific templates can be defined in the `components` element in the HTML template file. Nodes can then be rendered using those micro-templates using the `render` filter.
|
||||
|
||||
The context of the micro-template is the node being rendered. As such, children and properties of that node are in the global scope.
|
||||
The context of the micro-template is the node being rendered. As such, children and properties (`value`, `values`, `attributes`) of that node are in the global scope.
|
||||
|
||||
```kdl
|
||||
menu "Midnight meal" price="10 €" {
|
||||
|
|
@ -159,8 +171,3 @@ menu "Midnight meal" price="10 €" {
|
|||
{{ menu | render }}
|
||||
</body>
|
||||
```
|
||||
|
||||
## Samples
|
||||
|
||||
* `samples/cv/cv.template.html`: Template to generate a CV, see `samples/cv.kdl` for the input data.
|
||||
* `samples/facture/facture.template.html`: Template to generate a French invoice, see `samples/facture.kdl` for the input data.
|
||||
|
|
|
|||
Loading…
Reference in a new issue