Site Content

Plan: Developer Foundations

Lesson 18 of 28 · 30 min

Overview

BigCommerce’s GraphQL Storefront API allows you to retrieve site content from each storefront channel. Having access to site content makes it easier to build headless storefront applications using BigCommerce’s built-in content, such as theme widgets.

Queries are made in the context of a particular storefront channel. For example, queries for web pages return only web pages for a specific storefront channel. This is useful for Multi-Storefront use cases where you only need site content for a specific channel.

Queries do not support RSS-syndicated content pages as these are deprecated.

Site Content Features

You can use the Site schema to perform the following:

Query web page content, including HTML pages, contact forms, and blog posts
Retrieve banner content on home, search, category, and brand pages
Retrieve rendered widgets built using Page Builder or the Widgets API
Retrieve web pages and blog posts using the web page URL

Web Pages

Query web page content on specific channels to view the following:

Page type
Title of the page (name)
Is the page visible in the storefront navigation (Yes/No) - Use the isVisibleInNavigation field to filter for only pages that appear in the storefront’s navigation menu. Without the filter, queries will return pages that are hidden from the menu, as these pages are still accessible by URL
Page SEO

For more information on web pages, see Page Types.

Routes

Routes is another way to retrieve web pages, similar to the Web Pages schema used in the previous section. Routes allows you to retrieve web pages, the main blog index page, and blog posts using the web page URL. The following query retrieves information for the page with the given path URL.

query {
  site {
    route(path: "/blogs/") {
      node {
        id
        ... on Blog {
          name
          description
          path
          isVisibleInNavigation
          posts {
            edges {
              node {
                name
                tags
              }
            }
          }
        }
      }
    }
  }
}

Rendered Regions

Rendered regions allows you to retrieve rendered widgets on plain-text pages. The following query returns the rendered HTML content for all widgets that are placed in Regions on the given page.

query {
  site {
    content {
      pages(filters: {pageType: NORMAL}) {
        edges {
          node {
            ... on NormalPage {
              path
              renderedRegions {
                regions {
                  name
                  html
                }
              }
            }
          }
        }
      }
    }
  }
}

Blogs

Queries for blogs retrieve published blog posts and exclude draft blogs. They will return published blogs even if they are hidden from the storefront’s navigation menu, as the main blog index page and published blog posts are still accessible by URL.

query {
  site {
    content {
      blog {
        name
        description
        path
        posts(filters: {tags: "graphql"}) {
          edges {
            node {
              entityId
              name
              tags
              htmlBody
              plainTextSummary(characterLimit: 100)
              author
              path
              publishedDate {
                utc
              }
              seo {
                pageTitle
                metaKeywords
                metaDescription
              }
            }
          }
        }
      }
    }
  }
}

Banners

Retrieve banners using the following example query. Queries return only visible banners.

query {
  site {
    content {
      banners {
        homePage {
          edges {
            node {
              entityId
              name
              content
              location
            }
          }
        }
      }
    }
  }
}

Product Reviews

Create and query product reviews with the GraphQL Storefront API. Before you can use this feature, you must enable product reviews, enable the “only accept product reviews from past customers” setting, and enable reCAPTCHA for your storefront.

Example - Create a product review

mutation {
  catalog {
    addProductReview (
      reCaptchaV2: "12345"
      input: {
        productEntityId: 81
          review: {
            title: "Great product"
            text: "Would recommend"
            author: "example author"
            rating: 4  # integer value between 1 and 5
            email: "name@example.com"
        }
      }
    ){
      errors {
        ...on NotAuthorizedToAddProductReviewError {
          message
        }
        ...on CustomerAlreadyReviewedProductError {
          message
        }
        ...on ProductIdNotFoundError {
          message
        }
        ...on InvalidInputFieldsError {
          message fields
        }
        ...on Error{
          message
        }
      }
    }
  }
}

Example - Query product reviews

query {
  site {
    products (entityIds: [81]) {
      edges {
        node {
          reviews {
            edges {
              node {
                entityId
                author {
                  name
                }
                title
                text
                rating
                createdAt {
                  utc
                }
              }
            }
          }
        }
      }
    }
  }
}

Resources

Plan: Developer Foundations

Lesson 18 of 28 · 30 min

Overview

Queries do not support RSS-syndicated content pages as these are deprecated.

Site Content Features

You can use the Site schema to perform the following:

Query web page content, including HTML pages, contact forms, and blog posts
Retrieve banner content on home, search, category, and brand pages
Retrieve rendered widgets built using Page Builder or the Widgets API
Retrieve web pages and blog posts using the web page URL

Web Pages

Query web page content on specific channels to view the following:

Page type
Title of the page (name)
Is the page visible in the storefront navigation (Yes/No) - Use the isVisibleInNavigation field to filter for only pages that appear in the storefront’s navigation menu. Without the filter, queries will return pages that are hidden from the menu, as these pages are still accessible by URL
Page SEO

For more information on web pages, see Page Types.

Routes

query {
  site {
    route(path: "/blogs/") {
      node {
        id
        ... on Blog {
          name
          description
          path
          isVisibleInNavigation
          posts {
            edges {
              node {
                name
                tags
              }
            }
          }
        }
      }
    }
  }
}

Rendered Regions

Rendered regions allows you to retrieve rendered widgets on plain-text pages. The following query returns the rendered HTML content for all widgets that are placed in Regions on the given page.

query {
  site {
    content {
      pages(filters: {pageType: NORMAL}) {
        edges {
          node {
            ... on NormalPage {
              path
              renderedRegions {
                regions {
                  name
                  html
                }
              }
            }
          }
        }
      }
    }
  }
}

Blogs

query {
  site {
    content {
      blog {
        name
        description
        path
        posts(filters: {tags: "graphql"}) {
          edges {
            node {
              entityId
              name
              tags
              htmlBody
              plainTextSummary(characterLimit: 100)
              author
              path
              publishedDate {
                utc
              }
              seo {
                pageTitle
                metaKeywords
                metaDescription
              }
            }
          }
        }
      }
    }
  }
}

Banners

Retrieve banners using the following example query. Queries return only visible banners.

query {
  site {
    content {
      banners {
        homePage {
          edges {
            node {
              entityId
              name
              content
              location
            }
          }
        }
      }
    }
  }
}

Product Reviews

Example - Create a product review

mutation {
  catalog {
    addProductReview (
      reCaptchaV2: "12345"
      input: {
        productEntityId: 81
          review: {
            title: "Great product"
            text: "Would recommend"
            author: "example author"
            rating: 4  # integer value between 1 and 5
            email: "name@example.com"
        }
      }
    ){
      errors {
        ...on NotAuthorizedToAddProductReviewError {
          message
        }
        ...on CustomerAlreadyReviewedProductError {
          message
        }
        ...on ProductIdNotFoundError {
          message
        }
        ...on InvalidInputFieldsError {
          message fields
        }
        ...on Error{
          message
        }
      }
    }
  }
}

Example - Query product reviews

query {
  site {
    products (entityIds: [81]) {
      edges {
        node {
          reviews {
            edges {
              node {
                entityId
                author {
                  name
                }
                title
                text
                rating
                createdAt {
                  utc
                }
              }
            }
          }
        }
      }
    }
  }
}