Office Materials Generator beta - document generation
The Office Materials Generator (OMG) is now beta released. The code works for core functions, although the beta is time-limited to Dec 31 2011. The licence is at the bottom of this page, and all aspects of the licence must be complied with in order to use the beta code.
Digital Marketing Office Materials Generator
OMG is designed to streamline the ability for partners (and customers at a later date) to easily architect Microsoft solutions. It helps to solve a common problem in which different sections of a document (or set of documents) are inconsistent due to the difficulty of ensuring that (for example) the bill of materials matches the architecture diagram. OMG is designed to model all complexity and mathematics in Excel (where it is easily managed), whilst document templates are created within Word. A generation cycle blends the Excel model information with the Word template and generates a set of output documents.
OMG is used to output Word documents for architectural and pricing artifacts such as:
- Solution benefits overview
- Architecture documents
- Pricing documents
OMG uses a simple templating system within Word to output the generated documents. It is designed with extensiblity in mind and permits the easy definition of new template functions to be added to the processing cycle.
Template commands in Word supports useful functions such as:
- If statements (if Excel value THEN include Word text )
- Foreach statements (foreach cell in a group of cells from Excel)
- Include files (include a file, including the ability to conditionally include a file)
- Easy references to Excel model information (simply include cell names in curly braces - eg {customer} )
Overview
Templates are enclosed in curly braces and either refer to an Excel model or execute commands such as opening the model. For example this next line is blank in the output document, but it opens the named Excel document. It creates an internal variable "model" that's referred to later in the document. The italics are ignored for the purposes of executing the template, although the output is styled identically.
The default name that’s used for shorthand references to Excel named cells is “model”, so this is the variable name to generally use when opening an Excel document.
- {Excel.Open("model", "Test.xlsx")}
Referring to Excel cells:
Referring to Excel cells is via references enclosed in curly braces. These references optionally include an output style (format) after the reference. Creating these names within Excel is covered later in this document.
- Customer: {customer}
- Donation amount: {Donation_amount dollar}
- Date of donation: {Date_of_donation date}
- Quantity: {Quantity}
- Percent: {Percent_value percent}
- Will you donate? {Definitely_donate yesno}
There are three types of template commands above:
- Open the Excel model
- A simple reference to a named cell – e.g. “customer”
- A reference to a named cell with an output format – e.g. “Date_of_donation date”
- This is the same as a simple reference but with the type after the reference
- Valid formats are date, percent, dollar, yesno or truefalse
Creating named cells in Excel
In order to create named cells within Excel use the technique “Name a cell or a range of cells” in the following document: https://office.microsoft.com/en-us/excel-help/define-and-use-names-in-formulas-HA010342417.aspx#BMcreate_a_name_by_using_a_selection_of
The simplest technique to create a name is as follows (Office 2010):
- Select a cell
- Click in the box shown below and type the name – eg “Customer” into the box in the top left underneath the ribbon (highlighted below)
Including other documents
Include a file:
- {Word.Include(“IncludedFile.docx”)}
Conditionally include a file:
{include if ($model.GetNamedCell(”Definitely_donate”)) “IncludeIfTrue.docx”}
IF statements
To have a section of the document included or not depending on a variable use the following template text:
{if ($model.GetNamedCell(”Definitely_donate”))}
This section of text will only be included if the named cell is true
{end}
FOREACH statements
A typical requirement is to produce copies of a document for a number of similarly named variables in the Excel document as follows. In the Excel document there are four named cells: Name1, Name2, Name3 and Name4. Note that because Name4 doesn’t contain anything it is not included in the foreach results.
{ foreach ($nameSuffix in $model.GetAllCellsLike(“Name”))}
- Name : {Name$nameSuffix}
{end}
Installation and 'hello world' Guide
- Download test
- Unpack the download
- Start __start_TemplateEngine
- Click "..."
- Choose the configuration file "OMG_Configuration.xml" in the TestDocs
directory - Click "generate"
- Examine the generated TestDocs\Test.docx file (delete and regenerate if
required) - Note well: While the template file can be open in Word during generation -
the Excel model can't be open
Comments, suggestions or improvements are always welcomed!
Screen snapshot below:
LICENCE
This license governs use of the accompanying software. If you use the software, you accept this license. If
you do not accept the license, do not use the software.
1. Definitions
The terms "reproduce," "reproduction," and "distribution" have the same meaning here as under U.S.
copyright law.
"You" means the licensee of the software.
"Your company" means the company you worked for when you downloaded the software.
"Reference use" means use of the software within your company as a reference, in read only form, for the
sole purposes of debugging your products, maintaining your products, or enhancing the interoperability of
your products with the software, and specifically excludes the right to distribute the software outside of
your company.
"Licensed patents" means any Licensor patent claims which read directly on the software as distributed by
the Licensor under this license.
2. Grant of Rights
(A) Copyright Grant- Subject to the terms of this license, the Licensor grants you a non-transferable,
non-exclusive, worldwide, royalty-free copyright license to reproduce the software for reference use.
(B) Patent Grant- Subject to the terms of this license, the Licensor grants you a non-transferable,
non-exclusive, worldwide, royalty-free patent license under licensed patents for reference use.
3. Limitations
(A) No Trademark License- This license does not grant you any rights to use the Licensor’s name, logo, or
trademarks.
(B) If you begin patent litigation against the Licensor over patents that you think may apply to the
software (including a cross-claim or counterclaim in a lawsuit), your license to the software ends
automatically.
(C) The software is licensed "as-is." You bear the risk of using it. The Licensor gives no express
warranties, guarantees or conditions. You may have additional consumer rights under your local laws which
this license cannot change. To the extent permitted under your local laws, the Licensor excludes the
implied warranties of merchantability, fitness for a particular purpose and non-infringement.
Copyright 2011 Microsoft Australia Pty Ltd All rights reserved