Getting Started

In this getting started tutorial we review a simple DLEX report and then use the dlex-layout endpoint to create a new PDF.

This tutorial reviews a DLEX file in DynamicPDF Designer and then calls the dlex-layout endpoint to generate a report from that DLEX file. DLEX (DynamicPDF Layout Engine XML) files are XML files that describe how to layout a PDF document in a platform-independent way using the DynamicPDF Cloud API Designer WSWYG application.

tip

You must have a DynamicPDF Cloud API account before completing the steps in this tutorial. Click on the Sign Up For FREE button in the upper right-hand corner to sign up for a free account.

Other Features

For other DynamicPDF Cloud API features, please review these tutorials.

Review the Tutorial Resources

We use several resources in the DLEX file to generate a PDF report and the subsequent API call. You can access the resources needed by adding the Getting Started resources to your cloud storage space in the Resource Manager. The resources required are:

getting-started.dlex,
getting-started.json, and
getting-started.png.

tip

If you are not familiar with the Resource Manager or Apps Manager, refer to the following tutorial and relevant Users Guide pages.

Let's review the resources needed by reviewing them in the Resource Manager. After logging into the DynamicPDF Cloud API website, you are first taken to the Environment Manager.

Log into the DynamicPDF Cloud API to open the Environment Manager.

Figure 1. The DynamicPDF Cloud API's Environment Manager.

The Environment Manager is the dashboard for working with the DynamicPDF Cloud API. Use the dashboard to manage resources, assign apps and app keys, manage users, review billing, review reports, and access online documentation.

Select Manage Resources to open the Resource Manager.
Note it presents a samples folder. Before continuing you must add the Getting Started Samples sample folder containing the sample resources to your cloud storage space using the Resource Manager.

tip

If you do not see a samples folder, then right-click the root folder and add the samples folder.

Highlight the samples folder and then select Add Samples to open the Samples dialog.
From the Samples dialog, select Getting Started, and the folder, getting-started, to add the required resources.

Figure 2. Adding Getting Started samples from the DynamicPDF Cloud Storage using the Resource Manager.

Your cloud storage space is where you store resources on the cloud. Depending upon your subscription level, you are provided with 10mb, 100mb, 250mb, or unlimited storage space. You manage resources in cloud storage using the Resource Manager.

But many resources will also be used on your local system, namely, processing instructions JSON documents and JSON data. It makes sense that these files would be on your local system, as the JSON data will be a dynamic resource that you provide to your endpoints to generate the PDF documents. Later, when examining the dlex-layout endpoint, you will move the JSON layout data to your local filesystem.

danger

Your data is your data, not the world's! Always keep your real data on your local system and not in your cloud storage space to maintain security and privacy.

In the samples/Getting Started folder you should see the following files:
- getting-started.dlex
- getting-started.json, and
- getting-started.png.

Figure 3. Resource Manager displaying the files needed for tutorial.

Examine the DLEX file in Designer

Let's examine the DLEX file by opening it in Designer.

Open DLEX File

Double-click on getting-started.dlex to open the file in Designer.

Load JSON Data

Open the Layout Data Editor by selecting the Edit Layout Data button.

Figure 4. The Edit Layout Data button in Designer.

The data should be preloaded if both the DLEX and JSON files have the same name. If not, load the JSON data into the Layout Data Editor by selecting Open JSON Data and then selecting the getting-started.json file in the File Manager.

Figure 5. The Open JSON File button in the Layout Data Explorer.

The JSON data consists of the fields title and author followed by the sales array. The sales array consists of individual sales consisting of id, name, quantity, and price.

{
  "title": "Concession Sales Report",
  "author": "John Doe",
  "sales": [
    {
      "id": "123XA",
      "name": "Popcorn",
      "quantity": 22,
      "price": 2.22
    },
    {
      "id": "333YA",
      "name": "Hotdog",
      "quantity": 12,
      "price": 1.99
    },
    {
      "id": "11XX",
      "name": "Grape Soda",
      "quantity": 40,
      "price": 0.99
    },
    {
      "id": "453XY",
      "name": "Taco",
      "quantity": 10,
      "price": 2.99
    },
    {
      "id": "78YY",
      "name": "Burrito",
      "quantity": 13,
      "price": 3.99
    },
        {
      "id": "7564A",
      "name": "Samosa",
      "quantity": 22,
      "price": 2.99
    },
    {
      "id": "898CE",
      "name": "Peanuts",
      "quantity": 35,
      "price": 1.99
    },
    {
      "id": "121QW",
      "name": "Creme Soda",
      "quantity": 420,
      "price": 0.99
    },
    {
      "id": "546RL",
      "name": "Bottled Water",
      "quantity": 30,
      "price": 2.99
    },
    {
      "id": "986CY",
      "name": "Potato Chips",
      "quantity": 101,
      "price": 1.39
    },
    {
      "id": "45YC",
      "name": "Hershey's Chocolate",
      "quantity": 23,
      "price": 0.99
    },
    {
      "id": "9123J",
      "name": "Snickers",
      "quantity": 11,
      "price": 1.99
    },
    {
      "id": "892XG",
      "name": "Almonds",
      "quantity": 12,
      "price": 1.99
    },
    {
      "id": "997LQ",
      "name": "Trail Mix",
      "quantity": 2,
      "price": 3.99
    }
  ]
}

After opening the file, you should now see the JSON data in the Layout Data Editor.
Close the Layout Data Editor.

Figure 6. Data in Designer's Layout Data Editor.

Review the Data Explorer

On the bottom right of Designer, expand the Data Explorer to view the JSON fields loaded into the Data Explorer.

Figure 7. The Data Explorer in Designer.

After loading a valid JSON data file in the Layout Data Editor, the Data Explorer parses the fields and loads the field names and structure.

Review the Cover Page

Notice the page has an Image element and two RecordBox elements.

Figure 8. A page in Designer with an Image element and two RecordBox fields.

The image was loaded by selecting the path from the Resource Manager while the title and the author are the author and title fields are from the JSON dataset.

Figure 9. An image loaded from the Resource Manager.

Right-click anywhere on the page and notice the element choices provided appear in a context menu.

Figure 10. Use Designer's context menu to add elements to a document.

Review the Report

Scroll down to the report section and notice the report consists of a header, detail, and footer.

Figure 11. The report sections of getting-started.dlex in Designer.

The header and footer repeat per new complete page of data, while the data row repeats for each record in the JSON dataset. The header contains four labels, one for each of the data fields.

Also, notice that the order total and the report total are expressions where the order total multiplies the quantity by the price for each data record. The footer sums the quantity multiplied by price for all data records.

quantity * price
sum(quantity*price)

Review the DLEX File

Designer creates a DLEX file which is used with JSON data to generate a PDF. A DLEX file is XML and provides the instructions to generate a report.

Select the View DLEX Source button to view the DLEX file.

Figure 12. The View DLEX Source button.

As you can see, the DLEX file is an XML document that specifies a report's layout using XML tags.

Figure 13. The DLEX Source View displaying the getting-started.json file.

You can access the schema for the DLEX specification at DLEX XML Schema.

info

Note that a DLEX file is read-only in Designer. Modifying a DLEX file manually requires you download the file, modify it, and then upload it back to the Resource Manager.

caution

Unless you are an experienced user, it is better to NOT edit a DLEX file directly.

Test the Report Creation in Designer

Now let's generate the PDF by processing the DLEX file and JSON data to create a PDF.

Click the Run Report button (the green arrow) to generate the PDF.

Figure 14. The Run Report button in Designer.

The PDF opens in a new browser tab and it displays the cover-page and report.

Figure 15. The report generated and displayed in a new browser tab.

Create the dlex-layout API Call

Now that we have reviewed the DLEX file in Designer and ensured it worked by generating the PDF report, let's create the dlex-layout endpoint REST call.

Obtain the API Key

Return to the Environment Manager and select Apps and API Keys to open the Apps And API Keys dialog.

Figure 16. The Apps and API Keys in the Environment Manager.

From the default, select [copy] to copy the API key to your local clipboard and paste the key somewhere convenient.

Figure 17. Copy the API key to clipboard by clicking [copy].

danger

Keep this key safe!

Download the JSON Data

Return to the Resource Manager and select the getting-started-data.json file.
Right-click the file and select Download from the context menu.
Move the file from the Downloads folder on your local system to the location desired. Here we use C:/holding/getting-started as the local system path.

info

Remember, the DynamicPDF Cloud API works with any operating system's filesystem.

Create the API Call

Open a command window (on Windows the Command Prompt) and enter the following cURL command.

curl -X POST https://api.dynamicpdf.com/v1.0/dlex-layout
-H "Autorization: Bearer <apikey>"
-F "DlexPath = samples/getting-started/gettingstarted.dlex"
-F "LayoutData = C:/holding/getting-started.json"
-o geting-started-output.pdf

Replace the authorization key with your own key.

tip

If you do not have cURL on your operating system refer to the following page to install it (https://curl.se).

tip

Note that we used the path to the downloaded JSON data and not the data in the Resource Manager. As a general rule you should use data files locally.

The dlex-layout endpoint takes an HTTP POST request which we specify using -X and the request type, POST. The -F flags specify that the DlexPath and the LayoutData parameters are form fields. The DlexPath parameter is the path to the DLEX file in the Resource Manager while the LayoutData field is the path to the JSON data on your local system. Finally, the -o flag specifies the name to save the resultant PDF as a file on your local system.

Review the Created PDF

Open the created PDF and review the document. The document consists of the report generated by the DLEX.

Figure 18. The generated PDF report.

Client Library

Although you can call REST points directly, using a client library usually makes calling a REST endpoint easier. Let's use the the client libraries to call the dlex-layout endpoint.

Select the tab containing the language desired to view the remaining steps tailored to the selected language.

Complete Source

You can access the complete source for this project at one of the following GitHub projects.

Language	File Name	Location (package/namespace/etc.)	GitHub Project
Java	`GettingStartedInFive.java`	`com.dynamicpdf.api.examples`	https://github.com/dynamicpdf-api/java-client-examples
C#	`GettingStartedInFive.cs`	`GettingStartedInFive`	https://github.com/dynamicpdf-api/dotnet-client-examples
Nodejs	`GettingStartedInFive.js`	`nodejs-client-examples`	https://github.com/dynamicpdf-api/nodejs-client-examples
PHP	`GettingStartedInFive.php`	`php-client-examples`	https://github.com/dynamicpdf-api/php-client-examples

C# Instructions

C# (.NET)
Java
Node.js
PHP

Available on NuGet:

Install-Package DynamicPDF.API

Create a new Visual Studio Console App (.NET Core) and name the project GettingStartedInFive.
Add the DynamicPDF.API NuGet package to the project.
Add a new method named Run.
Create a new LayoutDataResource instance and in the constructor pass the path to the layout data.
Create a new DlexLayout instance and in the constructor pass the path in the Resource Manager to the DLEX file.

info

As previously discussed, layout data resides on your local system while DLEX files reside in your cloud storage space that you access using the Resource Manager.

Add the call to the endpoint by adding the DlexLayout instances Process method.
Ensure the call returns a response and save the resultant PDF to a file.
In Main add the reference to the Runmethod.
Run the application and the endpoint returns the processed PDF.

using DynamicPDF.Api;
using System;
using System.IO;

namespace GettingStartedInFive
{
    class Program
    {
        static void Main(string[] args)
        {
            Run("DP.xxxxxxxxxxxx", "C:/temp/dynamicpdf-api-samples/");
        }

        public static void Run(String apiKey, String basePath)
        {
            // Load the Layout Data. This will normally come from a dynamic source, but in this example, it is static
            LayoutDataResource layoutDataResource = new LayoutDataResource(basePath + "getting-started.json"); 
            // Path to the DLEX in the cloud
            DlexLayout dlexLayout = new DlexLayout("samples/getting-started/getting-started.dlex", layoutDataResource);
            // Set the API Key
            dlexLayout.ApiKey = apiKey;
            // Call the dlex-layout endpoint
            PdfResponse pdfResponse = dlexLayout.Process();

            if (pdfResponse.IsSuccessful)
            {
                // Write the PDF to a file
                File.WriteAllBytes(Path.Combine(basePath, "getting-started-output.pdf"), pdfResponse.Content);
            }
            else
            {
                // Something went wrong
                Console.WriteLine(pdfResponse.ErrorJson);
            }
        }
    }
}

Available on NPM:

npm i @dynamicpdf/api

Get the DynamicPDF API package from npm.
Create a new class named GettingStartedInFive.
Add a new static asynchronous method named Run to the class.
Create a new LayoutDataResource instance and in the constructor pass the path to the layout data.
Create a new DlexLayout instance and in the constructor pass the path in the Resource Manager to the DLEX file.
Add the call to the endpoint by adding the DlexLayout instances process method.
Ensure the call returns a response and save the resultant PDF to a file.

import fs from 'fs';
import {
    LayoutDataResource,
    DlexLayout,
    Endpoint
} from "@dynamicpdf/api"


export class GettingStartedInFive {

    static async Run() {
        var layoutData = new LayoutDataResource("C:/temp/dynamicpdf-api-samples/getting-started.json");
        var dlexEndpoint = new DlexLayout("samples/getting-started/getting-started.dlex", layoutData);
        dlexEndpoint.apiKey =  "DP.xxxxxxxxxxxx";
        
        var res = await dlexEndpoint.process();
        
        if (res.isSuccessful) {
            var outFile = "C:/temp/dynamicpdf-api-samples/getting-started-output.pdf";
            var outStream = fs.createWriteStream(outFile);
            outStream.write(res.Content);
            outStream.close();
            console.log("Pdf was generated and saved at: " + outFile);
        } else {
            console.log(res.errorJson);
        }
    }
}

await GettingStartedInFive.Run();

After the class add code to call the Run method and wait for the results asynchronously.
Run the application and the endpoint returns the processed PDF.

node GettingStartedInFive.js

Available on Maven:

https://search.maven.org/search?q=g:com.dynamicpdf.api

<dependency>
  <groupId>com.dynamicpdf.api</groupId>
  <artifactId>dynamicpdf-api</artifactId>
  <version>1.0.0</version>
</dependency>

Create a new Maven project and add the DynamicPDF API as a dependency, also add the Apache Commons IO library.

<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.8.0</version>
</dependency>

Create a new class named GettingStartedInFive with a main method.
Create a new method named Run.
Create a new LayoutDataResource instance and in the constructor pass the path to the layout data.
Create a new DlexLayout instance and in the constructor pass the path in the Resource Manager to the DLEX file.
Add the Run method to main.
Add the call to the endpoint by adding the DlexLayout instances process method.
Ensure the call returns a response and save the resultant PDF to a file.

package com.dynamicpdf.api.gettingstarted;

import java.io.File;
import java.io.IOException;
import org.apache.commons.io.FileUtils;
import com.dynamicpdf.api.DlexLayout;
import com.dynamicpdf.api.LayoutDataResource;
import com.dynamicpdf.api.PdfResponse;

public class GettingStartedInFive {

    public static void main(String[] args) {
        GettingStartedInFive.Run("DP.V9xxxxxxxxxxxxxxxx",
                "C:/temp/dynamicpdf-api-samples/");
    }

    public static void Run(String apiKey, String basePath) {
        LayoutDataResource layoutDataResource = new LayoutDataResource(basePath + "getting-started.json");
        DlexLayout dlexLayout = new DlexLayout("samples/getting-started/getting-started.dlex", layoutDataResource);
        dlexLayout.setApiKey(apiKey);
        PdfResponse pdfResponse = dlexLayout.process();

        try {
            FileUtils.writeByteArrayToFile(new File(basePath + "getting-started-output.pdf"),
                    pdfResponse.getContent());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Run the application and the endpoint returns the processed PDF.

Available as a Composer package:

composer require dynamicpdf/api

Add the DynamicPDF API package to Composer.
Create a new PHP file named class named GettingStartedInFive.
Add a static function named Run.
Create a new LayoutDataResource instance and in the constructor pass the path to the layout data.
Create a new DlexLayout instance and in the constructor pass the path in the Resource Manager to the DLEX file.
Add the call to the endpoint by adding the DlexLayout instances Process method.
Ensure the call returns a response and save the resultant PDF to a file.

<?php

require __DIR__ . '/vendor/autoload.php';

use DynamicPDF\Api\LayoutDataResource;
use DynamicPDF\Api\DlexLayout;

class GettingStartedInFive
{
    private static string $BasePath = "C:/temp/dynamicpdf-api-samples/";
    public static function Run()
    {
        $layoutData = new LayoutDataResource(GettingStartedInFive::$BasePath . "getting-started.json");
        $dlexEndpoint = new DlexLayout("samples/getting-started/getting-started.dlex", $layoutData);
        $dlexEndpoint->ApiKey = "DP.xxxxxxxxxxxx";
        $response = $dlexEndpoint->Process();
        file_put_contents(GettingStartedInFive::$BasePath . "getting-started-output.pdf", $response->Content);
    }
}
GettingStartedInFive::Run();

Add the call to Run at the PHP file's bottom.
Run the application and the PDF is generated at the specified location.

php GettingStartedInFive.php

In all four languages we created a new LayoutDataResource instance that contains the path to the JSON data. This is the path to the JSON on your local system. We then created a new DlexLayout instance that takes the path to the DLEX file in your cloud storage space and the LayoutDataResource instance. The DlexLayout instance then calls the Process or process (depending upon language) method. The DynamicPDF API client library calls the REST endpoint and returns a response containing the PDF. We then saved the PDF to a file.

As you can see, the DynamicPDF Cloud API contains an easy-to-use PDF report designer (DynamicPDF Designer), REST endpoints, and client libraries that make generating PDFs easy. This is just one of the many examples of the uses provided by the DynamicPDF Cloud API for all of your PDF needs. Be sure to check out our many online tutorials and documentation for more information.

Other Features​

Review the Tutorial Resources​

Examine the DLEX file in Designer​

Open DLEX File​

Load JSON Data​

Review the Data Explorer​

Review the Cover Page​

Review the Report​

Review the DLEX File​

Test the Report Creation in Designer​

Create the dlex-layout API Call​

Obtain the API Key​

Download the JSON Data​

Create the API Call​

Review the Created PDF​

Client Library​

Complete Source​

C# Instructions​

Other Features

Review the Tutorial Resources

Examine the DLEX file in Designer

Open DLEX File

Load JSON Data

Review the Data Explorer

Review the Cover Page

Review the Report

Review the DLEX File

Test the Report Creation in Designer

Create the dlex-layout API Call

Obtain the API Key

Download the JSON Data

Create the API Call

Review the Created PDF

Client Library

Complete Source

C# Instructions