Fundraising tech/Form variants

In DonationInterface, one can alter the appearance or behavior of the payment forms by sending in a 'variant' querystring variable.

The variant is stored in session and so is 'sticky' - we need this so that variant behavior specified on the initial querystring from banners is applied all throughout the donation process, including when a donor returns from a payment processor. At that point the variant will no longer be on the querystring but we want it to continue affecting the form behavior, for example to show a post-payment request for the donor to add a monthly donation. This stickiness can make testing confusing. After using a variant, testers should either test in a fresh browser or incognito session, or clear payments-wiki cookies to ensure that they are seeing non-variant behavior.

Implementation details

The 'variant' mechanism allows replacement of any of the yaml files in a gateway's DonationInterface config subdirectory. Each variant corresponds to a subdirectory of the form_variants top-level directory. Under each variant subdirectory, there is a subdirectory for each payment processor whose forms can be altered by the variant. Yaml files in these subdirectories replace identically-named files in the processor's own config folder.

For example, under ingenico_gateway/config, the ui_modules.yaml file specifies a single ResourceLoader module to be loaded on all Ingenico payment forms:

scripts:
    - ext.donationInterface.ingenico-hosted

The 'employer' variant overrides that because a file named ui_modules.yaml exists in form_variants/employer/ingenico. It specifies both the standard Ingenico ResourceLoader module and an additional module. The standard module is specified because yaml files are entirely replaced rather than inherited and overridden (as happens in cascading SmashPig configuration).

scripts:
    - ext.donationInterface.ingenico-hosted
    - ext.donationInterface.employerAutoComplete

Tracking

Variants are tracked in the payment_form field of contribution_tracking. When a variant is in use, that field has the format "<gateway>.v=<variant>", for example "ingenico.v=employer"

Configuration variable

TODO

Commonly-replaced yaml files

TODO explain what you can do with each

message_replacements.yaml
country_fields.yaml

Variants

Employer

variant=employer

This displays a text field where the donor can type in their employer's name. Employer data is pulled from a csv [where is it]