Overview
Offer templates are always the first screen shown during checkout. System templates are used for the remainder of the checkout process. You can create an unlimited number of offer templates, but you will only create a single system template of each type. You're free to make as many alterations as you like to offer templates, but we recommend that you only alter the text and CSS of system templates because many of the code blocks within these system templates are essential to the proper functioning of the Subscription Management + Billing checkout process. Extensive modifications to system templates should be done in consultation with your Piano implementation team.
System Template Types
Default Offer: The default offer template is shown as the first screen during checkout if you trigger an offer without an offer template. So if you were using JavaScript to show an offer and failed to pass a templateId to tp.offer.show the default offer template would be used. See here for a complete breakdown of the default offer template.
Term Components: If you don't make the terms of your offer visible within an offer template, this system template will allow you to display those terms on the second screen of the checkout process. If the checkout flow features an offer template with information about term prices and length of access (examples: $19.99/year, 6.95/month, day pass for registration, etc), the Term Components screen won't come into effect. But if there's simply a "subscribe" or "register" button in the offer template, clicking that button would activate the Term Components screen. Within the "Checkout" system template Term Components is part of the <div view="state1">...</div> section. Term Components is inserted into that section of the "Checkout" system template through use of the <div term-selector-component></div> directive.
Already has access: This screen will display if users click on a term where they already have access to the resource associated with that term (or if they view an offer only including resources they already own). The "Already has access" screen includes a "renew now" button that displays if a customer already has access through a manually renewing subscription that is eligible for renewal.
Checkout: This system template is the backbone of the checkout process. It contains most of the logic of the checkout flow and several other system templates are embedded within it. There are two primary states with the Checkout template: state1 and state2. State1, as mentioned previously, is used with the Term Components screen. State2 is activated when a user clicks on a term. This term can be clicked on either from an offer template or from the Term Components screen. Some of elements included in state2:
-
business-logo: The logo added to Edit Business. Used in conjunction with a header component that can be customized using the "Checkout Components" system template. -
selectedTerm.resource.name: The resource name specified when the resource being converted on was created. -
input.chargeDisplayAmount: The charge amount. In case of free trials, this price differs from the default value shown on the offer template or Term Components screen. -
promo-code-component: Displayed if the term supports promotions that provide a discount. -
pay-what-you-want-form-component: Displayed if “Allow users to pay more” was enabled when payment term was configured. This component and promo code component are mutually exclusive because promotions and pay-what-you-want functionality cannot be used together. -
tariff-plan: Contains the rate plan for current term (i.e. start date, access duration, billing schedule). This component is not displayed with pay-what-you-want terms but contains information about changes in billing plan caused by applied promotions. It also includes tax and VAT information, if enabled. Taxes and VAT calculations should be set up with the assistance of your Piano representative. -
auth-component: This component is enabled if you're using Identity Management and “Checkout authentication in separate state” is disabled (meaning that registration and credit card input are handled on a single screen rather than two). Disabling "checkout authentication in separate state" will require the assistance of your Piano representative. -
payment-form-component: Billing country selector and all the available payment methods are displayed here (credit cards, Paypal, etc).
After the "state1" and "state2" code, the "Checkout" system template includes code for a number of "views" that come into effect only under particular circumstances. Those views include:
-
<div view="alreadyHasAccess">: Displays the "already has access"system template. -
<div view="auth">: Enabled if you're using Identity Management and “Checkout authentication in separate state” is enabled. This means that registration and credit card input are handled on a two screens rather than one (user must login/register before checking out). -
<div view="lockedPromoCode">: Enabled for payment terms that need to be unlocked in order for the user to access the term. On this screen user will be prompted to enter promo code in order to continue checkout. -
After clicking on a term that requires a promo code to be unlocked, a user will see this component.
-
<div view="externalVerification">: Seen for external verification terms, such as a print subscription confirmations. -
<div view="printAddress">: Displays the "print address collect screen" system template. Shown if you are collecting print address information as part of checkout. -
<div view="confirmation">: Displays the "Confirmation screen" system template. -
<div view="giftParams">: Displays the "Gift components" system template if gifting is enabled and a gift giver clicks to purchase on a gift term. -
<div view="redemption">: Displays the "redemption components" system template when a gift receiver clicks a “redeem” button. The gift receiver then enters a gift voucher code in order to redeem the gift.
Checkout Components: This system template contains basic checkout components, such as buttons, headers, and error messages. The included components:
-
previous-button-component: Back button. Returns user to previous screen. -
close-button-component: Close button. Closes modal template. -
complete-purchase-button-component: Complete purchase button. If taxes are not enabled on the application (and a confirmation step is therefore not required) this button is displayed on the purchase screen. Clicking it completes the purchase and takes the user to the receipt screen. -
goto-confirmation-component: Confirm purchase button. If taxes are enabled, this button is displayed on purchase screen. When it is clicked the user is taken a confirmation screen where they see the full price they are being charged (with taxes added to payment price) prior to payment . -
error-list-component: Error messages that can appear during checkout process (card validation error, server error, etc). -
account-header-component: The header at the top of checkout screens. Can contain the language selector (if localization is enabled and more than one language is configured) along with login/logout buttons and the user's name/email. -
purchase-receipt-component: Contains the wording that is visible on the receipt template which is shown to user after they've completed checkout. -
scroll-modal-to-component: "Scroll to" button for modals. "Back to top" can be implemented as<a href="#" scroll-modal-to x="0">Back to top</a>.
Checkout Style: This is the global CSS used for all system templates except for the Default Offer system templates, which have their own CSS. This templates allows you to control the style of any element in any system template, with the exception of Default Offer system templates.
Payment Components: For payable terms, this system template is inserted into the "Checkout" system template's "state2." The included components:
-
payment-form-component: This component is displayed if payment of any type is required and the user needs to select a payment method. It will not be displayed if no payment provider is configured. If there is more than one payment method available, the user will be able to select from the available options. The component includes:-
<div consents-list>: Displays any configured consent fields. -
<div mock-form-component>: Mock payment providers that can be used for testing in Sandbox. -
<div paypal-through-braintree-form-component>: Paypal account component. User can add paypal account information into this component. That account information will then be stored for future purchases. -
<div worldpay-rxml-form-component>and<div worldpay-hpp-form-component>: Worldpay integration components. -
<div worldpay-token-form-component>: Tokenized version of the Worldpay integration. -
<div spreedly-form-component>: Credit card component for Spreedly and Spreedly-integrated providers (currently Stripe). -
<div edgil-payway-provider-form-component>: Edgil credit card component. -
<div zero-form-component>: Applied in case of a 100-percent-off promo code applied to one-off term (which doesn't require payment).
-
-
<div cc-form-component>: Credit card fields. If the user has a stored card, that card will be displayed as the primary payment method by default. -
payment-method-selector-component: This component is embedded within the<-- payment-form-component -->so that users can select a payment method. -
billing-country: Component includes information about the user's country. This component is related to tax and VAT calculations. A user's country will be automatically detected during checkout, but they are given the the ability to change the billing country if that information is incorrect. With US or Canadian taxes, the user is required to input a zip code in order to taxes to be calculated. -
pay-what-you-want-form-component: The logic of the pay-what-you-want component. Available methods for this section are described in comments in the code.
Provider Components: Code from this system template is inserted into the "payment components" system template. This is the configuration code for selected payment providers (Braintree, Stripe, GoCardless, etc.) and payment methods (Paypal, Credit Card, etc.). Because this system template needs to communicate with various payment providers, we don't recommend making extensive changes to it.
Print address collect screen: This screen is used to collect a print address from a customer. Print address collection can be enabled on a payment term and will be required before purchase is completed.
It is not possible to add custom fields to the "Print address collect screen" template, which is the one that handles the address collection. In case that you want to add custom fields to the Checkout, you can create a form with all of the custom fields that you need to collect, and then add this form to the "Checkout form" option that is available under your "Show offer" card in Composer.
Promotion Components: Includes a field where users input promo codes, along with buttons to apply or remove the promo code. The <!-- promo code another term dialog --> component is enabled if a user tries to input a promo code for a different term than the one selected. In that case, the user will be prompted to select the term using that promotion.
Note that by default, system error message wordings cannot be changed as they are the same across all clients.
But if you'd like to have a generic error message shown instead, you can add the below JavaScript to the end of the Promotion Components template.
<custom-script>
var timer = setInterval(function(){
if(document.querySelector("#view-state2 .promo-code-input-wrapper .field-error") != null) {
clearInterval(timer);
document.querySelector("#view-state2 .promo-code-input-wrapper .field-error").innerHTML = "A different error message!";
}
}, 20);
</custom-script>
Where you would insert your own custom copy instead of the text A different error message!.
The variable isSelectedTermLocked returns a true value in case that the selected term from the offer is locked by a promotion.
The classes promo-code-input-locked and promo-code-input serve to differentiate the div elements associated with promotions that are locked and unlocked, respectively. Our system utilizes these distinct classes to apply specific CSS styling to these elements based on the particular promotion scenario. The ng-click="inputClick()" directive is implemented to provide a visual feedback, specifically a subtle "click" animation, when a user hovers their mouse cursor over the input element. This enhances the user interface by providing interactive cues.
Redemption components: These components are used by gift receivers when redeeming gifts. See here for more information on gifting offers.
Gift components: These components are used by gift givers when checking out. See here for more information on gifting offers.
Confirmation screen: This screen is only shown if tax is being applied on top of the displayed payment price. In such a case, after customers input payment information, this screen shows them the full price they will be charged before the payment goes through. After clicking the "complete purchase" button on this screen, the receipt screen will be shown to the user.
Consent components: This template is used to display any consent fields you've set up in Subscription Management + Billing. See here for more information on consents.
Custom login/register: This template was created for a client with a custom user integration. Unless your Piano representative tells you otherwise, you can ignore this template.
External verification components: Contains components used to input external verification data for external terms.
Receipt: The receipt screen is shown once checkout is complete. You can customize receipts on a per term basis, but there is not currently a default receipt configured for registration terms. The standard payment term receipt is used instead.
Error screen: This error screen displays if anything goes wrong during checkout.