Table of contents

• Plugins

  • Sku Selector
  • Quantity Selector
  • Accessories Selector
  • Price
  • ShippingCalculator
  • Buy Button
  • Notify Me
  • Minicart
  • Expiration

• Notes

---

See also in Portuguese.

---

Sku Selector

Usage

Call the plugin in an empty div:

$('.sku-selector-container').skuSelector(data, options);

• data must be a JSON with API standard SKUs.

• options (optional) is an object that may have the following properties:

  • selectOnOpening default: false. If true, at initialization the plugin selects the first available SKU (the first one that comes in the array).

  • modalLayout default: false. If true, it uses the modal template.

  • warnUnavailable default: false. If true, it shows "notify me" form when an unavailable SKU is selected.

  • showPriceRange default: false. If true, it shows the minimum and maximum price among the selectable SKUs with the dimensions already selected.

  • forceInputType default: null. If not falsy, it forces the inputType of all dimensions to be that.

Events

Triggers the following events:

• skuReady.vtex [] when the SKU Selector is rendered.
• skuDimensionChanged.vtex [productId, name, value] when a dimension is selected.
• skuSelected.vtex [productId, sku] when an SKU is defined.
• skuUnselected.vtex [productId, selectableSkus] when the SKU becomes undefined.

---

Quantity Selector

Usage

Call the plugin in an empty div:

$('.quantity-selector-container').quantitySelector(productId, options);

• productId the product ID.

• options (optional) is an object that may have the following properties:

  • unitBased default: false. Defines whether to use bulk selector (quantity calculator).

  • unitVariations default: []. If unitBased == true, specifies the unit options for each SKU. It is a collection of {skuId: Number, measurementUnit: String, unitMultiplier: Number}.

  • max default: 10. Defines the maximum amount that can be selected.

  • initialQuantity default: 1. Sets the quantity initially selected.

  • decimalPlaces default: 2. Sets the number of decimal places for the units input. It should not exceed 12.

Events

Triggers the following events:

• quantityReady.vtex [productId, quantity] when the Quantity Selector is rendered.
• quantityChanged.vtex [productId, quantity] when quantity is changed.

It listens for the following events:

• quantityChanged.vtex [productId, quantity] The quantity can be changed through external scripts and the plugin will be updated.

---

Accessories Selector

Usage

Call the plugin in an empty div:

$('.acc-selector-container').accessoriesSelector(productId, data, options);

• productId the product ID which is the accessories’ parent.

• data must be a JSON with API standard accessories.

• options (none currently.)

Events

Triggers the following events:

• accessoriesUpdated.vtex [productId, accessories] when an accessory is changed. The accessories array contains the accessories of a particular product, with properties like sku and quantity.

---

Price

Listens for changes in the selected SKU and updates the price labels.

Uses standard price information when there is no SKU selected.

Usage

Call the plugin in an empty div. If it contains some HTML, it will be used when a Sku is not defined.

$('.productPrice').price(productId, options);

• productId the product ID.

• options (optional) is an object that can have the following properties

  • originalSku default: null. Must be set if the above option is true.

  • modalLayout default: false. If true, it uses the modal template.

Events

Listens for the following events:

• skuSelected.vtex [productId, sku]
• skuUnselected.vtex [productId, selectableSkus]

---

Shipping Calculator

Offers a form for calculating shipping, plus a button to show it.

Usage

Call the plugin in an empty div.

$('.shipping-calc-ref').shippingCalculator(productId, options);

• productId the product ID.

• options (optional) is an object that can have the following properties:

  • strings Sets the messages to be displayed.

    Default:

    {
        "calculateShipping": 'Calcule o valor do frete e prazo de entrega para a sua região:',
        "enterPostalCode": 'Calcular o valor do frete e verificar disponibilidade:',
        "requiredPostalCode": 'O CEP deve ser informado.',
        "invalidPostalCode": 'CEP inválido.',
        "requiredQuantity": 'É necessário informar a quantidade do mesmo Produto.',
        "siteName": 'Vtex.Commerce.Web.CommerceContext.Current.WebSite.Name',
        "close": 'Fechar'
    }
    

    Suggested english version:

    {
        "calculateShipping": 'Calculate the shipping value and delivery deadline for your region:',
        "enterPostalCode": 'Calculate the shipping value and check availability:',
        'requiredPostalCode': 'The ZIP code must be informed.',
        'invalidPostalCode': 'Invalid ZIP code.',
        'requiredQuantity': 'You must enter the quantity of the same Product.',
        "siteName": 'Vtex.Commerce.Web.CommerceContext.Current.WebSite.Name',
        "close": 'Close'
    }
    

Events

Listens for the following events:

• skuSelected.vtex [productId, sku]
• skuUnselected.vtex [productId, selectableSkus]
• quantityReady.vtex [productId, quantity]
• quantityChanged.vtex [productId, quantity]

---

Buy Button

Usage

Call the plugin on the a that acts as a buy button:

$('.buy-button').buyButton(productId, data, options);

• productId the product ID. It may be an array of product IDs - in such case, it will be a button that enables buying all products at the same time.

• data (optional) is an object that can have the sku, quantity, seller and salesChannel properties.

• options (optional) is an object that may have the following properties.

  • errorMessage Error message to be triggered if the user clicks the button without having chosen an SKU. This message will appear in the parameters of the vtex.buyButton.failedAttempt event. Default: "Please select the desired template."

  • alertOnError default: true. Determines whether to display an alert with the errorMessage.

  • redirect default: true. Sets the Redirect property in the querystring. Must be true for product page, and false for modal.

  • instaBuy default: false. If true, when an available SKU is selected, the button is clicked.

  • hideUnselected default: false. If true, it is hidden when there is no SKU selected.

  • hideUnavailable default: false. If true, it is hidden when the selected SKU is unavailable.

  • target default: null. Sets the target query parameter. A valid value is "orderform".

  • requireAllSkus default: false. If productId is an array, this option determines whether all product IDs must have an SKU selected, or whether partial purchases are accepted (only for those selected).

Events

Triggers the following events:

• modalHide.vtex [] when redirect=false and the button is clicked.
• cartProductAdded.vtex [] when redirect=false, the button is clicked and the AJAX response is returned.
• buyButtonFailedAttempt.vtex [errorMessage] when the button is clicked but there’s no valid SKU.
• buyButtonThrough.vtex [url] when the button is clicked and there is a valid SKU.

Listens for the following events:

• skuSelected.vtex [productId, sku]
• skuUnselected.vtex [productId, selectableSkus]
• quantityChanged.vtex [productId, quantity]
• accessorySelected.vtex [productId, accessory]

---

Notify Me

Usage

Call the plugin in an empty div:

$('.portal-notify-me-ref').notifyMe(productId, options);

• productId the product ID.

• options (opcional) is an object that may have the following properties.

  • ajax default: true. Defines whether the form submit should be done with AJAX.

  • sku default: null. Sets the SKU to be used. If it exists, it ignores SKU selection events.

  • strings Sets the messages to be displayed.

    Default:

    {
        "title": "",
        "explanation": "Para ser avisado da disponibilidade deste Produto, basta preencher os campos abaixo.",
        "namePlaceholder": "Digite seu nome...",
        "emailPlaceholder": "Digite seu e-mail...",
        "loading": "Carregando...",
        "success": "Cadastrado com sucesso. Assim que o produto for disponibilizado você receberá um email avisando.",
        "error": "Não foi possível cadastrar. Tente mais tarde."
    }
    

    Suggested english version:

    {
        "title": "",
        "explanation": "To be notified of the availability of this Product, just fill in the fields below.",
        "namePlaceholder": "Enter your name...",
        "emailPlaceholder": "Enter your email...",
        "loading": "Loading...",
        "success": "Successfully registered. As soon as the product is made available you will receive an email notifying you.",
        "error": "Registration failed, please try again later."
    }
    

Events

Triggers the following events:

• notifyMeSubmitted.vtex [productId, sku, promise]: when the form is sent.

Listens for the following events:

• skuSelected.vtex [productId, sku]
• skuUnselected.vtex [productId, selectableSkus]

---

Minicart

Usage

Call the plugin in an empty div:

$('.portal-minicart-ref').minicart(options);

• options (optional) is an object that may have the following properties

  • valuePrefix default: "R$ ". Sets the text to be displayed before the value.

  • valueSufix default: "". Sets the text to be displayed after the value.

  • availabilityMessages Sets the messages displayed for each API availability code.

    Default:

    {
        "available": "",
        "unavailableItemFulfillment": "Este item não está disponível no momento.",
        "withoutStock": "Este item não está disponível no momento.",
        "cannotBeDelivered": "Este item não está disponível no momento.",
        "withoutPrice": "Este item não está disponível no momento.",
        "withoutPriceRnB": "Este item não está disponível no momento.",
        "nullPrice": "Este item não está disponível no momento."
    }
    

    Suggested english version:

    {
        "available": "",
        "unavailableItemFulfillment": "This item is currently unavailable.",
        "withoutStock": "This item is currently unavailable.",
        "cannotBeDelivered": "This item is currently unavailable.",
        "withoutPrice": "This item is currently unavailable.",
        "withoutPriceRnB": "This item is currently unavailable.",
        "nullPrice": "This item is currently unavailable."
    }
    

  • showMinicart default: true. Defines whether the minicart should be displayed.

  • showTotalizers default: true. Defines whether the totalizers should be displayed.

Events

Triggers the following events:

• cartProductRemoved.vtex [] when an item is removed by the minicart.
• minicartMouseOver.vtex []
• minicartMouseOut.vtex []
• minicartUpdated.vtex []

Listens for the following events:

• cartProductAdded.vtex [] the Minicart is updated.
• cartProductRemoved.vtex [] the Minicart is updated.

---

Expiration

session-expiration.js

Utilitary expiration timer, reset by events. When time expires, the user session is cleaned up (cookies are cleared) and the user is redirected to a URL.

Public functions

vtex.portal.startExpiration(url, millis, events)

Start expiration timer.

Parameters and defaults:

• url = '/'
• millis = 10 * 60 * 1000 (10 minutes)
• events = ["mousemove", "keyup", "click", "scroll"]

vtex.portal.stopExpiration()

Stops current expiration timer.

---

Notes

General notes

The options can be passed in three ways. They are, in order of priority:

1. Through JavaScript, in the plugin request.
2. With data- attributes in the elements..
3. Changing the default options (object $.fn.nomeDoPlugin.default).

After a plugin is initialized, the target element will contain, in its data object (access via $().data()), a reference to its plugin instance.

Dependências

Plugin	jQuery	front.utils	Dust (core)	Catalog SDK
Sku Selector	✔	✔	✔	✗
Quantity Selector	✔	✗	✔	✗
Accessories Selector	✔	✔	✔	✗
Price	✔	✔	✔	✗
Shipping Calculator	✔	✗	✔	✔
Buy Button	✔	✗	✗	✔
Notify Me	✔	✗	✔	✔
Minicart	✔	✔	✔	✗
Expiration	✔	✗	✗	✗