{"id":16415442,"url":"https://github.com/ttskch/svg-paper","last_synced_at":"2025-03-21T03:32:05.699Z","repository":{"id":226527951,"uuid":"375233326","full_name":"ttskch/svg-paper","owner":"ttskch","description":"The world's most maintainable way to create paper-printable documents 🖨💘","archived":false,"fork":false,"pushed_at":"2021-07-20T05:23:53.000Z","size":1425,"stargazers_count":28,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-18T10:27:50.562Z","etag":null,"topics":["a4","adobe-xd","figma","pdf","pdf-generation","svg"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/ttskch.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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-06-09T05:12:21.000Z","updated_at":"2024-09-25T06:13:18.000Z","dependencies_parsed_at":"2024-03-08T03:48:24.826Z","dependency_job_id":null,"html_url":"https://github.com/ttskch/svg-paper","commit_stats":{"total_commits":47,"total_committers":2,"mean_commits":23.5,"dds":"0.021276595744680882","last_synced_commit":"9c898c25e4a141d55ec658cda184926c82a75bbb"},"previous_names":["ttskch/svg-paper"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttskch%2Fsvg-paper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttskch%2Fsvg-paper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttskch%2Fsvg-paper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttskch%2Fsvg-paper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ttskch","download_url":"https://codeload.github.com/ttskch/svg-paper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221811376,"owners_count":16884305,"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":["a4","adobe-xd","figma","pdf","pdf-generation","svg"],"created_at":"2024-10-11T07:05:47.754Z","updated_at":"2025-03-21T03:32:05.692Z","avatar_url":"https://github.com/ttskch.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# svg-paper\n\n[![Travis (.com)](https://img.shields.io/travis/com/ttskch/svg-paper.svg?style=flat-square)](https://travis-ci.com/ttskch/svg-paper)\n[![npm version](https://img.shields.io/npm/v/svg-paper.svg?style=flat-square)](https://www.npmjs.com/package/svg-paper)\n[![npm](https://img.shields.io/npm/dm/svg-paper?label=npm\u0026style=flat-square)](https://www.npmjs.com/package/svg-paper)\n[![](https://data.jsdelivr.com/v1/package/npm/svg-paper/badge)](https://www.jsdelivr.com/package/npm/svg-paper)\n\nThe world's most maintainable way to create paper-printable documents 🖨💘\n\n![](https://user-images.githubusercontent.com/4360663/121766151-f6b64d80-cb8a-11eb-8736-3a28b4c03d70.png)\n\n## TOC\n\n\u003cdetails\u003e\n\n* [Workflows](#workflows)\n* [Installation](#installation)\n    * [CDN](#cdn)\n    * [npm](#npm)\n* [How to prepare SVG template](#how-to-prepare-svg-template)\n* [Basic usage](#basic-usage)\n* [Beautify preview screen](#beautify-preview-screen)\n* [Passing variables from back-end to front-end](#passing-variables-from-back-end-to-front-end)\n    * [PHP and Twig example](#php-and-twig-example)\n* [Tips](#tips)\n  * [Hiding content before placeholders are replaced](#hiding-content-before-placeholders-are-replaced)\n* [PDF generation](#pdf-generation)\n\n\u003c/details\u003e\n\n## Workflows\n\nYou can print beautiful and maintainable paper documents by following steps.\n\n1. Design the document with [Adobe XD](https://www.adobe.com/products/xd.html), [Figma](https://www.figma.com/), or something\n1. Export it as SVG\n1. Embed SVG into your HTML and fix it with **svg-paper** on client side\n1. That's it 💥\n\n## Installation\n\n### CDN\n\nYou can get the built assets from [jsDelivr](https://www.jsdelivr.com/package/npm/svg-paper).\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/svg-paper/dist/svg-paper.min.css\"\u003e\n```\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/svg-paper/dist/svg-paper.min.js\"\u003e\u003c/script\u003e\n```\n\n### npm\n\nOf course you also can install via [npm](https://www.npmjs.com/package/svg-paper).\n\n```bash\n$ npm install svg-paper\n```\n\n## How to prepare SVG template\n\nSee [this doc](docs/how-to-prepare-svg-template.md) 📝\n\n## Basic usage\n\nFirst, just embed SVG content in `.paper` element like following.\n\n```html\n\u003cbody\u003e\n  \u003cdiv class=\"paper\"\u003e\n    \u003csvg\u003e...\u003c/svg\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\nNext, load `svg-paper[.min].js` with `\u003cscript\u003e` tag or import/require `svg-pager[.min].js` as a module.\n\n```html\n\u003cscript src=\"svg-paper.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const paper = new SvgPaper()\n  // ...\n\u003c/script\u003e\n```\n\nor\n\n```js\nimport SvgPaper from 'svg-paper'\n// or\n// const SvgPaper = require('svg-paper')\n\nconst paper = new SvgPaper()\n```\n\nThen you can replace or adjust SVG contents in DOM easily with svg-paper like following.\n\n```js\npaper\n  // replace placeholder to actual value\n  .replace('%placeholder1%', 'Actual value 1')\n  // ... and more\n\n  // set max width to 1000\n  // in the other words, if actual width of the content is bigger than 1000 it shrinks automatically\n  .adjustText('#selector1', 1000)\n\n  // set max width to 800 and brings the element #selector2 to the center of 800 width area   \n  .adjustText('#selector2', 800, 'middle')\n\n  // of course you can bring it to the end\n  .adjustText('#selector3', 800, 'end')\n\n  // automatically wrap or shrink actual content so that it fits within the specified area (600 x 300)\n  .adjustTextarea('#selector4', 600, 300)\n\n  // you can pass some additional args\n  .adjustTextarea('#selector5',\n    600,  // width \n    300,  // height\n    1.2,  // lineHeight : default is 1.2 times font-size\n    0.5,  // paddingX   : default is 0.5 times font-size\n    0.5,  // paddingY   : default is 0.5 times font-size\n    false // nowrap     : default is false. if true, content will not be wrapped\n  )\n\n  // finally, apply all replacing and adjusting to DOM\n  .apply()\n```\n\n## Beautify preview screen\n\nTo beautify preview screen, you should add only 3 lines to your HTML 👍\n\n```html\n\u003chead\u003e\n  ...\n  \u003clink rel=\"stylesheet\" href=\"svg-paper.min.css\"\u003e \u003c!-- here --\u003e\n  \u003cstyle\u003e@page { size: A4 }\u003c/style\u003e \u003c!-- here --\u003e\n\u003c/head\u003e\n\n\u003cbody\u003e\n  \u003cdiv class=\"paper A4\"\u003e \u003c!-- here --\u003e\n    \u003csvg\u003e...\u003c/svg\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\nJust load `svg-paper.min.css` (or `svg-paper.css`), in `\u003chead\u003e` set [@page size](https://developer.mozilla.org/en-US/docs/Web/CSS/@page/size), and set the class of `.paper` element to specify page size.\n\nAvailable page sizes are:\n\n* `A3` `A3 landscape`\n* `A4` `A4 landscape`\n* `A5` `A5 landscape`\n* `letter` `letter landscape`\n* `legal` `legal landscape`\n\n## Passing variables from back-end to front-end\n\nsvg-paper depends on DOM, so in most cases you have to pass variables to be replaced with placeholders in template from back-end to front-end.\n\nThe most easy ways is just passing replacements and text/textarea adjustment parameters to front-end as JSON string.\n\n### PHP and Twig example\n\n```php\n// Controller\npublic function paperAction($id)\n{\n    $model = $repository-\u003efindById($id);\n    \n    return $this-\u003erender('paper.html.twig', [\n        'svg' =\u003e file_get_contents('/path/to/paper.svg'),\n        'replacements' =\u003e [\n            '%name%' =\u003e $model-\u003ename,\n            // ... and more\n        ],\n    ]);\n}\n```\n\n```twig\n{# paper.html.twig #}\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  \u003clink rel=\"stylesheet\" href=\"svg-paper.min.css\"\u003e\n  \u003cstyle\u003e@page { size: A4 }\u003c/style\u003e\n\u003c/head\u003e\n\n\u003cbody\u003e\n  \u003cdiv class=\"paper A4\"\u003e\n    {{ svg|raw }}\n  \u003c/div\u003e\n  \u003cdiv data-replacements=\"{{ replacements|json_encode }}\"\u003e\u003c/div\u003e\n\n  \u003cscript src=\"svg-paper.min.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"your-script.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n```js\n// your-script.js\nconst paper = new SvgPaper()\n\nconst replacements = $('[data-replacements]').data('replacements')\n\nfor (let [search, replacement] of Object.entries(replacements)) {\n  paper.replace(search, replacement)\n}\n\npaper.apply()\n```\n\n## Tips\n\n### Hiding content before placeholders are replaced\n\nsvg-paper replaces placeholders and adjust text/textarea after DOM loaded, so the content before replaced and adjusted will be shown on the screen for a moment 🤔\n\nThis problem is very easy to solve just by adding some \"blinder\" layer on the content and disappear it after `.apply()` 👍\n\n```html\n\u003cbody\u003e\n  \u003cdiv id=\"blinder\" style=\"width:100vw; height:100vh; background-color:#ccc\"\u003e\u003c/div\u003e\n  \u003cdiv class=\"paper\"\u003e\n    \u003csvg\u003e...\u003c/svg\u003e\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\n```js\npaper.apply()\n\ndocument.querySelector('#blinder').style.display = 'none'\n```\n\n## PDF generation\n\nYou can easily print to PDF directly by using [electron-pdf](https://github.com/fraserxu/electron-pdf).\n\nThe basic usage of electron-pdf is following.\n\n```bash\n$ npm install --global electron-pdf\n$ electron-pdf your-document.html your-document.pdf\n```\n\nBut svg-paper modifies HTML content by JavaScript, so you have to wait it before printing by following.\n\n```bash\n$ electron-pdf your-document.html your-document.pdf -e # -e is the shorthand for --waitForJSEvent\n```\n\n```html\n\u003c!-- your document --\u003e\n\u003cbody\u003e\n  ...\n  \u003cscript\u003edocument.body.dispatchEvent(new Event('view-ready'))\u003c/script\u003e \u003c!-- 'view-ready' is the default event name for --waitForJSEvent --\u003e\n\u003c/body\u003e\n```\n\nTo learn more see [README of electron-pdf](https://github.com/fraserxu/electron-pdf#to-generate-a-pdf-after-the-an-async-task-in-the-html).\n\nEnjoy! ✨\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttskch%2Fsvg-paper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fttskch%2Fsvg-paper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttskch%2Fsvg-paper/lists"}