slim-stencil-tools - npm Package Compare versions

Comparing version 0.1.2 to 0.2.0

package.json

 {
   "name": "slim-stencil-tools",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Lightweight, jQuery-free utility library for BigCommerce Stencil themes",
@@ -5,0 +5,0 @@ "main": "dist/slim-stencil-tools.js",

README.md

@@ -11,8 +11,131 @@ # slim-stencil-tools
 
-### Usage
-This library is a lightweight, jQuery-free alternative to Bigcommerce's standard [Stencil Utils](https://stencil.bigcommerce.com/docs/the-stencil-utils-package) package.  slim-stencil-tools is NOT a direct replacement for Stencil Utils, but rather a leaner API client designed for usecases where some of Stencil Utils' functionality isn't needed (ie- a React/Redux implementation that doesn't need the default PageManager or Events system).  Complete details on what is and isn't included follow in the documentation.
+### About
+This library is a lightweight, jQuery-free alternative to Bigcommerce's standard [Stencil Utils](https://stencil.bigcommerce.com/docs/the-stencil-utils-package) package.  slim-stencil-tools is NOT a direct replacement for Stencil Utils, but rather a leaner API client designed for usecases where some of Stencil Utils' functionality isn't needed (ie- a React/Redux implementation that doesn't need the default Events system or jQuery dependency).  Primarily, slim-stencil-tools facilitates the basic HTTP functionality required for a Stencil theme.
 
+slim-stencil-tools also makes it easier to retrieve JSON data from the Stencil API if desired.  Although some features of slim-stencil-utils were designed with React components in mind, it does not require any framework or dependencies to function (although you'll probably want to use some polyfills, read on for details).
+
 ### Documentation
-Complete documentation is coming soon.  Seriously, really soon...like by December 16, 2016!
+slim-stencil-tools is written in ES6 and transpiled via babel to run in the browser.  The standard Stencil theme's Webpack setup will allow you to include this library as a module.
 
+#### Installation
+* Run `npm install --save slim-stencil-tools` to install the package and save it as a dependency.
+* Import the appropriate parts of the library where needed in your code.  For example, if you need access to the library's Cart API functions in a file:
+```javascript
+  import { Cart as CartApi } from 'slim-stencil-tools';
+```
+
+#### Usage
+slim-stencil-tools is split up into several exports that can be used in your modules as needed.  Some of the included functions allow you to specify a "component" that will be receiving the retrieved data.  This allows you to leverage Stencil's custom Handlebars templates to specify the contents and shape of the JSON data returned.  To use this functionality, you'll need to do the following:
+* Create a directory for your custom "data" templates.  This directory should be a child of the "templates/components" directory in your Stencil theme.  slim-stencil-tools assumes this directory will be named "data", but you can specify another name using the `componentPath` property of the optional `opts` object on relevant functions.
+* Create a new layout file for your "data" templates.  In your Stencil theme's "templates/layout" directory, create a new file "data.html" containing the following:
+```javascript
+  {{#block "data_objects"}}{{/block}}
+```
+* Create individual "data" templates for each data retrieval function, specifying the data you require.  These templates will all go in the "templates/components/data" directory, and all need to be named with a common suffix.  The suffix defaults to "-data", but can be specified using the `componentSuffix` property of the optional `opts` object on relevant functions.  For example, here's a file creating a JSON object `cart`, saved as "templates/components/data/cart-data.html":
+```javascript
+  {{inject "cart" cart}}
+
+  {{#partial "data_objects"}}
+    {{jsContext}}
+  {{/partial}}
+
+  {{> layout/data}}
+```
+Using Stencil's Handlebars helpers, you can also create smaller named variables for only the parts of the Stencil object you need in a given component, reducing the amount of data to be downloaded.  For example, if you only need to retrieve a category's description, you could use a data template like this, saved as "templates/components/data/category-data.html":
+```javascript
+  {{inject "categoryDescription" category.description}}
+
+  {{#partial "data_objects"}}
+    {{jsContext}}
+  {{/partial}}
+
+  {{> layout/data}}
+```
+* Now you can use slim-stencil-tools to retrieve JSON data from Bigcommerce.  This makes it trivial to render data on the client-side using something like React, rather than being stuck working with pre-rendered HTML.
+
+
+##### Base
+```javascript
+  import { Base as BaseApi } from 'slim-stencil-tools';
+```
+
+The Base import is the underlying API function used by slim-stencil-tools.  In most cases, you won't need to import it directly, but you can if you need to add or extend functionality.
+
+##### Cart
+```javascript
+  import { Cart as CartApi } from 'slim-stencil-tools';
+```
+
+The Cart import contains all functions related to retrieving and manipulating data within the cart.
+
+###### getCartContent(component, opts)
+Retrieves the current content of the cart according to the specified data component.  `opts` object is optional and can be used to override the default `componentPath` and `componentSuffix` attributes.
+```javascript
+  const data = CartApi.getCartContent('cart');
+```
+
+###### addToCart(formData)
+Adds a product to the cart using a FormData object as per the default product page form.
+```javascript
+  const productForm = document.querySelector('#product-page-form');
+  const formData = new FormData(productForm);
+  CartApi.addToCart(formData);
+```
+
+###### removeFromCart(itemId)
+Removes a product from the cart by item id (the cart-specific item id, NOT product id).
+```javascript
+  CartApi.removeFromCart(itemToRemove);
+```
+
+###### updateCartQty(opts)
+Change the quantity of a product in the cart.  `opts` object accepts properties `itemId` and `qty`.
+```javascript
+  const changeQty = {
+    itemId: 1234,
+    qty: 3,
+  };
+  CartApi.updateCartQty(changeQty);
+```
+
+###### submitCouponCode(code)
+Submit a coupon or gift certificate code.
+```javascript
+  CartApi.submitCouponCode('muchsavings');
+```
+
+###### getShippingEstimate(opts)
+Retrieve a shipping estimate for items in the cart.  Example coming soon.
+
+###### submitShippingEstimate(params)
+Submit selected shipping estimate.  Example coming soon.
+
+##### Page
+```javascript
+  import { Page as PageApi } from 'slim-stencil-tools';
+```
+
+The Page import contains a function that allows you to fetch a page by URL and render it to a specified Handlebars template file or a "data" component yielding JSON as described above.  Example coming soon.
+
+##### Product
+```javascript
+  import { Product as ProductApi } from 'slim-stencil-tools';
+```
+
+###### getProduct(productId, component, opts)
+Retrieve product data by product id and render it to a specified "data" component, yielding JSON.  `opts` object is optional and can be used to override the default `componentPath` and `componentSuffix` attributes.
+```javascript
+  ProductApi.getProduct(12345, 'quick-view');
+```
+
+##### imageUrl
+```javascript
+  import { imageUrl } from 'slim-stencil-tools';
+```
+
+The `imageUrl` function is a utility function that creates a URL string from a Stencil image "data" attribute and a supplied size string.
+```javascript
+  const url = imageUrl(imageData, '600x600');
+```
+
 ### Notes
@@ -19,0 +142,0 @@ slim-stencil-tools uses modern JavaScript APIs and capabilities that might not be supported in older browsers, specifically ES6 promises and the Fetch API.  You'll likely need to polyfill for best browser support.  The standard stencil theme's dependencies includes babel-polyfill which should take care of the ES6 promises, but here's a [great alternative](https://github.com/stefanpenner/es6-promise) just in case you aren't using babel-polyfill.

src/api/Base.js

@@ -8,2 +8,4 @@ import fetchStatus from '../lib/fetch-status';
  * @param {String} method ['GET', 'POST', 'PUT', 'DELETE']
+ * @param {String} componentPath
+ * @param {String} componentSuffix
  * @param {String} component
@@ -20,2 +22,4 @@ * @param {Boolean} remote
   method: 'GET',
+  componentPath: 'data',
+  componentSuffix: 'data',
   component: null,
@@ -63,3 +67,4 @@ remote: false,
         'stencil-options': options.component ? JSON.stringify({
-          render_with: `data/${options.component.toLowerCase()}-data`,
+          // eslint-disable-next-line max-len
+          render_with: `${options.componentPath}/${options.component.toLowerCase()}-${options.componentSuffix}`,
         }) : '{}',
@@ -66,0 +71,0 @@ },

src/api/Cart.js

@@ -7,7 +7,9 @@ import { bcClient } from './Base';
  * @param {String} component
+ * @param {Object} component
  */
-export const getCartContent = (component = 'cart') => new Promise((resolve, reject) => {
+export const getCartContent = (component = 'cart', opts = {}) => new Promise((resolve, reject) => {
   bcClient({
     url: '/cart.php',
     component,
+    ...opts,
   }).then(response => resolve(response))
@@ -14,0 +16,0 @@ .catch(error => reject(new Error(error)));

src/api/Product.js

@@ -8,7 +8,9 @@ import { bcClient } from './Base';
  * @param {String} component
+ * @param {Object} opts
  */
 // eslint-disable-next-line import/prefer-default-export
-export const getProduct = (productId, component = 'product') => bcClient({
+export const getProduct = (productId, component = 'product', opts = {}) => bcClient({
   url: `/products.php?productId=${productId}`,
   component,
+  ...opts,
 });

src/lib/fetch-status.js

@@ -5,3 +5,3 @@ /**
  */
-export default function fetchStatus(response) {
+const fetchStatus = (response) => {
   if (!response.ok) {
@@ -12,2 +12,4 @@ throw Error(response.statusText);
   return response;
-}
+};
+
+export default fetchStatus;

src/slim-stencil-tools.js

@@ -5,2 +5,3 @@ import * as Base from './api/Base';
 import * as Product from './api/Product';
+import imageUrl from './lib/image-url';
 
@@ -12,2 +13,3 @@ const slimStencilTools = {
   Product,
+  imageUrl,
 };
@@ -20,4 +22,5 @@
   Product,
+  imageUrl,
 };
 
 export default slimStencilTools;

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

242922

increased by2.77%

Number of package files

29

increased by3.57%

Lines of code

889

increased by2.42%

Number of lines in readme file

153

increased by410%

No dependency changes