Tutorial - Manage manual parts and embed Word Macros


In this tutorial, we will learn to:

  • Use manual parts (sections that are not modified when regenerating the document)
  • Add Word macros to the generated document


We will start from the project developed in the first 15 minutes tutorial as starting point to. If you did not run the first tutorial, you can import the final project in Eclipse: select File -> New -> Example and then pxDoc Final Library Example.

From this project, we will:

  • Include a "personal review" of each author, which are independant from the model and managed through manual parts
  • Add Word macros to automatically expand the subdocuments (here, the manual parts) and to save a consolidated single document (e.g. for configuration management purpose)

    If you did not run the first tutorial, you can download the final project here and import it in Eclipse


Get resources for the manual parts

Download the two resource files we will need for this tutorial:

Copy them in the templates folder of your pxDoc project:


Insert a manual part

Why manual parts?

We know that, in real life, we cannot (and do not want to) put everything in models and that documentation cannot be 100% generated. So we need to be able to insert in our generated document some content that is:

  • manually written in a Word document, out of the model
  • not erased when regenerating the document

This is the purpose of the manual parts.


Here, we want to add, for each author, a block that presents a review of the author.



In pxDoc, manual parts are Word subdocuments, generated from a template .docx file the first time but not modified by pxDoc afterwards.

The template we will use in this tutorial is a simple block of text, but you could have any content inside (a blank document, a table or survey for the review...).


Insert the manual part

To insert a manual part, we use the keyword subdocument and specify the path to the subdocument (where the manual part will be stored) and the path to the template used to create them the first time.

 We decide here that subdocuments will be stored in a subfolder PersonalReviews and that their filename will be based on the author name: 

var filename = "PersonalReviews/" + author.name +".docx"
subDocument filename fromTemplate:"templates/template.docx"


We add a title in the Quote style and few paragrah breaks for a better layout:

	#Quote  {"Our personal review" }
	var filename = "PersonalReviews/" + author.name +".docx"
	subDocument filename fromTemplate: "templates/template.docx"


Insert this code after the table definition.


Add macros in the generated document

In Word, subdocuments are not automatically displayed when opening a document: we only see hyperlinks to these documents and we need to expand them manually (View -> Outline -> Expand subdocuments).

To be more efficient, we developped two simple macros that are stored in the ".dotm" Word template you added to the project. To embed these macros in the generated document, add the attachedTemplate attribute to the document keyword:

document attachedTemplate:"templates/pxdoc.dotm"

You can of course embed your own macros in a .dotm file to have them available in the generated document


For this tutorial, we placed the pxdoc.dotm file as resource of the project. But in real life, it should be located somewhere accessible by all the users (shared folder,...): the macros are not embedded in the generated document, pxDoc only specifies a link to the .dotm template


Launch the generation

Here is the final code of your generator:

package org.pragmaticmodeling.example.mygenerator

import library.Library

pxDocGenerator LibraryGenerator stylesheet:MyStylesheet
	root template main(Library library) {

		document attachedTemplate:"templates/pxdoc.dotm" {
			for (author : library.authors) {

				#Heading1 {
					image path:author.picture height:2.8cm hPosition(align: right relativeFrom:margin) vPosition(align:center relativeFrom:line)

				font bold underline color: "122,91,255" {"Biography" }
				section columns:2 type:continuous // Starting a continuous section with 2 columns
				italic {author.biography }
				section type:continuous // Get back to a single column

				table left:2.5cm borders(color:"84,138,183") [ width:20pc vAlign:center | width:40pc vAlign:center| width:20pc vAlign:center ] {

					row header shadingColor:"84,138,183" {
						cell {#CellTitle align:center{"Category" } }
						cell {#CellTitle {"Title" } }
						cell {#CellTitle align:center {"Publication date" } }
					for (book : author.books.sortBy[category]) {
						row {
							cell [ merge:automatic] {
								#Normal align:center {book.category.getName }
							cell {bold {book.title } }
							cell {
								#Normal align:center{
									italic {book.publicationDate }
				#Quote {"Our personal review" }
				var filename = "PersonalReviews/" + author.name + ".docx"
				subDocument filename fromTemplate: "templates/template.docx"





 Launch the project in Run or Debug mode


If you did not run the first 15 minutes tutorial, you need to import the Library model in the second Eclipse that opens: select File -> New -> Example and then pxDoc Library Test Model


Launch the generation by right-clicking on Library MyLibrary → pxDoc → 15 minutes tutorial.



When the document opens, you will notice that there are macros in the document (security warning) and that two icons appear in the Quick Access Toolbar: 


Looking at the location you specified for the document generation, you will see the subfolder containing the created subdocuments:


Use our macros to expand the subdocuments and save a consolidated version of the document 


Expand subdocuments and add some content to them

When opening the document, we only see hyperlinks and not the content of the sudocuments:


Just click on the first icon we provided to expand them automatically:



Now you can write anything you want in the manual part. 



Save the document, and open the subdocuments: you will see that their content has been updated.

Anybody can update these files independantly, you just need to ensure that their last version is stored in the right place (here, the PersonalReviews folder) 


Freeze the current version of the consolidated document

For configuration management purpose, or any other reason, you may want to save a consolidated version of the document that includes the subdocuments. This is the purpose of our second macro, which expand all the sudocuments, update all the fields and opens the Save As window: