SoftBreak and NoSplitZone

When creating a report using Designer, there are situations where you might need to use the SoftBreak layout element with one or more NoSplitZone layout elements. Using these layout elements properly is not always intuitive when starting, so the following topic illustrates using these two layout elements together.

This project is available on Github as designer-usersguide-examples.

In this example project we use the following JSON dataset and the softbreaksubreport.dlex DLEX report.

The following JSON is incomplete due to size. Refer to the GitHub project for complete dataset.

JSON Data

The JSON dataset consists of a report containing two subreports. One of the subreports is further nested by another subreport.

{
  "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
            }
          ]
        },
          
..... snip ....

      "regiondata": [
        {
          "name": "description",
          "description": "ayay ickthay oatcay ofyay ackblay aintpay overedcay allyay . arscay andyay ussesbay alledstay inyay owsnay iftsdray . ayay ickthay oatcay ofyay ackblay aintpay overedcay allyay . arscay andyay ussesbay alledstay inyay owsnay iftsdray"
        },
        {
          "name": "history",
          "description": "ayay ickthay oatcay ofyay ackblay aintpay overedcay allyay . arscay andyay ussesbay alledstay inyay owsnay iftsdray."
        },

.... snip ....

The dataset consists of multiple regions, each region contains two states, and each state includes two cities. A region also has regional data describing a region, its geography, history, and available entertainment.

Figure 1. Data model of JSON dataset consisting of regional data.

Refer to JSON for more information on data models and JSON formatting requirements when using Designer

Upon loading the JSON data into designer, the Data Explorer shows the regions as an array containing two nested arrays: regiondata and states. The states nested array itself contains a nested array of cities.

Figure 2. JSON data loaded in the Data Explorer.

Report

The report we create will consist of a regions report, with a subreport for states and a subreport for regiondata. The states subreport in turn contains the cities subreport.

If you have not created subreports, then refer to the many Designer tutorials and Users Guide documentation. Here it is assumed you understand creating reports and subreports.

Figure 3. The logical layout of the report and subreports used in this DLEX file.

autoSplit Property

Open the DLEX file in Designer and scroll to the report. Notice the report's details has an autoSplit property. By default the value for this property is false.

Figure 4. The softbreaksubreport.dlex file where the report's details autoSplit property is false.

When a report's Detail layout element's autoSplit property is false, then when generating the PDF, the DynamicPDF layout engine does not split content when it is larger than a page. For example, when generating the PDF for this example, it does not display all the regional information in the regiondata subreport, as the amount of data is greater than the page size.

Figure 5. When autoSplit is false, the example report's content runs past the page margin.

To fix this issue, change the autoSplit property to true. Generate the PDF, and the report logically splits the content with a new page.

Figure 6. When autoSplit is true, the example report logically splits the content with new pages.

However, note that the autoSplit property uses its best judgment to split the report into pages. For example, the states in a region might create a page break between states.

Figure 7. The autoSplit property logically determines where to place page breaks between content.

In our report data, there are only two states per region, and so we would like to keep them grouped. To accomplish this grouping, we use a NoSplitZone layout element.

NoSplitZone Layout Element

A NoSplitZone layout element creates a region where the layout elements within that region are kept together. For example, if we added a NoSplitZone to the top-level region information and the states and cities subreports, then we could be assured that they remain together.

Figure 8. Adding a NoSplitZone layout element to the sample report.

Figure 9. After adding a NoSplitZone the state and city data is not split.

Although the sections in the NoSplitZone layout element remain together, the regional information splits logically because the report's autoSplit property is true.

Figure 10. The regional information is partially displayed under the state/city data and partially on its own page.

But it would be nice to display the regional information on its own page. An easy way to accomplish this is to add SoftBreak layout element to the report.

SoftBreak Layout Element

The SoftBreak layout element attempts to create a page break at the specified location if it can. When using a soft break, first change the report's autoSplit property to false.

Creating a SoftBreak layout element without changing autoSplit to false causes the soft break to have no effect.

After ensuring the autoSplit property is false you can then add a SoftBreak layout element between the states subreport and the regionData subreport. This informs the DynamicPDF layout engine to create a page break if at all possible between the two subreports.

Figure 11. Adding a SoftBreak layout element between two subreports.

Generate the PDF and the report splits between the states and cities subreports and the regional data subreport.

Figure 12. Generating the report with a SoftBreak splits the reports between subreports.

In this topic