diff --git a/CHANGES.rst b/CHANGES.rst index 41e77d2..f5c2744 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,3 +1,7 @@ +0.9.0 (2020-04-15) +------------------- +- New syntax : {%- and -%} to merge lines/paragraphs + 0.8.1 (2020-04-14) ------------------- - fix #266 @@ -14,103 +18,37 @@ ------------------- - Add the possibility to add RichText to a Richtext - Prevent lxml from attempting to parse None - -0.6.3 (2019-06-20) -------------------- - PR #207 and #209 - -0.6.2 (2019-06-09) -------------------- - Handle spaces correctly when run are split by Jinja code (#205) - -0.6.1 (2019-06-05) -------------------- - PR #203 - -0.6.0 (2019-06-03) -------------------- - DocxTemplate now accepts file-like objects (Thanks to edufresne) 0.5.20 (2019-05-23) ------------------- - Fix #199 - -0.5.19 (2019-05-23) -------------------- - Add support for file-like objects for replace_media (#197) - -0.5.18 (2019-05-20) -------------------- - Fix #176 - -0.5.17 (2019-01-20) -------------------- - Delegated autoescaping to Jinja2 Environment (#175) - -0.5.16 (2019-01-11) -------------------- - Force to use python-docx 0.8.7 (#170) - Add getting undeclared variables in the template (#171) - -0.5.15 (2019-01-02) -------------------- - Added `PAGE_BREAK` feature (#168) - -0.5.14 (2018-12-23) -------------------- - Fixed issue #159: autoescaped values for both str and unicode. - -0.5.12 (2018-12-18) -------------------- - Fix tables with gridSpan that have less cells after the tc forloop (#164) - -0.5.11 (2018-11-21) -------------------- - Smart double quotes in jinja tags are now converted into simple double quotes - -0.5.10 (2018-11-20) -------------------- - Smart quotes in jinja tags are now converted into simple quotes - Add custom jinja filter example in tests/ - Reformat the code to be a little more PEP8 compliant - -0.5.9 (2018-11-18) ------------------- - Add {% hm %} tag for table columns horizontal merging (Thanks to nickgashkov) - Split tests/tests_files dir into templates and output dirs - -0.5.8 (2018-11-08) ------------------- - autoescape support for python 2.7 - fix issue #154 - -0.5.7 (2018-11-07) ------------------- - Render can now autoescape context dict - -0.5.6 (2018-10-18) ------------------- - Fix invalid xml parse because using {% vm %} - -0.5.5 (2018-10-05) ------------------- - Cast to string non-string value given to RichText or Listing objects - Import html.escape instead of cgi.escape (deprecated) - -0.5.4 (2018-09-19) ------------------- - Declare package as python2 and python3 compatible for wheel distrib - -0.5.3 (2018-09-19) ------------------- - Add sub/superscript in RichText - -0.5.2 (2018-09-13) ------------------- - Fix table vertical merge - -0.5.0 (2018-08-03) ------------------- - An hyperlink can now be used in RichText 0.4.13 (2018-06-21) diff --git a/docs/conf.py b/docs/conf.py index 5ed19b7..e49608b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,9 +53,9 @@ copyright = u'2015, Eric Lapouyade' # built documents. # # The short X.Y version. -version = '0.7' +version = '0.9' # The full version, including alpha/beta/rc tags. -release = '0.7.x' +release = '0.9.x' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index 187a9d5..7e8cf18 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -89,6 +89,29 @@ But use this instead in your docx template :: This syntax is possible because MS Word considers each line as a new paragraph and ``{%p`` tags are not in the same paragraph in the second case. +Split and merge text +.................... + +* You can merge a jinja2 tag with previous line by using ``{%-`` +* You can merge a jinja2 tag with next line by using ``-%}`` + +A text containing Jinja2 tags may be unreadable if too long:: + + My house is located {% if living_in_town %} in urban area {% else %} in countryside {% endif %} and I love it. + +One can use *ENTER* or *SHIFT+ENTER* to split a text like below, then use ``{%-`` and ``-%}`` to tell docxtpl to merge the whole thing:: + + My house is located + {%- if living_in_town -%} + in urban area + {%- else -%} + in countryside + {%- endif -%} + and I love it. + +**IMPORTANT :** Use an unbreakable space (*CTRL+SHIFT+SPACE*) when a space is wanted at line beginning or ending. + + Display variables ................. @@ -96,7 +119,7 @@ As part of jinja2, one can used double braces:: {{ }} -But if ```` is a RichText :ref:`RichText` object, you must specify that you are changing the actual 'run' :: +But if ```` is a RichText_ object, you must specify that you are changing the actual 'run':: {{r }} @@ -114,7 +137,7 @@ method to concatenate several strings and styles at python side and only one Cell color .......... -There is a special case when you want to change the background color of a table cell, you must put the following tag at the very beginning of the cell :: +There is a special case when you want to change the background color of a table cell, you must put the following tag at the very beginning of the cell:: {% cellbg %} @@ -124,7 +147,7 @@ Column spanning ............... If you want to dynamically span a table cell over many column (this is useful when you have a table with a dynamic column count), -you must put the following tag at the very beginning of the cell to span :: +you must put the following tag at the very beginning of the cell to span:: {% colspan %} @@ -133,11 +156,13 @@ you must put the following tag at the very beginning of the cell to span :: Escaping ........ -In order to display ``{%``, ``%}``, ``{{`` or ``}}``, one can use :: +In order to display ``{%``, ``%}``, ``{{`` or ``}}``, one can use:: {_%, %_}, {_{ or }_} + .. _RichText: + RichText -------- @@ -153,9 +178,9 @@ you do not specify a style in ``RichText()``, the style will go back to a micros This will affect only character styles, not the paragraph styles (MSWord manages this 2 kind of styles). Hyperlink with RichText -....................... ++++++++++++++++++++++++ -You can add an hyperlink to a text by using a Richtext with this syntax :: +You can add an hyperlink to a text by using a Richtext with this syntax:: tpl=DocxTemplate('your_template.docx') rt = RichText('You can add an hyperlink, here to ') @@ -167,7 +192,7 @@ Inline image ------------ You can dynamically add one or many images into your document (tested with JPEG and PNG files). -just add ``{{ }}`` tag in your template where ```` is an instance of doxtpl.InlineImage :: +just add ``{{ }}`` tag in your template where ```` is an instance of doxtpl.InlineImage:: myimage = InlineImage(tpl,'test_files/python_logo.png',width=Mm(20)) @@ -200,7 +225,7 @@ See tests/escape.py example for more informations. Another solution, if you want to include a listing into your document, that is to escape the text and manage \n, \a, and \f you can use the ``Listing`` class : -in your python code :: +in your python code:: context = { 'mylisting':Listing('the listing\nwith\nsome\nlines \a and some paragraph \a and special chars : <>&') } @@ -324,7 +349,7 @@ By this way you will be able to add some custom jinja filters:: doc.render(context,jinja_env) doc.save("generated_doc.docx") -Then in your template, you will be able to use :: +Then in your template, you will be able to use:: Euros price : {{ price_dollars|multiply_by(0.88) }} diff --git a/docxtpl/__init__.py b/docxtpl/__init__.py index 96a8997..211bd79 100644 --- a/docxtpl/__init__.py +++ b/docxtpl/__init__.py @@ -7,7 +7,7 @@ Created : 2015-03-12 import functools import io -__version__ = '0.8.1' +__version__ = '0.9.0' from lxml import etree from docx import Document @@ -410,7 +410,8 @@ class DocxTemplate(object): tpl.replace_media(io.BytesIO(image_stream), io.BytesIO(new_image_stream)) Note: for images, the aspect ratio will be the same as the replaced image - Note2 : it is important to have the source media file as it is required + + Note2: it is important to have the source media file as it is required to calculate its CRC to find them in the docx """ diff --git a/tests/templates/merge_paragraph_tpl.docx b/tests/templates/merge_paragraph_tpl.docx index 71faa5a..9d5e388 100644 Binary files a/tests/templates/merge_paragraph_tpl.docx and b/tests/templates/merge_paragraph_tpl.docx differ