Commit a695184f authored by Matija Obreza's avatar Matija Obreza
Browse files

README asciidoc

parent af6deda3
Excel Template Merge with JSON
==============================
December 2015: Documentation commit {buildNumber}
:revnumber: {projectVersion}
:doctype: book
:toc: left
:toclevels: 5
:icons: font
:numbered:
:source-highlighter: pygments
:pygments-css: class
:pygments-linenums-mode: table
This is a simple tool has two components: a bit that converts Excel
spreadsheet data into JSON and the other bit that takes an Excel
spreadsheet and fills it with data from JSON.
Putting both together allows you to create many Excel files, each using
the same Excel file as template, but filling each one with data from a
list of JSON objects. This is very similar to the Merge function in
Word, but the template is an Excel spreadsheet.
Converting Excel rows to JSON
-----------------------------
This tool opens an Excel file and converts each row to a JSON object. It
uses JSON Path to put cell values into the appropriate location in the
JSON object.
[width="100%",cols="25%,25%,25%,25%",options="header"]
|===============================================
|Registration Date |Last Name |First Name |Email
|3-Jul-16 |Doe |Mary |mary.doe@localhost
|5-May-16 |Doe |John |john.doe@localhost
|27-Nov-16 |Doe |Joe |joe.doe@localhost
|===============================================
The trivial mapping would convert the first row into an array:
[source,json]
----
[ "3-Jul-16", "Doe", "Mary", "mary.doe@localhost" ]
----
That’s not very helpful, but it is JSON! We provide information on
mapping of each spreadsheet column:
[width="100%",cols="25%,25%,25%,25%"]
|===============================================
|date|last|first|email
|===============================================
This mapping produces a much more informative object:
[source,json]
----
{
"date": "3-Jul-16",
"last": "Doe",
"first": "Mary",
"email": "mary.doe@localhost"
}
----
Note: Empty or null mapping will ignore the column.
Sub-object mapping
^^^^^^^^^^^^^^^^^^
You can map the personal information from the spreadsheet to a
sub-object.
[source,json]
----
{
"date": "3-Jul-16",
"person": {
"last": "Doe",
"first": "Mary",
"email": "mary.doe@localhost"
}
}
----
The mapping instructions that generate this JSON are:
[width="100%",cols="25%,25%,25%,25%"]
|===============================================
|date|person.last|person.first|person.email
|===============================================
Mapping to arrays
^^^^^^^^^^^^^^^^^
Mapping spreadsheet data to arrays:
[source,json]
----
{ ..., "names": [ "Doe", "Mary"], ...}
----
The mapping instructions that generate this JSON are:
[source,json]
----
[ "date", "names[0]", "names[1]", "email" ]
----
Data conversion
~~~~~~~~~~~~~~~
The tool will keep spreadsheet numbers as numbers and it will attempt to
convert dates to the POSIX timestamp.
Note: The “Date detection” is based on the cell formatting information.
Providing default values
^^^^^^^^^^^^^^^^^^^^^^^^
Instead of starting off from a blank JSON object you can provide the
initial JSON document. The library will extend the default object with
mapped values.
Filling Excel with JSON data
----------------------------
Say you have an Excel spreadsheet that looks more or less like a form:
[width="100%",cols="33%,67%",]
|================================================================
2+|This is a simple registration form. Please fill out the details and send by email back to us.
|*Registration date*|The date (dd-mmm-yyyy)
2+|Personal information
|*Your name*|
|*First name*|
|*Company*|
2+|Other information
|*XXX*|
|*ZZZ*|
|================================================================
This tool allows for filling out Excel templates with data provided as
JSON. Each cell that should be filled must have a Name reference defined
in Excel. The tool inspects all names defined and uses the ones starting
with `JSON.` to properly populate the cell.
The syntax for the cell name follows JSON Path: `"JSON." + jsonPath`
Simple example
~~~~~~~~~~~~~~
The input JSON object that is used to populate the spreadsheet:
[source,json]
----
{
"date": "3-Jul-16",
"person": {
"last": "Doe",
"first": "Mary",
"email": "mary.doe@localhost"
}
}
----
Name JSON.date will pull “3-Jul-16” from JSON, JSON.person.last will
pull “Doe”, and JSON.person.first will pull “Mary”, etc.
Data from arrays
~~~~~~~~~~~~~~~~
Your template may contain a tabular section:
[width="100%",cols="34%,33%,33%",]
|================================================================
3+|A section with tabular data in the Excel template
|*Dependant*|*Date of birth*|*Email*
|Please fill...||
|Please fill...||
|Please fill...||
|================================================================
With the input JSON containing the data:
[source,json]
----
{
"date": "3-Jul-16",
"dependants": [
{ "name": "Deb", "dob": "1-Jan-1971", "email": "deb.doe@localhost" },
{ "name": "Deborah", "dob": "2-Jan-1972", "email": "deborah.doe@localhost" },
{ "name": "Debby", "dob": "3-Jan-1973", "email": "debby.doe@localhost" }
]
}
----
First, the name is defined that references all the rows and columns of
the subtable. The name should match the JSON Path expression that
resolves to the array (in this case “dependants"). The Excel range name
needs to be `JSON.dependants`.
The first row of the defined range is used to define how the array
elements map to the columns. Each cell in the first row defines a new
name range:
[width="100%",cols="34%,33%,33%",]
|================================================================
|`JSON.dependants.name` |`JSON.dependants.dob` |`JSON.dependants.email`
|================================================================
The JSON Path expression for column with names is `dependants[].name`.
Excel Name names do not allow for special characters (*[, ], =, -*),
therefore the “array” reference of JSON path expression is ignored.
The spreadsheet filled with data from the JSON:
[width="100%",cols="34%,33%,33%",]
|================================================================
3+|A section with tabular data in the Excel template
|*Dependant*|*Date of birth*|*Email*
|Deb|1-Jan-1971|deb.doe@localhost
|Deborah|2-Jan-1972|deborah.doe@localhost
|Debby|3-Jan-1973|debby.doe@localhost
|================================================================
Excel Merge
-----------
This is very similar to the Merge function in Word, but the template is
an Excel spreadsheet and the result are many Excel files filled with
data sourced from another spreadsheet.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment