Creating a new Visualforce receipt layout

In order to change the formatting for receipt and settings values used in the receipt template, or to add new custom fields, you will need to create a new Visualforce that uses the ReceiptTemplateController class.

For more information on how the Receipting SmartPack uses Visualforce pages in conjunction with receipt values and receipt settings, see Receipt PDF Template Overview.

This article assumes that you have some knowledge of Visualforce!

Using ReceiptTemplateController in your Visualforce pages

The ReceiptTemplateController class is a custom controller apex class that is included in the Canadian Receipting SmartPack. The SmartPack generates receipts by including user-defined Visualforce pages in a parent Visualforce page that handles matching the Visualforce page to the appropriate receipt template definition, fetching the appropriate receipt objects, and rendering everything as a PDF. Individual receipt templates should implement the ReceiptTemplateController and any external CSS stylesheets.

See the example below of the first few lines of a Visualforce template page. You can also use the included Visualforce template pages as examples or even clone and then modify them.

<page controller="kell6_core.ReceiptTemplateController" readonly standardstylesheets="false">
    <stylesheet value="{!URLFOR($Resource.TemplateStyles)}"></stylesheet>

    <div class="wrapper">
...
	</div>
</page>

ReceiptTemplateController variables

The following variables are available for use in template Visualforce (VF) pages:

  • Receipt
    • kell6_core__Receipt__c object. Use this to display values from the receipt fields.
  • LetterValues
    • Map<String,String>. This contains the labels, image definitions and accompanying letter text from the Receipt Template Settings.
  • ReplacedReceipts
    • String. This string is a comma separated list of all the other Receipts that are being replaced by the generate receipt.
  • DateFormat
    • String. The date format set in the Receipt Template Setting saved as a string for easier use in template VF pages.
  • CurrencyFormat
    • String. The currency format set in the Receipt Template Setting saved as a string for easier use in template VF pages.
  • halves
    • List<Integer>. A list that contains '1' and '2'. This can be used to easily create double receipts when combined with the <apex:repeat> tag. See the Receipt_Double VisualForce page as an example.
  • thirds
    • List<Integer>. A list that contains '1', '2', and '3'. This can used to easily create triplicate receipts when combined with the <apex:repeat> tag. See the Receipt_Double VisualForce page as an example that uses the halves variable.
  • Installments
    • List<kell6_core__Receipt_Installment__c>. This list contains all values from the Receipt Installments for any Installment gifts and can be used to create lists or tables with installment details using the <apex:repeat> or <apex:datatable> tags. This list will be empty for Single Receipts. Please note that the Receipt Installment object does not include many fields out of the box (like gift date or gift amount), so those fields will need to be added and calculated using other custom logic before this list is likely to be useful.

LetterValues

The LetterValues map is used to pull in the labels and imaged defined in the Receipt Template Setting.  All of the values returned are strings, so you will need to convert to date or currency if you wish to do any additional formatting. Any values that are not defined in the Receipt Template Setting will return a blank string (''). For images, the returned value can be paired with the $Resource tag in VisualForce to place images. For text labels and especially for the Accompanying Letter merge value, using the escape="false" attribute is recommended so that admins can add basic html formatting within the Receipt Template setting.

Below is an example of merging in the Receipt Title as defined in the Receipt Template Settings

<outputtext value="{!LetterValues['Receipt Title']}" escape="false"></outputtext>

The following values are available in the LetterValues map.

  • Label Amount
  • Label Appraiser Details
  • Label Benefit Value
  • Label Campaign
  • Label Description
  • Label Donation Date
  • Label Donor Address
  • Label Donor
  • Label Place of Issue
  • Label Receipt Date
  • Label receipt Number
  • Label Tax Deductible Amount
  • Letter Logo
  • Letter Sender Signature
  • Receipt Logo
  • Receipt Sender Signature
  • Charity Name and Address
  • Charitable Registration Number
  • Custom Text
  • CRA Information
  • Receipt Title
  • Receipt Subtitle
  • Accompanying Letter Sender
  • Receipt Sender
  • Place of Issue
  • Replacement Note
  • Accompanying Letter

Formatting Tips

For a more extensive list, please see Styling and Formatting in Receipt Templates (forthcoming).

Date and Currency Formatting

You can use the DateFormat and CurrencyFormat variables along with the <apex:outputText> tag to universally apply the Date and Currency Formats defined by administrators. This is particularly useful for organizations that generate receipts in both English and French.

<outputtext value="{0,date,{!DateFormat}}">
	<param value="{!TODAY()}">
</outputtext>

<outputtext value="{0, number, {!CurrencyFormat}}">
	<param value="{!Receipt.kell6_core__Receipted_Amount__c}">
</outputtext>

Images

Use the $Resource global merge field to pull in the logo and signature images defined in Receipt Template Settings.

<img src="%7B!%24Resource%5BLetterValues%5B'Receipt%20Logo'%5D%5D%7D" alt="Logo">

<image url="{!$Resource[LetterValues['Receipt Logo']]}" alt="Logo"></image>

Conditional Display

Occasionally, you will want to only display label values if they are defined, or only display values on the receipt if they are defined. There are several methods for this, including using <apex:outputPanel>, setting the rendered attribute on <apex:outputField> or <apex:outputText>, or using the display or visibility properties on html elements.

<outputpanel layout="block" rendered="{!NOT(ISBLANK(LetterValues['Charity Name and Address']))}">
	<outputtext value="{!LetterValues['Charity Name and Address']}" escape="false"></outputtext>
</outputpanel>

<outputtext value="{!LetterValues['Charity Name and Address']}" escape="false" rendered="{!NOT(ISBLANK(LetterValues['Charity Name and Address']))} /&gt;

&lt;tr style=" display:>
	...


<tr style="visibility: {!IF(NOT(ISBLANK(Receipt.Description__c)), 'visible', 'hidden')};">
	...
</tr></outputtext>