Skip to content

Commit 10dc96e

Browse files
marcoscaceresmarcoscaceres
authored
Add fine-grained errors reporting for PaymentAddress (#712)
1 parent 8257ef3 commit 10dc96e

File tree

1 file changed

+222
-16
lines changed

1 file changed

+222
-16
lines changed

‎index.html‎

Lines changed: 222 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -490,6 +490,39 @@ <h3>
490490
}
491491
</pre>
492492
</section>
493+
<section>
494+
<h3>
495+
Fine-grained error reporting
496+
</h3>
497+
<p>
498+
A developer can use the <a data-link-for=
499+
"PaymentDetailsUpdate">shippingAddressErrors</a> member of the
500+
<a>PaymentDetailsUpdate</a> dictionary to indicate that there are
501+
validation errors with specific attributes of a
502+
<a>PaymentAddress</a>. The <a data-link-for=
503+
"PaymentDetailsUpdate">shippingAddressErrors</a> member is a
504+
<a>AddressErrorFields</a> dictionary, whose members specifically
505+
demarcate the fields of a <a>physical address</a> that are erroneous
506+
while also providing helpful error messages to be displayed to the
507+
end user.
508+
</p>
509+
<pre class="example">
510+
request.onshippingaddresschange = ev =&gt; {
511+
ev.updateWith(validateAddress(request.shippingAddress));
512+
};
513+
function validateAddress(shippingAddress) {
514+
const error = "Can't ship to this address.";
515+
const shippingAddressErrors = {
516+
cityError: "FarmVille is not a real place.",
517+
postalCodeError: "Unknown postal code for your country.",
518+
};
519+
// Empty shippingOptions implies that we can't ship
520+
// to this address.
521+
const shippingOptions = [];
522+
return { error, shippingAddressErrors, shippingOptions };
523+
}
524+
</pre>
525+
</section>
493526
<section data-link-for="PaymentResponse">
494527
<h3>
495528
POSTing payment response back to a server
@@ -1713,6 +1746,7 @@ <h2>
17131746
dictionary PaymentDetailsUpdate : PaymentDetailsBase {
17141747
DOMString error;
17151748
PaymentItem total;
1749+
AddressErrorFields shippingAddressErrors;
17161750
};
17171751
</pre>
17181752
<p>
@@ -1756,6 +1790,14 @@ <h2>
17561790
"PaymentCurrencyAmount.value">value</a> is a negative number.
17571791
</p>
17581792
</dd>
1793+
<dt>
1794+
<dfn>shippingAddressErrors</dfn> member
1795+
</dt>
1796+
<dd>
1797+
Represents validation errors with the shipping address that is
1798+
associated with the <a data-cite="!DOM#event-target">event
1799+
target</a>.
1800+
</dd>
17591801
</dl>
17601802
</section>
17611803
</section>
@@ -2040,7 +2082,7 @@ <h2>
20402082
Physical addresses
20412083
</h2>
20422084
<p>
2043-
A <dfn>physical address</dfn> is composed of the following concepts.
2085+
A <dfn>physical address</dfn> is composed of the following parts.
20442086
</p>
20452087
<dl data-sort="">
20462088
<dt>
@@ -2704,6 +2746,154 @@ <h2>
27042746
</dd>
27052747
</dl>
27062748
</section>
2749+
<section data-dfn-for="AddressErrorFields" data-link-for=
2750+
"AddressErrorFields">
2751+
<h2>
2752+
<dfn>AddressErrorFields</dfn> dictionary
2753+
</h2>
2754+
<pre class="idl">
2755+
dictionary AddressErrorFields {
2756+
DOMString addressLineError;
2757+
DOMString cityError;
2758+
DOMString countryError;
2759+
DOMString dependentLocalityError;
2760+
DOMString languageCodeError;
2761+
DOMString organizationError;
2762+
DOMString phoneError;
2763+
DOMString postalCodeError;
2764+
DOMString recipientError;
2765+
DOMString regionError;
2766+
DOMString regionCodeError;
2767+
DOMString sortingCodeError;
2768+
};
2769+
</pre>
2770+
<p>
2771+
The members of the <a>AddressErrorFields</a> dictionary represent
2772+
validation errors with specific parts of a <a>physical address</a>.
2773+
Each dictionary member has a dual function: firstly, its presence
2774+
denotes that a particular part of an address is suffering from a
2775+
validation error. Secondly, the string value allows the developer to
2776+
describe the validation error (and possibly how the end user can fix
2777+
the error).
2778+
</p>
2779+
<p class="note">
2780+
Developers need to be aware that users might not have the ability to
2781+
fix certain parts of an address. As such, they need to be mindful to
2782+
not to ask the user to fix things they might not have control over
2783+
(e.g., <a>languageCodeError</a>).
2784+
</p>
2785+
<dl>
2786+
<dt>
2787+
<dfn>addressLineError</dfn> member
2788+
</dt>
2789+
<dd>
2790+
Denotes that the <a>address line</a> has a validation error. In the
2791+
user agent's UI, this member corresponds to the input field that
2792+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2793+
"PaymentAddress">addressLine</a> attribute's value.
2794+
</dd>
2795+
<dt>
2796+
<dfn>cityError</dfn> member
2797+
</dt>
2798+
<dd>
2799+
Denotes that the <a>city</a> has a validation error. In the user
2800+
agent's UI, this member corresponds to the input field that
2801+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2802+
"PaymentAddress">city</a> attribute's value.
2803+
</dd>
2804+
<dt>
2805+
<dfn>countryError</dfn> member
2806+
</dt>
2807+
<dd>
2808+
Denotes that the <a>country</a> has a validation error. In the user
2809+
agent's UI, this member corresponds to the input field that
2810+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2811+
"PaymentAddress">country</a> attribute's value.
2812+
</dd>
2813+
<dt>
2814+
<dfn>dependentLocalityError</dfn> member
2815+
</dt>
2816+
<dd>
2817+
Denotes that the <a>dependent locality</a> has a validation error.
2818+
In the user agent's UI, this member corresponds to the input field
2819+
that provided the <a>PaymentAddress</a>'s <a data-link-for=
2820+
"PaymentAddress">dependentLocality</a> attribute's value.
2821+
</dd>
2822+
<dt>
2823+
<dfn>languageCodeError</dfn> member
2824+
</dt>
2825+
<dd>
2826+
Denotes that the <a>language code</a> has a validation error. In
2827+
the user agent's UI, this member corresponds to the input field
2828+
that provided the <a>PaymentAddress</a>'s <a data-link-for=
2829+
"PaymentAddress">languageCode</a> attribute's value.
2830+
</dd>
2831+
<dt>
2832+
<dfn>organizationError</dfn> member
2833+
</dt>
2834+
<dd>
2835+
Denotes that the <a>organization</a> has a validation error. In the
2836+
user agent's UI, this member corresponds to the input field that
2837+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2838+
"PaymentAddress">organization</a> attribute's value.
2839+
</dd>
2840+
<dt>
2841+
<dfn>phoneError</dfn> member
2842+
</dt>
2843+
<dd>
2844+
Denotes that the <a>phone number</a> has a validation error. In the
2845+
user agent's UI, this member corresponds to the input field that
2846+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2847+
"PaymentAddress">phone</a> attribute's value.
2848+
</dd>
2849+
<dt>
2850+
<dfn>postalCodeError</dfn> member
2851+
</dt>
2852+
<dd>
2853+
Denotes that the <a>postal code</a> has a validation error. In the
2854+
user agent's UI, this member corresponds to the input field that
2855+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2856+
"PaymentAddress">postalCode</a> attribute's value.
2857+
</dd>
2858+
<dt>
2859+
<dfn>recipientError</dfn> member
2860+
</dt>
2861+
<dd>
2862+
Denotes that the <a>recipient</a> has a validation error. In the
2863+
user agent's UI, this member corresponds to the input field that
2864+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2865+
"PaymentAddress">addressLine</a> attribute's value.
2866+
</dd>
2867+
<dt>
2868+
<dfn>regionError</dfn> member
2869+
</dt>
2870+
<dd>
2871+
Denotes that the <a>region</a> has a validation error. In the user
2872+
agent's UI, this member corresponds to the input field that
2873+
provided the <a>PaymentAddress</a>'s <a data-link-for=
2874+
"PaymentAddress">region</a> attribute's value.
2875+
</dd>
2876+
<dt>
2877+
<dfn>regionCodeError</dfn> member
2878+
</dt>
2879+
<dd>
2880+
Denotes that the region code representation of the <a>region</a>
2881+
has a validation error. In the user agent's UI, this member
2882+
corresponds to the input field that provided the
2883+
<a>PaymentAddress</a>'s <a data-link-for=
2884+
"PaymentAddress">regionCode</a> attribute's value.
2885+
</dd>
2886+
<dt>
2887+
<dfn>sortingCodeError</dfn> member
2888+
</dt>
2889+
<dd>
2890+
The <a>sorting code</a> has a validation error. In the user agent's
2891+
UI, this member corresponds to the input field that provided the
2892+
<a>PaymentAddress</a>'s <a data-link-for=
2893+
"PaymentAddress">sortingCode</a> attribute's value.
2894+
</dd>
2895+
</dl>
2896+
</section>
27072897
<section>
27082898
<h2>
27092899
Creating a <code>PaymentAddress</code> from user-provided input
@@ -3914,21 +4104,37 @@ <h2>
39144104
</li>
39154105
</ol>
39164106
</li>
3917-
<li>If <var>request</var>.<a>[[\options]]</a>.<a data-lt=
3918-
"PaymentOptions.requestShipping">requestShipping</a> is true,
3919-
and
3920-
<var>request</var>.<a>[[\details]]</a>.<a>shippingOptions</a>
3921-
is empty, then the developer has signified that there are no
3922-
valid shipping options for the currently-chosen shipping
3923-
address (given by <var>request</var>'s <a data-lt=
3924-
"PaymentRequest.shippingAddress">shippingAddress</a>). In
3925-
this case, the user agent SHOULD display an error indicating
3926-
this, and MAY indicate that the currently-chosen shipping
3927-
address is invalid in some way. The user agent SHOULD use the
3928-
<a data-lt="PaymentDetailsUpdate.error">error</a> member of
3929-
<var>details</var>, if it is present, to give more
3930-
information about why there are no valid shipping options for
3931-
that address.
4107+
<li>
4108+
<p>
4109+
If <var>request</var>.<a>[[\options]]</a>.<a data-lt=
4110+
"PaymentOptions.requestShipping">requestShipping</a> is
4111+
true, and
4112+
<var>request</var>.<a>[[\details]]</a>.<a>shippingOptions</a>
4113+
is empty, then the developer has signified that there are
4114+
no valid shipping options for the currently-chosen
4115+
shipping address (given by <var>request</var>'s
4116+
<a data-lt=
4117+
"PaymentRequest.shippingAddress">shippingAddress</a>).
4118+
</p>
4119+
<p>
4120+
In this case, the user agent SHOULD display an error
4121+
indicating this, and MAY indicate that the
4122+
currently-chosen shipping address is invalid in some way.
4123+
The user agent SHOULD use the <a data-lt=
4124+
"PaymentDetailsUpdate.error">error</a> member of
4125+
<var>details</var>, if it is present, to give more
4126+
information about why there are no valid shipping options
4127+
for that address.
4128+
</p>
4129+
<p>
4130+
Further, if the <a data-lt=
4131+
"PaymentDetailsUpdate.shippingAddressErrors">shippingAddressErrors</a>
4132+
member is present, the user agent SHOULD display an error
4133+
specifically for each erroneous field of the shipping
4134+
address. This is done by matching each present member of
4135+
the <a>AddressErrorFields</a> to a corresponding input
4136+
field in the shown user interface.
4137+
</p>
39324138
</li>
39334139
</ol>
39344140
</li>

0 commit comments

Comments
 (0)