Developers > Kernel Documentation > HTML formatting > ReportBuilder.pm

ReportBuilder.pm

ReportBuilder

This is a utility for building tabulated reports. It is content-agnostic, and simply handles the formatting of data into a table, depending on the input provided. If the report is to be interactive (links, JS, etc.), those features must be included in the content of the report; ie. you must code the links, divs, etc. yourself in the values that you pass.

Input

all input can be passed in a control hash

    title => content for titlebar; 


headers => array of header content; 
    data => array of arrays of data content; 
    tools => content for toolbar; 


foot => content for footer; 
    nodata => no data warning message
    show_tools_if_nodata => flag controlling tool display if no data
    show_data_if_nodata => flag controlling display of data area if no data
    width => width of report table
    cwidth => widths of columns (array of same size as headers)

The show_* flags are true/false values to control the display of those report fields/rows if there is no content for the respective rows. In other cases, the row is left out completely if there is no content.

The toolbar is normally used to place links or buttons to operate on the report as a whole. The footer area is used to append more information that pertains to the report (such as help text, or sub-reports).

You can append additional rows of data using the push() method. To add one row, pass the row as an array of values or a reference to an array of values:

    $rpt->push($dataref);
    $rpt->push(@data);

To add multiple rows, pass an array of rows, each one a reference to an array of values:

    $rpt->push(@rows);

Simple Usage Example:

    my $rpt = new ExSite::ReportBuilder(
                     title=>"My Report",
                     headers=>["Col 1","Col 2","Col 3"],
                     data=>\@data,
                     tools=>"do something",
                     foot=>"report generated on ".localtime(),
              );
    $rpt->push($data);  # add another row of data
    $rpt->push(@data);  # add another row, or multiple rows of data
    print $rpt->make;   # generate the report

Output

ReportBuilder returns the HTML for display the formatted report.

Reports have 3 structures:

  • if data is an array of arrays:
    •     +----------------------------------------------+
    | title                                        |
    +------------+---------------------+-----------+
    | header1    | header 2            | header 3  |
    +------------+---------------------+-----------+
    | data1A     | data2A              | data3A    |
    +------------+---------------------+-----------+
    | data1B     | data2B              | data3B    |
    +------------+---------------------+-----------+
    | tools                                        |
    +----------------------------------------------+
    | foot                                         |
    +----------------------------------------------+
  • if data is a simple array:

    •     +----------------------------------------------+
    | title                                        |
    +------------+---------------------------------+
    | header1    | data1                           |
    +------------+---------------------------------+
    | header2    | data2                           |
    +------------+---------------------------------+
    | header3    | data3                           |
    +------------+---------------------------------+
    | tools                                        |
    +----------------------------------------------+
    | foot                                         |
    +----------------------------------------------+
  • if data is a scalar
    •     +----------------------------------------------+
    | title                                        |
    +----------------------------------------------+
    | data                                         |
    +----------------------------------------------+
    | tools                                        |
    +----------------------------------------------+
    | foot                                         |
    +----------------------------------------------+

The HTML output uses the following CSS classes. Example CSS can be found in _ExSite/css/ExSite.css. (If you are using these reports in ExSite control panels, you will probably be using this stylesheet by default.)

    table.Report - the entire report
    table.Report caption - the title
    th.ReportTools - the tools row
    th - normal th elements are column headings
    tr.A, tr.B - alternating data rows
    td.label, td.data - row elements in the 2nd report style, above
    td.ReportFooter - the footer row, if any

Dynamic Reports

Dynamic reports use DHTML functions to make the report fully interactive. You can:

Set a report to be dynamic by either setting the dynamic attribute when you instantiate the object, or by calling the dynamic() method:

    $rpt->dynamic()

Dynamic reports use the Jquery framework (and the DataTables plugin) to perform the dynamic report modifications.

Topics