Skip to content

sc-pdf

*This document is a user guide for the sc-pdf component release version 7.2

go-to-typical-definition

 

1. Purpose

The new sc-pdf component can be used to generate formatted pdf documents for printing, audit or other purposes. The component uses javascipt library PDFMAKE.

pdfs can be fully customised with: - styling - tables and columns - headers and footers - images - etc.

It allows data to be taken from template definitions and formatted in a suitable way that meets the needs of the customer. The resulting pdf can then be viewed live, downloaded or printed, and can now be uploaded and saved on the formbird server via a variety of means.

The component requires a valid PDFMAKE object which specifies the format for the output PDF. See PDFMAKE for documentation and correct practice.

 

2. Definition

sc-pdf is defined by a set of name/value pair fields consisting of:

  • Required system fields
  • Required customizable fields
  • Optional customizable fields

Note:

  1. Default values for fields described in the tables below are shown in bold text.

2.1. Required System Fields

Field Valid Values Description
componentName sc-pdf The component name.

Example:
"componentName": "sc-pdf"

2.2. Required Customisable Fields

Field Valid Values Description
name Any value written in camel case Defines the name of the sc-pdf field in the document and database.

Example: "name": "testScPdf"

2.3. Optional Customisable Fields

Field Valid Values Description
buttonLabel Any value Changes the action button label to provide more information.

Example:
"buttonLabel": "Open in new tab"
buttonType value Default Value.
buttonType Download Sets the action button to Download. Clicking the button downloads the pdf.

Example: "buttonType": "Download"
Open Sets the action button to Open. Clicking the button opens the pdf in a new tab.

Example: "buttonType": "Open"
Print Sets the action button to Print. Clicking the button opens the pdf in a new tab and opens browser print dialog menu.

Example: "buttonType": "Print"
none Default Value.
Removes the action button from the component display.
disableSave true Clicking the action button or changing the pdf value (through the rulesets) does not trigger the Save icon to flash.
Exiting the form without saving changes to the sc-pdf field value does not trigger a warning message to display.
In the Angular version of the sc-pdf component, clicking the Save icon will not save the sc-pdf field value to the document.
In the AngularJS version of the sc-pdf component, clicking the Save icon will save the sc-pdf field value to the document.

Example: "disableSave": true
false Default Value.
Changing the sc-pdf field value (i.e. entering or editing a value) or clicking action button does trigger the Save icon to flash.
Exiting the form without saving changes to the sc-pdf field value does trigger a warning message to display.
In both the Angular and AngularJS versions of the sc-pdf component, clicking the Save icon will save the sc-pdf field value to the document.
docDefName Variable name When using rulesets to dynamically assign the pdf definition, this field is used to fetch the definition from the document via an assignable variable. This variable must contain a valid pdfDefintion object as per PDFMAKE documentation. docDefName takes preference over pdfDefintion
This can either be the sc-pdf component name variable or another name entirely
See tutorials for further information

Example:
"docDefName": "pdfDef"
enabled false No updates can be made to the sc-pdf, all buttons are hidden, except those in full width for print and download. Only a preview can be loaded from a paired sc-uploader component specified by 'scUploaderName'. It will fetch either a pdf file from the uploader with the specified 'pdfFileName' or the component 'name'. If there is no corresponding file no preview will be shown.
In this mode, it is best to ensure the sc-uploader component is disabled as well to prevent saved PDF deletions.

Example: "enabled": false
true Default Value.
PDF's can be generated and buttons are functional.
fullWidth true The sc-pdf preview displays the full width of the form. Reccommended displaying the sc-pdf component in full width.

Example: "fillWidth": true
false Default value.
The sc-pdf does not display the full width of the form.
label Any value Defines the name of the sc-pdf field on the form i.e. the field label.

Example: "label": "Test sc-pdf"
Defaults to no label is displayed.
openInSameWindow true When using buttonType: "Open" or "Print", it will open/Print the pdf from the intial same tab.

Example: "openInSameWindow": true
false Default value.
The pdf will open/print in a new tab/window.
defaultDef valid pdfmake object Pdf definition used by the component. See PDFMAKE documentation for more information.

Example:
"defaultDef": "function main(context) { const pdfDef = { content: 'Example test document.}; return pdfDef; }"
OR
"defaultDef": "{ content: 'Example test document' }"
pdfFileName Any Value Defines the name of the name of the downloaded/printed pdf.

Example:
"pdfFileName": "examplePdfName"
Defaults to component Name.
preview false Hides the preview window, leaving just print button.

Example:
"preview": false
true Default value.
Displays the pdf preview window
scUploaderName any sc-uploader component name Specifies what uploader to save the generated PDF. Only required for uploadType 'scUploader'. A sc-uploader component is needed on the document definition for this functionality to work.
The name of the uploaded pdf file should be specified with 'pdfFileName' however defaults to the sc-pdf component 'name'

Example:
"scUploaderName": "testScUploader"
uploadDefault true This will upload the default pdf definition defaultDef to the server. Use this functionality when you have a basic pdf that needs to be generated and then utilsed elsewhere like email.
false Default value.
The default pdf definition will not be uploaded to the server.
uploadType scUploader This upload type requies scUploaderName and this uses the uploader component to upload the PDF to the server. The PDF is available through the saved sc-uploader object. This type allows for visual representation of saved pdf's in the uploader field, however requires the upload to be completed before the user saves or exits the page.
Example:
"uploadType": "scUploader"
onGen This upload type generates the pdf when it is created. Note that the defaultDef does not allow for pdf uploading as it is displayed when the component is instatiated. Eg. when the docDefName is assigned to in the rulesets.
preSave PDF will be uploaded to the server on the pre-save event. Ie just before the document is saved. This ensures that the document is saved with the PDF on a successful save event.
none Default value.
The pdf will not be uploaded and is generated live when the page loads given there is a pdf definition object.
useGenerateButton true Turns off automatic generation of PDF when the assigned pdfDefinition is changed. Generate PDF button must be clicked to generate a PDF from the pdfDefinition. Works best in cases where users want control when to generate PDF's.

Example:
"useGenerateButton": true`
false Default value.
Document is watched for changes and PDF will be updated on changes. This works with rulesets where assigning of the variable from docDefName is performed once, before the component is disabled.
visible false The sc-pdf component is not visible on the form.

Example:
"visible": false
true Default Value.
The sc-pdf component is visible on the form.

 

3. Typical Definition

Below is a typical sc-pdf definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{ 
    "componentName": "sc-pdf",
    "defaultDef": "{content:'Example test document.'}",
    "name": "report1Pdf",
}

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

    "fullWidth": true,
    "pdfFileName": "examplePdfFileName",
    "previewWidth": 500,
    "previewHeight": 300,
    "buttonType": "Print",
    "buttonLabel": "Print in new tab",
    "openInSameWindow": false,
    "docDefName": "pdfString",
    "uploadDefault": false,
    "uploadType": "OnGen",
    "scUploaderName": "testScUploaderName",
    "useGenerateButton": true

 

4. Examples

Example 1

sc-pdf defined with the typically needed fields. This will autogenerate a basic PDF with the text Example test document.

{ 
  "componentName": "sc-pdf",
    "defaultDef": "{content:'Example test document.'}",
    "name": "typicalDefnScPdf"
}

 

Example 2

This example will generate a larger preview window with the text 'Example document' and a Print action button with the label 'Print in a New Tab'. As we have defined docDefName, we can assign from the ruleset a generated PDF Object that will override the default pdf definition here. This workflow works best when working with images, or information from a template that requires a rulset to be used.

{
        "componentName": "sc-pdf",
        "fullWidth": true,
        "buttonType": "Print",
        "buttonLabel": "Print in New Tab",
        "defaultDef": "{ content: 'Example document text' }",
        "name": "typicalDefnScPdf",
        "docDefName": "pdfDef"
}

Example 3

This example will generate a basic PDF only when the Generate PDF button is clicked, and it will upload and save the PDF URL to the document.

{
        "componentName": "sc-pdf",
        "fullWidth": true,
        "defaultDef": "{ content: 'Example document' }",
        "name": "typicalDefnScPdf",
        "pdfFileName": "exampleTestPdfName",
        "uploadtype": "onGen",
        "uploadDefault": true,
        "useGenerateButton": true
},
{
                "componentName": "sc-uploader",
        "fullWidth": true,
        "name": "exampleScUploader"
}

An example output is...

"typicalDefnScPdf": {
  "fileName": "exampleTestPdfName.pdf",
  "fileNo": "418a9760-6f97-11ed-b85e-fdf3cd548c0e",
  "date": "2022-11-29T03:38:14.869Z"
 }

 

Example 4

This example will generate a basic PDF only when the Generate PDF button is clicked, and it will save this PDF to the defined sc-uploader. Once we are happy with our generated pdf, to avoid saving more PDFs to the uploader, we should set the component to enabled:false.

{
        "componentName": "sc-pdf",
        "fullWidth": true,
        "defaultDef": "{ content: 'Example document' }",
        "name": "typicalDefnScPdf",
        "scUploaderName": "exampleScUploader",
        "uploadtype": "scUploader",
        "useGenerateButton": true,
        "enabled":true
},
{
                "componentName": "sc-uploader",
        "fullWidth": true,
        "name": "exampleScUploader"
}

 

Example 5

Here we will incorporate sc-pdf with sc-signature for sign on glass functionality using the rulesets. When the Generate PDF button is clicked, and it will grab the signature from the other component . Note docDefName defaults to pdfDef

Document:

{
        "componentName": "sc-signature",
        "name": "auditorSignature",
        "label": "Auditor's Signature",
        "saveAsImage": true
},
{
        "componentName": "sc-pdf",
        "fullWidth": true,
        "name": "report2Pdf",
        "pdfFileName": "ExampleTestPDF1"
},
{
                "componentName": "sc-uploader",
        "fullWidth": true,
        "name": "exampleScUploader"
}

Ruleset:

ruleOnfieldChangedPDFUpdate : { // handles PDF updates
        ruleCondition : function(ntf) {
            return ( (ntf.document.status === 'Completed') )
    },
    ruleAction : function(ntf, cb) {
            var ft3 = ntf.scope;
            const imgNames = {};

      console.log("Saving Signature to pdf"); // signature must be saved already
      const signatureURL = window.location.origin + "/" + ntf.document.auditorSignature[0];

            let dateStr = ft3.moment(ntf.document.signedDate).format('DD/MM/YYYY HH:mm a');

            // create data for pdfValue
            let val = createData();

            ntf.document.pdfDef = val; // assign pdf to default docDefName
            ft3.showField('report2Pdf', true);

            function createData() {
                    // creating PDF Definition
          let data = {
            info: {
              title: 'audit'+"1234",
              author: "some name",
            },
            content: [
              {
                text: 'Formbird PDF with Rulesets',
                style: 'header',
              }, 
              'This document has an id = ' + context.documentId,
                    'This document has a template id = ' + context.template.documentId,
              { text: "This is a test" },
              {image: "testSignature", fit: [100, 100] }
              ],
            styles: {
              header: {
                fontSize: 24,
                bold: true
                }
            },
          images: [
                    "testSignature": signatureURL;
          ]};
          // convert data to String 
            //  dataStr +=  JSON.stringify(data); // use this line for production
          let dataStr =  JSON.stringify(data, null, "\t"); // for debugging purposes (easy to read)
          return dataStr
        }
}}

 

Example 6

Below is one of our PDF Editor Templates that help with visualising the pdf as you create it.

example-pdf-editor

 

5. Additional Information

More information: For more information on features, valid pdf defintion values, table formatting and more see PDFMAKE website.