Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/optimistex/xlsx-template-ex

The template engine for generate xlsx documents
https://github.com/optimistex/xlsx-template-ex

Last synced: about 1 month ago
JSON representation

The template engine for generate xlsx documents

Awesome Lists containing this project

README 

        
# Excel template engine



The Documentation available on languages:

1. [English](https://github.com/optimistex/xlsx-template-ex#readme)

2. [Русский](README.ru.md)



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:

```javascript

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



```javascript

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](https://github.com/optimistex/xlsx-template-ex/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](https://github.com/optimistex/xlsx-template-ex/blob/master/LICENSE) file for the full text)