{"id":15010657,"url":"https://github.com/tokenmill/docx-utils","last_synced_at":"2025-04-09T18:34:30.685Z","repository":{"id":62433506,"uuid":"96019564","full_name":"tokenmill/docx-utils","owner":"tokenmill","description":"Easily work with .docx files from Clojure (a wrapper on Apache POI library).","archived":false,"fork":false,"pushed_at":"2019-09-04T10:54:45.000Z","size":256,"stargazers_count":12,"open_issues_count":5,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-25T09:31:10.817Z","etag":null,"topics":["clojars","clojure","docx","poi"],"latest_commit_sha":null,"homepage":"","language":"Clojure","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/tokenmill.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-07-02T11:41:24.000Z","updated_at":"2024-09-10T13:48:30.000Z","dependencies_parsed_at":"2022-11-01T21:15:56.096Z","dependency_job_id":null,"html_url":"https://github.com/tokenmill/docx-utils","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenmill%2Fdocx-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenmill%2Fdocx-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenmill%2Fdocx-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenmill%2Fdocx-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tokenmill","download_url":"https://codeload.github.com/tokenmill/docx-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248088263,"owners_count":21045671,"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":["clojars","clojure","docx","poi"],"created_at":"2024-09-24T19:35:13.590Z","updated_at":"2025-04-09T18:34:30.664Z","avatar_url":"https://github.com/tokenmill.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"http://www.tokenmill.lt\"\u003e\n      \u003cimg src=\".github/tokenmill-logo.svg\" width=\"125\" height=\"125\" align=\"right\" /\u003e\n\u003c/a\u003e\n\n# docx-utils\nLibrary that helps to work with `.docx` files.\n\nEssentially, it is a Clojure wrapper on [Apache POI](https://poi.apache.org/) library.  \n\nThe main idea is to use plain data instead of Apache POI classes to transform a `.docx` document.\n\nThere are 2 types of transformations: append and replace.\n\nIt is possible to append and replace the following data types:\n- in-line text;\n- paragraph text;\n- image;\n- table;\n- bullet list;\n- numbered list.\n\n## Latest Version\nThe latest version of `docx-utils` is hosted on [Clojars](https://clojars.org/lt.tokenmill/docx-utils):\n\n[![Clojars Project](https://img.shields.io/clojars/v/lt.tokenmill/docx-utils.svg)](https://clojars.org/lt.tokenmill/docx-utils)\n\n## Main concepts\nMain entrance function is `docx-utils.core/transform`. It has 3 versions:\n- 1 argument version takes in a list of transformations, it creates an empty `.docx` document, applies all transformations and returns a file path of the resulting document. Note that Resulting file is created in a temp folder and it will be deleted after the JVM exits. This function could/should be used to create a template `docx` document.\n- 2 argument version takes in a template-file-path and a list of transformations. It loads the template document applies transformations and returns the resulting document. If the template-file-path is nil then new `docx` is created and used as a template.\n- 3 argument version takes in a template-file-path, output-file-path and a list of transformations. It loads a template document, applies the transformations and stores the resulting document in a file under the output-file-path. If output-file-path is `nil` then error is thrown.\n\nNote that if a placeholder is not found in the template then nothing happens, only a log warning is produced.\n\n## Documentation\nThe complete [API documentation](https://tokenmill.github.io/docx-utils/) is also available (codox generated).\n\n## Examples\nTo replace a placeholder with a paragraph text:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :replace-text\n                             :placeholder \"%{PLACEHOLDER}\"\n                             :replacement \"Standalone paragraph.\"}])\n```\n\nTo replace a placeholder inside a text paragraph:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :replace-text-inline\n                             :placeholder \"%{PLACEHOLDER}\"\n                             :replacement \"in-lined text\"}])\n```\n\nTo replace a placeholder with a data `table`:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :replace-table\n                             :placeholder \"%{PLACEHOLDER}\"\n                             :replacement [[\"cell 11\" \"cell 12\" \"cell 13\"]\n                                           [\"cell 21\" \"cell 22\" \"cell 23\"]]}])\n```\n\nTo replace a placeholder with a bulleted list:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :replace-bullet-list\n                             :placeholder \"%{PLACEHOLDER}\"\n                             :replacement [\"item 1\" \"item 2\" \"item 3\"]}])\n```\n\nTo replace a placeholder with a numbered list:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :replace-numbered-list\n                             :placeholder \"%{PLACEHOLDER}\"\n                             :replacement [\"item 1\" \"item 2\" \"item 3\"]}])\n```\n\nTo replace a placeholder with an image:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :replace-image\n                             :placeholder \"%{PLACEHOLDER}\"\n                             :replacement \"/path/to/image/file.jpg\"}])\n```\n\nTo append a text paragraph to the end of the template document:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :append-text\n                             :replacement \"Text paragraph.\"}])\n```\n\nTo append a text snippet to the end of the last paragraph of the template document:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :append-text-inline\n                             :replacement \"text snippet\"}])\n```\n\nTo append a data table to the end of the template document:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :append-table\n                             :replacement [[\"cell 11\" \"cell 12\" \"cell 13\"]\n                                           [\"cell 21\" \"cell 22\" \"cell 23\"]]}])\n```\n\nTo append a bullet list to the end of the template document:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :append-bullet-list\n                             :replacement [\"item a\" \"item b\" \"item c\"]}])\n```\n\nTo append a numbered list to the end of the template document:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :append-numbered-list\n                             :replacement [\"item a\" \"item b\" \"item c\"]}])\n```\n\nTo append an image to the end of the template document:\n```clojure\n(docx-utils.core/transform \"/path/to/template/file.docx\"\n                           [{:type        :replace-image\n                             :replacement \"/path/to/image/file.jpg\"}])\n```\n\n# Future work\n- `:replacement` could be either a `String` or a map. If `String` then the value is pasted into the document without any additional formating (the formating of the placeholder is preserved), if a map is provided the underlying `Run` is formated accordingly to the options provided in a map, e.g. `{:bold true :text \"Bolded text\"}`.\n- `:type` value should be somehow taken from a list of values. Maybe a namespace with constants? e.g. `(def REPLACE_TEXT :replace-text)`. Or Java enums?\n- expose a Java interface to the library.\n\n## License\n\nCopyright \u0026copy; 2017-2019 [TokenMill UAB](http://www.tokenmill.lt).\n\nDistributed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenmill%2Fdocx-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftokenmill%2Fdocx-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenmill%2Fdocx-utils/lists"}