bigcommerce / stencil-utils

Utility library for the Stencil theme framework.

Stencil Utils

Stencil utils is a utility library that contains the BigCommerce Stencil Events system and other tools that will help and enhance the experience of building a theme with the Stencil framework.

Documentation

https://developer.bigcommerce.com/stencil-docs/adding-event-hooks-to-your-theme/stencil-utils-api-reference

Getting Started

Stencil Utils is written in ES6 and is currently transpiled to ES5 with babel for running client side within browsers. Stencil utils can either be imported to your theme as a module, or included as a standalone script.

Installing Stencil Utils on your theme

As an ES6 module

• Run npm install @bigcommerce/stencil-utils to install the latest tagged version of stencil-utils for use with your theme.
• Import the library import utils from 'bigcommerce/stencil-utils'; in modules that depend on it.

Using standalone

If you do not want to support es6 modules, Stencil Utils can be included as a normal script:

• Copy the bundled script from dist/stencil-utils.min.js to your theme.
• Include the script in your HTML document
• Access stencil utils from window.stencilUtils.

Now you are playing with power!

Testing

Just simply run npm run test

License

Copyright (c) 2015-present, BigCommerce Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes software developed by Bigcommerce Inc.
4. Neither the name of Bigcommerce Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY BIGCOMMERCE INC ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BIGCOMMERCE INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

stencil-utils's Issues

utils.api.product.getById not returning videos on localhost

We are trying to retrieve product by ID using utils.api.product.getById and custom template with fromt-matter product: to display product information. When we run theme locally product.videos.list.length always 0. If we access same product just navigating to it on local host we can see videos. Also when we deploy it to bigcommerce product.videos.list.length start working on api call. Its only not working if we call api on localhost

Default export not working properly

I'm not sure what I'm missing here:

import hooks from './hooks';
import api from './api';
import tools from './tools';

const StencilUtils = {
    hooks: hooks,
    api: api,
    tools: tools,
};

export {hooks, api, tools};
export default StencilUtils;

/* global define */
(function(root) {
    if (typeof define === 'function' && define.amd) {
        define(function() {
            return (root.stencilUtils = StencilUtils);
        });
    } else if (typeof module === 'object' && module.exports) {
        module.exports = StencilUtils;
    } else {
        window.stencilUtils = StencilUtils;
    }
}(this));

Then, in assets/js/theme/common/product-details.js:

import utils from 'bigcommerce/stencil-utils';

utils.hooks.on('cart-item-add', (event, form) => {
    // do stuff
});

When the files load, I get an error that utils is undefined. If I change the file to this:

import {hooks} from 'bigcommerce/stencil-utils';

hooks.on('cart-item-add', (event, form) => {
    // do stuff
});

It works correctly. So, it appears something is not working correctly with the default export statement. Is there something obviously wrong here with the import or export statements that would cause this issue?

Events: If you are creating factory methods for on/off/init, you don't need to expose the actual event classes.

As the title says, you should pull in each of the event classes in a private array. Then you can do a basic map over them to call emitterInit() on them. The pattern of putting all of the classes in the same object where you have your factory methods is very weird. Also in the off() method, you are calling .on() on the event class.

Behavior change in price_range.max and .min in product.getById

Hi, for some time we've called product.getById for 2 products to render the price ranges for the 2 products compared in a table at the bottom of this page.
https://kuranda.com/dog-breeds/airedale-terrier

Somewhere along the way the behavior has changed where the max price returned is no longer correct for both and the min price is wrong for the second. You can see the correct prices ranges by taking a look at the first and third products on this page.
https://kuranda.com/dog-beds

I can confirm it's not an issue where my template is changing the value, if I look at the debug context for the data returned by the API call it shows the incorrect numbers as they render on the page. The only parameter I'm passing to the call besides the product ID is my custom template to render the response with.

Our products do have around 250 variants, and the true max price is found toward the end of that range assuming you sort by order of creating those variants. It's possible the change in behavior is that whatever happens on the API side with stencil utils is now capping the amount of variants it loads where before it loaded all of them. We are also on v2 product options if that makes a difference.

Add to Cart button on product page not firing itemAdd script using stencil-utils 6.12.0

Expected behavior

Clicking the Add to Cart button should trigger the overlay, the preview modal and add the item to the cart.

Actual behavior

Clicking the Add to Cart button only updates the button text and does not add the item to the cart or trigger the preview modal.

Steps to reproduce behavior

Download the latest version of Cornerstone, at this time is 6.5.0, and install. Connect to any store and go to any product and try to add to cart.

Additional Notes

I was able to revert back to previous versions of stencil-utils and confirmed the product added to the cart. I tested this on both stencil-utils versions 6.8.1 and 6.11.0. Tested on multiple computers and different clients and found the issue to be consistent with the latest stencil-utils version.

Stencil-cli version stencil --version: 5.2.0

Node version node -v: 14.15.0

NPM version npm -v: 6.14.8

Return as JSON

I understand the Storefront API will take care of this in a sense, but is there any reason why we have to use a template in the params to return data, instead of just getting this back as a json object? Seems like an unnecessary step

utils.api.product.getById() response content-type has been changed

Please check this store and the ajax request in Web Developer tool:
https://chiara-furniture-demo.mybigcommerce.com/hemnes-shoe-cabinet/

The response content-type has been changed from text/html to text/plain.
http://prntscr.com/nqvkkj
http://prntscr.com/nqvla0

Which causes error when parsing JSON data in stencil-utils/lib/request.js line 110
http://prntscr.com/nqvlxd
http://prntscr.com/nqvnsc

It affects some themes using getById() with template sections.

Uncaught ReferenceError: exports is not defined

Current development environment on my computer:

• MacOS 12.3.1
• Nodejs v12.9.0
• Npm v6.10.2
• Stencil-cli v4.0.0

When I execute the command stencil start and the website is opened, an error appears in the browser's console:

index.js:170 Uncaught ReferenceError: exports is not defined
at Module../node_modules/@bigcommerce/stencil-utils/node_modules/query-string/index.js (index.js:170:1)
at webpack_require (bootstrap:63:1)
at Module../node_modules/@bigcommerce/stencil-utils/src/lib/utils.js (utils.js:2:21)
at webpack_require (bootstrap:63:1)
at Module../node_modules/@bigcommerce/stencil-utils/src/api/product-attributes.js (theme-bundle.main.js:5951:68)
at webpack_require (bootstrap:63:1)
at Module../node_modules/@bigcommerce/stencil-utils/src/api.js (api.js:1:1)
at webpack_require (bootstrap:63:1)
at Module. (main.js:1:1)
at Module../node_modules/@bigcommerce/stencil-utils/src/main.js (theme-bundle.main.js:6918:30)
./node_modules/@bigcommerce/stencil-utils/node_modules/query-string/index.js @ index.js:170
webpack_require @ bootstrap:63
./node_modules/@bigcommerce/stencil-utils/src/lib/utils.js @ utils.js:2
webpack_require @ bootstrap:63
./node_modules/@bigcommerce/stencil-utils/src/api/product-attributes.js @ theme-bundle.main.js:5951
webpack_require @ bootstrap:63
./node_modules/@bigcommerce/stencil-utils/src/api.js @ api.js:1
webpack_require @ bootstrap:63
(anonymous) @ main.js:1
./node_modules/@bigcommerce/stencil-utils/src/main.js @ theme-bundle.main.js:6918
webpack_require @ bootstrap:63
(anonymous) @ theme-bundle.main.js:4540
./assets/js/theme/global/quick-search.js @ theme-bundle.main.js:4608
webpack_require @ bootstrap:63
(anonymous) @ theme-bundle.main.js:1872
./assets/js/theme/global.js @ theme-bundle.main.js:1944
webpack_require @ bootstrap:63
(anonymous) @ bootstrap:196
./assets/js/app.js @ theme-bundle.main.js:368
webpack_require @ bootstrap:63
(anonymous) @ bootstrap:196
(anonymous) @ bootstrap:196
(index):8186 Uncaught TypeError: window.stencilBootstrap is not a function
at (index):8186:20
(anonymous) @ (index):8186

Is anyone having the same problem as me? Please give me your advice and solution to fix this issue. I am very appreciative of that.

utils.api.product.getById( ) returns different attribute keys than default page context.

When you look at ?debug=context a product is returned as the following object with cherry picked attributes:

 {
        "id": <ID>,
        "sku": "<SKU>",
        "name": "<NAME>",
        ...
        "image": {
          "data": "<URL>",
          "alt": "<ALT>"
        },
}

But query the same product with utils.api.product.getById( ) and it returns

 {
        "id": <ID>,
        "sku": "<SKU>",
        "title": "<NAME>",
        ...
        "main_image": {
          "data": "<URL>",
          "alt": "<ALT>"
        },
}

My goal was to have one component that I could use both in the API call, and using the regular page context. Is there a reason these attributes are returned differently?

currency-selector doesn't work

when user togger currency selector, the following hook doesn't get trigger
stencilUtils.hooks.on('currencySelector-toggle', (event) => {
console.log('event', event);
});

i checked the base code:
currencySelector() {
this.subscribe('input', '[data-currency-selector-toggle]', (event) => {
this.emit('currencySelector-toggle', event);
});
}

i wasn't able to find [data-currency-selector-toggle] on store with currency selector

analytics.track JS appended to API responses breaks some implementations

For some time I've used
utils.api.cart.getContent({ template: 'custom/json/cart-product-ids' ... }
with the following code in that template
{{ json cart.items }}
So I can take the response inside the callback of utils.api.cart.getContent and parse json to get that cart contents.

Sometime yesterday the server started appending a <script> tag the end of the response with analytics.track('Product Added'... and so on inside which broke our site/ability to put things in the cart since the script is trying to parse the response as JSON.

Is there some way we can send an option parameter to ask for a json response (vs html) or somehow as the library here to not append that script tag as if the response were HTML? If this exists in the options parameter now, it would be great to see some explanation of what those options are in the docs since
https://developer.bigcommerce.com/stencil-docs/ZG9jOjIyMDcyMA-stencil-utils#get-cart

Thanks

How can I use utils.api.productAttributes.optionChange on checkout SDK ?

When I am trying to use utils.api.productAttributes.optionChange on the checkout SDK, I am getting the response data but the attribute/option of the item is not changed .... How to use it so I can change the product option value on the checkout page ? Here is my code
utils.api.productAttributes.optionChange(238,'item_id=0aaaee28-865d-4c32-b99a-e826b7488adb&attribute%5B116%5D=112233444',(err, response) => { console.log(response.data); });

Create ability for custom hooks.

Currently you have to have your hook name prefixed with cart, product, cookie, etc which is kind of silly. Can we expand this hook to a more generalized API so you can call and listen to ANY type of event within a BigCommerce theme.

Multiple consecutive calls to utils.api.cart.itemAdd not working

Hi,

We are trying to issue several calls to utils.api.cart.itemAdd one after another. We dont see any errors and result returning has id, hash, and all other data generated by utils.api.cart.itemAdd. Please see atached

But when we view the cart we don't see all items there. We actualy were never able to see all items it either 1 out of 3 added or 2 out of 3. Please see result after 3 items added we can only see 2, but same calls may generate only 1 item in the cart

getCustomer() - Q/FR

Hi There

Any reason why stencil-utils does not feature a method to get current customer object or by id like getCustomer()
To me it seems appropriate, or am I missing something?

Uncaught (in promise) TypeError: Cannot read property 'physicalItems' of undefined: cart.js:71

Hello,

I've been seeing this error on multiple Cornerstone themes.

This happens on page-load, I assume this is happening when you land on a BC page and have an empty cart, potentially related to the theme checking for the quantity in cart to update the count-pill.

This is the error that shows up in console:

cart.js:71 

Uncaught (in promise) TypeError: Cannot read property 'physicalItems' of undefined
    at cart.js:71
    at cart.js:44
    at request.js:124

Origin of the error is /stencil-utils/src/api/cart.js

Any ideas on how to resolve, is this a problem with a cornerstone version, or stencil utils version, or both?

/cart.php?action=save_giftwrapping truncates the message

Hi, I'm working on some modifications where instead of gift wrapping we're sending personal notes. We can add the message but it seems BigCommerce is truncating the message to 27 characters. Can this limit be modified/configured/augmented?

I attach some screenshots

utils.api.product.getById No Timeout on mobile

Using a desktop the method will work without issue however when on mobile the issue will will hang my webpage. It will not return a response or error, just sit there awaiting. This was tested on Android (Firefox, Chrome) and iOS (Safari).

SIDE NOTE: On desktop the method will grab products even when the product is hidden in the storefront. Mobile will throw a 404 error.

Bind "this" on API class methods

I'm having an issue using the stencil-utils/src/api/product.js aka utils.api.product.getById method because of the "this" keyword.

Please bind(this) on all class methods to keep scope in order.

/**
 * FOR EXAMPLE 
 * after this line: https://github.com/bigcommerce/stencil-utils/blob/master/src/api/product.js#L13
 * add the following code
 */
this.getById = this.getById.bind(this);

This will prevent any issues with this referring to some outside Class

utils.api.productAttributes.optionChange can't convert null to object

if you use a demo store in the console simply run this

window.stencilUtils.api.productAttributes.optionChange(77, "action=add&product_id=77&attribute%5B108%5D=69&attribute%5B109%5D=10&qty%5B%5D=1", function (err, resp) {
                console.log('err', err);
                console.log('resp', resp);
            });

and you'll have the error can't convert null to object

api.getPage() ignores some options on production

When specifying options for a getPage request, such as limit, you are able to see the expected results on localhost. However, when the theme is bundled and pushed to the live store, the options no longer work (they are overridden by options set in the front matter for the page).

For example, if I run the following function in localhost, it will return 100 products, but on the live site, it will return the number of products specified in the category.html YAML:

There is a more thorough explanation written here (not by me): https://support.bigcommerce.com/s/question/0D51B00003sQyL1/stencilutils-api-getpage-options-issue

Any chance this can be fixed so we can specify options within our requests that differ from those specified in the front matter?

Stencil Utils has not been kept up to date

npm install @bigcommerce/stencil-utils after running this we get
$ npm install @bigcommerce/stencil-utils
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE package: '@bigcommerce/[email protected]',
npm WARN EBADENGINE required: { node: '>=14.0.0 <19.0.0' },
npm WARN EBADENGINE current: { node: 'v20.11.0', npm: '10.2.4' }
npm WARN EBADENGINE }

up to date, audited 1763 packages in 5s

137 packages are looking for funding
run npm fund for details

24 vulnerabilities (21 moderate, 3 high)

To address issues that do not require attention, run:
npm audit fix

To address all issues (including breaking changes), run:
npm audit fix --force

Run npm audit for details.

You should at least make sure you support the latest node LTS plunking security vulnerabilities into apps is not good engineering.