diff --git a/wix-ecom-frontend/wix-ecom-frontend.service.json b/wix-ecom-frontend/wix-ecom-frontend.service.json new file mode 100644 index 0000000000..d6363c43f6 --- /dev/null +++ b/wix-ecom-frontend/wix-ecom-frontend.service.json @@ -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.", + "", + "
", + "", + "**Important:** Actions performed by Velo functions other than the `refreshCart()` function do not trigger the `onCartChange()` event handler.", + "", + "
" ], + "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" ] } } \ No newline at end of file