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.
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.
- Merge PDFs
- Completing an AcroForm
- Creating a PDF from a DLEX (dlex-layout Endpoint)
- Creating a PDF from a DLEX (pdf Endpoint)
- Adding Bookmarks to a PDF
- Extract Image Metadata
- Extract PDF Metadata
- Extract PDF's Text
- Extract XMP Metadata
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
, andgetting-started.png
.
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 theGetting Started Samples
sample folder containing the sample resources to your cloud storage space using the Resource Manager.
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.
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
, andgetting-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.
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.
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].
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.
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.
If you do not have cURL on your operating system refer to the following page to install it (https://curl.se).
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.
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
instancesProcess
method. - Ensure the call returns a response and save the resultant PDF to a file.
- In
Main
add the reference to theRun
method. - 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
instancesprocess
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 amain
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 tomain
.Add the call to the endpoint by adding the
DlexLayout
instancesprocess
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
instancesProcess
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.