Xataface HTML Reports Module 0.2
HTML Reports Module for Xataface
Grouping Reports
See also:
Advanced Template Creation

Reports can also be grouped based on the value of specific columns. By creating a header or footer section in your template with a field macro will effectively cause the report, when run, to be grouped based on the fields in the headers and footers. Summary calculation fields can also be placed in header and footer sections to display summary results for particular columns (e.g. sum, count, avg, etc..).

Multiple levels of groups are supported also. E.g. By having 2 header sections, a report would be grouped on the fields in the first heading - then within each group, they would be separated into subgroups based on the fields in the second heading. This could be used, for example, to group transactions by Year, and also by category within each year.

A Look At the HTML Source

Before getting into the WYSIWYG features or grouping, let's take a look at the HTML that the report generator looks for when determining groups.

Section Headers

Any div tag in the template with a xf-htmlreports-section-header class will be treated as a section header. E.g.:

<div class="xf-htmlreports-section-header">
        My Report Title
</div>

A section header that contains no field placeholder macros is effectively a report header. I.e. the report generator will display this section once only at the beginning of the report.

Grouping Records

If the section header contains a field placeholder macro, then this field will be used to group the records in the report, and this header will be displayed before each group. For example, if our table had a field year and we wanted out report to separate the records into years, and place a heading to mark the beginning of a year you could have a section header as follows:

<div class="xf-htmlreports-section-header">
    Year: {$year}
</div>

Sub Groups

It is also possible to have subgroups by defining multiple section headers.

See also:
Multiple Headers / Subgroups

Summary Fields

The module also supports summary fields to display totals in section headers and footers.

See also:
Summary Fields

The Section Footers

Any div tag in the template with a xf-htmlreports-section-footer class will be treated as a section footer.

e.g.

<div class="xf-htmlreports-section-footer">
        My Report Footer
</div>

Headers and footers are grouped into matching pairs. If you are using multiple subgroups, you should make sure that there are an equal number of header sections as there are footer sections. Everything you can do inside a header section, you can also do inside a footer, and vice versa.

Adding Headers and Footers with the WYSIWYG Editor

Adding section headers and footers using the WYSIWYG editor can be accomplished with the Add Section Header

Screen_shot_2011-08-11_at_11.00.54_AM.png?max_width=640

and Add Section Footer

Screen_shot_2011-08-11_at_11.01.04_AM.png?max_width=640

buttons.

Clicking the Add Section Header button will add a section to the top of your template. In the editor it will be marked clearly. The resulting reports won't include the dotted border or the icon in the top left of the section.

Screen_shot_2011-08-11_at_11.01.15_AM.png?max_width=640

Similarly, clicking the Add Section Footer button will add a section to the bottom of your template.

Screen_shot_2011-08-11_at_11.01.30_AM.png?max_width=640

An Example with Section Headers

For this example we'll expand our Hello World example from earlier by adding a section header to group our tools list by tool type.

We begin by opening our Hello World template for editing. Then we click the Add Section Header toolbar button

Screen_shot_2011-08-11_at_11.13.01_AM.png?max_width=640

to add a section header.

Let's add the tool_type field to the header section. First we click the cursor inside the section header that we added, and click the Insert Field button on the toolbar to browse through the fields in our table.

Expand the Fields node and select the Tool Type field. This will add the {$tool_type_id} placeholder inside our section header. We'll expand this by prefixing the text "Tools of Type " so that the report makes sense.

Screen_shot_2011-08-11_at_11.11.51_AM.png?max_width=640

We'll click on the Preview button to see what this report will look like with the first 10 records of our set.

Screen_shot_2011-08-11_at_11.12.12_AM.png?max_width=640

It looks OK, but it is difficult to differentiate the section headers from the section bodies since they are both using the same size font.

Next we'll try to make the font of the section header into bold font. We'll use the Paragraph Format drop-down for this. Select the text in the section header, and then select "Heading 1" from the Paragraph Format drop down.

Screen_shot_2011-08-11_at_11.12.49_AM.png?max_width=640
Note:
There is currently a bug/annoyance in the editor that causes the section header section to be removed when the font is changed in the heading text. Notice that the section heading dotted border and icon disappeared when the font was changed. We need to add it back by clicking the Add Section Header button, then selecting and dragging our text back into the new, empty section header.
Screen_shot_2011-08-11_at_11.13.31_AM.png?max_width=640

Now that we have our template looking the way we want, we'll try to preview it again.

Screen_shot_2011-08-11_at_11.13.48_AM.png?max_width=640

Now the section headers are differentiated from the section bodies nicely.

Grouping with the Table View

So far we have been using the list view for all of our examples. The Table View can also be used with grouping. In this case it will still group the records based on the fields in the section headers and footers, but the record lists will be tabular with rows being records in the found set, and columns corresponding to the fields listed in the template body, appearing in the order in which they are declared.

Clicking on the Preview Report as Table button in the toolbar

Screen_shot_2011-08-11_at_11.51.58_AM.png?max_width=640

will show us a sample of what the table view will look like. In our case (from the example above) our table will only have one column because the template body only contained a single column.

Screen_shot_2011-08-11_at_11.51.42_AM.png?max_width=640

Summary

The HTML Reports module includes some powerful header and footer capabilities that can be used to group records in a report together. This section demonstrated how to create section headers and footers and how adding fields to those sections resulted in grouping reports into separate groups and subgroups.

Subsequent sections expand on this technique by adding summary fields and multiple levels of headers and footers to produce sub-sections also.

See also:
Advanced Template Creation
Multiple Headers / Subgroups
Summary Fields
 All Data Structures Files Functions Variables Enumerations