woocommerce/woocommerce-paypal-payments
2
0
Fork 0
mirror of https://github.com/woocommerce/woocommerce-paypal-payments.git synced 2025-09-05 08:59:14 +08:00
Code Issues Projects Packages Wiki Activity Actions 7

💡 Improve comments in PayerData module

Browse source
This commit is contained in:
Philipp Stracker 2024-08-20 14:18:30 +02:00
parent 63b5055903
commit a51748f805
No known key found for this signature in database
1 changed files with 29 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

49
modules/ppcp-button/resources/js/modules/Helper/PayerData.js
View file

@ -10,30 +10,30 @@
* Postal address details. * Postal address details.
* *
* @typedef {Object} AddressDetails * @typedef {Object} AddressDetails
* @property {?string} country_code - Country code (2-letter). * @property {undefined|string} country_code - Country code (2-letter).
* @property {?string} address_line_1 - Address details, line 1 (street, house number). * @property {undefined|string} address_line_1 - Address details, line 1 (street, house number).
* @property {?string} address_line_2 - Address details, line 2. * @property {undefined|string} address_line_2 - Address details, line 2.
* @property {?string} admin_area_1 - State or region. * @property {undefined|string} admin_area_1 - State or region.
* @property {?string} admin_area_2 - State or region. * @property {undefined|string} admin_area_2 - State or region.
* @property {?string} postal_code - Zip code. * @property {undefined|string} postal_code - Zip code.
*/ */
/** /**
* Phone details. * Phone details.
* *
* @typedef {Object} PhoneDetails * @typedef {Object} PhoneDetails
* @property {?string} phone_type - Type, usually 'HOME' * @property {undefined|string} phone_type - Type, usually 'HOME'
* @property {?{national_number: string}} phone_number - Phone number details. * @property {undefined|{national_number: string}} phone_number - Phone number details.
*/ */
/** /**
* Payer details. * Payer details.
* *
* @typedef {Object} PayerDetails * @typedef {Object} PayerDetails
* @property {?string} email_address - Email address for billing communication. * @property {undefined|string} email_address - Email address for billing communication.
* @property {?PhoneDetails} phone - Phone number for billing communication. * @property {undefined|PhoneDetails} phone - Phone number for billing communication.
* @property {?NameDetails} name - Payer's name. * @property {undefined|NameDetails} name - Payer's name.
* @property {?AddressDetails} address - Postal billing address. * @property {undefined|AddressDetails} address - Postal billing address.
*/ */
// Map checkout fields to PayerData object properties. // Map checkout fields to PayerData object properties.
@ -55,7 +55,14 @@ const FIELD_MAP = {
* *
* @return {?PayerDetails} Full billing details, or null on failure. * @return {?PayerDetails} Full billing details, or null on failure.
*/ */
export const payerData = () => { export function payerData() {
/**
* PayPalCommerceGateway.payer can be set from server-side or via JS:
* - Server-side: Set by PHP when a WC customer is known.
* - Dynamic JS: When a payment method provided billing data.
*
* @see {setPayerData}
*/
const payer = window.PayPalCommerceGateway?.payer; const payer = window.PayPalCommerceGateway?.payer;
if ( ! payer ) { if ( ! payer ) {
return null; return null;
@ -104,18 +111,20 @@ export const payerData = () => {
} }
return data; return data;
}; }
/** /**
* Updates the DOM with specific payer details. * Updates the DOM with specific payer details.
* *
* Used by payment method callbacks that provide dedicated billing details, like Google Pay.
* Note: This code only works on classic checkout
*
* @param {PayerDetails} newData - New payer details. * @param {PayerDetails} newData - New payer details.
* @param {boolean} [overwriteExisting=false] - If set to true, all provided values will replace existing details. If false, or omitted, only undefined fields are updated. * @param {boolean} [overwriteExisting=false] - If set to true, all provided values will
* replace existing details. If false, or omitted,
* only undefined fields are updated.
*/ */
export const setPayerData = ( newData, overwriteExisting = false ) => { export function setPayerData( newData, overwriteExisting = false ) {
// TODO: Check if we can add some kind of "filter" to allow customization of the data.
// Or add JS flags like "onlyUpdateMissing".
const setValue = ( path, field, value ) => { const setValue = ( path, field, value ) => {
if ( null === value || undefined === value || ! field ) { if ( null === value || undefined === value || ! field ) {
return; return;
@ -136,4 +145,4 @@ export const setPayerData = ( newData, overwriteExisting = false ) => {
setValue( path, element, value ); setValue( path, element, value );
} ); } );
}; }