From bbec1024b580df3f18afb03b78f0b604c84eef02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roger=20Sch=C3=B6nb=C3=A4chler?= <42278642+schoero@users.noreply.github.com> Date: Sun, 29 Oct 2023 10:02:32 +0100 Subject: [PATCH] docs: update migration guide --- docs/migration.md | 50 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 11 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index beec3e3..92fe292 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -4,39 +4,49 @@ With version 4 of SwissQRBill, the API has been completely reworked. The main goal was to make the API more flexible and reduce the complexity of the library. -In previous versions, SwissQRBill extended PDFKit and add a few methods to create the QR slip. While this approach made it really easy to create a QR Bill, it limited the flexibility of PDFKit and introduced a lot of complexity to the library. +In previous versions, SwissQRBill extended PDFKit and added a few methods to create the QR slip. While this approach made it really easy to create a QR Bill, it limited the flexibility of PDFKit and introduced a lot of complexity to the library. With the new API, you can now create an independent QR Slip and attach it to any existing PDFKit document. This removes all the limitations of previous versions and opens up a lot of new possibilities. However, this approach passes some of the complexity to the user, that was previously handled by the library. In version 4, the library contains the following parts - PDF - - SwissQRBill class to create a QR Slip as a PDF - - Table class to create a table + - SwissQRBill class to create a QR Slip to attach to an existing PDFKit document + - SwissQRCode class to create the standalone Swiss QR Code to attach to an existing PDFKit document + - Table class to create a table to attach to an existing PDFKit document - SVG - - SVG class to create a QR Slip as SVG + - SwissQRBill class to create a QR Slip as a SVG + - SwissQRCode class to create the standalone Swiss QR Code as a SVG - Utils - Utility functions +- Types + - Typescript types +- Errors + - Errors thrown by the library +- Bundle + - Pre built bundle of the library containing all the parts ## Breaking changes Lots of the API has changed. The following list contains the most important changes. -- The entrypoints have changed. Previously the library exported a "barrel file" that contained all the classes. Now the library exports the classes directly. +- The entrypoints have changed. Previously the library exported a "barrel file" that contained all the classes. Now the library exports the classes separately. - `swissqrbill/pdf` - - `swissqrbill/table` - `swissqrbill/svg` - `swissqrbill/utils` - `swissqrbill/types` - `swissqrbill/errors` -- The table method is now it's own class and has been completely rewritten. As a part of the rewrite, some properties have been renamed. Check the [updated documentation](./table/table.md) for the new names. -- Events are removed from SwissQRBill + - `swissqrbill/bundle` +- SwissQRBill no longer extends PDFKit. Instead, it is now a standalone class that can be used to create a QR Slip. The QR Slip can then be attached to any existing PDFKit document. +- The table method is now it's own class and has been completely rewritten. As a part of the rewrite, some properties have been renamed. Check the [updated documentation](./pdf/index.md#table) for the new names. The Table class can now also be attached to any existing PDFKit document. +- Events are removed from SwissQRBill. ## Migration ### Importing the library Depending on how you imported the library, you might need to change the import statement. +Please read the new [importing documentation](./importing.md) for more information and examples on how to import the library now. #### Node.js and self bundling (webpack) @@ -50,8 +60,7 @@ import { PDF } from "swissqrbill"; ```ts // SwissQRBill >= v4 import PDFDocument from "pdfkit"; -import { SwissQRBill } from "swissqrbill/pdf"; -import { Table } from "swissqrbill/table"; +import { SwissQRBill, Table } from "swissqrbill/pdf"; ``` #### Pre built bundle @@ -70,6 +79,25 @@ If you previously used the pre built bundle, provided by SwissQRBill, you now ha ``` +### Standalone classes + +Since SwissQRBill is now a standalone class, you have to create the PDFDocument separately from the QR slip. +You can then attach the QR slip to the document using the [`attachTo()`](./pdf/index.md#attachtodoc-xposition-yposition) method. + +```ts +const pdf = new PDFDocument(); +const qrBill = new SwissQRBill({ /* ... */ }); +qrBill.attachTo(pdf); +``` + +The same applies to the new Table class. + +```ts +const pdf = new PDFDocument(); +const table = new Table({ /* ... */ }); +table.attachTo(pdf); +``` + ### PDFKit events -SwissQRBill previously emitted events that could be used to add page numbers to the document. Since the library no longer extends PDFKit, this is no longer possible. You now have to follow the [documentation of PDFKit](http://pdfkit.org/docs/getting_started.html#switching_to_previous_pages) +SwissQRBill previously emitted events that could be used to add page numbers to the document. Since the library no longer extends PDFKit, this is no longer possible. You now have to follow the [documentation of PDFKit](http://pdfkit.org/docs/getting_started.html#switching_to_previous_pages) to learn how to add page numbers to your document.