Reports - TenthPres/TouchPoint-WP GitHub Wiki

TouchPoint-WP can embed a SQL Report run in TouchPoint into your website, automatically updating periodically.

Usage

This feature is enabled by default. To use it, just add a shortcode where you want the report's output to appear.

Note that the report runs in the context of the API user, not the user viewing the page.

[TP-Report type="sql" name="BudgetSummary"]

[TP-Report type="python" name="BudgetSummary"]

Replace BudgetSummary with the name of a SQL report saved in your TouchPoint Special Content. This shortcode can take the following parameters:

type - 'sql' or 'python', depending on which type of report you're embedding. Defaults to 'sql'.
name - This should be the name of the file, as saved in TouchPoint.
interval - The number of hours between updates. Defaults to 24 for daily updates. Must be 0.25 (15 minutes) or greater.
p1 - If your SQL script expects a value for @p1, you can put it in this space. Python scripts can also access this value through Data.p1.
showUpdated - True or false. If true, a caption will be added below the table indicating when the last update took place. Default true.
inline - True or false. If true, the content of the report will be printed inline wherever the shortcode is, (potentially mid-sentence). If false, the report will be printed in a figure block. Default false.

Special Stuff for SVGs

If your Python report outputs valid SVG content, there are a few special things you can do, working with it as an image.

Typical Embedding

Like any other report, you can just embed it directly on a webpage with the methods described above.
This is what we do on this page. One nice thing about this method is that text within your SVG should obey your site's CSS, so fonts and such should automatically match the site.

Using as an Image (SVG)

If you have an SVG report embedded on your site somewhere, you can also refer to the SVG directly as an image, if you want to use it in an <img> tag, or in a background, or in emails. The URL is /touchpoint-api/report/py/{reportName}.svg, or, if you have caching systems that treat .svg urls as static assets (we do), you can also use /touchpoint-api/report/py/{reportName}/svg. For example, we can access our "BudgetSummaryChart" report as an SVG image at /touchpoint-api/report/py/BudgetSummaryChart/svg.

<img src="https://www.tenth.org/touchpoint-api/report/py/BudgetSummaryChart/svg" alt="A chart of Tenth's giving" />

The trouble with SVGs, though, is that they don't always render consistently--especially in email clients, and especially in Gmail.

Using as an Image (PNG)

To render more consistently, you can convert the SVG to a PNG. You can do this by adding .png or _png to the end of the url. You can also add a bg url parameter to specify the background color of the image. For example, we can access our "BudgetSummaryChart" report as a PNG image with a pink background at /touchpoint-api/report/py/BudgetSummaryChart/svg_png?bg=pink. Colors can be specified as six-digit hex codes or with common color names.

<img src="https://www.tenth.org/touchpoint-api/report/py/BudgetSummaryChart/svg_png?bg=pink" alt="A chart of Tenth's giving" />

One downside of this method is that text within the image is not styled by the site's CSS. In particular, fonts will be limited to those available to PHP running on your server, which may not match the site. To some degree, you can control this with CSS within the SVG and (if possible) by installing fonts on the server, but you should expect some inconsistency in these ways.

This feature requires the Imagick PHP extension and SVG capabilities within it, which seem to typically be enabled or available by default, but may not be available on all hosts.