diff --git a/docs/content/1.getting-started/1.index.md b/docs/content/1.getting-started/1.index.md index 3114021..9f27475 100644 --- a/docs/content/1.getting-started/1.index.md +++ b/docs/content/1.getting-started/1.index.md @@ -1,22 +1,53 @@ --- -description: "Introduction to `nuxt-pdf` and its features for exporting html pages to pdf." +description: "Introduction to `nuxt-pdf`." --- # Introduction -`nuxt-pdf` is a Nuxt 3 wrapper around [jsPDF](https://github.com/parallax/jsPDF), a package that allows you to export PDF documents from your web apps. +`nuxt-pdf` is an open source Nuxt 3 PDF toolkit, that allows you to easily render PDFs application or server side. ::list{type="success"} -- Adds built in Nuxt 3 support to export components to a PDF Document -- Works with native Nuxt 3 refs, allowing you to keep your clean Nuxt 3 code free from any external package +- Client side exporting of Vue components to HTML +- Server side rendering of complex PDFs +- Simple encryption of your PDFs, by allowing you to set a password and permissions +- Editable forms inside your PDFs +- Pre-build components to quickly develop your PDF +- documentation, recipes and example code to get you started :: -After installing the module you will be able to access the function like so: -```ts -// file: ~/app.vue -import { exportToPDF } from '#imports' +::callout +#summary +Show me the code! -await exportToPDF('my-pdf-file.pdf', HTMLElement) -``` +#content +Visit the [quick start](/nuxt-pdf/getting-started/quick-start) page to see code examples. +:: + +## Which method is right for me? + +Generating PDFs on the client or through the server fundamentally change how the PDF is compiled and created. We try and ensure that our feature set matches both methods equally, however there are a few method-specific features. These are listed below. + +| | Application Side | Server Side | +|-----------------------------------------------------|------------------|-------------| +| **Features** | | | +| Convert Vue components to PDFs | ✅ | ❌ | +| Add Encryption to your PDFs | ✅ | ✅ | +| Define Layouts for your PDFs | ❌ | ✅ | +| Use your Tailwind Styles | ✅ | ❌ | +| Use pre-build components to create your PDF | ❌ | ✅ | +| Define your default PDF options in `nuxt.config.ts` | ❌ | ✅ | + +One factor that this table does not take into account is the reliablity and consistency, that server side generated PDFs will add to your application. Generating a PDF from HTML code, may result in different appearences, based on the browser, screen size and other settings on an individuals PC, limiting the control you have over the finished product. Rendering your PDFs on the server side, will allow you to control the output to a mich higher degree. + +### Use cases + +#### Application side + +- You need to quickly develop your PDF integration +- You already have Vue components developed, that can be reused to generate the PDFs +- You are not concerned about minor layout shifts and differences between browsers + +#### Server side -See more in the [Quick Start section](/nuxt-pdf/getting-started/quick-start). +- You require a higher degree of control over the output +- You are developing complex PDFs that may require large amounts of data, you do not want to directly expose to a users client diff --git a/docs/content/1.getting-started/3.quick-start.md b/docs/content/1.getting-started/3.quick-start.md index a05bcee..c7ff97c 100644 --- a/docs/content/1.getting-started/3.quick-start.md +++ b/docs/content/1.getting-started/3.quick-start.md @@ -12,9 +12,20 @@ export default defineNuxtConfig({ }) ``` -That's it! You can now begin exporting Nuxt 3 components to PDF. For example: +## Examples + +That's it! You can now begin creating PDFs in your Nuxt 3 application! + +### Application side + +You can export Vue components to HTML through our composables. You can learn more about using `nuxt-pdf` in the application side [here](/nuxt-pdf/application-side). ```vue +// file: ~/components/PDF.vue + + +``` - -``` +Or use our server side code based approch to define your design! You can learn more about using `nuxt-pdf` on the server side [here](/nuxt-pdf/server-side). -We offer two separate options parameters, that allow you to customize your pdf export. +```ts +// file: ~/server/api/pdf/my-pdf.vue +import { createPDF, streamReturnPDF } from '#pdf' + +export default eventHandler(async (event) => { + const pdf = createPDF() + pdf.text('Welcome to NuxtPDF!') + pdf.end() -- The `documentOptions`, allow you to customize the general layout of your document. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/jsPDF.html). -- The `htmlOptions`, allow you to customize the conversion of your HTML to a canvas. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/module-html.html#~html). + return streamReturnPDF(event, pdf) +}) +``` diff --git a/docs/content/1.getting-started/4.composables.md b/docs/content/1.getting-started/4.composables.md deleted file mode 100644 index 5af26c4..0000000 --- a/docs/content/1.getting-started/4.composables.md +++ /dev/null @@ -1,46 +0,0 @@ -# Composables - -`nuxt-pdf` exposes multiple composables, that you can access to easily create pdfs through vue code. - - -## exportToPDF - -Through this composable you can directly reference a HTML element, which will then be exported to a PDF. - -```ts -import { exportToPDF } from '#imports' - -const pdfSection = ref(null) - -const DOCUMENT_OPTIONS = {} // See all options: http://raw.githack.com/MrRio/jsPDF/master/docs/jsPDF.html -const HTML_OPTIONS = {} // See all options: http://raw.githack.com/MrRio/jsPDF/master/docs/module-html.html#~html - -await exportToPDF('FILE_NAME.pdf', pdfSection, DOCUMENT_OPTIONS, HTML_OPTIONS) -``` - -## htmlToPdf - -`htmlToPdf` allows you to pass an HTML string and format it into a PDF. This can allow you to futhur customize the behaviour of how the module interacts with your UI. - -```ts -import { htmlToPdf } from '#imports' - -const openInWindow = async (HTMLElement: HTMLElement) => { - const pdf = await htmlToPdf(HTMLElement, - undefined, - { - html2canvas: { - scale: 0.7, - useCORS: true - } - }) - const totalPages = pdf.getNumberOfPages() - const pdfHeight = pdf.getPageHeight() - await pdf.html('I am a custom pdf!!!', { - x: 20, - y: (pdfHeight - 50) * totalPages // place in the bottom - }) - const blob = pdf.output('blob') - window.open(URL.createObjectURL(blob), '_blank') -} -``` diff --git a/docs/content/1.getting-started/5.getting-help.md b/docs/content/1.getting-started/4.getting-help.md similarity index 100% rename from docs/content/1.getting-started/5.getting-help.md rename to docs/content/1.getting-started/4.getting-help.md diff --git a/docs/content/2.application-side/4.composables.md b/docs/content/2.application-side/4.composables.md new file mode 100644 index 0000000..360cfac --- /dev/null +++ b/docs/content/2.application-side/4.composables.md @@ -0,0 +1,75 @@ +# Composables + +`nuxt-pdf` exposes multiple composables, that you can access to easily create pdfs through vue code. + +## Options + +Both of our composables, accept 2 seperate configuration options. +- The `documentOptions`, allow you to customize the general layout of your document. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/jsPDF.html). +- The `htmlOptions`, allow you to customize the conversion of your HTML to a canvas. You can find the options [here](http://raw.githack.com/MrRio/jsPDF/master/docs/module-html.html#~html). + + +## `exportToPDF` + +`exportToPDF` allows you to usea native vue ref, to target either a native HTML element, or a Vue component, which will then be converted into a PDF. + +The composable accepts 4 parameters: +- The fileName +- The component you wish to convert +- The documentOptions +- The HTMLOptions. + +To learn more about the options, please refer [here](#options) + +```vue + + + +``` + +### Tips & Tricks + +- Ensure that the section you want to export has a fixed width, to ensure the layout does not shift when exporting +- Setting a fixed width and height, to match your document size, will lead to better results +- Use the `scale` option in the document section, to slightly increase or decrease the size of the rendered html +- Optimize your HTML to reduce the PDF file size + +## `htmlToPDF` + +`htmlToPdf` allows you to pass an HTML string and format it into a PDF. This can allow you to futhur customize the behaviour of how the module interacts with your UI. + +```ts +import { htmlToPdf } from '#imports' + +const openInWindow = async (HTMLElement: HTMLElement) => { + const pdf = await htmlToPdf(HTMLElement, + undefined, + { + html2canvas: { + scale: 0.7, + useCORS: true + } + }) + const totalPages = pdf.getNumberOfPages() + const pdfHeight = pdf.getPageHeight() + await pdf.html('I am a custom pdf!!!', { + x: 20, + y: (pdfHeight - 50) * totalPages // place in the bottom + }) + const blob = pdf.output('blob') + window.open(URL.createObjectURL(blob), '_blank') +} +``` diff --git a/docs/content/2.application-side/_dir.yml b/docs/content/2.application-side/_dir.yml new file mode 100644 index 0000000..201d148 --- /dev/null +++ b/docs/content/2.application-side/_dir.yml @@ -0,0 +1,2 @@ +title: Application-Side +icon: heroicons-outline:computer-desktop diff --git a/docs/content/3.server-side/_dir.yml b/docs/content/3.server-side/_dir.yml new file mode 100644 index 0000000..06a72e8 --- /dev/null +++ b/docs/content/3.server-side/_dir.yml @@ -0,0 +1,2 @@ +title: Server-Side +icon: heroicons-outline:computer-desktop