xlsx-template-ex

The template engine for generate xlsx documents

Usage no npm install needed!

<script type="module">
  import xlsxTemplateEx from 'https://cdn.skypack.dev/xlsx-template-ex';
</script>

README

Excel template engine

The Documentation available on languages:

  1. English
  2. Русский

Supported files: xlsx

The component implements making some template-based reports. It has the flexible syntax similar to template expressions in the Angular framework.

The syntax

Supported 2 types of expressions:

  • Output a property value: {{value|pipe:arg1:argN}}
  • Output an array data: [[value|pipe:arg1:argN]]

Where:

  • value - name of property that contain some value or an array
  • pipe - some function for additional processing some value
  • arg1, argN - arguments/parameters passing to a pipe function

Implemented expression variants

  • {{propertyName}} - output a value as is

  • {{propertyName|date}} - the value formatted as date (DD.MM.YYYY)

  • {{propertyName|time}} - the value formatted as time (hh:mm:ss)

  • {{propertyName|datetime}} - the value formatted as date and time (DD.MM.YYYY hh:mm:ss)

  • {{fileName|image}} - find a picture file by file name. If the picture found, then it embed into a table cell

  • {{propertyArrayName|find:propertyName:propertyValue}} - find a value in the array propertyArrayName that has the property propertyName that equal propertyValue

  • {{propertyObjectName|get:propertyName}} - return a value of the property propertyArrayName from the object propertyObjectName

  • [[array|repeat-rows:3]] - process the array of values and output the content into the section from 3 rows started from current. The rows will be duplicated according to the size of the array.

  • [[array|filter:propertyName:checkValue]] - filter the array. If provided only propertyName, then We will get an array of objects that contain the property. If provided propertyName and checkValue, then We will get an array of objects that contain the property propertyName with value checkValue.

  • [[array|tile:blockRows:blockColumns:tileColumns]] - process the array of values and output the data by blocks. The source block defines by blockRows and blockColumns. The block will be output in a grid with tileColumns number columns.

Examples

We will output this data:

let data = {
    reportBuildDate: 1526443275041,

    results: [
        { text: 'some text 1', answerText: 'a text of an answer 1'},
        { text: 'some text 2', answerText: 'a text of an answer 2'},
        { text: 'some text 3', answerText: 'a text of an answer 3'},
        { answerText: 'a text of an answer 3'},
    ],
};

Let's make a template:

!!! In the example / used instead of | because of a trouble with the markdown syntax

A B
{{reportBuildDate/date}} {{results/find:text:some text 2/get:answerText}}
[[results/filter:text/repeat-rows:1]] {{text}} {{answerText}}
[[results/filter:text/tile:1:1:2]]{{answerText}}

Received result:

A B
16.05.2018 a text of an answer 2
some text 1 a text of an answer 1
some text 2 a text of an answer 2
some text 3 a text of an answer 3
a text of an answer 1 a text of an answer 2
a text of an answer 3

Get started

const fs = require("fs");
const XlsxTemplate = require('xlsx-template-ex');

const data = {
    reportBuildDate: 1526443275041,

    results: [
        { text: 'some text 1', answerText: 'a text of an answer 1'},
        { text: 'some text 2', answerText: 'a text of an answer 2'},
        { text: 'some text 3', answerText: 'a text of an answer 3'},
        { answerText: 'a text of an answer 3'},
    ],
};

XlsxTemplate.xlsxBuildByTemplate(data, 'template-file.xlsx')
    .then((buffer) => fs.writeFileSync('./out.xlsx', buffer))
    .catch((error) => console.log('xlsxHelper error:', error));

Troubleshooting

Please follow this guidelines when reporting bugs and feature requests:

  1. Use GitHub Issues board to report bugs and feature requests (not our email address)
  2. Please always write steps to reproduce the error. That way we can focus on fixing the bug, not scratching our heads trying to reproduce it.

Thanks for understanding!

Contribute

  • npm start - Run the demo from a production build.
  • npm run start-dev - Run the demo in a developing mode.
  • npm run build - Build the demo for production.

License

The MIT License (see the LICENSE file for the full text)