There are a number of different ways to customize ReportingTools behavior, depending on the level of re-use you intend. And how much control (and thus how much of the work) you want to exert yourself. The overall workflow of transforming an object into HTML to be inserted into your report can be seen in the figure below, which can also be found in ReportingTools/inst/examples:
As you can see, each step is controllable via arguments to the publish function or the specification of class methods. Here is a "brief" explanation of what each of them do.
There are two ways to take full control of the HTML generation process to generate fully custom HTML representing particular objects or classes of objects:
- Specifying .toHTML in publish() - This wrests complete control of HTML generation away from the defaults. The function you specify is responsible for constructing the HTML representing that individual object exactly as it will appear in the final HTML page.
- Defining an objectToHTML method (via setMethod) for a class - This permanently changes ReportingTools' behavior for that class (when the method is present). That is, All objects of that class, across multiple calls to publish() will use your method. As above, your method is responsible for generating HTML exactly as it will appear within the final HTML report.
When custom HTML generation is not present, objects are transformed into data.frames, modified to reflect exact desired output (e.g., adding, removing, or transforming columns), and then transformed into HTML. Both of these steps are also fully customizable, as follows:
- Specifying a .toDF function within publish() - This overrides the default behavior ( calling as.data.frame() ) for transforming that individual object into a basic data.frame. Conceptually, this transformation should be about representing the object as a data.frame as exactly as possible. Customization for the purpose of display should happen in the modification step.
- Specifying a toReportDF method for a class - as in (1) but the custom behavior will be used for all objects of that class across multiple calls to publish().
- Specifying a .modifyDF function or list of functions within publish() - This customizes the "decoration" step of preparing the data.frame representing that individual object for display in your report. If you specify a list of functions, they will be called sequentially in the order that they appear in the list, each function after the first receiving the output from the previous function as input. The first (/only) function specified here will be passed the data.frame created during the (1)/(2) base df creation step.
- Specifying a modifyReportDF method for a class - As in (3), but the behavior will be used for all objects of that class (and you can only specify a single function, not a list).
Note that arguments to publish will always override existing S4 methods for objectToHTML, toReportDF and modifyReportDF.
For permanent/often reused customizations, you can create a package which depends on ReportingTools which exports custom, class-specific methods for any or all of these steps. Once such a package is installed, loading it and using ReportingTools normally should "just work" and utilize your customizations by default.
Hope that helps.