https://github.com/vtex/front.portal-plugins
Portal front end plugins
https://github.com/vtex/front.portal-plugins
srv-store-framework xp-developer
Last synced: 10 months ago
JSON representation
Portal front end plugins
- Host: GitHub
- URL: https://github.com/vtex/front.portal-plugins
- Owner: vtex
- License: mit
- Created: 2013-05-24T22:02:03.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2020-07-03T15:29:27.000Z (over 5 years ago)
- Last Synced: 2025-04-14T09:14:49.637Z (10 months ago)
- Topics: srv-store-framework, xp-developer
- Language: CoffeeScript
- Size: 1.08 MB
- Stars: 33
- Watchers: 209
- Forks: 14
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
### Table of contents
- Plugins
- [Sku Selector](#sku-selector)
- [Quantity Selector](#quantity-selector)
- [Accessories Selector](#accessories-selector)
- [Price](#price)
- [ShippingCalculator](#shipping-calculator)
- [Buy Button](#buy-button)
- [Notify Me](#notify-me)
- [Minicart](#minicart)
- [Expiration](#expiration)
- [Notes](#notas)
---
See also in [Portuguese](https://github.com/vtex/front.portal-plugins/blob/master/README.pt-BR.md).
---
# 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 | ✔ | ✗ | ✗ | ✗ |
[jQuery]: http://www.jquery.com
[front.utils]: https://github.com/vtex/front.utils
[Dust (core)]: http://linkedin.github.io/dustjs/