How to Add a Format as HTML Pro Task Step

Introduction

This article provides guidance to creating an HTML document in the Format as HTML Pro The Format as HTML Pro tool is used to create a task step that produces single or multiple HTML documents. You can choose to create the HTML template from scratch or import a pre-existing template. Recordsets and other task step properties can also be used to populate the HTML document to product dynamic content documents. These documents can then be consumed and then delivered by Output or Execute task steps. tool using a single recordset input. For a detailed description of how to handle multiple input recordsets, see How to use Multiple Recordsets in Format as HTML Pro.

As the Format as HTML Pro tool has been designed for users with a moderate-to-advanced level of knowledge of HTML, this article does not go into detail about creating the HTML document; however, specific BPA Platform-related information is provided.

Creating the Task Step

Note: This procedure assumes you have a task with an existing step capable of outputting a recordset that can be consumed by the Format as HTML Pro tool. For a list of tools outputting to or consuming from this tool, refer to the product help (Format as HTML Pro Technical Summary).

The Format as HTML Pro tool does not require any global configuration; it can be immediately added to a task.

To add a new Format as HTML Pro step to an existing task:

Open the relevant task (if creating a new task, see How to Create a Basic Task).
Either:

►

Click and drag the Format as HTML Pro icon from the Task Browser to the task Design area.

–OR–

►

From the task's Design tab, right-click on empty space and select New > Format > Format as HTML Pro.

In the General tab, Name your task step.
Go to the Data tab and configure the format of the data sources. If your interface does not show the Data tab, your task does not contain steps capable of outputting a recordset; you can go straight to the Design tab to create the HTML document there.
1. Drag the relevant recordset to the Structure pane.
  Adding Recordsets
  Available recordsets from previous task steps are shown in the Input Recordsets pane. Drag the relevant recordsets whose data you want in the HTML document, to the Structure pane in the required data structure order.
  Tip: If all records from a single input recordset are required without any customisation, drag the relevant Results from ... to the Data Sources pane and select the document generation options. If data customisation is required, carry out the following sequence before creating or importing the HTML template — note that you must have the required data structure for your HTML template to hand first.
  TIP: When creating your data structure, the first nodes should be what you want to do to the recordset before specifying which recordset is involved.
  Tip: In the unlikely event a data source is renamed outside of the Format as HTML Pro tool, open the relevant task step(s) for the new data source name to be applied to your data Structure.
2. Highlight the new recordset and select the relevant document output from the Document Generations Options pane.
  How Do I Do This?
  Note that this pane is only available for the parent-level results set under Document.
  From the Document Generation Options pane, you specify when a new document is generated:
  ► Single Document — Generate a new document each time the Format as HTML Pro task step is run.
  ► New Document when Column changes — Generate a new document each time the value in a specified column changes. Select the relevant column.
  Tip: You can nominate multiple columns to generate new documents from. If so, the nominated columns are read as an OR statement rather than an AND. You do not need to restructure your recordset data to achieve this; each record is read and processed in turn.
  ► One Document for each row — Generate a new document for every record in the input recordset.
3. If generating a New Document when column changes or wanting to add sub-totals per group, you must have a group node. Group nodes control which records are returned; rather than saying "here is my data, group it" (recordset node as the parent to the group node), group nodes work in the opposite manner by saying "group the following data by these columns" (group node as the parent to the recordset). Right-click the newly added recordset to convert it to a group node.
  Grouping Your Data
  This feature acts in the same manner as the GROUP BY condition in SQL. If your input recordset data is not grouped, you are getting generating a New Document when Columns change, or wanting sub-totals generated per group, you should create a group node. Group nodes control which records are returned; rather than saying "here is my data, group it" (recordset node as the parent to the group node), group nodes work in the opposite manner by saying "group the following data by these columns" (group node as the parent to the recordset).
  Note: When creating the group node, if more than one column is selected to group on, the grouping is composite rather than hierarchical. For a detailed description of how to create hierarchical groupings, see Creating Hierarchical Groupings.
  To add a group node, you must convert the recordset node added previously to the group template (right-click the node > Templates > Convert to Group). Then select the relevant Column and Key.
  Tip: To see all grouped recordset data without any further manipulation, it is this node you drag to the HTML area in the Design tab (select Table with Children from the resultant menu).
4. Rename the group node to a meaningful name so you can see its function at a glance.
5. Because we converted the recordset node to a group, we now need to re-add the original recordset back to the data structure to ensure its records are available to the document, grouped accordingly. Drag it to the Structure as a child node to the group node.
6. If sub-totals are required, these are added to the group node if one exists — the logic behind it being that a sub-total is generated for each group. If not using a group node, then you add the sub-total to the parent recordset. Right-click the required node and select Add Subtotals.
  Creating Sub Totals
  You can create sub-totals for any required columns on either the group node (to generate a sub-total per group) or the recordset node (to generate a sub-total per recordset not per record).
  To add sub-totals to the output, right-click on the required node and select Templates > Add Subtotals.
  Note: If there is a difference between the data source's and the document output's number of accepted decimal places, be aware that values are aggregated first then rounded up or down to meet the output's needs. To avoid any rounding differences, it is recommended you round the values in your data source step first.
7. If grand totals are required, you convert a recordset to the grand totals template — add another recordset as a child node to the group node if using one, or the parent recordset. Convert the new node to the grand total template.
  Creating Grand Totals
  Grand totals are sums of all values, typically currency, in a column in the recordset. They are added as child nodes to either the group node (to generate a grand -total per group) or the recordset node (to generate a total per recordset not per record).
  You create grand totals in a similar way to creating groups:
  1. Add another recordset node to either the group or .parent recordset node.
  2. Right-click the new child node and select Templates > Convert to Grand Total.
  3. Select the relevant column to total on and click OK.
  4. As best practise, rename this node to indicate what you are totalling.
8. At this point, you can adjust the data displayed in the final HTML document in terms of removing unwanted columns or changing column headers. Highlight the recordset node and use the tools at the bottom of the interface to adjust
  Adjusting the Recordset Structure
  By default, all columns in the consumed recordset(s) are included in the HTML output without any further data manipulation. You can tailor what is included in your HTML document to suit.
  If required, you can exclude recordset columns from your HTML document. Highlight the relevant column in the Columns pane and click Remove.
  You can adjust recordset columns to suit — by changing the column name to a user-friendly name in the template, or by changing the aggregation type. Highlight the column and adjust the Column Properties to suit.
  Click the image to view full size.
  By default, sub and grand total columns use the sum aggregation type. If required, you can create aggregations for other columns in the recordsets.
9. Finally, you must ensure a relationship exists between each node to ensure the data is extracted correctly. Highlight each child node in turn and from the Relationship tab, ensure a link exists between the parent and child node's keys.
  Specifying the Recordset Relationships
  If your Structure has parent-child relationships, you must create the relationships between them to ensure the correct data is displayed in the document. You do this in the Relationship tab:
  Click the image to view full size.
  Drag the relevant columns from the Parent pane to their equivalent in the Child pane. Do this for every parent child relationship you have created. Note that this feature is only available when the child node is highlighted in the Structure pane.
For more information about the features and functionality available in the Data tab, refer to the product help (Introducing the Data Tab).

Go to the Design tab to create the HTML template. The design area is a completely free-form area, allowing you to use any valid HTML elements as required. To use the recordset data you have constructed, drag required recordset nodes into the design area.

Design Tab Parameters

A Note About the BPA Platform-Specific HTML

A few things to note about the HTML:

► class="-bpa-fah-row-[node_id]" — This class is a BPA Platform-specific class. It handles looping through the node_id's input recordset and outputs each record found on a new line. You can add this class to any valid HTML element (p, span, div, and so on).

For example:

  <table>
    <thead>
      <tr>
        <th>ORDER_DATE</th>
      </tr>
    </thead>
    <tbody>
      <tr class="-bpa-fah-row-ResultsfromDatabaseQueryODBC6">
        <td>{{ORDER_DATE}}</td>
      </tr>
    </tbody>
  </table>

outputs the following HTML:

  <table>
    <thead>
      <tr>
        <th>ORDER_DATE</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><span>01-Jul-2019</span></td>
      </tr>
      <tr>
        <td><span>02-Jul-2019</span></td>
      </tr>
      <tr>
        <td><span>03-Jul-2019</span></td>
      </tr>
      <tr>
        <td><span>04-Jul-2019</span></td>
      </tr>
    </tbody>
  </table>

■ Putting class="-bpa-fah-row-[parent_node_id]" in a <tr> element renders a new row in the table for each record in the input recordset. If this was the <table> element, it generate a new table for every record.

Tip: To find the ID for a node, drag it from the Structure pane into some free space in the HTML design area and select Node ID from the menu.

► class="-bpa-fah-node-[node_id]" — This class is a BPA Platform-specific class. It handles looping through the node_id's input recordset and outputs each record contiguously.

For example:

  <table>
    <thead>
      <tr>
        <th>ORDER_DATE</th>
      </tr>
    </thead>
    <tbody>
      <tr class="-bpa-fah-node-ResultsfromDatabaseQueryODBC6">
        <td>{{ORDER_DATE}}</td>
      </tr>
    </tbody>
  </table>

creates the following HTML:

  <table>
    <thead>
      <tr>
        <th>ORDER_DATE</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><span>01-Jul-2019</span><span>02-Jul-2019</span><span>03-Jul-2019</span><span>04-Jul-2019</span></td>
      </tr>
    </tbody>
  </table>

Note: Do not apply CSS (styling) to these classes; it is ignored and removed at task run-time.

► Marker fields — Marker fields are those wrapped in {{ }}. These are placeholders for BPA Platform data; in this scenario, for recordset data. The markers must belong to a parent -bpa-class otherwise a validation error may occur.

Each BPA Platform-specific class is valid until the closing tag in which it resides — for example, if you put a class inside a div, all markers encountered in that div must belong to the declared node ID. Markers from other node IDs placed inside the div will generate an error unless their class is also declared inside the div. In fact, it is perfectly acceptable to declare a BPA Platform class inside the body tag, however, you should only declare the highest level parent node here. If your data structure has more than one parent node at the same level, you shouldn't declare any BPA Platform classes in the body tag.

For a detailed description of how to use all features and functionality available in the Design tab, refer to the product help (Introducing the Design Tab).

Go to the Options tab and select the relevant error handling options for this task step.

How Do I Do This?

The Options tab allows you to define how errors in this step are handled at task runtime.

If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Task).

By default, data from grouped nodes are sorted according to their values; if grouping by a numeric field, this results in the following output:

1, 2, 3 ... 10, 11, 12 ... 20, 21, 22 ... 30, 31, 32, and so on.

If string-based sorting is required, enable Use string comparison for 'Group by' ordering in the Compatibility panel; numeric fields would then output as:

1, 10, 11 ... 2, 20, 21 ... 3, 30 31, and so on.
Click to save the task step.