Skip to content

Commit 66c6dda

Browse files
wix-docs-fedsroysha-wix
wix-docs-feds
and
roysha-wix
authored
new ecom-frontend module
changes: Service wix-ecom-frontend is new Co-authored-by: roysha-wix <[email protected]>
1 parent 678cc98 commit 66c6dda

File tree

1 file changed

+386
-0
lines changed

1 file changed

+386
-0
lines changed

‎wix-ecom-frontend/wix-ecom-frontend.service.json

Lines changed: 386 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,386 @@
1+
{ "name": "wix-ecom-frontend",
2+
"mixes": [],
3+
"labels":
4+
[ "new" ],
5+
"location":
6+
{ "lineno": 1,
7+
"filename": "wixEcomFrontend.js" },
8+
"docs":
9+
{ "summary": "The `wix-ecom-frontend` module contains functionality for working with eCommerce elements from client-side code.",
10+
"description":
11+
[ "Using the eCommerce frontend API, you can interact with the native cart and checkout components on your site.",
12+
"",
13+
" With the eCommerce frontend API, you can:",
14+
" + Refresh the cart to display its latest state.",
15+
" + Listen to changes in the native cart components.",
16+
" + Open the Side Cart panel.",
17+
" + Navigate to the [Cart Page](https://support.wix.com/en/article/customizing-the-cart-page).",
18+
" + Navigate to the [Checkout Page](https://support.wix.com/en/article/customizing-the-checkout-page).",
19+
"",
20+
" To use the eCommerce frontend API, import `wixEcomFrontend` from the `wix-ecom-frontend` module:",
21+
"",
22+
" ```javascript",
23+
" import wixEcomFrontend from 'wix-ecom-frontend';",
24+
" ```",
25+
"",
26+
" ## Before you begin",
27+
"",
28+
" It's important to note the following points before starting to code:",
29+
"",
30+
" + You need to [add eCommerce functionality to your site](https://dev.wix.com/docs/rest/business-solutions/e-commerce/wix-e-commerce-platform-handbook/get-started/wix-site-creators-velo-developers-add-e-commerce-functionality-to-a-site).",
31+
"",
32+
" + Upgrade your site to a premium business plan in order to [accept payments](https://support.wix.com/en/article/accepting-payments-an-overview).",
33+
"",
34+
" ## Terminology",
35+
"",
36+
" + **Cart**: Holds information about a potential transaction, including details about selected items, prices, and discounts, as well as the potential buyer.",
37+
" + **Side Cart**: A preview of the cart page, which opens as a panel on the side of a page.",
38+
" + **Cart Page**: A page where a buyer can view and manage the items in their cart.",
39+
" + **Checkout Page**: A page where a buyer finalizes a purchase. Each checkout holds information about the items to be purchased, price and tax summaries, shipping and billing information, any applied discounts, and more." ],
40+
"links": [],
41+
"examples": [],
42+
"extra":
43+
{ } },
44+
"properties": [],
45+
"operations":
46+
[ { "name": "navigateToCartPage",
47+
"labels": [],
48+
"nameParams": [],
49+
"params": [],
50+
"ret":
51+
{ "type":
52+
{ "name": "Promise",
53+
"typeParams":
54+
[ "void" ] },
55+
"doc": "Fulfilled - When the navigation is complete." },
56+
"locations":
57+
[ { "lineno": 70,
58+
"filename": "wixEcomFrontend.js" } ],
59+
"docs":
60+
{ "summary": "Directs the browser to navigate to the site visitor's Cart Page.",
61+
"description":
62+
[ "The `navigateToCartPage()` function returns a Promise that resolves when the browser successfully navigates to the [Cart Page](https://support.wix.com/en/article/customizing-the-cart-page)." ],
63+
"links": [],
64+
"examples":
65+
[ { "title": "Navigate to the cart page",
66+
"body":
67+
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
68+
"import wixEcomBackend from 'wix-ecom-backend';",
69+
"",
70+
"$w('#myNavigateToCartPageButton').onClick(() => {",
71+
"",
72+
" // example values for the options object",
73+
" const options = {",
74+
" lineItems: [{",
75+
" catalogReference: {",
76+
" // Wix Stores appId",
77+
" appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e',",
78+
" // Wix Stores productId",
79+
" catalogItemId: '3fb6a3c8-988b-8755-04bd-5c59ae0b18ea',",
80+
" },",
81+
" quantity: 1",
82+
" }]",
83+
" };",
84+
"",
85+
" // add item to cart and navigate to cart page",
86+
" wixEcomBackend.currentCart.addToCurrentCart(options)",
87+
" .then(() => {",
88+
" console.log('item added to cart');",
89+
" // navigate to cart page after adding item",
90+
" wixEcomFrontend.navigateToCartPage();",
91+
" })",
92+
" .catch((error) => {",
93+
" console.error(error);",
94+
" // Handle the error",
95+
" });",
96+
"});" ],
97+
"extra":
98+
{ } } ],
99+
"extra":
100+
{ } },
101+
"extra":
102+
{ } },
103+
{ "name": "navigateToCheckoutPage",
104+
"labels": [],
105+
"nameParams": [],
106+
"params":
107+
[ { "name": "checkoutId",
108+
"type": "string",
109+
"doc": "ID of the checkout to navigate to." },
110+
{ "name": "options",
111+
"type": "wix-ecom-frontend.CheckoutPageOptions",
112+
"doc": "Additional parameters for customizing the checkout flow.",
113+
"optional": true } ],
114+
"ret":
115+
{ "type":
116+
{ "name": "Promise",
117+
"typeParams":
118+
[ "void" ] },
119+
"doc": "Fulfilled - When the navigation is complete." },
120+
"locations":
121+
[ { "lineno": 82,
122+
"filename": "wixEcomFrontend.js" } ],
123+
"docs":
124+
{ "summary": "Directs the browser to navigate to the site visitor's Checkout Page.",
125+
"description":
126+
[ "The `navigateToCheckoutPage()` function returns a Promise that resolves when the browser successfully navigates to the [Checkout Page](https://support.wix.com/en/article/customizing-the-checkout-page).",
127+
"",
128+
"> **Note:** The `checkoutId` parameter is **required**. To get a `checkoutId`, use one of the following `wix-ecom-backend` functions:",
129+
"> + [`createCheckoutFromCurrentCart()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-backend/current-cart/create-checkout-from-current-cart)",
130+
"> + [`cart.createCheckout()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-backend/cart/create-checkout)",
131+
"> + [`checkout.createCheckout()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-backend/checkout/create-checkout)" ],
132+
"links": [],
133+
"examples":
134+
[ { "title": "Navigate to the checkout page",
135+
"body":
136+
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
137+
"",
138+
"$w('#myNavigateToCheckoutPageButton').onClick(() => {",
139+
"",
140+
" // Example checkoutId and options values",
141+
" const checkoutId = '12345678-1234-1234-1234-1234567890ab';",
142+
" const options = {",
143+
" skipDeliveryStep: true,",
144+
" hideContinueBrowsingButton: false,",
145+
" overrideContinueBrowsingUrl: 'https://www.myExampleSite.com/upsellPage',",
146+
" // override ThankYouPage URL with dynamic orderId parameter",
147+
" overrideThankYouPageUrl: 'https://www.myExampleSite.com/customThankYouPage/{orderId}'",
148+
" };",
149+
"",
150+
" wixEcomFrontend.navigateToCheckoutPage(checkoutId, options)",
151+
" .then(() => {",
152+
" console.log('Navigated successfully');",
153+
" })",
154+
" .catch((error) => {",
155+
" console.error(error);",
156+
" // Handle the error",
157+
" });",
158+
"});" ],
159+
"extra":
160+
{ } } ],
161+
"extra":
162+
{ } },
163+
"extra":
164+
{ } },
165+
{ "name": "onCartChange",
166+
"labels": [],
167+
"nameParams": [],
168+
"params":
169+
[ { "name": "handler",
170+
"type": "wix-ecom-frontend.onCartChangeHandler",
171+
"doc": "The name of the function or the function expression to run when the cart is changed." } ],
172+
"ret":
173+
{ "type": "void" },
174+
"locations":
175+
[ { "lineno": 120,
176+
"filename": "wixEcomFrontend.js" } ],
177+
"docs":
178+
{ "summary": "Adds an event handler that runs when the cart changes.",
179+
"description":
180+
[ "The event handler set by the `onCartChange()` function runs when the cart changes.",
181+
"",
182+
"The `onCartChange()` event handler is triggered when:",
183+
"+ The cart is modified by native UI elements such as the 'Add to Cart' button, increase (+) and decrease (-) item quantity buttons, remove line item button (x), etc.",
184+
"+ The [`refreshCart()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-frontend/refresh-cart) function is called.",
185+
"",
186+
"<blockquote class=\"important\">",
187+
"",
188+
"**Important:** Actions performed by Velo functions other than the `refreshCart()` function do not trigger the `onCartChange()` event handler.",
189+
"",
190+
"</blockquote>" ],
191+
"links": [],
192+
"examples":
193+
[ { "title": "Add an event handler for cart changes",
194+
"body":
195+
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
196+
"import wixEcomBackend from 'wix-ecom-backend';",
197+
"",
198+
"$w.onReady(function () {",
199+
"",
200+
" // handler function that gets the current cart on cart change",
201+
" const handler = () => {",
202+
" wixEcomBackend.currentCart.getCurrentCart()",
203+
" .then(cart => {",
204+
" let cartId = cart._id;",
205+
" console.log('cart ID: ', cartId);",
206+
" })",
207+
" .catch(error => {",
208+
" console.error(error);",
209+
" // Handle the error",
210+
" });",
211+
" };",
212+
"",
213+
" wixEcomFrontend.onCartChange(handler);",
214+
"});" ],
215+
"extra":
216+
{ } } ],
217+
"extra":
218+
{ } },
219+
"extra":
220+
{ } },
221+
{ "name": "openSideCart",
222+
"labels": [],
223+
"nameParams": [],
224+
"params": [],
225+
"ret":
226+
{ "type": "void" },
227+
"locations":
228+
[ { "lineno": 54,
229+
"filename": "wixEcomFrontend.js" } ],
230+
"docs":
231+
{ "summary": "Opens the Side Cart panel.",
232+
"description":
233+
[ "The `openSideCart()` function opens the Side Cart panel on the current page.",
234+
"",
235+
"> **Notes:**",
236+
"> + We are gradually replacing the existing [Mini Cart](https://support.wix.com/en/article/customizing-the-mini-cart) with the new Side Cart panel.",
237+
"> + This function will fail when viewing the site on mobile because there is no Mini Cart on the mobile site.",
238+
"> + The new Side Cart works on mobile sites. When Side Cart functionality becomes available for your site, `openSideCart()` will work on mobile." ],
239+
"links": [],
240+
"examples":
241+
[ { "title": "Open the Side Cart",
242+
"body":
243+
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
244+
"",
245+
"$w('#myOpenSideCartButton').onClick(() => {",
246+
" // on button click - open the side cart",
247+
" wixEcomFrontend.openSideCart();",
248+
"});" ],
249+
"extra":
250+
{ } } ],
251+
"extra":
252+
{ } },
253+
"extra":
254+
{ } },
255+
{ "name": "refreshCart",
256+
"labels": [],
257+
"nameParams": [],
258+
"params": [],
259+
"ret":
260+
{ "type":
261+
{ "name": "Promise",
262+
"typeParams":
263+
[ "void" ] },
264+
"doc": "Fulfilled - When the cart refresh is complete." },
265+
"locations":
266+
[ { "lineno": 40,
267+
"filename": "wixEcomFrontend.js" } ],
268+
"docs":
269+
{ "summary": "Updates cart UI elements, like the [Cart Icon](https://support.wix.com/en/article/customizing-the-cart-icon) and Side Cart with the most recent cart data.",
270+
"description":
271+
[ "The `refreshCart()` function returns a Promise that resolves when the latest cart data is retrieved, and the cart UI elements are refreshed.",
272+
"",
273+
"> **Note:** Calling the `refreshCart()` function will trigger the [`onCartChange()`](/wix-ecom-frontend/on-cart-change) event handler." ],
274+
"links": [],
275+
"examples":
276+
[ { "title": "Refresh the cart",
277+
"body":
278+
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
279+
"import wixEcomBackend from 'wix-ecom-backend';",
280+
"",
281+
"$w('#myAddAndRefreshCartButton').onClick(() => {",
282+
"",
283+
" // example values for the options object",
284+
" const options = {",
285+
" lineItems: [{",
286+
" catalogReference: {",
287+
" // Wix Stores appId",
288+
" appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e',",
289+
" // Wix Stores productId",
290+
" catalogItemId: '3fb6a3c8-988b-8755-04bd-5c59ae0b18ea',",
291+
" },",
292+
" quantity: 1",
293+
" }]",
294+
" };",
295+
"",
296+
" wixEcomBackend.currentCart.addToCurrentCart(options)",
297+
" .then(() => {",
298+
" console.log('item added to cart');",
299+
" // refresh the cart after adding item",
300+
" wixEcomFrontend.refreshCart();",
301+
" })",
302+
" .catch((error) => {",
303+
" console.error(error);",
304+
" // Handle the error",
305+
" });",
306+
"});" ],
307+
"extra":
308+
{ } } ],
309+
"extra":
310+
{ } },
311+
"extra":
312+
{ } } ],
313+
"callbacks":
314+
[ { "name": "onCartChangeHandler",
315+
"labels": [],
316+
"nameParams": [],
317+
"params": [],
318+
"ret":
319+
{ "type": "void" },
320+
"locations":
321+
[ { "lineno": 141,
322+
"filename": "wixEcomFrontend.js" } ],
323+
"docs":
324+
{ "summary": "Function that runs when a cart changes.",
325+
"links": [],
326+
"examples": [],
327+
"extra":
328+
{ } },
329+
"extra":
330+
{ } } ],
331+
"messages":
332+
[ { "name": "CheckoutPageOptions",
333+
"locations":
334+
[ { "lineno": 103,
335+
"filename": "wixEcomFrontend.js" } ],
336+
"docs":
337+
{ "links": [],
338+
"examples":
339+
[ { "title": "Navigate to the checkout page",
340+
"body":
341+
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
342+
"",
343+
"$w('#myNavigateToCheckoutPageButton').onClick(() => {",
344+
"",
345+
" // Example checkoutId and options values",
346+
" const checkoutId = '12345678-1234-1234-1234-1234567890ab';",
347+
" const options = {",
348+
" skipDeliveryStep: true,",
349+
" hideContinueBrowsingButton: false,",
350+
" overrideContinueBrowsingUrl: 'https://www.myExampleSite.com/upsellPage',",
351+
" // override ThankYouPage URL with dynamic orderId parameter",
352+
" overrideThankYouPageUrl: 'https://www.myExampleSite.com/customThankYouPage/{orderId}'",
353+
" };",
354+
"",
355+
" wixEcomFrontend.navigateToCheckoutPage(checkoutId, options)",
356+
" .then(() => {",
357+
" console.log('Navigated successfully');",
358+
" })",
359+
" .catch((error) => {",
360+
" console.error(error);",
361+
" // Handle the error",
362+
" });",
363+
"});" ],
364+
"extra":
365+
{ } } ],
366+
"extra":
367+
{ } },
368+
"members":
369+
[ { "name": "skipDeliveryStep",
370+
"type": "boolean",
371+
"doc": "Whether to skip the delivery details step in checkout. For example, if the product is for pick-up only.\n\nDefault: `false`" },
372+
{ "name": "hideContinueBrowsingButton",
373+
"type": "boolean",
374+
"doc": "Whether to hide the [\"Continue Browsing\"](https://support.wix.com/en/article/customizing-links-on-your-cart-page#customizing-the-continue-browsing-links) button from top-right-hand corner of the Checkout Page.\n\nDefault: `false`" },
375+
{ "name": "overrideContinueBrowsingUrl",
376+
"type": "string",
377+
"doc": "URL to replace the default \"Continue Browsing\" URL. For example, if you'd like to redirect the customer to your own custom page." },
378+
{ "name": "overrideThankYouPageUrl",
379+
"type": "string",
380+
"doc": "URL to replace the default [Thank You Page](https://support.wix.com/en/article/customizing-the-thank-you-page) URL.\n\nPass `{orderId}` (not the order ID itself) as a parameter to the URL to dynamically insert the order ID. See the example on the right for more information." } ],
381+
"extra":
382+
{ },
383+
"labels": [] } ],
384+
"extra":
385+
{ "scopes":
386+
[ "frontend" ] } }

0 commit comments

Comments
 (0)