{"id":16098835,"url":"https://github.com/tormozz48/xlsx-template","last_synced_at":"2025-08-26T12:04:52.153Z","repository":{"id":41579724,"uuid":"232062911","full_name":"tormozz48/xlsx-template","owner":"tormozz48","description":"Fill xlsx template with placeholders. Replaces them by provided data.","archived":false,"fork":false,"pushed_at":"2021-04-06T07:39:57.000Z","size":655,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T10:36:26.459Z","etag":null,"topics":["array","date","excel","formatters","link","number","placeholders","template","template-library","templating","xlsx","xlsx-template","xlsx-workbook"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tormozz48.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-06T09:04:08.000Z","updated_at":"2025-02-27T17:19:46.000Z","dependencies_parsed_at":"2022-08-20T10:10:39.743Z","dependency_job_id":null,"html_url":"https://github.com/tormozz48/xlsx-template","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tormozz48%2Fxlsx-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tormozz48%2Fxlsx-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tormozz48%2Fxlsx-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tormozz48%2Fxlsx-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tormozz48","download_url":"https://codeload.github.com/tormozz48/xlsx-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248594143,"owners_count":21130313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["array","date","excel","formatters","link","number","placeholders","template","template-library","templating","xlsx","xlsx-template","xlsx-workbook"],"created_at":"2024-10-09T18:24:50.417Z","updated_at":"2025-04-12T16:12:12.264Z","avatar_url":"https://github.com/tormozz48.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xlsx-template\nFill workbook by given data into places marked by special placeholders.\n\n[![Build Status](https://travis-ci.org/tormozz48/xlsx-template.svg?branch=master)](https://travis-ci.org/tormozz48/xlsx-template)\n[![codecov](https://codecov.io/gh/tormozz48/xlsx-template/branch/master/graph/badge.svg)](https://codecov.io/gh/tormozz48/xlsx-template)\n\n## Install\n\nInstall package via npm:\n```\nnpm install @tormozz48/xlsx-template\n```\n\n## Usage Example\nAssume there `./template-simple.xlsx` XLSX file in your working directory with given content:\n\n| # | A | B | C | D | E |\n| --- | --- | --- | --- | --- | --- |\n| 1 | str(data.strVal) | number(data.numberVal 0.00) | date(data.dateVal dd/mm/yyyy) | link(data.linkVal) | {str(data.strVal)} |\n| 2 |   | number(data.numberVal) | date(data.dateVal) | | |\n\n```js\nconst {XLSXPopulateTemplate} = require('xlsx-template');\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\n\nawait xlsxPopulateTemplate.loadTemplate('./template-simple.xlsx');\nxlsxPopulateTemplate.applyData({\n    data: {\n        strVal: 'Some String value',\n        numberVal: 3.14159,\n        dateVal: new Date(2020, 0, 6),\n        linkVal: {text: 'some link', ref: 'http://github.com'}\n    }\n});\nawait xlsxPopulateTemplate.toFile('./output.xlsx');\n```\n\nCode above will create new file `./output.xlsx` with replacing all placeholders from `./template-simple.xlsx` on provided data.\nIt also will set valid format to cells according to used placeholders.\n\n| # | A | B | C | D | E |\n| --- | --- | --- | --- | --- | --- |\n| 1 | Some String value | 3,14 | 06/01/2020 | [some link](http://github.com) | str(data.strVal) |\n| 2 |   | 3,14159 | 06-01-2020 |   |   |\n\n### Apply values given by arrays.\n\nIt is possible to fill range of rows by values given as array. For example array of objects such as:\n```js\n[\n    {\n        strVal: 'Github',\n        numberVal: 134.1222,\n        dateVal: new Date(2020, 1, 1),\n        linkVal: {text: 'github', ref: 'https://github.com'}\n    },\n    {\n        strVal: 'Facebook',\n        numberVal: 4352.232,\n        dateVal: new Date(2020, 2, 23),\n        linkVal: {text: 'facebook', ref: 'https://facebook.com'}\n    },\n    {\n        strVal: 'Google',\n        numberVal: 733.2122321,\n        dateVal: new Date(2020, 3, 7),\n        linkVal: {text: 'google', ref: 'https://google.com'}\n    }\n]\n```\n\napplied to following template:\n\n| # | A | B | C | D |\n| --- | --- | --- | --- | --- |\n| 1 | str(data[i].strVal) | number(data[i].numberVal 0.00) | date(data[i].dateVal dd/mm/yyyy) | link(data[i].linkVal) |\n\nwill fill first three rows by corresponded values from data array:\n\n| # | A | B | C | D |\n| --- | --- | --- | --- | --- |\n| 1 | Github | 134,12 |\t01/02/2020 | [github](https://github.com) |\n| 2 | Facebook | 4352,23 |\t23/03/2020 | [facebook](https://facebook.com) |\n| 3 | Google |\t733,21 | 07/04/2020 | [google](https://google.com) |\n\n## Placeholders\n\n### str()\n\nPaste given value to a cell marked with placeholder and use default cell string formatter.\n\n| # | A |\n| --- | --- |\n| 1 | str(data.foo) |\n\n```js\nxlsxPopulateTemplate.applyData({data: {foo: 'Hello World'}});\n```\n\n| # | A |\n| --- | --- |\n| 1 | Hello World |\n\n### number()\n\nPaste given value to a cell and use number formatter. Optionally use second argument of number placeholder function to specify\nnumber format which should be applied to cell value.\n\n| # | A |\n| --- | --- |\n| 1 | number(data.foo, 0.00) |\n\n```js\nxlsxPopulateTemplate.applyData({data: {foo: 3.14159}});\n```\n\n| # | A |\n| --- | --- |\n| 1 | 3.14 |\n\n### date()\n\nPaste given value to a cell and use date formatter. Optionally use second argument of date placeholder function to specify\ndate format which should be applied to cell value. Default date format is `dd-mm-yyyy`.\n\n| # | A |\n| --- | --- |\n| 1 | date(data.foo dd/mm/yyyy) |\n\n```js\nxlsxPopulateTemplate.applyData({data: {foo: new Date(2020, 0, 9)}});\n```\n\n| # | A |\n| --- | --- |\n| 1 | 09/01/2020 |\n\n### link()\n\nCreate link value in cell with placeholder. Needs to receive data item as object with fields: `text` and `ref` where `text` - is\nlink text representation and `ref` - is link reference url.\n\n| # | A |\n| --- | --- |\n| 1 | link(data.foo) |\n\n```js\nxlsxPopulateTemplate.applyData({data: {foo: {text: 'Github', ref: 'https://github.com'}}});\n```\n\n| # | A |\n| --- | --- |\n| 1 | [Github](https://github.com) |\n\n\n### {} - raw formatter\n\nA special formatter which allows to simply expand inner placeholder without appliyng it. It is useful when\nthere you need to fill template with some part of needed data at first stage and then fill rest of data at second stage.\n\n| # | A |\n| --- | --- |\n| 1 | {str(data.foo)} |\n\n```js\nxlsxPopulateTemplate.applyData({});\n```\nAfter first call it simply expand inner placeholder `str(data.foo)` so it will be ready to use on next call.\n\n| # | A |\n| --- | --- |\n| 1 | str(data.foo) |\n\n```js\nxlsxPopulateTemplate.applyData({data: {foo: 'Hello World'}});\n```\n\n| # | A |\n| --- | --- |\n| 1 | Hello World |\n\n### array item placeholders\n\nTo fill multiple rows below by corresponded array items you should use `[i]` to mark data node\nthat should be applied as array of items.\n\n| # | A |\n| --- | --- |\n| 1 | str(data[i].name) |\n\n```js\nxlsxPopulateTemplate.applyData({data: [\n    {name: 'Github'},\n    {name: 'Facebook'},\n    {name: 'Google'}\n]);\n```\n\n| # | A |\n| --- | --- |\n| 1 | Github |\n| 2 | Facebook |\n| 3 | Google |\n\n## API\n\n#### .loadTemplate(templatePath)\n\nAsync function to load XLSX workbook from buffer of file or event create it from scratch.\nLoads XLSX workbook from file:\n```js\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\nawait xlsxPopulateTemplate.loadTemplate('./template-simple.xlsx');\n```\n\nLoads XLSX workbook from buffer:\n```js\nconst buffer = await fs.readFile('./template-simple.xlsx');\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\nawait xlsxPopulateTemplate.loadTemplate(buffer);\n```\n\nCreates XLSX workbook from scratch (empty workbook)\n```js\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\nawait xlsxPopulateTemplate.loadTemplate();\n```\n\n#### .applyData(data)\n\nFills matched template placeholders with given data.\n```js\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\nawait xlsxPopulateTemplate.loadTemplate();\nxlsxPopulateTemplate.applyData({foo: 'bar'})\n```\n\n#### .toBuffer()\n\nAsync function which serializes current workbook into buffer.\n\n```js\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\nawait xlsxPopulateTemplate.loadTemplate();\nconst buffer = await xlsxPopulateTemplate.toBuffer();\n```\n\n#### .toFile(filePath)\n\nAsync function which saves XLSX workbook into file with given filePath on local filesystem.\n\n```js\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\nawait xlsxPopulateTemplate.loadTemplate();\nawait xlsxPopulateTemplate.toFile('./my-awesome.xlsx');\n```\n\n#### .workbook\n\nGetter which simply returns XLSX workbook instance of [xlsx-populate2](https://www.npmjs.com/package/xlsx-populate2) package.\nIt is usefull for direct manipulation with workbook or it inner parts like cells, rows and columns.\n\n```js\nconst xlsxPopulateTemplate = new XLSXPopulateTemplate();\nawait xlsxPopulateTemplate.loadTemplate();\n\nconst workbook = xlsxPopulateTemplate.workbook;\nworkbook.sheet('Sheet1').cell('A1').value('Foo');\n```\n\n## Development\n\nSome useful commands for development:\n\n* `npm run build` - compiles typescript code into javascript code.\n* `npm run clean` - cleans js dist folder with compiled javascript code.\n* `npm run format` - performs code formatting via prettier tool.\n* `npm run lint` - runs tslint syntax checker.\n* `npm run test` - runs mocha tests.\n* `npm run test -watch` - runs mocha tests in \"watch\" mode. Launch tests on every code change.\n* `npm run test -cov` - runs mocha tests with coverage calculation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftormozz48%2Fxlsx-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftormozz48%2Fxlsx-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftormozz48%2Fxlsx-template/lists"}