Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

new ecom-frontend module #3067

Merged
merged 1 commit into from
Jul 29, 2024
Merged

new ecom-frontend module #3067

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
386 changes: 386 additions & 0 deletions wix-ecom-frontend/wix-ecom-frontend.service.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,386 @@
{ "name": "wix-ecom-frontend",
"mixes": [],
"labels":
[ "new" ],
"location":
{ "lineno": 1,
"filename": "wixEcomFrontend.js" },
"docs":
{ "summary": "The `wix-ecom-frontend` module contains functionality for working with eCommerce elements from client-side code.",
"description":
[ "Using the eCommerce frontend API, you can interact with the native cart and checkout components on your site.",
"",
" With the eCommerce frontend API, you can:",
" + Refresh the cart to display its latest state.",
" + Listen to changes in the native cart components.",
" + Open the Side Cart panel.",
" + Navigate to the [Cart Page](https://support.wix.com/en/article/customizing-the-cart-page).",
" + Navigate to the [Checkout Page](https://support.wix.com/en/article/customizing-the-checkout-page).",
"",
" To use the eCommerce frontend API, import `wixEcomFrontend` from the `wix-ecom-frontend` module:",
"",
" ```javascript",
" import wixEcomFrontend from 'wix-ecom-frontend';",
" ```",
"",
" ## Before you begin",
"",
" It's important to note the following points before starting to code:",
"",
" + 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).",
"",
" + Upgrade your site to a premium business plan in order to [accept payments](https://support.wix.com/en/article/accepting-payments-an-overview).",
"",
" ## Terminology",
"",
" + **Cart**: Holds information about a potential transaction, including details about selected items, prices, and discounts, as well as the potential buyer.",
" + **Side Cart**: A preview of the cart page, which opens as a panel on the side of a page.",
" + **Cart Page**: A page where a buyer can view and manage the items in their cart.",
" + **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." ],
"links": [],
"examples": [],
"extra":
{ } },
"properties": [],
"operations":
[ { "name": "navigateToCartPage",
"labels": [],
"nameParams": [],
"params": [],
"ret":
{ "type":
{ "name": "Promise",
"typeParams":
[ "void" ] },
"doc": "Fulfilled - When the navigation is complete." },
"locations":
[ { "lineno": 70,
"filename": "wixEcomFrontend.js" } ],
"docs":
{ "summary": "Directs the browser to navigate to the site visitor's Cart Page.",
"description":
[ "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)." ],
"links": [],
"examples":
[ { "title": "Navigate to the cart page",
"body":
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
"import wixEcomBackend from 'wix-ecom-backend';",
"",
"$w('#myNavigateToCartPageButton').onClick(() => {",
"",
" // example values for the options object",
" const options = {",
" lineItems: [{",
" catalogReference: {",
" // Wix Stores appId",
" appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e',",
" // Wix Stores productId",
" catalogItemId: '3fb6a3c8-988b-8755-04bd-5c59ae0b18ea',",
" },",
" quantity: 1",
" }]",
" };",
"",
" // add item to cart and navigate to cart page",
" wixEcomBackend.currentCart.addToCurrentCart(options)",
" .then(() => {",
" console.log('item added to cart');",
" // navigate to cart page after adding item",
" wixEcomFrontend.navigateToCartPage();",
" })",
" .catch((error) => {",
" console.error(error);",
" // Handle the error",
" });",
"});" ],
"extra":
{ } } ],
"extra":
{ } },
"extra":
{ } },
{ "name": "navigateToCheckoutPage",
"labels": [],
"nameParams": [],
"params":
[ { "name": "checkoutId",
"type": "string",
"doc": "ID of the checkout to navigate to." },
{ "name": "options",
"type": "wix-ecom-frontend.CheckoutPageOptions",
"doc": "Additional parameters for customizing the checkout flow.",
"optional": true } ],
"ret":
{ "type":
{ "name": "Promise",
"typeParams":
[ "void" ] },
"doc": "Fulfilled - When the navigation is complete." },
"locations":
[ { "lineno": 82,
"filename": "wixEcomFrontend.js" } ],
"docs":
{ "summary": "Directs the browser to navigate to the site visitor's Checkout Page.",
"description":
[ "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).",
"",
"> **Note:** The `checkoutId` parameter is **required**. To get a `checkoutId`, use one of the following `wix-ecom-backend` functions:",
"> + [`createCheckoutFromCurrentCart()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-backend/current-cart/create-checkout-from-current-cart)",
"> + [`cart.createCheckout()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-backend/cart/create-checkout)",
"> + [`checkout.createCheckout()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-backend/checkout/create-checkout)" ],
"links": [],
"examples":
[ { "title": "Navigate to the checkout page",
"body":
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
"",
"$w('#myNavigateToCheckoutPageButton').onClick(() => {",
"",
" // Example checkoutId and options values",
" const checkoutId = '12345678-1234-1234-1234-1234567890ab';",
" const options = {",
" skipDeliveryStep: true,",
" hideContinueBrowsingButton: false,",
" overrideContinueBrowsingUrl: 'https://www.myExampleSite.com/upsellPage',",
" // override ThankYouPage URL with dynamic orderId parameter",
" overrideThankYouPageUrl: 'https://www.myExampleSite.com/customThankYouPage/{orderId}'",
" };",
"",
" wixEcomFrontend.navigateToCheckoutPage(checkoutId, options)",
" .then(() => {",
" console.log('Navigated successfully');",
" })",
" .catch((error) => {",
" console.error(error);",
" // Handle the error",
" });",
"});" ],
"extra":
{ } } ],
"extra":
{ } },
"extra":
{ } },
{ "name": "onCartChange",
"labels": [],
"nameParams": [],
"params":
[ { "name": "handler",
"type": "wix-ecom-frontend.onCartChangeHandler",
"doc": "The name of the function or the function expression to run when the cart is changed." } ],
"ret":
{ "type": "void" },
"locations":
[ { "lineno": 120,
"filename": "wixEcomFrontend.js" } ],
"docs":
{ "summary": "Adds an event handler that runs when the cart changes.",
"description":
[ "The event handler set by the `onCartChange()` function runs when the cart changes.",
"",
"The `onCartChange()` event handler is triggered when:",
"+ 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.",
"+ The [`refreshCart()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-frontend/refresh-cart) function is called.",
"",
"<blockquote class=\"important\">",
"",
"**Important:** Actions performed by Velo functions other than the `refreshCart()` function do not trigger the `onCartChange()` event handler.",
"",
"</blockquote>" ],
"links": [],
"examples":
[ { "title": "Add an event handler for cart changes",
"body":
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
"import wixEcomBackend from 'wix-ecom-backend';",
"",
"$w.onReady(function () {",
"",
" // handler function that gets the current cart on cart change",
" const handler = () => {",
" wixEcomBackend.currentCart.getCurrentCart()",
" .then(cart => {",
" let cartId = cart._id;",
" console.log('cart ID: ', cartId);",
" })",
" .catch(error => {",
" console.error(error);",
" // Handle the error",
" });",
" };",
"",
" wixEcomFrontend.onCartChange(handler);",
"});" ],
"extra":
{ } } ],
"extra":
{ } },
"extra":
{ } },
{ "name": "openSideCart",
"labels": [],
"nameParams": [],
"params": [],
"ret":
{ "type": "void" },
"locations":
[ { "lineno": 54,
"filename": "wixEcomFrontend.js" } ],
"docs":
{ "summary": "Opens the Side Cart panel.",
"description":
[ "The `openSideCart()` function opens the Side Cart panel on the current page.",
"",
"> **Notes:**",
"> + We are gradually replacing the existing [Mini Cart](https://support.wix.com/en/article/customizing-the-mini-cart) with the new Side Cart panel.",
"> + This function will fail when viewing the site on mobile because there is no Mini Cart on the mobile site.",
"> + The new Side Cart works on mobile sites. When Side Cart functionality becomes available for your site, `openSideCart()` will work on mobile." ],
"links": [],
"examples":
[ { "title": "Open the Side Cart",
"body":
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
"",
"$w('#myOpenSideCartButton').onClick(() => {",
" // on button click - open the side cart",
" wixEcomFrontend.openSideCart();",
"});" ],
"extra":
{ } } ],
"extra":
{ } },
"extra":
{ } },
{ "name": "refreshCart",
"labels": [],
"nameParams": [],
"params": [],
"ret":
{ "type":
{ "name": "Promise",
"typeParams":
[ "void" ] },
"doc": "Fulfilled - When the cart refresh is complete." },
"locations":
[ { "lineno": 40,
"filename": "wixEcomFrontend.js" } ],
"docs":
{ "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.",
"description":
[ "The `refreshCart()` function returns a Promise that resolves when the latest cart data is retrieved, and the cart UI elements are refreshed.",
"",
"> **Note:** Calling the `refreshCart()` function will trigger the [`onCartChange()`](/wix-ecom-frontend/on-cart-change) event handler." ],
"links": [],
"examples":
[ { "title": "Refresh the cart",
"body":
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
"import wixEcomBackend from 'wix-ecom-backend';",
"",
"$w('#myAddAndRefreshCartButton').onClick(() => {",
"",
" // example values for the options object",
" const options = {",
" lineItems: [{",
" catalogReference: {",
" // Wix Stores appId",
" appId: '215238eb-22a5-4c36-9e7b-e7c08025e04e',",
" // Wix Stores productId",
" catalogItemId: '3fb6a3c8-988b-8755-04bd-5c59ae0b18ea',",
" },",
" quantity: 1",
" }]",
" };",
"",
" wixEcomBackend.currentCart.addToCurrentCart(options)",
" .then(() => {",
" console.log('item added to cart');",
" // refresh the cart after adding item",
" wixEcomFrontend.refreshCart();",
" })",
" .catch((error) => {",
" console.error(error);",
" // Handle the error",
" });",
"});" ],
"extra":
{ } } ],
"extra":
{ } },
"extra":
{ } } ],
"callbacks":
[ { "name": "onCartChangeHandler",
"labels": [],
"nameParams": [],
"params": [],
"ret":
{ "type": "void" },
"locations":
[ { "lineno": 141,
"filename": "wixEcomFrontend.js" } ],
"docs":
{ "summary": "Function that runs when a cart changes.",
"links": [],
"examples": [],
"extra":
{ } },
"extra":
{ } } ],
"messages":
[ { "name": "CheckoutPageOptions",
"locations":
[ { "lineno": 103,
"filename": "wixEcomFrontend.js" } ],
"docs":
{ "links": [],
"examples":
[ { "title": "Navigate to the checkout page",
"body":
[ "import wixEcomFrontend from 'wix-ecom-frontend';",
"",
"$w('#myNavigateToCheckoutPageButton').onClick(() => {",
"",
" // Example checkoutId and options values",
" const checkoutId = '12345678-1234-1234-1234-1234567890ab';",
" const options = {",
" skipDeliveryStep: true,",
" hideContinueBrowsingButton: false,",
" overrideContinueBrowsingUrl: 'https://www.myExampleSite.com/upsellPage',",
" // override ThankYouPage URL with dynamic orderId parameter",
" overrideThankYouPageUrl: 'https://www.myExampleSite.com/customThankYouPage/{orderId}'",
" };",
"",
" wixEcomFrontend.navigateToCheckoutPage(checkoutId, options)",
" .then(() => {",
" console.log('Navigated successfully');",
" })",
" .catch((error) => {",
" console.error(error);",
" // Handle the error",
" });",
"});" ],
"extra":
{ } } ],
"extra":
{ } },
"members":
[ { "name": "skipDeliveryStep",
"type": "boolean",
"doc": "Whether to skip the delivery details step in checkout. For example, if the product is for pick-up only.\n\nDefault: `false`" },
{ "name": "hideContinueBrowsingButton",
"type": "boolean",
"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`" },
{ "name": "overrideContinueBrowsingUrl",
"type": "string",
"doc": "URL to replace the default \"Continue Browsing\" URL. For example, if you'd like to redirect the customer to your own custom page." },
{ "name": "overrideThankYouPageUrl",
"type": "string",
"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." } ],
"extra":
{ },
"labels": [] } ],
"extra":
{ "scopes":
[ "frontend" ] } }
Loading