vtex-utils

1.18.1 • Public • Published

Build Status npm version David

VtexUtils.js

A collection of utilities methods for Vtex stores.

Table of contents

Main

dist/
├── vtex-utils.js        (UMD)
├── vtex-utils.min.js    (UMD, compressed)
├── vtex-utils.common.js (CommonJS, default)
└── vtex-utils.esm.js    (ES Module)

Getting started

Direct download

Download the script here and include it.

<script type="text/javascript" src="/arquivos/vtex-utils.min.js"></script>

Package Managers

VtexUtils.js supports npm under the name vtex-utils.

npm install vtex-utils --save

Module Loaders

VtexUtils.js can also be loaded as an CommonJS or ES6 module (recomended).

// CommomJS
var VtexUtils = require('vtex-utils');
 
// ES6 module
import VtexUtils from 'vtex-utils';

Usage

With UMD (Universal Module Definition), the package is available on VTEX namespace.

// Initialize constructor
var vtexUtils = new VTEX.VtexUtils();
 
// VtexHelpers
var vtexHelpers = vtexUtils.vtexHelpers;
 
// GlobalHelpers (from UtilifyJS)
var globalHelpers = vtexUtils.globalHelpers;
 
// LocationHelpers (from UtilifyJS)
var locationHelpers = vtexUtils.locationHelpers;
 
// Storage (from Store2 | https://github.com/nbubna/store)
var storage = vtexUtils.storage

UtilifyJS

Docs for vtexUtils.globalHelpers and vtexUtils.locationHelpers methods can be found on UtilifyJS

Vtex Methods

vtexHelpers.formatPrice(number[, thousands[, decimals[, length[, currency]]]])

Formats Vtex price

  • number:

    • Type: Integer
    • The number to format
  • thousands (optional):

    • Type: String
    • Default: '.'
    • The thousands delimiter
  • decimals (optional):

    • Type: String
    • Default: ','
    • The decimal delimiter
  • length (optional):

    • Type: Integer
    • Default: 2
    • The length of decimal
  • currency (optional):

    • Type: String
    • Default: 'R$ '
    • Set currency

Example

vtexHelpers.formatPrice(1234); // R$ 12,34
vtexHelpers.formatPrice(123456); // R$ 1.234,56
vtexHelpers.formatPrice(123456, null, ',', 3); // R$ 1234,560
vtexHelpers.formatPrice(123456, ',', '.', 2, ''); // $ 1,234.56

vtexHelpers.unformatPrice(value[, decimal[, formatNumber]])

Unformat Vtex price. Value can be a single string or an array of values

  • value:

    • Type: String|Array
    • Price formatted
  • decimal (optional):

    • Type: String
    • Default: ','
    • The decimal delimiter
  • formatNumber (optional):

    • Type: Boolean
    • Default: false
    • Thousands separator (pt-BR default: '.')

Example

var priceFormatted = 'R$ 1.234,56';
vtexHelpers.unformatPrice(priceFormatted); // {unformatted: 123456, real: '1234', cents: '56'}
vtexHelpers.unformatPrice(priceFormatted, null, true); // {unformatted: 123456, real: '1.234', cents: '56'}
 
vtexHelpers.unformatPrice(['R$ 12,34', 'R$ 23,45', 'R$ 34,56']);
/*
[
    {unformatted: 1234, real: '12', cents: '34'}
    {unformatted: 2345, real: '23', cents: '45'}
    {unformatted: 3456, real: '34', cents: '56'}
]
*/

vtexHelpers.setInstallment(price, minPrice, maxInstallments[, interest])

Take the value of the installment with min price and max installments given

  • price:

    • Type: String|Number
    • Price to get installments. Can be formatted price or a integer value.
  • minPrice:

    • Type: String|Number
    • Min price for each installment. Can be formatted price or a integer value.
  • maxInstallments:

    • Type: Number
    • Max installments
  • interest (optional):

    • Type: Number
    • Default: 0
    • Interest rate

Example

vtexHelpers.setInstallment('R$ 3.499,00', 'R$ 430,00', 10) // {installments: 8, installmentValue: 43737, interest: 0}
vtexHelpers.setInstallment(349900, 43000, 10) // {installments: 8, installmentValue: 43737, interest: 0}

vtexHelpers.getPercentage(oldPrice, newPrice[, length])

Get the percentage of a discount

  • oldPrice:

    • Type: String|Number
    • Original price. Can be formatted price or a integer value.
  • newPrice:

    • Type: String|Number
    • Price with discount. Can be formatted price or a integer value.
  • length (optional):

    • Type: Number
    • Default: 0
    • Number of decimals

Example

vtexHelpers.getPercentage('R$ 179,90', 'R$ 149,50'); // 17 (17% OFF)
vtexHelpers.getPercentage(17990, 14900, 2); // 17.18 (17.18% OFF)

vtexHelpers.applyDiscountPercent(price, percent[, formatted])

Returns a discount amount or adding a set value.

  • price:

    • Type: String|Number
    • Price to apply discount. Can be formatted price or a integer value.
  • percent:

    • Type: String|Number
    • Percentage to apply. Can be formatted price or a integer value.
  • formatted (optional):

    • Type: Boolean
    • Default: false
    • Format result

Example

vtexHelpers.applyDiscountPercent('R$ 9,55', 37.27); // {discountPrice: 355, priceWithDiscount: 599, priceWithIncrease: 1310}
vtexHelpers.applyDiscountPercent('R$ 9,55', '37.27%'); // {discountPrice: 355, priceWithDiscount: 599, priceWithIncrease: 1310}
vtexHelpers.applyDiscountPercent('R$ 9,55', '37,27%'); // {discountPrice: 355, priceWithDiscount: 599, priceWithIncrease: 1310}
vtexHelpers.applyDiscountPercent(955, 37.27, true); // {discountPrice: 'R$ 3,55', priceWithDiscount: 'R$ 5,99', priceWithIncrease: 'R$ 13,10'}

vtexHelpers.fixProductSearchPrice(val)

Formats price from Vtex API /api/catalog_system/pub/products/search/ to use in formatPrice method

  • val:
    • Type: Number
    • Value to convert

Example

vtexHelpers.fixProductSearchPrice(250.25); // 25025

vtexHelpers.getFirstAvailableSku(product)

Get first available SKU from Vtex API /api/catalog_system/ end point

Returns an object with first available SKU or false if all are unvailable

  • product:
    • Type: Object
    • Product full data

Example

vtexjs.catalog.getProductWithVariations(1234)
    .then(function(res) {
        var availableSku = vtexHelpers.getFirstAvailableSku(res);
        window.console.log(availableSku);
    });

vtexHelpers.getOriginalImage(src)

Get the original VTEX image source from a thumb

  • src:
    • Type: String
    • The source of the thumb

Example

vtexHelpers.getOriginalImage('http://domain.vteximg.com.br/arquivos/ids/155242-292-292/image.png');
// http://domain.vteximg.com.br/arquivos/ids/155242/image.png

vtexHelpers.getResizedImage(src, width, height)

Change the width & height from a given VTEX image source

  • src:

    • Type: String
    • The source of the image
  • width:

    • Type: String | Integer
    • The new image with
  • height:

    • Type: String | Integer
    • The new image height

Example

vtexHelpers.getResizedImage('http://domain.vteximg.com.br/arquivos/ids/155242-292-292/image.png', 500, 600);
// http://domain.vteximg.com.br/arquivos/ids/155242-500-600/image.png
 
vtexHelpers.getResizedImage('http://domain.vteximg.com.br/arquivos/ids/155242/image.png', 100, 100);
// http://domain.vteximg.com.br/arquivos/ids/155242-100-100/image.png

vtexHelpers.getResizeImageByRatio(src, type, newSize, aspectRatio)

Resize proportionally an VTEX image by aspect ratio

  • src:

    • Type: String
    • The source of the image
  • type:

    • Type: String
    • Type to resize (width or height)
  • newSize:

    • Type: Number
    • New size to redimensioning
  • aspectRatio:

    • Type: Number
    • Image aspect ratio (calculate by (width / height))

Example

var imgSrc = 'http://domain.vteximg.com.br/arquivos/ids/155242-292-292/image.png';
var newSize = 250;
var aspectRatio = (10/15);
 
vtexHelpers.getResizeImageByRatio(imgSrc, 'width', newSize, aspectRatio);
// http://domain.vteximg.com.br/arquivos/ids/155242-250-375/image.png
 
vtexHelpers.getResizeImageByRatio(imgSrc, 'height', newSize, aspectRatio);
// http://domain.vteximg.com.br/arquivos/ids/155242-167-250/image.png

vtexHelpers.getServerTime(callback)

Get the Vtex server time

  • callback:
    • Type: Function
    • The callback to call when the request finishes. The callback will a javascript Date object.

Example

vtexHelpers.getServerTime(function(date) {
    window.console.log(date.getFullYear());
});

vtexHelpers.getCategories([categoryId[, depth]])

Get category tree

  • categoryId (optional):

    • Type: Integer
    • Default: undefined
    • Return the specific Category
  • depth (optional):

    • Type: Integer
    • Default: 50
    • The tree depth

Example

vtexHelpers.getCategories().then(function(res) {
    window.console.log(res)
}); // Return all categories
 
vtexHelpers.getCategories(1000001, 1).then(function(res) {
    window.console.log(res));
}); // Return first level from category id

vtexHelpers.getProductSpec(data, specName[, defaultVal])

Get product specification

  • data:

    • Type: Object
    • Vtex API data from /api/catalog_system/pub/products/search/ endpoint
  • specName:

    • Type: String
    • Specification name
  • defaultVal (optional):

    • Type: Boolean|String
    • Default: false
    • Value to return if spec doesn't exists

Example

// Data from API '/api/catalog_system/pub/products/search/'
var response = {
  Características: ["Cor real", "Ocasião", "Composição", "Cor"],
  Composição: ["Liga Mista, Pedra Natural Pirita"],
  Cor: ["Dourado"],
  Cor real: ["Ouro"],
  Ocasião: ["Weekend"],
  allSpecifications: ["Cor real", "Ocasião", "Composição", "Cor"],
  // More data...
};
 
vtexHelpers.getProductSpec(response, 'Cor'); // 'Dourado'
vtexHelpers.getProductSpec(response, 'Cores'); // false
vtexHelpers.getProductSpec(response, 'Cores', 'Branco'); // 'Branco'

vtexHelpers.getShipping(postalCode[, skuId[, quantity]])

Get product shipping value.

  • postalCode:

    • Type: String
    • Postal code to calculate. Can be xxxxx-xxx or xxxxxxxx format
  • skuId (optional):

    • Type: Integer
    • Default: skuId
    • Sku ID to calculate. If not passed, get first sku available on product page from skuJson global variable. If this method used on other pages, skuId is required
  • quantity (optional):

    • Type: Integer
    • Default: 1
    • Product quantity to calculate

Example

// On product page with a valid postal code
vtexHelpers.getShipping('01010-010')
  .then(function(res) {
    if ( !res.error ) {
      console.log('SUCCESS', res);
    }
 
    if ( res.error ) {
      console.log('INVALID TYPE', res);
    }
  });
 
/*
  Case success, will return an object with properties:
  {
    error: false,
    formattedResponse: {
      shippingValue: 'R$ 10,00',
      shippingText: 'Entrega em 4 dias úteis para o CEP 01010-010',
      shippingType: 'Frete Transportadora'
    }
    fullResponse: '<table><thead>...' // Original content from api
  }
 
  Case failed (invalid postal code, invalid sku ID, etc.), will return
  {
    error: true,
    formattedResponse: {
      shippingText: 'Não é possível calcular o valor do Frete para o CEP informado'
    }
    fullResponse: '<div class="cep-invalido" id="divFreteInvalido">...' // Original content from api
  }
*/

vtexHelpers.replaceBreakLines(str)

Replace break lines from product descriptions/more

  • str:
    • Type: String
    • String to replace

Example

var string = 'Foo\nBar\n\rBaz\r';
 
vtexHelpers.replaceBreakLines(string); // 'Foo<br />Bar<br /><br />Baz<br />'

vtexHelpers.stringIdsToArray(str[, separator])

Convert a string IDs given into an integer array values

  • str:

    • Type: String
    • String with IDs
  • separator (optional):

    • Type: String
    • Default: ','
    • Separator to split

Example

var commaStr = '1, 2, 3, 4';
stringIdsToArray(str); // [1, 2, 3, 4]
 
var dashedStr = ' - 1 - 2 - 3 - 4 - ';
stringIdsToArray(dashedStr, '-'); // [1, 2, 3, 4]

vtexHelpers.checkLogin()

Check if the user is logged into Vtex

Example

vtexHelpers.checkLogin().then(function(res) {
    // If user defined
    console.log(res);
})
.fail((err) => {
    // If user isn't defined
    console.log(err)
});

vtexHelpers.openPopupLogin([noReload[, url]])

Open default Vtex popup login.

Before use, don't forget to import Vtex Controller <vtex.cmc:welcomeMessage/>

  • noReload (optional):

    • Type: Boolean
    • Default: false
    • Reload page after login
  • url (optional):

    • Type: Boolean
    • Default: '/'
    • Url to rdirect

Example

vtexHelpers.openPopupLogin(); // Open popup and reload page after success login
vtexHelpers.openPopupLogin(true); // Open popup and don't reload page after success login
vtexHelpers.openPopupLogin(false, '/account'); // Open popup and don't reload page after success login and redirect to Account page

TIP

Use $(window).on('closed.vtexid', callback) event to set any property if noReload is true

If noReload is true, it'll ignore url param

vtexHelpers.addToCart(items[, expectedOrderFormSections[, salesChannel]])

Open default Vtex popup login.

Require vtexjs.

  • items:

    • Type: Array
    • An Array of Objects with item(s) to add
  • expectedOrderFormSections (optional):

    • Type: Array
    • Default: null
    • Fields to retrieve
  • salesChannel (optional):

    • Type: Integer/String
    • Default: 1
    • Sales Channel id

Example

var items = [{
    id: 1,
    quantity: 1,
    seller: '1',
  }, {
    id: 2,
    quantity: 2,
    seller: '1',
  }];
 
vtexHelpers.addToCart(items).then(function(res) {
  window.console.log(res);
})
.fail(function(err) {
  window.console.log(err);
});
 

vtexHelpers.clearCart()

Remove all items from cart. Require vtexjs.

Example

vtexHelpers.clearCart()
  .then(function(res) {
    window.console.log(res)
  })
  .fail(function(err) {
    window.console.log(err)
  });

vtexHelpers.notifyMe(name, email, skuId)

Send notify me data for unavailable products.

Return a promise.

  • name:

    • Type: String
    • Customer name
  • email:

    • Type: String
    • Customer e-mail
  • skuId:

    • Type: Integer
    • Sku ID (if product ID passed, will return a fail promise)

Example

var name = 'Test Notify';
var email = 'test.notify@email.com';
var skuId = 12321;
 
vtexHelpers.notifyMe(name, email, skuId)
  .then(function(res) {
    console.log(res.successMessage); // Cadastrado com sucesso. Assim que o produto for disponibilizado você receberá um email avisando.
  })
  .fail(function(err) {
    console.log(err.errorMessage); // Não foi possível cadastrar. Tente mais tarde.
  });

Rivets Utilify

Docs for RivetsUtilify can be found here

To set RivetsUtilify:

// Import RivetsUtilify
<script type="text/javascript" src="rivets-utilify.min.js"></script>
 
// Initialize constructor
var vtexUtils = new VTEX.VtexUtils();
 
// Sets method
vtexUtils.setRivetsUtilify(RivetsUtilify);

Tests

Tests are using mocha. To run the tests use:

$ npm test

License

VtexUtils.js is open-sourced software licensed under the MIT license.

Dependencies

jQuery 1.8.3+

vtexjs

Dependencies (19)

Dev Dependencies (2)

Package Sidebar

Install

npm i vtex-utils

Weekly Downloads

102

Version

1.18.1

License

MIT

Unpacked Size

637 kB

Total Files

10

Last publish

Collaborators

  • zeindelf