chore: First to parts of generate pdf how to.

.vscode/extensions.json

@@ -2,6 +2,7 @@
   "recommendations": [
     "arcanis.vscode-zipfs",
     "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode"
+    "esbenp.prettier-vscode",
+    "samuelcolvin.jinjahtml"
   ]
 }

packages/docs/howto/generate-pdf.yaml

@@ -0,0 +1,123 @@
+# Copyright 2020-2021 Lowdefy, Inc
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+_ref:
+  path: templates/general.yaml.njk
+  vars:
+    pageId: generate-pdf-document-from-data
+    pageTitle: Generate PDFs
+    section: How To
+    filePath: howto/generate-pdf.yaml
+    content:
+      - id: md1
+        type: MarkdownWithCode
+        properties:
+          content: |
+            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.
+
+            To see how this works, click this button to generate a PDF of this how-to guide.
+            [[INSERT BUTTON]]
+
+            Now click this button to share this article on Twitter 😉
+            [[ https://twitter.com/intent/tweet?url=https%3A%2F%2Fdocs.lowdefy.com%2Fgenerate-pdf-document-from-data&text=Generate%20pdf%20documents%20from%20data%20using%20@lowdefy%20-%20an%20open-source%20self-hosted%20low-code%20from%20work%20to%20build%20web%20apps%20and%20internal%20tools%20with%20ease.%20&hashtags=opensource%20%23selfhosted%20%23lowcode%20%23internaltools ]]
+
+            #### Generate PDF TDLR;
+
+            1. Select a client side PDF library and add the javascript to your Lowdefy app, we'll be using [PDFMake](https://github.com/bpampuch/pdfmake).
+            2. Register a custom [JsAction](/JsAction) method to generate the PDF document.
+            3. Add a button with a onClick action to call the generate PDF method.
+            4. Define the content of your PDF and add data variables as need.
+
+            ## Background
+
+            Generating PDFs is often required in workflow application 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 a 100% represent the latest data, or exactly match the desired formatting can be tricky and time consuming and thats were a auto generated PDFs can be a great solution.
+
+            ```
+              This how-to assumes that you are already running a Lowdefy app locally in dev mode. If not:
+              1) Create a empty folder.
+              2) Open your terminal or cmd and `cd` to your empty folder.
+              3) Run `npx lowdefy@latest init && npx lowdefy@latest dev` to initialize and start your Lowdefy app.
+            ```
+
+            ## 1. Choosing a open-source PDF library
+
+            The power of open-source is just amazing and as a result there are a number of well tested, popular, easy to use and free PDF generating libraries out there to choose from. Some of the popular ones are:
+              - [PDFMake](https://github.com/bpampuch/pdfmake)
+              - [JsPDF](https://github.com/MrRio/jsPDF)
+              - [PDFKit](https://github.com/foliojs/pdfkit)
+              - [Puppeteer](https://github.com/puppeteer/puppeteer)
+              - [PDF-lib](https://github.com/Hopding/pdf-lib)
+
+            > If you use open-source libraries to automate your business and save you time, the easiest to contribute to these tools is often just to sponsor the package maintainers. Please do do where possible. Look for the sponsorship links usually found in the repository 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 nothing beats adding custom code. Let's create a custom action which will generate a PDF based on PDFMake config.
+
+            1) Create a `public` folder inside your Lowdefy working directory.
+            2) Since all content in the `public` folder is served by the Lowdefy server, simply create a `pdfMake.js` file inside the `public` folder.
+            3) Add this script to the file and save.
+
+            ```js
+            import importUmd from './importUmd.js';
+            import vfs from './vfs_fonts.js';
+            const pdfMake = await importUmd(
+              `https://unpkg.com/pdfmake@0.1.71/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 the `public` folder. Then it loads [PDFMake](https://unpkg.com/pdfmake@0.1.71/build/pdfmake.min.js) from UNPKG. 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, and very importantly, if registers the `pdfMakeFn` function as a custom [JsAction](/JsAction) using `window.lowdefy.registerJsAction`. This gives our new method to the Lowdefy logic engine to use.
+
+            > IMPORTANT: We mentioned two other files here. [`importUmd.js`](/public/methods/importUmd.js) is a helper function to load umd modules from a source, and [`vfs_fonts.js`](/public/methods/vfs_fonts.js) is a virtualized font which we need to provide to PDFMake. Download these files and them inside your `public` folder.
+
+            4) 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:
+
+            ```html
+            <script type="module" src="/public/modules/pdfMake.js"></script>
+            ```
+
+            This loaded our `pdfMake.js` module file into HTML.
+
+            5) Finally, add your HTML to you Lowdefy application header. To do this, use the `app.html.appendHead` Lowdefy config property. So your `lowdefy.yaml` file should now look something like this:
+
+
+            ```yaml
+            name: Generate a PDF
+            lowdefy: 3.18.0
+
+            app:
+              html:
+                appendHead:
+                  _ref: my_header.html
+            ```
+
+            Congratulations, your custom JSAction is now available in you Lowdefy app and ready to use.
+
+            ## 3. Add a button and a action to generate a PDF

packages/docs/menus.yaml

@@ -47,6 +47,17 @@
           pageId: next-steps
           properties:
             title: Next steps
+    - id: howto
+      type: MenuGroup
+      properties:
+        title: How To
+        icon: QuestionOutlined
+      links:
+        - id: generate-pdf
+          type: MenuLink
+          pageId: generate-pdf
+          properties:
+            title: Generate PDFs
     - id: concepts
       type: MenuGroup
       properties: