| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| v:2.0:javascript [2015/10/13 00:46] – [Event usage examples] adam | v:2.0:javascript [2025/03/18 19:35] (current) – [Available Events] adam |
|---|
| |
| ===== Common Examples & Helpful Helpers ===== | ===== Common Examples & Helpful Helpers ===== |
| ==== Making a JSONP Cart Request ==== | ==== Adding Products to the Cart ==== |
| If you like to add a product to the cart behind the scenes or with your own custom behaviors, there's a simple helper to make the request and get back the JSON you need to update things on your end. See [[v:2.0:json|the JSONP page]] for more information on this. | <wrap tip>If you like to add a product to the cart behind the scenes</wrap> or with your own custom behaviors, there's a simple helper to make the request and get back the JSON you need to update things on your end. See [[v:2.0:json|the JSONP page]] for more information on this, but here's a quick code sample for reference: |
| | <code javascript> |
| | FC.client.request('https://'+FC.settings.storedomain+'/cart?name=My+Product&price=20').done(function(dataJSON) { |
| | // Perform custom code here |
| | }); |
| | </code> |
| |
| ==== Resetting the FoxyCart Session & Cookies ==== | ==== Resetting the FoxyCart Session & Cookies ==== |
| <script> | <script> |
| var FC = FC || {}; | var FC = FC || {}; |
| FC.onLoad = function () { | FC.onLoad = function() { |
| FC.client.on('cart-submit', function(params, next) { | FC.client.on('cart-submit', function(params, next) { |
| $element = $(params.element); | $element = $(params.element); |
| ==== "Mini-Cart" Display and HTML Helper Functionality ==== | ==== "Mini-Cart" Display and HTML Helper Functionality ==== |
| If you'd like to have a persistent display showing your website visitor their current cart total (and a quick link to open the cart), you'd add something like this: | If you'd like to have a persistent display showing your website visitor their current cart total (and a quick link to open the cart), you'd add something like this: |
| <code html><p data-fc-id="minicart"> | <code html><p data-fc-id="minicart" style="display:none;"> |
| <a href="https://YOURSTORE.foxycart.com/cart?cart=view"> | <a href="https://YOURSTORE.foxycart.com/cart?cart=view"> |
| <span data-fc-id="minicart-quantity">0</span> | <span data-fc-id="minicart-quantity">0</span> |
| </p></code> | </p></code> |
| The ''data'' attributes are the key. Stick those on any HTML element and it'll be updated automatically. | The ''data'' attributes are the key. Stick those on any HTML element and it'll be updated automatically. |
| * ''data-fc-id="minicart"'': If the ''FC.json.item_count'' is greater than 0, these elements will be shown. Otherwise they'll be hidden | * ''%%data-fc-id="minicart"%%'': If the ''FC.json.item_count'' is greater than 0, these elements will be shown. Otherwise they'll be hidden. |
| * ''data-fc-id="minicart-quantity"'': The inner HTML will be replaced by the value in ''FC.json.item_count''. | * ''%%data-fc-id="minicart-empty"%%'': If the ''FC.json.item_count'' is 0 (the cart is empty), these elements will be shown. Otherwise they'll be hidden |
| * ''data-fc-id="minicart-order-total"'': The inner HTML will be replaced by the value in ''FC.json.total_price'', formatted using the ''_currency_format'' function (which adds decimals but doesn't add currency symbols). | * ''%%data-fc-id="minicart-quantity"%%'': The inner HTML will be replaced by the value in ''FC.json.item_count''. |
| * ''data-fc-id="minicart-singular"'': The inner HTML will be shown if value in ''FC.json.item_count'' is equal to 1, and is hidden otherwise. It can be useful if you want to show "Item/Product" instead of "Items/Products" for ''FC.json.item_count'' = 1. | * ''%%data-fc-id="minicart-order-total"%%'': The inner HTML will be replaced by the value in ''FC.json.total_price'', formatted using the ''_currency_format'' function (which adds decimals but doesn't add currency symbols). |
| * ''data-fc-id="minicart-singular"'': The inner HTML will be shown if value in ''FC.json.item_count'' is greater than 1 or less than 1 (zero), and is hidden otherwise. | * ''%%data-fc-id="minicart-singular"%%'': The inner HTML will be shown if value in ''FC.json.item_count'' is equal to 1, and is hidden otherwise. It can be useful if you want to show "Item/Product" instead of "Items/Products" for ''FC.json.item_count'' = 1. |
| | * ''%%data-fc-id="minicart-plural"%%'': The inner HTML will be shown if value in ''FC.json.item_count'' is greater than 1 or less than 1 (zero), and is hidden otherwise. |
| |
| |
| ==== Available Events ==== | ==== Available Events ==== |
| * Template events. | * Template events. |
| * ''render.done'': This event gets called //after// the template is updated. It gets passed an object with ''selector'' and ''block_id'' attributes. So ''FC.client.on('render.done', function(params){});'', where ''params.selector'' and ''params.block_id'' exist. | * ''render.done'': This event gets called //after// the template is updated. |
| | * ''params'': ''selector'': HTML selector for the block being rendered, ''block_id'': Name of the block being rendered |
| * Sidecart events. | * Sidecart events. |
| * ''sidecart-show'': When the sidecart is displayed. | * ''sidecart-show'': When the sidecart is displayed. |
| | * ''params'': ''element'': HTML element that triggered the add to cart, ''data'': Parameters in the add to cart, ''url'': URL version of the add to cart |
| * ''sidecart-hide'': When the sidecart is hidden. | * ''sidecart-hide'': When the sidecart is hidden. |
| * ''sidecart-detach'': After the sidecart is hidden, the sidecart is actually detached from the DOM and this event fires. | * ''sidecart-detach'': After the sidecart is hidden, the sidecart is actually detached from the DOM and this event fires. |
| * Cart events. | * Cart events. |
| * ''cart-submit'': When an item is added to the cart. | * ''cart-submit'': When the cart is loaded - whether as an add to cart, view cart, empty cart request etc. |
| | * ''params'': ''element'': HTML element that triggered the add to cart, ''data'': Parameters in the cart request, ''url'': URL version of the cart request |
| * ''cart-item-quantity-update'': When a quantity is changed in the cart | * ''cart-item-quantity-update'': When a quantity is changed in the cart |
| | * ''params'': ''id'': Product ID being adjusted, ''quantity'': New quantity amount |
| * ''cart-item-remove'': When a quantity is removed from the cart | * ''cart-item-remove'': When a quantity is removed from the cart |
| * ''cart-coupon-add'': When a coupon is added | * ''params'': ''id'': Product ID being adjusted |
| | * ''cart-coupon-add'': When a coupon or gift card is added |
| | * ''params'': ''code'': Coupon or gift card code being added |
| * ''cart-coupon-remove'': When a coupon is removed | * ''cart-coupon-remove'': When a coupon is removed |
| | * ''params'': ''coupon_code_id'': Coupon code ID being removed |
| | * ''cart-gift-card-remove'': When a gift card is removed |
| | * ''params'': ''gift_card_code_id'': Gift card code ID being removed |
| * ''cart-update'': Called when the cart is updated. Things like rendering Twig templates or setting the FC.json. | * ''cart-update'': Called when the cart is updated. Things like rendering Twig templates or setting the FC.json. |
| * ''cart-shipping-options-update'': shipping option was selected | * ''cart-shipping-options-update'': Called when the shipping options are updated |
| | * ''params'': ''address'': JSON object including the address being used (for example ''FC.json.shipping_address''), ''fields'': JSON object including the fields for city, region, postcode and country that have changed (eg: ''{"shipping_city": "New York"}'') |
| * Checkout events. | * Checkout events. |
| * ''checkout-submit'': Called when the checkout is submitted | * ''checkout-submit'': Called when the checkout is submitted |
| * ''checkout-submit-enable'': Triggered when the checkout button is set to enabled (when all fields are completed and errors are handled). | * ''checkout-submit-enable'': Triggered when the checkout submit button is re-enabled (if a checkout submit attempt is stopped due to validation errors). |
| * ''checkout-submit-disable'': Called when checkout button is disabled due to errors | * ''checkout-submit-disable'': Called when checkout submit button is clicked, disabling the button and triggering validations to run. |
| * ''checkout-shipping-options-update'': shipping option was selected on the checkout | * ''checkout-shipping-options-update'': Called when the shipping options are updated on the checkout |
| | * ''params'': ''address'': JSON object including the address being used (for example ''FC.json.shipping_address''), ''custom_fields'': JSON object of any custom fields being included with the shipping rate calculations |
| * Customer events. Called on the cart and the checkout. | * Customer events. Called on the cart and the checkout. |
| * ''customer-email-update'': Called when an email address change triggers the email to be checked | * ''customer-email-update'': Called when an email address change triggers the email to be checked |
| | * ''params'': ''customer_email'': Email address that has been entered |
| * ''customer-login'': Called when a returning customer has successfully logged in. | * ''customer-login'': Called when a returning customer has successfully logged in. |
| * ''customer-address-update'': ''params'' should include address type, like shipping/billing/multiship. Triggered when ''cart.saveCartContactInfo()'' is called. | * ''customer-address-update'': Triggered when a complete address is entered for an address type (like billling/shipping etc). |
| * ''customer-address-change'': triggered when any of the customer address fields had been changed. | * ''customer-address-change'': Triggered when any of the customer address fields had been changed. |
| | * ''params'': ''address'': JSON object including the address being used (for example ''FC.json.shipping_address''), ''fields'': JSON object including the fields for city, region, postcode and country that have changed (eg: ''{"shipping_city": "New York"}'') |
| | * ''customer-shipping-option-select'': called when a customer selects a shipping rate. |
| | * ''params'': Parameters set to the contents of the address object (for example ''FC.json.shipping_address'') |
| ==== Accessing the FC object on your own website ==== | ==== Accessing the FC object on your own website ==== |
| |
| |
| === Preventing product add to cart actions with custom criteria=== | === Preventing product add to cart actions with custom criteria=== |
| Here's an example that prevents adding product category **Product2** if there are products in the cart that belong to the category **Product1**. | Here's an example that prevents adding product category ''Product2'' if there are products in the cart that belong to the category ''Product1''. |
| <code javascript> | <code javascript> |
| FC.client.on('cart-submit', function(params, next){ | FC.client.on('cart-submit', function(params, next){ |
| External scripts | External scripts |
| * ''foxycart.js'': namespace, session management, events, and utilities | * ''foxycart.js'': namespace, session management, events, and utilities |
| * ''foxycart.jsonp.js'': Used as a base for custom integrations and for the default Pageslide approach. | * ''foxycart.jsonp.js'': Used as a base for custom integrations and for the default Sidecart approach. |
| * ''foxycart.jsonp.pageslide.js'': The cart in a Pageslide approach. | * ''foxycart.jsonp.sidecart.js'': The cart in a Sidecart approach. |
| |
| === Pageload Events and Order of Execution === | === Pageload Events and Order of Execution === |
