Wix Blocks: About Collections

Wix Blocks enables you to add collections (databases) to your app. Managing collections in Blocks is similar to managing collections in Wix sites. But, there are a few points that are very different - check them out in this article. 

A Blocks collection is a placeholder

The most important thing to understand about a Blocks collection is that it is not supposed to hold data. It's a placeholder for the data of any site it's installed in. When you create a collection in Blocks, you only define the structure of the data and make it possible to refer to it in the app's code. But the data itself will change from site to site. 

This is because a Blocks collection can be used on multiple sites - even thousands of them. These sites can be very different from each other and have their own databases. Think about a collection that holds customer information. Every site can have a list of their own customers, and your widget can apply to all of them. 

When you change the structure of a collection in Blocks, it impacts any site it's installed on. So work with caution and don't make changes that can break sites. 

To add a collection to your app

1. Click the Database  icon in your app's left menu. 
2. Click New Collection.
3. Create a unique namespace for you app, if you haven't already done it. Make the namespace meaningful and clear (if you haven't named your app yet, you will be triggered to name it now). 
4. Name your collection.
5. Define the structure of your collection in the CMS. 
6. Optional - add test items to your collection. Remember that they are only placeholders. The actual data won't be imported to a site. 

See your collection in the editor

When you import a Blocks app that has a collection to your site, the collection will appear in the Content Collections section in the Databases  panel. Your app namespace will appear next to this collection, to indicate that it's from Blocks. From now on you can handle your collection like in any other Wix site. 

Access the collection data through code

First, write this import statement in your widget code: 

1
import wixData from 'wix-data';

To access your collection and perform various actions, query, insert, etc, use the following syntax with any wix-data API. For example, this is how you query a collection (learn more about your namespace): 

1
wixData.query("<yourAppNamespace>/<yourCollectionName>")
2
  .find()
3
  .then( (results) => {
4
    //your code using the "results";
5
  });

Learn more about working with the Wix Data API

Reference a collection on your site through the widget code

You might want to reference a collection on your site directly from your widget code without adding it to Blocks. There are two ways to do this:

• If you know the name and structure of the collection, you can use it in your widget code. For example, if Wix Stores is installed on the site, you can use the Stores/Products collection.

• You can pass the name of the collection or other information about the collection as properties in the Widget API.