RazorAntMain.Core.Pages.Page RazorAntMain.Core.Pages.Page

Support

Creating a Custom Report

While ProfitTrain now has more reporting options, each business has its own specific reporting needs and now you can make the exact report you need.

Reports are generated from Report Templates. Report Templates are very much like Invoice Templates, but a bit more advanced. If you have done some work with Invoice Templates than this isn't going to be too difficult, but if it is all new to you, then it might be best to look over the information on creating invoice templates as well.

What is a report template?

Just like an invoice template, an report template is a bundle. In OS X, bundles are simply folders that appears as a single file or resource in the Finder. To look inside a bundle right click the file and choose Show Package Contents. Inside our bundle you'll see a few files, including:

  • Info.plist -- Stores author info and details for each label used inside the report.
  • template.html -- the template file itself.
  • and other various CSS and image files the template uses.

The name of the bundle is the name of the report with a PTReportTemplate extension. So if you want to make a new report called "My Report", you want to start with a bundle called "My Report.PTReportTemplate". This extension tells OS X that is associate with ProfitTrain.

Getting Started

It is likely always best to start with an existing report template. I'd suggest downloading the report that is closest to what you want from the Report Gallery and starting there.

Assuming you now have a PTReportTemplate bundle on your Mac, start by renaming it to have a new name (so you have a report by a new name.)

Next, we need to right click the bundle in Finder and choose 'Show Package Contents'. This will show us the files inside the bundle.

Your bundle has 2 critical components: info.plist and template.html.

Info.plist

This is the file that has some basic information about your report.

  • TemplateIdenifier - unique template identifier
  • CreatorHomePage - creator's web site
  • CreatorName - creator's name
  • Version - version of this report
  • CBMinimumAppVersion - should be at least 2.1
  • ShortDescription - short description of report
  • RequiredDataSet - name of dataset need for report

The key item in this list is the RequiredDataSet. The value of this field will determine which dataset(s) ProfitTrain will generate for your report to take advantage of. Below are the valid datasets.

  • expenses - all expenses in the given date range by date and all expense categories alphabetically
  • expensesPerCategory - all expense categories with total alphabetically
  • invoices - all invoices in the given date range by sent date then invoice number
  • invoicesByClient - all invoices in the given date range by client name, sent date, invoice number
  • MonthlyTaxes - all months in given date range with taxes
  • MonthlyIncome - all months in given date range with income
  • paidInvoices - all paid invoices in the given date range by first payment date, then invoice number
  • toDos = all toDos by client name, name of task, and date performed (v2.2)
  • toDosByName = all toDos in the given date range by name of task, then date performed
  • transactions - all balance sheet items in the given date range by entry date

You may include multiple data sets in this line of info.plist. Just commas separate them.

If you chose your starting template wisely, you will not have to change the requireDataSet field. This will help you when you get to editing the template.html file.

template.html

This is the html file that will generate your report. If you are familiar with html than this should look mostly like you'd expect it to. If not, you are going to need to read a brief html tutorial to understand what you are seeing here.

Intermixed with the HTML are MGTemplateEngine markers just like you saw in the invoice template documentation.

{{invoice.invoiceNumber}}
  

These are the places where ProfitTrain will display the value of your data instead of the text or tags in your html file.

You'll need to edit the html file to reflect how you want your report to look. Then add in the MGTemplateEngine markers to put your data in. Often you'll want to loop through all the items in a set with a for loop as shown in the invoice template documentation.

Again if you've chosen your starting report wisely, your basic for loop is likely setup already and you simply need to change the fields or order of the data.

The main ingredient of the reports is of course your data. On the template objects page, you'll be able to see the different objects available to you as you are working on your report.