README
¶
GoReports
GoReports is a report generation tool that allows you to build and generate dynamic reports using a custom handlebars syntax that allows you to add SQL queries directly into the template and pass parameters to the queries.
See the Example section for a sample template.
Where to use GoReports?
Wherever there is a Print as PDF button, GoReports can be used to generate the PDF. Some examples are:
- Invoices
- Payment history
- Sales reports
Prerequisites
You need wkhtmltopdf installed and in your PATH for GoReports to work.
Installation
You can install the GoReports binary from the releases page.
Building from source
Requirements
- Go 1.18 or higher
- Enable
CGO_ENABLEDbygo env -w CGO_ENABLED=1. This is required for the SQLite driver to work.
Building locally
go env -w CGO_ENABLED=1
go build
OpenAPI Documentation
GoReports has an OpenAPI documentation that can be found at /swagger endpoint when the server is running.
Usage and Documentation
GoReports is a command line tool. You can run goreports --help to see the available commands and flags.
Start GoReports using Docker
- Build the Docker image using the following command:
docker build -t goreports \
--build-arg db_dialect=your_db_dialect \
--build-arg db_user=your_db_username \
--build-arg db_password=your_db_password \
--build-arg db_host=your_db_host \
--build-arg db_port=your_db_port \
--build-arg db_name=your_db_name .
Note: Database information is required to execute the queries in the templates and fetch the data for the reports.
- Run the Docker image using the following command:
docker run -p 3200:3200 goreports
Set up GoReports on your machine
goreports init
This will ask you for your external database credentials to execute the queries in the templates from and create
a config.json storing the credentials, as well as, a data/ directory in goreports config directory based on your OS.
An internal SQLite database will be created in the data/ directory to store the
reports.
Start the server
goreports start
This will start goreports server on port 3200.
Template syntax
GoReports uses an extended handlebars syntax to parse and render templates. The syntax is as follows:
[P[PARAMETER_NAME]]- This will be replaced with the value of the parameter passed to the template[Q[SQL_QUERY]]- This will be replaced with the results of the SQL query. If the query returns multiple rows, the result will be an array of objects. If the query returns a single row, the result will be a be inserted directly into the HTML{{#each [Q[SQL_QUERY]]}}- This will execute the (multiple results) SQL query and pass the result array to the handlebars block. You can then access the properties of each object in the array like you would in a normal handlebars
Example
This is a snippet of a template that uses all the syntaxes mentioned above:
<div style="max-width: 800px; margin: 0 auto;">
<h1>Payment History Report</h1>
<p>[P[extra_param]]</p> <!-- This is a parameter passed to the template at request/render time -->
<table>
<tr>
<th>Date</th>
<th>Invoice Number</th>
<th>Amount Paid</th>
</tr>
{{#each [Q[SELECT creation_date, invoice_number, amount_paid FROM payments WHERE customer_id =
[P[customer_id]] ]]}} <!-- This is a query passed to the template with a parameter in it -->
<tr>
<td>{{creation_date}}</td>
<td>{{invoice_number}}</td>
<td>{{amount_paid}}</td>
{{/each}}
<tr>
</table>
</div>
It generates (along with hidden CSS code) this report when rendered. As you can see, The SQL query is executed with the customer_id param (passed at each render request in the API) and its multiple results are passed to the handlebars loop.
Save a report
To save a report, send a POST request to GoReports' server at /report/save endpoint with the following JSON body:
{
"name": "required",
"title": "required",
"description": "optional",
"header": "<html>optional</html>",
"body": "<html>required</html>",
"footer": "<html>optional</html>"
}
The name field is the name of the report. Rendering the report will require this name.
The body field is the template to be parsed and rendered into PDF.
header and footer fields are optional and will be prepended and appended to the body respectively on each page.
Note: page numbers are generated at render time and replace the footer or the header if aer positioned at the bottom or the top of the page respectively.
Render a report
After saving a report you can render it by sending a POST request to /report/render endpoint with the following JSON body and options:
{
"reportName": "payment_history",
"printingOptions": {
"paperSize": "A4",
"landscape": false,
"marginTop": 20,
"marginRight": 0,
"marginBottom": 10,
"marginLeft": 0,
"pageNumbers": {
"enabled": false,
"position": "bottom-center || top-left || top-center || top-right || bottom-left || bottom-center || bottom-right"
}
},
"params": {
"customer_id": 2,
"extra_param": "This is a parameter passed from the client."
}
}
Note: It is on you to provide the necessary margins to show headers, footers and page numbers. Page numbers replace footers/headers if positioned on the bottom/top.
The report will be rendered into PDF and sent as a buffer in the response.
Delete a report
To delete a report, send a DELETE request to GoReports' server at /report/delete endpoint with the following JSON body:
{
"reportName": "required"
}
List all reports
To list all reports, send a GET request to GoReports' server at /report/list endpoint.
Limitations
- Footers and headers may overlap with the generated page numbers if the positioning are the same
- Errors currently are being returned written inside the PDF. This will be fixed in the future
- Handlebars helper functions are not supported as should be compiled into GoReport's binary
Contributing
Pull requests are always welcomed and encouraged. For major changes, please open an issue first to discuss what you would like to change.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Documentation
¶
There is no documentation for this package.
Source Files
Directories