# Readme Here is the HOW TO/documentation for adding private sales (VP = "Ventes Privées") on the client website. ## Checklist VP Go to the [VP checklist](checklist.md). ## Intro You have to **keep the same classes/attributes names** as described in this document otherwise the VPs won't work. The way it has been generalised allows developers to add a few classes/attributes and HTML elements into the existing code to activate the VP module. Developers then add a CSS layer to **style the generic classes**. Follow the setup first and then start adding classes/attributes and HTML as described below. IMPORTANT: DiscountNinja will be disabled for connected users during the VPs as it isn't compatible with the VP module. ## 1. Include the VP files to the project 1. Copy and paste the snippet file `app_sales.liquid` (from the [doc/shopify](/doc/shopify) folder) into the `snippets` folder of the destination site. 2. Render the snippet `app_sales`in the `` of `theme.liquid`: **IMPORTANT** It must be included AFTER any DiscountNinja related scripts. ```html {% render 'app_sales' %} ``` ## 2. Create a window object with Liquid data 1. Copy-paste [the following code "snippet"](doc/shopify/settings_schema.json) at the end of `settings_schema.json`. 2. Copy-paste [FR translations](doc/shopify/fr.json), [EN translations](doc/shopify/en.json) and any other relevant language file into `fr.json` and `en.json`. ## 3. Init prices for products with handles (usually on collection page, search page and cross-sells) Check for app integrations below for USF. 1. Add the `data-vp-handle` **attribute** with the "product_handle" as a value to the product "container class". 2. Add the `vp-original-prices` **class** to the HTML element which contains the original price. It is going to hide when the VPs price will be added. 3. After the HTML element which contains the original product price, add the following code: ```html ``` _Note: reuse to the same CSS classes to stay consistent._ **Example**: ```html

``` ### Remark: `Liquid` handles special characters (ex: `©`) without escaping them, but JS doesn't (which can be relevant in some implementation of product recommendations for ex.). To keep them properly formatted in product handles for ex., the functions `unescape()` or `decodeURI()` can be used. | Type | Name | Description | | ----- | -------------------- | ------------------------------------------------------------------------ | | attr | `data-vp-handle` | Attribute to place the product handle in | | class | `vp-original-prices` | Class to use to hide original price | | class | `vp-prices` | Class to gather all the VP prices. Make sure to `style="display: none;"` | | class | `vp-prices-min` | Class for the minimum price | | class | `vp-prices-max` | Class for the maximum price | | class | `vp-prices-discount` | Class for the discounted price | | class | `vp-prices-absolute-discount` | Class to show absolute discount (eg. `-5€`) rather than `%` | ## 4. Init prices for products with variants (usually on product page, cart, quickshop) 1. Add a `data-vp-id` **attribute** with the "product id/variant_id" as a value to the product "container class". 2. _(optional)_ If the product is in the cart, add the `data-vp-qty` **attribute** with the quantity as a value on the same element you've added the `data-vp-id` attribute to. 3. Add the `vp-original-prices` **class** to the HTML element which contains the original price. It is going to hide when the VPs price will be added. 4. After the HTML element which contains the original price, add the following code: (**adapt** `product.tags` according to whether it's on the product page, cart or quickshop) ```html ``` 5. _(optional)_ If the product is in the cart, you can add an element for each of these classes _(doc below)_ inside the element with the `vp-prices` class. 1. `vp-prices-discount` (will be populated with the discounted amount (eg. `-10%`) or the absolute discounted amount (eg. `-5€`) if the `vp-prices-absolute-discount` class is added) 2. `vp-prices-discount-tags` (will be populated with the line item discount tags (eg. `VP_AH16` or `10€`)) 3. `vp-prices-compare-at-price` (will be populated with the compare at price per item (not multiplied by quantity)) 4. `vp-prices-final-price` (will be populated with the final price per item (not multiplied by quantity)) _Note: reuse the same CSS classes to stay consistent._ **Exemple** (in the cart/mini cart): ```html

{{ line_item_price | money }}

``` | Type | Name | Description | | --------- | ---------------------------- | ------------------------------------------------------------------------------ | | attribute | `data-vp-id` | Attribute for the product **id** | | attribute | `data-vp-qty` | Attribute for the product **quantity** | | class | `vp-original-prices` | Class to use to hide original price | | class | `vp-prices` | Wrapper class for all the VP prices. Make sure to add `style="display: none;"` | | class | `vp-prices-min` | Class for the lowest price | | class | `vp-prices-max` | Class for the highest price | | class | `vp-prices-discount` | Class for the discounted amount (eg. `-10%`) | | class | `vp-prices-absolute-discount` | Class to show absolute discount (eg. `-5€`) rather than `%` | | class | `vp-prices-discount-tags` | Class for the line item discount tags (eg. `VP_AH16` or `10€`) | | class | `vp-prices-compare-at-price` | Class for the original price per item (not multiplied by quantity) | | class | `vp-prices-final-price` | Class for the the final price per item (not multiplied by quantity) | ## 5. Init cart total 1. Wrap the current total prices container with the `vp-cart-original-total` **class**. 2. After that HTML element, add the following code: ```html ``` _Note: reuse to the same CSS classes to stay consistent._ Example : ```html

{{ cart.total_price | money_without_trailing_zeros }} {{ initTotalPrice | money_without_trailing_zeros }}

``` | Type | Name | Description | | ----- | ---------------------------------------- | --------------------------------------------------------------------------------- | | class | `vp-cart-original-total` | Class to use to hide original cart price | | class | `vp-cart-total-container` | Class to use to wrap new totals in. Make sure to `style="display: none;"` | | class | `vp-prices-discount-tags` | Will be populated with cart-level discount codes | | class | `vp-prices-coupon-tags` | Will be populated with removable coupons (entered by customer) | | class | `vp-cart-total` | Class added to an empty element to receive the new total calculated based on VPs. | | class | `vp-cart-compare-at` | Class for the `compare_at_price` (the initial non-discounted price) | | class | `vp-cart-total-discount-with-compare-at` | Class for the `total_discount_with_compare_at` (= the amount saved in total) | | class | `vp-cart-total-discount` | Class for the `total_discount` (= the amount saved through cart level discounts) | | class | `vp-prices-discount-tags` | Class for the cart discount tags (eg. `-30€` or `VIP`). | ## 6. Init checkout buttons and error messages 1. Add the `vp-checkout-btn` **class** to the button/div which when clicked goes to the checkout. 2. _(optional)_ Add `

` after the checkout form — it will be populated by error messages if there are any. 3. Don't forget to follow the same steps for mini-carts. ```html ``` ## 7. Add form for coupons It is possible to add a discount code form on the cart page (for the customer to enter coupons, get feedback on them and have prices updated accordingly). To have that feature, add this code on the cart page (and drawer if relevant). ```html {% if settings.sales_enable_coupons %} {% endif %} ``` _Note:_ replace "Appliquer" with a translatable variable. ## 8. Add form for fidelity coupons It is possible to add a fidelity coupons form on the cart page (for the customer to select a single fidelity coupon, get feedback and have prices updated accordingly). To have that feature, add this code on the cart page (and drawer if relevant). ```html {% if settings.sales_enable_fidelity_coupons %} {% endif %} ``` ## 9. Refresh VP prices when needed In some cases (filtering, sorting, infinite scrolling,...) when products are dynamically changing on the page, prices need to be refreshed. _Note: USF search should be handles by default in most cases already._ Calling `document.dispatchEvent(new Event("vp-rerender"))` will run the VP script again and go over all the non-initialised prices. Here is an example: ```js // For example after filtering // "oz:theme:reinit" is an event example on HW which is dispacth when filters are used document.addEventListener('oz:theme:reinit', () => { document.dispatchEvent(new Event('vp-rerender')); // We dispatch "vp-rerender" which "refresh"/"rerender" the VP }); ``` ##### DEFINITION | Type | Name | Description | | ----- | ----------------- | --------------------------------------------------------------------------------- | | class | `vp-checkout-btn` | Main class to use on the checkout button (just before generating the draft order) | ## 10. Create Lightregister The lightregister page allows users to get directed to a specific page (setup in the _Customize_ of the theme) once they're logged-in. 1. In **live theme**, create a new **page liquid template** called `lightregister` 2. Create a page using that template and publish it 3. In development theme, create a `page.lightregister.liquid` file in the `template` folder and copy paste [the content of this template](doc/shopify/page.lightregister.liquid) in it. 4. Add [the following SCSS file](doc/shopify/lightregister.scss) to your theme The content of the page can now be administered through the options in the _Customize_ bit of the theme. ## 11. (annex) - App Integration : USF ### App Integration: USF If the website is using USF, products with handles on the collection page and search pages will need to be edited like so through the app: 1. Add the `data-vp-handle` **attribute** to `searchResultsGridViewItem`. ```javascript searchResultsGridViewItem: ` /* ... */

/* ... */ `; ``` 2. Find HTML element which contains the original price and add the `vp-original-prices` **class** to it. 3. After the HTML element which contains the original price, add the following code: ```html ``` 3. Add the `data-vp-handle` **attribute** to `searchResultsListViewItem`. ```javascript searchResultsListViewItem: ` /* ... */

/* ... */ `; ``` 4. Repeat **Step 2** and **Step 3** for this element. 5. Add the `data-vp-handle` **attribute** to `instantSearchItem`. ```javascript instantSearchItem: ` /* ... */

/* ... */ `; ``` 5. Repeat **Step 2** and **Step 3** for this element. ## 12. (annex) - App Integration : Algolia 1. In `algolia_helpers.js.liquid`, add the `productHandle` function under `algolia.helpers`: ```javascript algolia.helpers = { productHandle: function productHandle() { return this.handle; }, }; ``` 2. In `algolia_autocomplete_product.hogan.liquid` add the `data-vp-handle="[[# helpers.productHandle ]][[/ helpers.productHandle ]]"` attribute on the product container 3. Add the `vp-original-prices` on the initial price container 4. Add the `vp-prices` container under it. Example: ```html

[[# helpers.autocompletePrice ]][[/ helpers.autocompletePrice ]]

[[# helpers.fullHTMLTitle ]][[/ helpers.fullHTMLTitle ]]

[[# meta ]] [[ meta.global.baseline ]] [[/ meta ]]

``` ## Notes - If something is not working properly, make sure jquery is available *(note: soon-to-be-deprecated-as-all-of-jquery-will-be-removed-very-very-soon :-) )* - If JS is added manually, make sure it has the `data-ot-ignore` attribute if the destination website has CookiePro installed Example: `` ```javascript import jquery from 'jquery'; window.$ = window.jQuery = jquery; ```