64 |
74 |
75 | Adding multiple line items at once
65 | 66 |67 | If you're adding multiple line items at once, you can use the `CartJS.addItems()` method, rather than multiple calls to `CartJS.addItem()`. 68 |
69 | 70 |71 | This method leverages new functionality added to the Shopify Ajax API in January 2020 that supports multiple items being added at once. 72 |
73 |
76 |
86 |
--------------------------------------------------------------------------------
/docs/guide/sections/core-api/attributes.md:
--------------------------------------------------------------------------------
1 | In addition to cart items, Shopify also provides support for cart attributes, which are used to store custom information about an order.
2 | For example, a common use case for attributes is to store a flag indicating whether the customer would like their order gift wrapped.
3 |
4 | Cart.js provides some conveniences around manipulating these attributes.
5 | Let's take the gift wrap example and see how we could implement it with a simple checkbox:
6 |
7 | ```html
8 |
12 |
13 |
19 | ```
20 |
21 | Now, any time a customer checks or un-checks the options, CartJS will make an update request to the Shopify server.
22 |
23 | Cart.js provides convenience methods for setting multiple attributes at once, clearing attributes, and setting the special-case `note` attribute.
24 | For a full list of supported methods, see the [API Reference][].
25 |
26 | [API Reference]: /pages/reference/#core-api
27 |
--------------------------------------------------------------------------------
/docs/guide/sections/core-api/callbacks.md:
--------------------------------------------------------------------------------
1 | All Core API methods that result in an Ajax request being made to the server allow you to specify one or more callback functions, just like a regular jQuery `$.ajax()` request.
2 | Callbacks are specified through an `options` hash, passed as the final optional argument to the core methods.
3 |
4 | To take a common example, we'll often want to provide callback methods to handle possible results when we try to add an item to our cart.
5 | We want to inform the user of the success or failure of their action, and potentially take some other action.
6 |
7 | ```html
8 |
9 |
10 |
11 |
12 |
34 | ```
35 |
--------------------------------------------------------------------------------
/docs/guide/sections/core-api/cart-state.md:
--------------------------------------------------------------------------------
1 | If we want to inspect the state of our cart at any time, we can access the `CartJS.cart` object.
2 | You can read any of the standard cart properties (such as `item_count` or `requires_shipping`, for example), as well as a list of the current `items` in the cart.
3 |
4 | While developing with Cart.js, it's often useful to open your browser's Javascript console and inspect the cart state, or test out Cart.js methods.
5 | Here's an example from the developer console in Chrome:
6 |
7 | Note on multiple line items with the same variant ID
77 | 78 |79 | Shopify will collate multiple line items for the same variant into one — for example, if we clicked "Add Five Widgets" in the example above again, we'd end up with one line item with `"quantity": 10` instead of two line item with `"quantity: 5"`. 80 |
81 | 82 |83 | However, this *doesn't* apply when you add the same variant with custom line item properties that differ — if we changed the value of the `added_by` property and clicked the button, we'd end up with separate line items. 84 |
85 |
9 |
12 |
23 |
--------------------------------------------------------------------------------
/docs/guide/sections/core-api/configuration.md:
--------------------------------------------------------------------------------
1 | In the "Setup" section above, we saw that we need to call `CartJS.init()` before use, like this:
2 |
3 | {% raw %}
4 | ```html
5 |
13 | ```
14 | {% endraw %}
15 |
16 | As you can see, the `init()` method takes two arguments.
17 | The first argument is required, and is provided by rendering the current Shopify cart as a JSON object through the {% raw %}`{{ cart | json }}`{% endraw %} Liquid tag.
18 |
19 | The second argument is an optional hash of configuration options.
20 | A full list of these options is available in the [Option Reference][].
21 |
22 | [Option Reference]: /pages/reference/#options
23 |
--------------------------------------------------------------------------------
/docs/guide/sections/core-api/removing-items.md:
--------------------------------------------------------------------------------
1 | Removing items works in a similar way to updating items -- just call the `removeItem()` method, passing the line number of the line item you'd like to remove.
2 | As with the update method, if you'd like to remove all line items with a particular variant ID, you can use `removeItemById()` instead.
3 |
4 | If you'd like to empty the cart completely, just call the `clear()` method:
5 |
6 | ```html
7 |
8 |
9 |
14 | ```
15 |
--------------------------------------------------------------------------------
/docs/guide/sections/core-api/updating-items.md:
--------------------------------------------------------------------------------
1 | Updating the quantities or properties of line items is just as simple as adding them -- we just make a call to the `updateItem()` method.
2 |
3 | Let's continue from our example above, and say we want to have a button that doubles the number of widgets in our order.
4 |
5 | ```html
6 |
7 |
8 |
14 | ```
15 |
16 | Don't write values via the cart object
13 | 14 |15 | You should only ever *read* values from `CartJS.cart`, and avoid altering the object directly. 16 |
17 | 18 |19 | Assigning a value with code like `CartJS.cart.items[0].quantity = 5;` will make the change locally in the browser, but won't save it to the server. 20 | This means that the changes will be lost when the customer refreshes or navigates to a new page, or when Cart.js fetches an updated version of the cart from Shopify. 21 |
22 |
17 |
32 |
--------------------------------------------------------------------------------
/docs/guide/sections/data-api.md:
--------------------------------------------------------------------------------
1 | The Data API is the easiest way to start using Cart.js, and for a lot of use cases it'll be all you need.
2 |
3 | All you need to do is add the appropriate `data-` attributes to your code, and the event listeners automatically set up by Cart.js will do the rest.
4 |
5 | This guide provides a quick overview - for a full list of available markup attributes, check out the [Data API Reference][].
6 |
7 | [Data API Reference]: /pages/reference#data-api
8 |
--------------------------------------------------------------------------------
/docs/guide/sections/data-api/adding-items.md:
--------------------------------------------------------------------------------
1 | To create an element that adds an item to the cart on a `click` event, just mark up an element with a `data-cart-add` attribute, and set the value of the attribute to the ID of the variant you'd like to add:
2 |
3 | ```html
4 |
5 | ```
6 |
7 | Of course, you can always use Liquid to render these elements dynamically in your templates:
8 |
9 | {% raw %}
10 | ```html
11 | {% for variant in product.variants %}
12 |
13 | {% endfor %}
14 | ```
15 | {% endraw %}
16 |
17 | You can also optionally specify a quantity and selling plan for the add action:
18 |
19 | ```html
20 |
21 | ```
22 |
--------------------------------------------------------------------------------
/docs/guide/sections/data-api/removing-items.md:
--------------------------------------------------------------------------------
1 | To create an element that removes a line item from the cart on a `click` event, use `data-cart-remove` or `data-cart-remove-id`.
2 |
3 | The difference between these two is that `data-cart-remove` expects the index of the line item you'd like to remove from the cart, while `data-cart-remove-id` expects a variant ID.
4 |
5 | See [Updating Items][] in the Core API section for an explanation of why this distinction is required.
6 |
7 | ```html
8 |
9 | ```
10 |
11 | [Updating Items]: #core-api-updating-items
12 |
--------------------------------------------------------------------------------
/docs/guide/sections/data-api/submitting-forms.md:
--------------------------------------------------------------------------------
1 | If you've already got a working Shopify theme, you'll already have a couple of `
16 | ```
17 | {% endraw %}
18 |
19 | When the customer clicks "Buy Now", Cart.js will intercept the form submission and convert it to an Ajax request.
20 | All of the usual inputs - `id` to specify the variant ID, `quantity` to specify the quantity, `selling_plan` to specify the selling plan, and `properties[]` to specify line item properties - are supported.
21 |
22 | Existing items referenced by index, not variant ID
18 | 19 |20 | One important thing to note is that the `updateItem()` method takes the ***line number*** (the "index") of the item in the cart you'd like to update, not the variant ID. 21 | This is because it's possible (and quite common) to have multiple items in the cart with the same variant ID but with different properties. 22 |
23 | 24 |25 | Shopify uses a 1-based index for line items, so the index of the first line item in a cart is `1`, not `0` as is common in many programming languages. 26 |
27 | 28 |29 | If you'd like to update an item using just the variant ID, you can use `updateItemById()`, which operates the same way as `updateItem()` but takes the variant ID as the first parameter. 30 |
31 |
23 |
31 |
32 | Form submission doesn't work with files
24 |25 | Because Ajax requests don't support `POST` requests with `enctype="multipart/form-data"`, Cart.js won't be able to submit your form if it contains `` elements. 26 |
27 |28 | This is something that we hope to auto-detect in future, but for now you should avoid using `data-cart-submit` on forms that need to upload files. 29 |
30 |
33 |
38 |
--------------------------------------------------------------------------------
/docs/guide/sections/data-api/toggling-items.md:
--------------------------------------------------------------------------------
1 | If you want to give your customers the ability to "toggle" items in or out of their cart, you can use a `data-cart-toggle` attribute on an element that fires a `change` event (like a checkbox or radio input).
2 |
3 | A common use case for this is having an "added extra" on the cart page before the customer checks out - for example, a gift card.
4 |
5 | Let's say we have a selection of gift cards a customer can choose from, and that we've created a collection containing them:
6 |
7 | {% raw %}
8 | ```html
9 | {% for gift_card_product in collections.gift-cards.products %}
10 |
14 | {% endfor %}
15 | ```
16 | {% endraw %}
17 |
18 | This code will render a checkbox that a customer can turn on or off to add or remove the desired gift card from their card.
19 |
--------------------------------------------------------------------------------
/docs/guide/sections/dom-binding.md:
--------------------------------------------------------------------------------
1 | Full documentation for the DOM Binding module is coming soon.
2 |
3 | In the meantime, you can check out the example on the [front page][] in combination with the [Rivets.js documentation][] to get an idea of how things work.
4 |
5 | [front page]: /
6 | [Rivets.js documentation]: http://rivetsjs.com/
7 |
--------------------------------------------------------------------------------
/docs/guide/sections/events.md:
--------------------------------------------------------------------------------
1 | To make it easy to respond to changes in the customer's cart, Cart.js fires a number of custom jQuery events that you can bind listeners to.
2 |
3 | All events are triggered on the `document`, are prefixed with a `cart` namespace, and pass the current cart object as the first custom event argument.
4 |
5 | For example, if we wanted to update a `` element with the number of items in the cart after a request, we could listen for the `cart.requestComplete` event like so:
6 |
7 | {% raw %}
8 | ```html
9 | You have {{ cart.item_count }} items in your cart.
10 |
11 |
16 | ```
17 | {% endraw %}
18 |
19 | A complete list of the events triggered by Cart.js is available in the [Event Reference][].
20 |
21 | [Event Reference]: /pages/reference#events
22 |
--------------------------------------------------------------------------------
/docs/guide/sections/getting-started.md:
--------------------------------------------------------------------------------
1 | Getting started with Cart.js is designed to be pretty easy.
2 |
3 | You just need to fetch a copy of the library, include it in your theme, and call a single initialisation method.
4 | Then you can make calls to Cart.js from within your theme code.
5 |
--------------------------------------------------------------------------------
/docs/guide/sections/getting-started/browser-support.md:
--------------------------------------------------------------------------------
1 | If you're using only the Core and Data functionality of Cart.js (that is,
2 | you're using the `cart.js` or `cart.min.js` library in your theme), then the
3 | range of browsers your theme will support is limited purely by the version of
4 | jQuery you're using. That means that using a `1.x` version of jQuery will allow
5 | you to support IE6+, Chrome, Firefox, Safari 5.1+ and up.
6 |
7 | If you're using the DOM Binding functionality (that is, you're using the
8 | `rivets-cart.min.js` library in your theme), then you may see problems on
9 | browsers that don't support the ES5 Javascript standard (namely, Internet
10 | Explorer 8 and below).
11 |
12 | As of November 2015, Shopify no longer requires themes submitted to the theme
13 | store to support Internet Explorer 8, so as long as you don't have a special use
14 | case that requires supporting these older browsers, you can happily use the DOM
15 | Binding library in your themes.
16 |
17 | Form submission doesn't work with checkout forms
34 |35 | Be careful not to add the `data-cart-submit` attribute to forms that target `action="/checkout"`, as Cart.js will intercept the event and customers won't be redirected to the checkout. 36 |
37 |
18 |
35 |
--------------------------------------------------------------------------------
/docs/guide/sections/getting-started/installation.md:
--------------------------------------------------------------------------------
1 | Cart.js is available via the `npm` or `bower` package managers, from
2 | [cdnjs](https://cdnjs.com), or simply by downloading the latest version of the
3 | library.
4 |
5 | #### NPM
6 | ```shell
7 | npm install shopify-cartjs
8 | ```
9 |
10 | #### Bower
11 | ```shell
12 | bower install shopify-cartjs
13 | ```
14 |
15 | #### CDNJS
16 | ```html
17 |
18 |
19 |
20 | ```
21 |
22 | #### Download
23 | Download the latest version of the library: cartjs.zip.
24 |
--------------------------------------------------------------------------------
/docs/guide/sections/getting-started/module-loaders.md:
--------------------------------------------------------------------------------
1 | If you're using Cart.js and Rivets with module loaders like Webpack, you'll
2 | need to make a couple of minor tweaks to ensure things work smoothly.
3 |
4 | Ensure you're pulling in jQuery and Rivets in your `webpack.config.js` or
5 | equivalent:
6 |
7 | {% raw %}
8 | ```js
9 | new webpack.ProvidePlugin({ $: "jquery", rivets: "rivets", }),
10 | ```
11 | {% endraw %}
12 |
13 | and also make sure that Rivets is available globally in your entrypoint file:
14 |
15 | {% raw %}
16 | ```js
17 | global.rivets = rivets;
18 | ```
19 | {% endraw %}
--------------------------------------------------------------------------------
/docs/guide/sections/getting-started/next-steps.md:
--------------------------------------------------------------------------------
1 | Now that you gotten Cart.js set up with your theme, you're ready to start using the library.
2 |
3 | The recommended (and easiest) way to interact with Cart.js is via the Data API.
4 | All this requires is adding some additional markup to your HTML and Cart.js will take care of the rest - you don't need to write any additional Javascript.
5 |
6 | If you want to do something that's not supported by the Data API, or use Cart.js from within your own custom Javascript, then you can use the Core API to call methods on the `CartJS` object directly.
7 | Of course, these two approaches aren't mutually exclusive - you can always use the Data API for the majority of your cart functionality, drop down to the Core API only when needed.
8 |
9 | What's the issue with older browsers?
19 | 20 |21 | Non-ES5 browsers (namely, IE8) don't support EcmaScript 5's 22 | `Object.defineProperty()` method, which Rivets.js uses to observe 23 | changes on data models and trigger DOM updates. 24 |
25 | 26 |27 | Earlier versions of Cart.js provided a workaround for this by bundling 28 | a number of ES5 shims and polyfills into the library, as well as 29 | forcibly binding and re-binding Rivets views whenever a charge to the 30 | cart occurred. This "compatibility mode" was dropped once Shopify 31 | changed their theme guidelines to only require support for Internet 32 | Explorer 9+. 33 |
34 |
10 |
18 |
19 | Once you've gotten the hang of the Core and Data APIs, you might be interested in using Cart.js in conjunction with Rivets.js to create HTML templates that are automatically updated along with your cart.
20 | That's covered in the [DOM Binding][] section later on.
21 |
22 | [DOM Binding]: #dom-binding
23 |
--------------------------------------------------------------------------------
/docs/guide/sections/getting-started/setup.md:
--------------------------------------------------------------------------------
1 | The Cart.js distribution comes packaged with three versions of the library:
2 |
3 | 11 | The Core API is covered first in the documentation below, as it provides the foundation for the Data API. 12 |
13 | 14 |15 | However, if you just want to get stuck in to using Cart.js, feel free to go straight to the coverage of the Data API. 16 |
17 |
4 |
17 |
18 | Once you've selected the version you'd like to use, add the relevant file to your theme's `/assets` directory.
19 |
20 | You then just need to include the script on your page and call `CartJS.init()`.
21 | The best place to do this is at the bottom of your theme's `theme.liquid` file, so that Cart.js functionality is available across your whole site.
22 |
23 | Because Cart.js depends on jQuery, you should load it after you've included the jQuery library.
24 |
25 | {% raw %}
26 | ```html
27 | ... contents of your theme.liquid ...
28 |
29 |
30 |
31 |
32 |
33 |
34 |
35 |
36 |
37 |
42 |
43 | 5 | `cart.js` is the unminified source code, containing the Core and Data APIs. 6 |
7 | 8 |9 | `cart.min.js` is a minified version of the library, and also contains the Core and Data APIs. 10 |
11 | 12 |13 | `rivets-cart.min.js` is a minified version of Cart.js that also bundles the Rivets.js library. 14 | Together, they provide support for the DOM Binding functionality. 15 |
16 |