- Updated ContributionStatementGenerator block to allow StatementStar…

[bmurphy-dev]

…tMonth page parameter.

Notice

In case you are submitting a non bug-fix-PR, we highly recommend you to engage in a PR discussion first.

There are many factors we consider before accepting a pull request. This includes:

1. Whether or not the Rock system you run is a standard, main-line build. If it is not, there is a lower chance we will accept your request since it may impact some other part of the system you don't regularly use.
2. Features that would be used by less than 80% of Rock organizations, or ones that don't match the goals of Rock.

With the PR discussion we can assess your proposed changes before you start working on it so that we can come up with the best possible approach to it. This may include:

1. Coming up with an alternate approach that does not involve changes to core.
2. Advising how your proposed solution be done in a different way that is more efficient and consistent with the rest of the system.
3. Have one of our core developers make the changes for you. This may be the case if the change involves intricate tasks like an EF migration or something similar.

Proposed Changes

This change adds an additional page parameter to control the Start Month of the Contribution Statement Generator for the purposes of electronic statements specifically to handle International Tax Filing rules which do not align with the calendar year.
See this overview video and Rock Idea for details.
There are additional checks in place to handle using only the StatementYear page parameter, only the StatementEndMonth page parameter, only the StatementStartMonth page parameter or any combination of the three.

Fixes: #

Types of changes

What types of changes does your code introduce to Rock?
Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality, which has been approved by the core team)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• This is a single-commit PR. (If not, please squash your commit and re-submit it.)
• I verified my PR does not include whitespace/formatting changes -- because if it does it will be closed without merging.
• I have read the Contributing to Rock doc
• By contributing code, I agree to license my contribution under the Rock Community License Agreement
• Unit tests pass locally with my changes
• I have added any required unit tests or integration tests that prove my fix is effective or that my feature works
• I have included updated language for the Rock Documentation (if appropriate)

Further comments

Documentation

Current usage of the existing parameters are undocumented with exception to this recipe. New parameters will be documented in an upcoming recipe to build off of Jim's recipe upon release of v17 with the first release of the StatementEndMonth page parameter.

Migrations

If your pull request requires a migration, please exclude the migration from the Rock.Migration project, but submit it with your pull request. Please add a note to your pull request that provides a heads up that a migration file is present.

[bmurphy-dev]

Below are test examples using the page parameters is various ways with the date range results according to calendar year (US) tax filing needs versus select International tax filing needs that don't always align with the calendar year.

US CALENDAR BASED TEST CASES FOR ContributionStatementGenerator.ascx.cx USING StatementStartMonth and StatementEndMonth

A. no months given, StatementYear only 

	StatementYear of > Date Range Returned
	2023 	> 1/1/2023 - 12/31/2023
	2024 	> 1/1/2024 - 12/31/2024

All the following test cases have StatementYear = 2024

B. StatementStartMonth of > Date Range Returned 
	a 	> 1/1/2024 - 12/31/2024
	-1 	> 1/1/2024 - 12/31/2024
	0 	> 1/1/2024 - 12/31/2024
	1 	> 1/1/2024 - 1/31/2024
	10 	> 1/1/2024 - 10/31/2024
	12 	> 1/1/2024 - 12/31/2024
	13 	> 1/1/2024 - 12/31/2024

C. StatementEndMonth of > Date Range Returned 
	a 	> 1/1/2024 - 12/31/2024
	-1 	> 1/1/2024 - 12/31/2024
	0 	> 1/1/2024 - 12/31/2024
	1 	> 1/1/2024 - 1/31/2024
	10 	> 1/1/2024 - 10/31/2024
	12 	> 1/1/2024 - 12/31/2024
	13 	> 1/1/2024 - 12/31/2024

D. StatementStartMonth and StatementEndMonth of same, within year > Date Range Returned
	a - a 	> 1/1/2024 - 12/31/2024
	-1 - -1 > 1/1/2024 - 12/31/2024
	1 - 1 	> 1/1/2024 - 1/31/2024
	5 - 5 	> 5/1/2024 - 5/31/2024
	12 - 12 > 12/1/2024 - 12/31/2024
	13 - 13 > 1/1/2024 - 12/31/2024

E. StatementStartMonth and StatementEndMonth different, within year > Date Range Returned
	0 - 5 	> 1/1/2024 - 5/31/2024
	3 - 6 	> 3/1/2024 - 6/30/2024
	6 - 12 	> 6/1/2024 - 12/31/2024
	10 - 12 > 10/1/2024 - 12/31/2024
	10 - 13 > 10/1/2024 - 12/31/2024
	12 - 13 > 12/1/2024 - 12/31/2024
	13 - 13 > 1/1/2024 - 12/31/2024
	1 - 12 	> 1/1/2024 - 12/31/2024, normal condition 

F. StatementStartMonth after StatementEndMonth, i.e. start month is in prior year > Date Range Returned
	This is the case for NZ and Aus
	4 - 3 	> 4/1/2023 - 3/31/2024
	11 - 1 	> 11/1/2023 - 1/31/2024
	6 - 5 	> 6/1/2023 - 5/31/2024

INTERNATIONAL TEST CASES FOR ContributionStatementGenerator.ascx.cx USING StatementStartMonth and StatementEndMonth (note the date formatting mix based on locale as dd/MM/yy)

A. no months given, StatementYear only

	2023 > 1/1/23 - 31/12/23
	2024 > 1/1/24 - 31/12/24

All the following test cases have StatementYear = 2024

B. StatementStartMonth of > Date Range Returned
	 a 	> 1/1/24 - 31/12/24
	-1 	> 1/1/24 - 31/12/24
	0 	> 1/1/24 - 31/12/24
	1 	> 1/1/24 - 31/1/24
	10 	> 1/1/24 - 31/10/24
	12 	> 1/1/24 - 31/12/24
	13 	> 1/1/24 - 31/12/24

C. StatementEndMonth of > Date Range Returned
	a 	> 1/1/24 - 31/12/24
	-1 	> 1/1/24 - 31/12/24
	0 	> 1/1/24 - 31/12/24
	1 	> 1/1/24 - 31/1/24
	10 	> 1/1/24 - 31/10/24
	12 	> 1/1/24 - 31/12/24
	13 	> 1/1/24 - 31/12/24

D. StatementStartMonth and StatementEndMonth of same, within year > Date Range Returned
	a - a 	> 1/1/24 - 31/12/24
	-1 - -1 > 1/1/24 - 31/12/24
	1 - 1 	> 1/1/24 - 31/1/24
	5 - 5 	> 1/5/24 - 31/5/24
	12 - 12 > 1/12/24 - 31/12/24
	13 - 13 > 1/1/24 - 31/12/24

E. StatementStartMonth and StatementEndMonth different, within year > Date Range Returned
	0 - 5 	> 1/1/24 - 31/5/24
	3 - 6 	> 1/3/24 - 30/6/24
	6 - 12 	> 1/6/24 - 31/12/24
	10 - 12 > 1/10/24 - 31/12/24
	10 - 13 > 1/10/24 - 31/12/24
	12 - 13 > 1/12/24 - 31/12/24
	13 - 13 > 1/1/24 - 31/12/24
	1 - 12 - normal condition > 1/1/24 - 31/12/24

F. StatementStartMonth after StatementEndMonth, i.e. start month is in prior year > Date Range Returned
	This is the case for NZ and Aus
	4 - 3 	> 1/4/23 - 31/3/24
	11 - 1 	> 1/11/23 - 31/1/24
	6 - 5 	> 1/6/23 - 31/5/24