Widget Builder File Structure in BigCommerce

When you work with the widget generator, it generates a file structure that it uses to carry out its function. Some of these files are not generated by default, so below we will describe the file structure used by Widget Builder in BigCommerce. Each file has a specific purpose and contributes to the development and customization of the widget.

Basic Structure

📂 Widget Name
 ┣ 📜 config.json
 ┣ 📜 query.graphql
 ┣ 📜 schema.json
 ┣ 📜 widget.html
 ┗ 📜 widget.yml

File config.json

This file is used to test different configuration options in a development environment. Facilitates validation and adjustment of widget configurations before deployment.

Its content will depend on how your schema.json is.

Example

{
  "blocks": [
    {
      "title": "Example Title",
      "text": "Example Text"
    }
  ]
}

File query.graphql

This file allows you to execute GraphQL queries, providing dynamic data to the widget. It is useful for advanced functions such as creating product sets.

Example

query productsById($productIds: [Int!]) {
    site {
        products(entityIds: $productIds) {
            edges {
                node {
                    entityId
                    path
                    sku
                    defaultImage {
                        ...ImageFields
                    }
                    brand {
                        name
                    }
                    name
                    reviewSummary {
                        summationOfRatings
                        numberOfReviews
                    }
                    prices {
                        price {
                            ...MoneyFields
                        }
                    }
                }
            }
        }
    }
}

fragment ImageFields on Image {
    url: url(width: 320)
    altText
}

fragment MoneyFields on Money {
    formatted
}

File schema.json

This file defines the configuration options that will be available to the non-developer user, allowing customization of the widget through a friendly interface.

To see more details about the possible configuration options, you can visit the official bigcommerce documentation.

Example

[
  {
    "type": "array",
    "label": "Block Section",
    "id": "blocks",
    "defaultCount": 1,
    "entryLabel": "Blocks",
    "schema": [
      {
        "type": "tab",
        "label": "Block",
        "sections": [
          {
            "settings": [
              {
                "type": "input",
                "id": "title",
                "label": "Item Title",
                "placeholder": "Enter a title",
                "default": "Example Title"
              },
              {
                "type": "text",
                "id": "text",
                "label": "Item Text",
                "placeholder": "Enter a text",
                "default": "Example Text"
              }
            ]
          }
        ]
      }
    ]
  }
]

File widget.html

This file includes the Handlebars and HTML code necessary to create the widget template. Defines the visual structure and elements of the widget.

Example

<ul class="ysw-w-block-section">
    {{#each blocks}}
        <li class="ysw-w-block-section__block">
            <h3 class="ysw-w-block-section__title">{{title}}</h3>
            <p class="ysw-w-block-section__text">{{text}}</p>
        </li>
    {{/each}}
</ul>

File widget.yml

This file contains a unique identifier for the widget, allowing operations such as updating, renaming or deleting the widget. It is essential for managing the life cycle of the widget.

Example

0ac104d1-b114-4fc8-b347-6f11sc952287