Contribution Statements - HTML Option
=====================================
The HTML option for contribution statements allows for more complete customization than
is possible with the default statements. The special content files **StatementHeader** and
**StatementNotice** still control what is displayed at the top of the statements. But with
the HTML option enabled, you can also control the format of the rest of the statement with
the new files **StatementTemplate**, **StatementTemplateBody**, and **StatementTemplateFooter**.
Later in this article, samples of the files are provided, as well as information about the
replacement codes that can be used in the templates.
To switch to the new custom statements, prepare the above-mentioned files per the directions
below. Then add the setting ``UseNewStatementsFormat`` with a value of ``True``. After setting this
to ``True``, the first time you view a contribution statement, if you have not already created the
files, default files for **StatementTemplate** and **StatementTemplateBody** will be created and
placed on the Text Content tab.
.. Important::
The default templates will be suitable in most cases. Do not attempt extensive customization unless
you have the in-staff HTML expertise to make the desired changes to the statement templates. It is
outside the scope of our support to create customized statements for you or to offer guidance beyond
the information provided in this help article.
Custom Statements for Ministry Fund Sets
----------------------------------------
If you currently use the Custom Statements feature, allowing you to generate custom statements
for particular sets of funds, you can still use that feature with this HTML option. As before,
you will continue to define the header and notice for your custom statements with the
**CustomStatements** file. But with the ``UseNewStatementsFormat`` setting set to ``True``,
you will now also be able to define the ``Template``, ``TemplateBody``, and ``Footer``.
.. seealso::
:doc:`CustomStatements`
All five elements can be configured either by including a block of HTML code within the appropriate
tags (such as `` [HTML code block] ``) or by referencing an external special content file
as an attribute within the tag. An example of this second method is ````
where the filename can be one of your own choosing. The sample code below contains the available tags
and demonstrates their use with the second (external file) method.
.. code-block:: xml
:linenos:
.. _StatementCoverLetter:
Including a Cover Letter
------------------------
You can prepend a cover letter to statements by including HTML code similar to the following at the
top of the section of the **StatementTemplate** file. The final line is important as it creates
the page break between the cover letter and the statement proper.
.. code-block:: html
:linenos:
Sample Church
105 Highway 151
Ventura, TN 34773
615.232.3432
{{contributor.Name}}
{{{contributor.MailingAddress}}}
Dear {{contributor.Name}},
We are grateful for your generosity this past year. Your gifts have made possible the various ministries of Sample Church, making
a difference in the lives of people in this community. Attached is your giving statement for {{FmtDate fromDate}} - {{FmtDate toDate}}.
Again, thank you!
Settings Used with the HTML Option
----------------------------------
Some of the settings already in use for statements will continue to work with the HTML option
enabled. Others will no longer be used. The settings that will continue to be used are:
* MinContributionAmount
* NoTitlesOnStatements
* RequireAddressOnStatement
* ShowPledgeIfMet
The following settings will no longer be used when the HTML option is enabled because the options
can be controlled within the StatementTemplateBody or StatementTemplate:
* ContributionStatementFundDisplayFieldName
* DisplayNonTaxOnStatement
* NoPrintDateOnStatement
* PrintEnvelopeNumberOnStatement
* RequireCheckNoOnStatement
* RequireNotesOnStatement
* StatementAddrPos
* StatementRetAddrPos
Templating Language
-------------------
The statement template files use Handlebars to allow for extensive customization. The object
use in templating the statement is called a StatementContext. The following objects and
properties are available from the StatementContext.
.. csv-table::
:header: "Name", "Type", "Value", "Examples"
:widths: 20, 20, 60, 40
fromDate, DateTime, Start date of the statement; see DateTime below, 1/1/2019
toDate, DateTime, End date of the statement; see DateTime below, 12/31/2019
header, HTML, HTML of the statement header (StatementHeader special content), See *StatementHeader*
now, DateTime, The current date & time; see DateTime below, 1/25/2020
notice, HTML, HTML of the statement notice (StatementNotice special content), See *StatementNotice*
body, HTML, HTML of the statement body (StatementTemplateBody special content), See *StatementTemplateBody*
footer, HTML, HTML of the statement footer (StatementTemplateFooter special content), See *StatementTemplateFooter*
envelopeNumber, Text, The value of the contributor’s EnvelopeNumber extra value, 1234
contributor, ContributorInfo, "An object with properties describing the contributor including Name, MailingAddress, PeopleId, SpouseID, FamilyId, DeacesedDate, FamilyPositionId, Age, Joint, CampusId", See *ContributorInfo*
contributions, List, A list of tax deductible Contribution objects, See *Contributions*
giftsinkind, List, A list of gift-in-kind Contribution objects, See *Contributions*
nontaxitems, List, A list of non-tax deductible Contribution objects, See *Contributions*
pledges, List, A list of pledge summary objects, See *PledgeSummary*
taxSummary, List, A list of tax deductible summary objects, See *TaxSummary*
nontaxSummary, List, A list of non-tax deductible summary objects, See *NonTaxSummary
totalGiven, Decimal, The total amount of tax and non-tax deductible contributions, 1234.56
Objects
-------
DateTime
~~~~~~~~
These are only some of the most commonly-used properties. The full reference can be found
`here `_.
A DateTime object is often used to display only the date. Using ``{{FmtDate now}}`` would print
a date like ``7/30/2019``.
.. csv-table::
:header: "Property", "Example Value", "Description"
:widths: 20, 20, 80
Day, 30, The day of the month (1 - 31)
Hour, 15, The hour of the day in 24-hour format (0 - 23)
Minute, 36, The minute of the hour (0 - 59)
Month, 7, The month number (1 - 12)
Year, 2019, The 4-digit year
ContributorInfo
~~~~~~~~~~~~~~~
Use information from the names in this table with the format ``contributor.age`` where ``age`` is
replaced with the Name of the specific information desired.
.. csv-table::
:header: "Property", "Type", "Example Value", "Description"
:widths: 20, 15, 22, 70
Age, Integer, 30, The person’s age if available
CampusId, Integer, 1, The ID of the person’s campus
DeceasedDate, DateTime, 10/4/2019, "If the person is deceased, the date of their death"
FamilyId, Integer, 123, The person’s family ID
FamilyPositionId, Integer, 20, "The person’s position ID in the family (10 = Primary, 20 = Secondary, 30 = Child)"
hohInd, Integer, 1, "The person’s status as head of house (1 = Head, 2 = Spouse, 3 = Other)"
Joint, Boolean, true, Whether the person contributes jointly with spouse
MailingAddress, HTML, "123 Main St
Dallas, Texas
75240",
tags are automatically added to create a multi-line address for mailers
Name, Text, "Mr. and Mrs. Smith", "A calculated name based on combined rules from preferred name, CoupleName extra value, whether the couple are joint givers, and whether other titles are applied to the people this statement is for"
PeopleId, Integer, 456, The person’s TouchPoint ID
SpouseId, Integer, 457, The TouchPoint ID of the contributor’s spouse
Contributions
~~~~~~~~~~~~~
This list of contributions can be iterated using ``{{#each contributions}}``. See the Sample TemplateBody,
lines 103-115, for an example of how to use the properties in this table.
.. csv-table::
:header: "Property", "Type", "Example Value", "Description"
:widths: 20, 15, 22, 70
BundleType, Text, "Generic Envelopes, Loose Checks and Cash, Online", The type of bundle this contribution is in
CheckNo, Text, 1234, The check number recorded on the contribution
ContributionAmount, Decimal, 12.34, The total amount of the contribution (in dollars and cents)
ContributionDate, DateTime, 10/4/2019, The date recorded on the contribution
ContributionId, Integer, 123456, The contribution ID
ContributionType, Text, "Regular, Online", The description of the type of contribution recorded
ContributionTypeId, Integer, "1, 5, 10, 20", The ID of the type of contribution recorded
Description, Text, "Recurring Giving", The description recorded on the contribution
FundDescription, Text, Missions trips and Outreach, The description of the fund associated to the contribution
FundName, Text, Missions, The name of the fund associated to the contribution
Name, Text, Joe Smith, The name of the person who gave the contribution
Notes, Text, "In memory of…", The memo left by donor when making the gift
Decimal
~~~~~~~
The normal use of a Decimal object is to display a dollar amount. Using ``{{FmtMoney Amount}}`` would print the
amount as ``$12.34``.
PledgeSummary
~~~~~~~~~~~~~
This is a summary object intended for displaying sums that have been pledged or given to pledge funds.
.. csv-table::
:header: "Property", "Type", "Example Value", "Description"
:widths: 20, 15, 22, 70
CurrentYearTotal, Decimal, 800.00, Total amount given to the fund for the year of the statement
FundDescription, Text, Mission trips and outreach, The description of the fund
FundName, Text, Mission, The name of the fund
Given, Decimal, 900.00, Total amount given to the fund
Pledged, Decimal, 1000.00, Total amount pledged to the fund
PledgeDate, DateTime, 10/4/2019, The date of the earliest pledge made to the fund
PriorYearsTotal, Decimal, 100.00, Total amount given to the fund for the years preceding the statement
NonTaxSummary
~~~~~~~~~~~~~
This is a summarized list of totals by fund containing the properties *FundName, FundDescription,
ContributionAmount* for contributions that are classified as non-tax deductible. This list can be
iterated using ``{{#each nonTaxSummary}}``. See the Sample TemplateBody, lines 65-70 for an example
of how to use the properties listed above. Additionally, the following properties is available and
can be used as seen on lines 72-73 of the sample code.
.. csv-table::
:header: "Property", "Type", "Example Value", "Description"
:widths: 20, 15, 22, 70
Total, Decimal, 789.00, Total amount given to all funds
TaxSummary
~~~~~~~~~~
This is a summarized list of totals by fund containing the properties *FundName, FundDescription,
ContributionAmount* for contributions that are classified as tax deductible. This list can be
iterated using ``{{#each taxSummary}}``. See the Sample TemplateBody, lines 42-47 for an example
of how to use the properties listed above. Additionally, the following properties is available and
can be used as seen on lines 49-50 of the sample code.
.. csv-table::
:header: "Property", "Type", "Example Value", "Description"
:widths: 20, 15, 22, 70
Total, Decimal, 789.00, Total amount given to all funds
StatementOptions
-----------------
A script element in the StatementTemplate or StatementTemplateBody defined as can contain options defined as JSON within this block to set various options
for the generation of the PDF. The following definition explains all of the possible values and their defaults.
.. literalinclude:: Files/StatementOptions.json
:linenos:
HTML Template Files
-------------------
Below are samples of the required HTML template files.
StatementHeader
~~~~~~~~~~~~~~~
This file should exist (or, if not, should be created) at Administration > Special Content > HTML Content.
Below is sample source code for a statement header.
.. code-block:: html
:linenos:
105 Highway 151 | Ventura, TN 34773 | 615.232.3432
StatementNotice
~~~~~~~~~~~~~~~
This file should exist (or, if not, should be created) at Administration > Special Content > HTML Content.
Below is sample source code for a statement notice.
.. code-block:: html
:linenos:
NOTE: No goods or services were provided to you by the church in connection with any contribution;
any value received consisted entirely of intangible religious benefits.
Thank you for your faithfulness in the giving of your time, talents, and resources. Together we
can share the love of Jesus with our city
StatementTemplate
~~~~~~~~~~~~~~~~~
This file should be created at Administration > Special Content > Text Content. Below is sample code for
the StatementTemplate.
.. literalinclude:: Files/StatementTemplate.html
:linenos:
StatementTemplateBody
~~~~~~~~~~~~~~~~~~~~~
This file should be created at Administration > Special Content > Text Content. Below is sample code for
the StatementTemplateBody.
.. literalinclude:: Files/StatementTemplateBody.html
:linenos:
StatementTemplateFooter
~~~~~~~~~~~~~~~~~~~~~~~
This optional file can be created at Administration > Special Content > Text Content. Below is sample code for
the StatementTemplateFooter.
.. code-block:: html
:linenos:
Thank you for being a donor!
.. seealso::
:doc:`/Administration/Setting_Index`
|
|
+--------------------+------------------+
| **Latest Update** | **8/29/22** |
+--------------------+------------------+
Added link to Admin Settings article