Skip to content

Commit

Permalink
DEVDOCS-4688: [new] Stencil Ref, add getPageByGQL (bigcommerce#1718)
Browse files Browse the repository at this point in the history 
Co-authored-by: Traci Porter <[email protected]>
Co-authored-by: Sarah Riehl <[email protected]>
  • Loading branch information
@bc-andreadao @bc-traciporter @slsriehl
3 people authored and slsriehl committed Jan 27, 2023
1 parent 1271bca commit 5b48f1f
Showing 1 changed file with 114 additions and 90 deletions.
204 changes: 114 additions & 90 deletions docs/stencil-docs/reference-docs/stencil-utils-api-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,18 +24,17 @@ If you do not want to support ES6 modules, Stencil Utils can be included as a no
### Get page
[getPage](https://github.com/bigcommerce/stencil-utils/blob/master/spec/api.spec.js)

This method takes the form `utils.api.getPage(url, options, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| url | String | request URL (ex: `/cart.php`) |
| options | Object | Can contain `template`, [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) (for POST methods), `params` (for GET methods), and/or `config`. <br><br>The `template` option allows you to select a particular template, or an array of templates, for rendering one page. Each value must correspond to a file present in the theme's `templates/components/` subdirectory. <br><br>The `config` option can be used to pass extra resources, corresponding to attributes that are valid in a page's front matter, as an object. |
| callback | Function | Asynchronous function call to handle the results |
This method takes the form `utils.api.getPage(url, options, callback)`.

| Parameter | Type | Description/Usage |
|:----------|:-----|:------------------|
| url | string | request URL. For example, `/cart.php`. |
| options | object | Can contain `template`, [FormData (for POST methods)](https://developer.mozilla.org/en-US/docs/Web/API/FormData), `params` (for GET methods), and/or `config`. <br><br>The `template` option allows you to select a particular template, or an array of templates, for rendering one page. Each value must correspond to a file present in the theme's `templates/components/` subdirectory. <br><br>The `config` option can be used to pass extra resources, corresponding to attributes that are valid in a page's front matter, as an object. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

The `config` argument works like front matter: it encapsulates JSON. For a usage example of `config`, see the [Remote API Example](/stencil-docs/adding-event-hooks-to-your-theme/remote-api-example#remote_remote-api-example).

In the following example (from `common/faceted-search.js`), `api.getPage()` is called to help execute an `updateView()` function.
In the following example from `common/faceted-search.js`, an `updateView()` method uses `api.getPage()` to refresh page content.

```js title="Example: getPage" lineNumbers
updateView() {
Expand All @@ -52,13 +51,38 @@ updateView() {
this.refreshView(content);
});
}
```
```

The Cornerstone theme uses the `getPage` method in the following contexts:

### Usage in Cornerstone
- [`assets/js/theme/wishlist.js`](https://github.com/bigcommerce/cornerstone/blob/master/assets/js/theme/wishlist.js)
- [`assets/js/theme/gift-certificate.js`](https://github.com/bigcommerce/cornerstone/blob/master/assets/js/theme/gift-certificate.js)
- [`assets/js/theme/faceted-search.js`](https://github.com/bigcommerce/cornerstone/blob/master/assets/js/theme/common/faceted-search.js)

### Get page by GraphQL

[getPageByGQL](https://github.com/bigcommerce/stencil-utils/blob/master/src/api/index.js)

This method takes the form `utils.api.getPageByGQL(page, callback)`.

It allows you to render parts of a template using an inline GraphQL query, as shown in [Front Matter Reference - GraphQL attributes](/stencil-docs/reference-docs/front-matter-reference#graphql-attributes).

| Parameter | Type | Description/Usage |
|:----------|:-----|:------------------|
| page | string | Presentation template to use for rendering one page; for example, `pages/store-locator`. <br> The `template` option allows you to select a particular template. The value must correspond to a file in the theme's `templates/pages/` subdirectory. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

```js title="Example: getPageByGQL" lineNumbers

utils.api.getPageByGQL('pages/store-locator', (err, response) => {
if(err) {
console.error(err);
}
// Server returns HTML template in the response, even if response is unsuccessful
modal.updateContent(response);
});
```

## Cart API

The following methods allow your theme to work with [cart](https://github.com/bigcommerce/stencil-utils/blob/9cf7c26b0a1f9ca9da83274ebc375e73f20acac5/src/api/cart.js) contents in customized ways.
Expand All @@ -68,10 +92,10 @@ The following methods allow your theme to work with [cart](https://github.com/bi

This method takes the form `utils.api.cart.getCart(options, callback);`.

| Argument | Type | Description |
|---|---|---|
| options | object | Return product variant options |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description |
|:---|:---|:---|
| options | object | Return product variant options. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


```js title="Example: getCart" lineNumbers
Expand All @@ -90,10 +114,10 @@ utils.api.cart.getCart({includeOptions: true}, (err, response) => {

Get a sum of the cart line item quantities. It takes the form `utils.api.cart.getCartQuantity(options, callback);`.

| Argument | Type | Description |
|---|---|---|
| options | object | Return product variant options |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description |
|:---|:---|:---|
| options | object | Return product variant options. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

```js title="Example: getCartQuantity" lineNumbers
utils.api.cart.getCartQuantity({}, (err, response) => {
Expand All @@ -115,10 +139,10 @@ utils.api.cart.getCartQuantity({includeOptions: true}, (err, response) => {

The `itemAdd`method allows your code to add an item to the cart, with options. This method takes the form `utils.api.cart.itemAdd(FormData, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| FormData| [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object | Contains all details about the added item and its product options. <br><br>FormData example: <br>`action: add` <br>`product_id: 123` <br> `attribute[123]: 321` <br>`qty[]: 1` |
| callback| Function | Asynchronous function call to handle the results |
| callback | function | Asynchronous function the subject method calls to handle any results. |

`itemAdd` is called at the head of the following example (from `common/product-details.js`) to populate the cart.

Expand Down Expand Up @@ -161,11 +185,11 @@ utils.api.cart.itemAdd(this.filterEmptyFilesFromForm(new FormData(form)), (err,

The `itemUpdate` method allows your code to update a specified cart item’s quantity. This method takes the form `utils.api.cart.itemUpdate(itemId, qty, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| itemId | String | The item’s ID |
| qty | Integer | The item’s quantity in the cart |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| itemId | string | The item’s ID |
| qty | integer | The item’s quantity in the cart. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

```js title="Example: itemUpdate" lineNumbers
cartUpdate($target) {
Expand Down Expand Up @@ -219,10 +243,10 @@ cartUpdate($target) {

The `itemRemove` method allows your code to remove items from the cart. This method takes the form `utils.api.cart.itemRemove(itemId, callback);`.

| Argument| Type | Description/Usage |
|---|---|---|
| itemId | String | The item’s ID |
| callback | Function | Asynchronous function call to handle the results |
| Parameter| Type | Description/Usage |
|:---|:---|:---|
| itemId | string | The item’s ID. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


In the following example (from `cart.js`), `itemRemove` is called before the if/else test.
Expand All @@ -249,10 +273,10 @@ cartRemoveItem(itemId) {

The `update` method allows your code to update the set of items in the cart. It takes the form `utils.api.cart.update(itemId, qty, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| items | Array | The items in the cart |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| items | array | The items in the cart. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


The following example shows a call to `update` within the `itemUpdate` method:
Expand Down Expand Up @@ -292,10 +316,10 @@ itemUpdate(itemId, qty, callback) {

The `getItemGiftWrappingOptions` method allows your code to retrieve gift-wrapping options for the current cart item, in customized ways. It takes the form `utils.api.cart.getItemGiftWrappingOptions(itemId, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| itemId | String | The cart item |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| itemId | string | The cart item. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


The following example (from `cart.js`) calls `getItemGiftWrappingOptions` to display gift-wrapping options in a modal.
Expand Down Expand Up @@ -330,10 +354,10 @@ bindGiftWrappingEvents() {

The `submitItemGiftWrappingOption` method allows your code to handle the customer’s gift-wrapping selection for the current cart item. This method takes the form `utils.api.cart.submitItemGiftWrappingOption(itemId, qty, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| itemId | String | The cart item |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| itemId | string | The cart item. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


```js title="Example: submitItemGiftWrappingOption" lineNumbers
Expand All @@ -353,10 +377,10 @@ submitItemGiftWrappingOption(itemId, params, callback) {

The `getContent` method allows your code to display the cart contents in customized ways. It takes the form `utils.api.cart.getContent(options, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| options | Object | Template containing content and totals children |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| options | object | Template containing content and totals children. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


This example (from `cart.js`) shows a call to `getContent` within the `refreshContent` function.
Expand Down Expand Up @@ -407,11 +431,11 @@ refreshContent(remove) {

The `getShippingQuotes` method allows your code to retrieve shipping-cost quotes for the cart’s contents. It returns `shippingQuote` objects that contain IDs. You must follow `getShippingQuotes` by calling `submitShippingQuote` on a `quoteId`. This method takes the form `utils.api.cart.getShippingQuotes(params, renderWith, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| params | Object | Contains country_id, state_id, and zip_code |
| template | String/Array/Object | The template to use for rendering |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| params | object | Contains country_id, state_id, and zip_code. |
| template | string, array, object | The template to use for rendering. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


See `submitShippingQuotes` for an example.
Expand All @@ -426,10 +450,10 @@ This method takes the form `utils.api.cart.submitShippingQuote(quoteId, callback

The `submitShippingQuote` method must be called after `getShippingQuote`, which returns `shippingQuote` objects that contain IDs. The cart page renders the shipping quotes. When the user selects one of the quotes, this method sends that `quoteId` to the backend.

| Argument | Type | Description/Usage |
|---|---|---|
| quoteId | Number | ID for a shipping quote returned by `getShippingQuotes` |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| quoteId | number | ID for a shipping quote returned by `getShippingQuotes`. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


The following example from `cart/shipping-estimator.js` shows calls to both `getShippingQuotes` and `submitShippingQuote`.
Expand Down Expand Up @@ -475,10 +499,10 @@ bindEstimatorEvents() {

The `applyCode` method applies a coupon code or gift certificate to the cart. It takes the form `utils.api.cart.applyCode(code, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| code | String | Alphanumeric representation of the coupon or gift-certificate code |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| code | string | Alphanumeric representation of the coupon or gift-certificate code. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

In the following example from `cart.js`, `applyCode` is called before the final if/else test to apply a coupon code:

Expand Down Expand Up @@ -534,10 +558,10 @@ bindPromoCodeEvents() {

This method applies a gift certificate to a cart. It takes the form `utils.api.cart.applyGiftCertificate(code, callback);`.

| Argument | Type | Description |
|---|---|---|
| code | string | Gift certificate code to apply |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description |
|:---|:---|:---|
| code | string | Gift certificate code to apply. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

The following example calls `appleGiftCertificate`.

Expand Down Expand Up @@ -565,10 +589,10 @@ These methods allow your theme or app to retrieve standardized country names, by

The country `getById` method retrieves standardized country names by numeric ID. This method takes the form `utils.api.countries.getById(countryId, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| countryId | Number | Country code |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| countryId | number | Country code. |
| callback | function | Asynchronous function the subject method calls to handle any results. |


The following example makes a call to country `getById`.
Expand All @@ -585,10 +609,10 @@ utils.api.countries.getById(countryId, (err, res) => {

The `getByName` method retrieves states by country name, and returns an array of states that can be used in the callback. It takes the form `utils.api.countries.getByName(countryName, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| countryName | String | Country name |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| countryName | string | Country name |
| callback | function | Asynchronous function the subject method calls to handle any results. |

In the following example from `common/state-country.js`, `getByName` is called after the initial `if` test:

Expand Down Expand Up @@ -639,11 +663,11 @@ $('select[data-field-type="Country"]').on('change', (event) => {

The `optionChange` method is fired when the customer selects a product option for the current cart item (for example, changing a shirt’s color from a default "yellow" to "green"). This method takes the form `utils.api.productAttributes.optionChange(productId, params, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| params | Object | Contains a collection of IDs that map to product properties (color, size, etc.) |
| productId | Number | ID for this product |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| params | object | Contains a collection of IDs that map to product properties (color, size, etc.) |
| productId | number | ID for this product. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

In this example (from `common/product-details.js`), `optionChange` is called to update options in a Quick View modal.

Expand Down Expand Up @@ -672,11 +696,11 @@ if (_.isEmpty(productAttributesData) && hasOptions) {

This method configures product options in the cart. It takes the form `utils.api.productAttributes.configureInCart(itemId, options, callback);`.

| Argument | Type | Description|
|---|---|---|
| Parameter | Type | Description|
|:---|:---|:---|
| itemId | number | product ID|
| params | object | |
| callback | Function | Asynchronous function call to handle the results |
| callback | function | Asynchronous function the subject method calls to handle any results. |

```js title="Example: configureCart" lineNumbers
utils.api.productAttributes.configureInCart(itemId, options, (err, response) => {
Expand All @@ -695,11 +719,11 @@ utils.api.productAttributes.configureInCart(itemId, options, (err, response) =>

The product `getById` method allows your code to retrieve, and to present, detailed product information by product ID. This method takes the form `utils.api.product.getById(productId, params, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| productId | Number | ID for this product |
| params | Object | Contains request options and/or presentation template |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| productId | number | ID for this product |
| params | object | Contains request options and/or presentation template. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

```js title="Example: Product getById" lineNumbers
$('body').on('click', '.quickview', (event) => {
Expand Down Expand Up @@ -729,11 +753,11 @@ The `search` method allows you to present a customized user interface for search

The core search method takes the form `utils.api.search.search(query, params, callback);`.

| Argument | Type | Description/Usage |
|---|---|---|
| query | String | Contains the customer’s search query |
| params | Object | Contains request options and/or presentation template |
| callback | Function | Asynchronous function call to handle the results |
| Parameter | Type | Description/Usage |
|:---|:---|:---|
| query | string | Contains the customer’s search query |
| params | object | Contains request options and/or presentation template. |
| callback | function | Asynchronous function the subject method calls to handle any results. |

```js title="Example: search" lineNumbers
const doSearch = _.debounce((searchQuery) => {
Expand Down Expand Up @@ -959,4 +983,4 @@ getCartContent(cartItemHash, onComplete) {
```

## Resources
* [Stencil Utils](https://github.com/bigcommerce/stencil-utils) (BigCommerce GitHub)
* [Stencil Utils (BigCommerce GitHub)](https://github.com/bigcommerce/stencil-utils)

0 comments on commit 5b48f1f

Please sign in to comment.