Using a DLEX File to Create a PDF

DynamicPDF Report Writer creates and uses DLEX files to create PDFs by laying out a document using provided data. The overall steps to create a report are as follows.

1. Create the DLEX report using DynamicPDF Designer.
2. Test/debug the DLEX report by using a JSON data.
3. Instantiate a DocumentLayout instance using the desired DLEX file.
4. Specify the data used in generating the PDF.
5. Save the PDF.

DocumentLayout

The DocumentLayout class represents a document created using a supplied DLEX file. This class has an overloaded constructor to pass in the path to a DLEX file. It also has an overloaded constructor that allows passing in a DlexFile instance or a file path to the DLEX file.

public DocumentLayout(DlexFile dlex)
public DocumentLayout(string filePath)

After creating the DocumentLayout instance, the layout data is obtained from a LayoutData instance. The DocumentLayout class has two Layout methods for obtaining layout data.

public Document Layout(LayoutData layoutData)
public void Layout(LayoutData layoutData, Document document)

Layout Data Types

DLEX files use two types of layout data, static and repeating. When an object value appears consistently on a page or report, it is a static layout data element. Repeating layout data elements contain enumerable data or a data list that is used by a report to construct the finished PDF. This data can be an enumerable list, an array of objects, or data from a database.

For example, the following JSON document contains both static and repeating layout data elements. The PreparedBy and Company data layout elements are static while the Products data layout element is repeating.

{
  "PreparedBy":"John Doe",
  "Company":"NorthWinds Trading Company",
  "Products":[
    {
      "Name":"ProductA",
      "Price":1.99
    },
    {
     "Name":"ProductB",
     "Price":2.99
    }
  ]
}

Use static data layout elements for things like cover pages, headers, footers, and other areas where the value for a layout element appears only once. Layout elements in a page or in a report's header and footer can also display dynamic layout data elements; however, only values from the first row is used to display the layout element. If a layout element specifies data that is not in the object/row, the the element will try to retrieve the layout data element recursively from its parent data elements (if a sub-report) or from a constant data value from the layout data.

Layout Data

Layout data is provided to a DocumentLayout class through the class's Layout method. The Layout method takes a LayoutData class as a parameter.

NameValueLayoutData

The NameValueLayoutData class is for adding name/value data to layout a document. This class is a child class to the LayoutData class. When using this class, the data is only provided programatically. The NameValueLayoutData class provides the Add method to add these name/value pairs.

public void Add(string key, Object value)

After populating a NameValueLayoutData instance, the instance is supplied to a DocumentLayout instance using the Layout method. The following example illustrates a DLEX file with two layout data elements where the element's values are provided programmatically.

// Create the document's layout from a DLEX template
DocumentLayout layout = new DocumentLayout("SimpleReport.dlex");

ArrayList listOfProducts = new ArrayList();
listOfProducts.Add("A3234Y");
listOfProducts.Add("P123SX");
listOfProducts.Add("N8231M");

// Specify the data to be used
NameValueLayoutData layoutData = new NameValueLayoutData();
layoutData.Add("PreparedFor", "Alex Smith");
layoutData.Add("Products", listOfProducts);

// Layout the document and save the PDF
Document document = layout.Layout(layoutData);
document.Draw(outputFilePath);

' Create the document's layout from a DLEX template
Dim MyLayout As DocumentLayout = New DocumentLayout("SimpleReport.dlex")

' Specify the data to be used
Dim MyLayoutData As NameValueLayoutData = New NameValueLayoutData()
MyLayoutData.Add("PreparedFor", "Alex Smith")
MyLayoutData.Add("Products", MyListOfProducts)

' Layout the document And save the PDF
Dim MyDocument As Document = MyLayout.Layout(MyLayoutData)
MyDocument.Draw(outputFilePath)

public DocumentLayout(DlexFile dlex)
public DocumentLayout(string filePath)

The DocumentLayout class has two methods for obtaining layout data from the DLEX file. Use the GetLayoutElementById method to get a layout data element name from the DLEX file that was loaded into the DocumentLayout instance.

public LayoutElement GetLayoutElementById(string id)

Recall that you can use JSON data while creating your DLEX template and then not use the JSON data. For example, above the JSON document had the following two static elements.

  "PreparedBy":"John Doe",
  "Company":"NorthWinds Trading Company",

Rather than using the JSON data, you could programmatically provide the data. But be certain to use the same data element names.

layoutData.Add("PreparedBy", "John Doe");
layoutData.Add("Company", "NorthWinds Trading Company");

Laying Out and Outputting the Document

After adding layout data, the data is then used to lay out the document by calling the layout documents Layout method and passing in the layout data. A Document instance is then returned. Additional content or pages can be added to it or output to a PDF file, stream, or byte array.

The Layout method also contains an overloaded method that accepts an existing document object. This is useful when you need to append a document layout to a document you are already working with or want to append multiple document layouts to a single PDF. Remember, this method ignores the DLEX's metadata (author, keywords, subject, and title).

// Layout first document (metadata will be set to the document from the DLEX)
Document document = documentLayout1.Layout(layoutData1);
// Code for 2nd DocumentLayout
// Append to Document (metadata will be ignored from the DLEX)
documentLayout2.Layout(layoutData2, document);
// Code for 3rd DocumentLayout
// Append to Document (metadata will be ignored from the DLEX)
documentLayout3.Layout(layoutData3, document);
// Save the PDF
document.Draw(outputFilePath);

' Layout first document (metadata will be set to the document from the DLEX)
Dim MyDocument As Document = MyDocumentLayout1.Layout(MyLayoutData1)
' Code for 2nd DocumentLayout
' Append to Document (metadata will be ignored from the DLEX)
MyDocumentLayout2.Layout(MyLayoutData2, MyDocument)
' Code for 3rd DocumentLayout
' Append to Document (metadata will be ignored from the DLEX)
MyDocumentLayout3.Layout(MyLayoutData3, MyDocument)
' Save the PDF
MyDocument.Draw(outputFilePath)

LayoutData

When creating reports of any complexity, or with repeating data rows, you would use the LayoutData class. This class allows using JSON datasets, LINQ with XML data, and data from a database. For more information, refer to the Layout Data documentation topic.