It is possible to extend the functionality of Lowdefy beyond the framework's current capabilities by creating custom blocks, actions or operators. In this how-to example we will create a custom action to generate PDF documents client side or in the browser.
The full project folder for this how-to is available at: https://github.com/lowdefy/lowdefy/tree/main/packages/docs/howto/generatePdf
To see how this works, click this button to generate a PDF of an example invoice that will be discussed in this how-to.
Now click this button to share this article on Twitter 😉
Generate PDF TLDR;
- Select a client side PDF library and add the JavaScript to your Lowdefy app, we'll be using pdfMake.
- Register a JsAction method to generate the PDF document.
- Load the custom JavaScript using a script tag.
- Add a button with a onClick action to call the generate PDF method.
- Define the content of your PDF and add data variables as needed.
Background
Generating PDFs are often required in workflow applications where data needs to be parsed into a document. These type of documents can be anything from quotes or invoices to contracts or even recipes. Making these documents represent the latest data, or exactly match the desired formatting can be tricky and time consuming. Auto generated PDFs are a great solution.
This how-to assumes that you are already running a Lowdefy app locally in dev mode. If not:
- Create a empty folder.
- Open your terminal or cmd and
cdto your empty folder.- Run
npx lowdefy@latest init && npx lowdefy@latest devto initialize and start your Lowdefy app development server.
1. Choosing a open-source PDF library
The power of open-source is mind blowing. There are a number of well tested, popular, easy to use and free PDF generating libraries that we can possibly use. We'll be using pdfMake since it is well documented, and simple configuration settings. Some of the popular ones are:
If you use open-source libraries to automate your business and save you time, please try to thank the maintainers by contributing where possible or simply providing sponsorship. Look for the sponsorship links usually found in the project readme files.
2. Register a custom JavaScript Action
Lowdefy actions are triggered by page events, like onClick when a user clicks a button, or onEnter when the page loads. Lowdefy comes with a list of predefined actions, however, sometimes custom code is the best awnser. Let's create a custom action which will generate a PDF based on pdfMake config.
- Create a
publicfolder inside your Lowdefy working directory. - Since all content in the
publicfolder is served by the Lowdefy server, simply create apdfMake.jsfile inside thepublicfolder. - Add this script to the file and save.
/public/modules/pdfMake.js
import importUmd from './importUmd.js';
import vfs from './vfs_fonts.js';
const pdfMake = await importUmd(
`https://cdn.jsdelivr.net/npm/pdfmake@0.2.2/build/pdfmake.min.js`
);
const pdfMakeFn = async (
context,
filename,
docDefinition,
tableLayouts,
fonts
) => {
await pdfMake
.createPdf(docDefinition, tableLayouts, fonts, vfs)
.download(filename);
};
window.lowdefy.registerJsAction('pdfMake', pdfMakeFn);This script does a few things, first, it imports importUmd.js and the vfs_fonts.js file also from our public folder. Then it loads pdfMake from jsdelivr. Then we create an async function pdfMakeFn which takes some parameters like the filename and docDefinition and passes it to pdfMake as it is being called.
Finally, it registers the pdfMakeFn function as a custom JsAction using window.lowdefy.registerJsAction. This gives our new method to the Lowdefy logic engine to use.
IMPORTANT: We mentioned two additional files here.
importUmd.jsis a helper function to load umd modules from a source, andvfs_fonts.jsis a virtualized font which we provide to pdfMake. Download these files and copy them into yourpublicfolder.
3. Load the custom JavaScript using a script tag
With our JavaScript ready, we need to load the JavaScript onto our page in order for it to be evaluated by the browser.
Create a my_header.html file inside your project route and add the following HTML:
/my_header.html
<script defer type="module" src="/public/modules/pdfMake.js"></script>This loads the pdfMake.js module file into HTML.
Also, add the HTML file to your Lowdefy application header. To do this, use the app.html.appendHead Lowdefy config property. Your lowdefy.yaml file should look something like this:
/lowdefy.yaml
name: Generate a PDF
lowdefy: v3.23.3
app:
html:
appendHead:
_ref: my_header.htmlCongratulations 🎉 your custom JSAction is now available in you Lowdefy app and ready to use.
Up until this part, this how-to has been very generic and will likely be the same for most apps using pdfMake to generate PDFs.
In the next part we'll configure our example app to generate a PDF.
4. Generate a PDF when a button is clicked
Next, we want to add a button to the page, and when the button is clicked, our PDF will be generated and downloaded, client side.
Let's make this quick and simple, we'll change our Lowdefy config to:
/lowdefy.yaml
name: Generate a PDF
lowdefy: 3.23.3
app:
html:
appendHead:
_ref: my_header.html
pages:
- id: generate-a-pdf
type: PageHeaderMenu
blocks:
- id: generate_pdf_button
type: Button
properties:
title: Download PDF
icon: DownloadOutlined
events:
onClick:
- id: make_pdf
type: JsAction
params:
name: pdfMake
args:
- my_file_name.pdf
- pageMargins: 50
defaultStyle:
fontSize: 10
content:
- text: This pdf has been generated with Lowdefy and pdfMake.
bold: trueWhen you run this app, you'll have a 'Download PDF' button, and when clicked, a pdf will be generated and downloaded. This example should work like the button below.
4. Define the content of the PDF
Finally to demonstrate how powerful this can be, we'll build out our pdfMake config to generate an invoice. In practice we would request the account data from our database and then pass the data to pdfMake when the button is clicked. For this example, we'll just hard code the invoice data and set it to the page state. The full project folder for this example is available at: https://github.com/lowdefy/lowdefy/tree/main/packages/docs/howto/generatePdf
/lowdefy.yaml
lowdefy: 3.23.3
name: Generate PDF from data with Lowdefy
app:
html:
appendHead:
_ref: my_header.html
pages:
- id: example
type: PageHeaderMenu
properties:
title: Example
events:
onEnter:
- id: init_data
type: SetState
params:
invoice:
id: '0030135'
account_id: 'A-11344'
inv_date:
_date: now
subtotal: 397.034
discount: -19.8517
vat: 59.5551
total: 436.7374
balance: 413.2330
customer:
name: Service Center
phone: +123-456-7890
vat_nmr: 12-333-4567
address: |
123 Main St.
Anytown
CA
US
9999
services:
- name: Hosting and Maintannce
qty: 1
price: 235.90
code: X12-33C
- name: Developer Hours
qty: 16
price: 60.345
code: X12-39A
- name: Designer Hours
qty: 4
price: 40.122
code: X12-21A
- name: Project Management
qty: 2
price: 60.667
code: X12-49A
areas:
content:
justify: center
blocks:
- id: docs_button
type: Button
properties:
size: large
title: Generate Invoice
color: '#1890ff'
events:
onClick:
- id: make_pdf
type: JsAction
params:
name: pdfMake
args:
_ref: inv_template.yamlNote that we have split out the pdfMake config into a seperate file inv_template.yaml. This makes it more readible and the same template used in various parts of our app config. This is implemented using the _ref operator.
/inv_template.yaml
- _nunjucks:
on:
_state: invoice
template: 'INV--.pdf'
- pageMargins: [50, 25, 50, 70]
defaultStyle:
fontSize: 10
images:
logo:
_string.concat:
- _location: origin
- /public/logo_example.png
footer:
_function:
- columns:
- qr:
_string.concat:
- _location: origin
- /invoice?id="
- _state: invoice.id
- '"'
margin: [50, 0, 0, 0]
fit: '64'
- alignment: 'right'
fontSize: 7
margin: [0, 0, 50, 0]
text:
__nunjucks:
template: 'Page of '
on:
page:
__args: 0
total:
__args: 1
content:
- columns:
- width: 'auto'
margin: [0, 20, 0, 0]
stack:
- fontSize: 9
text: |
- fontSize: 7
text: |
Example Services Ltd.
112 Street Name
City, State 12345
Country
001-AB
+00-1234-5566
info@example.com
Vat Number: 444 5555 0000
- width: '*'
text: ' '
- width: 110
stack:
- width: 110
image: logo
- margin: [0, 5, 0, 0]
alignment: right
fontSize: 7
text: |
Example Services Ltd.
Reg Number: 2001/22224/09
- margin: [0, 20, 0, 20]
text: Customer Invoice
bold: true
alignment: center
fontSize: 14
- columns:
- width: 150
bold: true
text: |
INVOICE NUMBER:
DATE ISSUED:
ACCOUNT NUMBER:
- width: '*'
text:
_nunjucks:
template: |
on:
_state: invoice
- width: 150
bold: true
text: |
CUSTOMER:
ADDRESS:
- width: '*'
text:
_nunjucks:
template: |
on:
_state: invoice
- layout: 'lightHorizontalLines'
margin: [0, 10, 0, 0]
table:
widths: [70, '*', 70, 70, 70]
headerRows: 1
body:
_json.parse:
_nunjucks:
on:
services:
_state: invoice.services
template: |
[
[
{ "text": "ITEM CODE", "bold": true },
{ "text": "SERVICE", "bold": true },
{ "text": "UNIT PRICE", "bold": true, "alignment": "right" },
{ "text": "QTY", "bold": true, "alignment": "right" },
{ "text": "COST", "bold": true, "alignment": "right" }
],
]
- layout: 'headerLineOnly'
margin: [0, -5, 0, 0]
table:
widths: ['*', 70, 70, 70]
headerRows: 1
body:
- - ''
- ''
- ''
- ''
- - ''
- alignment: right
text: 'Subtotal:'
- ''
- alignment: right
text:
_number.toFixed:
- _state: invoice.subtotal
- 2
- - ''
- alignment: right
text: 'Discount (5%):'
- ''
- alignment: right
text:
_number.toFixed:
- _state: invoice.discount
- 2
- - ''
- alignment: right
text: 'VAT (15%):'
- ''
- alignment: right
text:
_number.toFixed:
- _state: invoice.vat
- 2
- - ''
- alignment: right
text: 'Total:'
- ''
- alignment: right
text:
_number.toFixed:
- _state: invoice.total
- 2
- layout: 'headerLineOnly'
margin: [0, -5, 0, 0]
table:
widths: ['*', 70, 70, 70]
headerRows: 1
body:
- - ''
- ''
- ''
- ''
- - ''
- alignment: right
bold: true
text: 'BALANCE DUE:'
- ''
- alignment: right
bold: true
text:
_number.toFixed:
- _state: invoice.balance
- 2The above example will generate a PDF invoice with a logo, a QR code, a footer, a header, a table with the invoice details, and a table with the invoice items. Click the button to see this in action.
Conclusion
This how-to aims to demonstrate how easy custom JsActions in Lowdefy can be. With Lowdefy's ability to reference data and use JavaScript libraries like pdfMake, Lowdefy becomes a superpower capable of even generating advanced PDFs with ease. Check out the project folder for this how-to and why not give it a try: https://github.com/lowdefy/lowdefy/tree/main/packages/docs/howto/generatePdf