Designer Structuring JSON

DynamicPDF Designer uses JSON documents when you create your DLEX templates.

You are not limited to JSON when creating your PDF. However, testing and debugging your DLEX document while using Designer requires JSON data.

JSON data in DynamicPDF Designer has some limitations in how data must be structured to create a report. JSON documents must be structured to consist of top-level data, followed by one or more arrays.

Think of your JSON document like this: top-level JSON elements are for static placement, the first JSON array after the top-level elements is for the report, then any nested arrays are for subreports.

Top Level Elements

Top level elements are ideal for using on a cover page or as a header or footer. JSON data from top-level elements can be placed on a page or any report section. But on headers and footers the same value is repeated when there are multiple pages. When a top-level element is placed in the details, then that value is repeated for each row.

{
  "ReportName": "Widget Stock By Region State and City",
  "Date": "09/21/2021",
  "Author": "John Doe"
}

Figure 1. Using top-level JSON elements in a report's header.

Figure 2. Using top-level JSON elements in a Page.

Repeating Data Elements

Use an array to represent JSON data as data rows. For example, in the following JSON data each element in the regions array constitutes a data-row. When placed in a report's Detail section, it adds each array element as a record, and the elements within the array as fields.

{
  "ReportName": "Widget Stock By Region State and City",
  "Date": "09/21/2021",
  "Author": "John Doe",
  "regions": [
    {
      "name": "North East",
      "description": "The north east region's stock by state.",
      "units": 369444
    },
    {
      "name": "South West",
      "description": "The South West region's stock by state.",
      "units": 3514011
    }
  ]
}

For example, in the preceding JSON document, the regions array is the repeating data row.

Figure 3. The regions array in a JSON document.

Add the name, description, and units elements as RecordBox elements in the Detail section and when the PDF is generated each array element is printed as a data row.

Figure 4. Repeating data elements represented as rows in the generated PDF.

Nested Elements

JSON arrays can have nested arrays, where each nested array corresponds to a Subreport layout element. For example, in the following JSON document, the regions array is the top-level report's Detail section, while states array is a Subreport. The cities array is a nested Subreport.

You can nest as many Subreport layout elements as is reasonable in your DLEX report.

{
  "ReportName": "Widget Stock By Region State and City",
  "Date": "09/21/2021",
  "Author": "John Doe",
  "regions": [
    {
      "name": "North East",
      "description": "The north east region's stock by state.",
      "units": 369444,
      "states": [
        {
          "name": "New Jersey",
          "units": 22609,
          "cities": [
            {
              "name": "Toms River",
              "units": 333
            },
            {
              "name": "Newark",
              "units": 22276
            }
          ]
        },
        {
          "name": "New York",
          "units": 346835,
          "cities": [
            {
              "name": "Albany",
              "units": 323423
            },
            {
              "name": "Catskill",
              "units": 23412
            }
          ]
        }
      ]
    },
    {
      "name": "South West",
      "description": "The South West region's stock by state.",
      "units": 3514011,
      "states": [
        {
          "name": "Arizona",
          "units": 2156764,
          "cities": [
            {
              "name": "Tempe",
              "units": 2124312
            },
            {
              "name": "Phoenix",
              "units": 32452
            }
          ]
        },
        {
          "name": "New Mexico",
          "units": 1357247,
          "cities": [
            {
              "name": "Las Cruces",
              "units": 1234124
            },
            {
              "name": "Albuquerque",
              "units": 123123
            }
          ]
        }
      ]
    }
  ]
}

Figure 4. A nested JSON array and corresponding subreport rows.

Multiple Same-Level Arrays

Designer also supports JSON with multiple arrays on the same level. For example, the following JSON has animals and plants on the same level.

{
  "store" : "petstore",
  "animals": [
    {
      "name": "dog"
    },
    {
      "name": "cat"
    }
  ],
  "plants": [
    {
      "name": "Ivy"
    },
    {
      "name": "grass"
    }
  ]
}

When displayed in Designer, the Data Explorer lists the top-level element, store, and then the two arrays, animals and plants.

Figure 5. Designer with two arrays on the same level.

However, notice that when adding the array to a report's details, you must select the animals array OR the plants array as the Report layout element's dataName property. If you tried to add the name under plants to the details, then Designer notifies you of the error, informing you that you must change the report's dataName to plants.

Multiple Arrays as SubReports

You also cannot create a subreport, as that implies that plants is nested within animals. Instead, you must treat separate arrays on the same level as different reports.

Figure 6. Arrays on the same level must be in different reports.

However, you can include multiple sub arrays within a single top-level array. For example, suppose we added a top-level array named stores that contained a sub array of plants and a sub array of animals; the following JSON illustrates.

{
  "stores": [
    {
      "name": "PetStore One",
      "animals": [
        {
          "name": "dog"
        },
        {
          "name": "cat"
        }
      ],
      "plants": [
        {
          "name": "Ivy"
        },
        {
          "name": "grass"
        }
      ]
    },
    {
      "name": "PetStore Two",
      "animals": [
        {
          "name": "dog2"
        },
        {
          "name": "cat2"
        }
      ],
      "plants": [
        {
          "name": "Ivy2"
        },
        {
          "name": "grass2"
        }
      ]
    }
  ]
}

What this JSON allows is a top-level report of stores, nested by two subreports, animals and plants.

Figure 7. Two subreports on the same level below stores.

Conclusion

All these arrays and nested arrays might seem complicated, but a good rule of thumb is to remember an array nested in another array indicates it should be a sub array of its parent. Arrays on the same level (sibling arrays) must either be a separate report or multiple sub reports if the siblings have a parent array.

Designer does not support nested objects, for example, you cannot have a Car object with a nested Engine object. You could have a Car object with a nested Tires array; however, each Tire object element in the Tires array would not be named in your JSON document.

{
  "Car": {
    "Tires": [
    {
      "position" : "left-front"
    },
    {
      "position" : "right-front"
    },
    {
      "position" : "left-rear"
    },
    {
      "position" : "right-rear"
    }
  ]
}

See Formatting JSON more information.

When creating a JSON dataset, always bear in mind that the end result is a report of repeating data rows where an array represents the row to be repeated. Always remember, the end result is a report of repeating data rows.

In this topic