Wix Blocks: Creating and Managing Collections
5 min read
Wix Blocks is open to all Wix Studio users. To get access to Blocks, join Wix Studio.
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.
Tips
- Pay attention to collection permissions and their security guidelines.
- Blocks collections are counted under the CMS Item and Collection limit
A Blocks collection is a placeholder
The most important thing to understand about a Blocks collection is that it is a placeholder for the data of any site it's installed on. 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 create a collection in Blocks, you define the fields of the collection, and make it possible to refer to it in the app's code. You can also add default data in Blocks, but you don’t have to. If you do add default data, it is automatically installed on the site together with the app, and can later be replaced by data from any site the app is installed on.
If you change the structure of a collection in Blocks in a future version of your app, it impacts any site it's installed on. So work with caution and don't make changes that can break sites.
About the default data
Data that you add to your Blocks collections will be imported to the site in which your app is installed, providing your site creators with default data for your app. If you choose to add default data, note that:
- The site your app is installed on can change that data later.
- The default data will only be imported in the first installation. If you release a new version of your app and change the data in the collection, it will not override the data that already exists in any site your app is installed on.
To add a collection to your app
- Click the Database
icon in your app's left menu. - Click New Collection.
- 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).
- Name your collection.
- Define the structure of your collection in the CMS.
- Optional - add items to your collection. This default data will be imported together with your app to any site it’s installed on
See your collection in the site editor
When you import a Blocks app that has a collection to your site, the collection will appear in the CMS 
section, under Your Collections. 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.
section, under Your Collections. 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. Important
If you delete the app from the site, the collection will be deleted as well.
Connecting elements to collection fields (data-binding)
If you want to connect an element to a collection field, you can choose. Do you want to connect it yourself from the app, or allow site-creators to connect this element on their own? For example if you build an app with complex logic that you need to control, you would probably use the first option. If you build a more design-oriented widget and want to give site-creators the freedom to connect any field they want to the design, your would use the second.
Here are some details about these two options:
Option 1: Connect an element to a collection in Blocks
You can connect an element to a collection field in Blocks, through adding a dataset. If you do this, note that:
- An outer widget cannot connect an inner-widget’s element to a dataset. You must go into the inner widget and connect the element from there.
- If you connect an app’s element to a dataset, you cannot allow a site creator to connect this element to a collection on their site. Therefore, you will also not be able to add the Connect to CMS
action button to this element’s action bar. Note that the action button will be disabled and appear gray.
To connect an element to a field in Blocks:
- Go to the Design tab.
- Click on the element.
- Click on the Connect to CMS
icon in the action bar. - Select a dataset, or add one if you haven't.
- Select the field to connect to your element.
Option 2: Allow site creator to connect the element on a site
You can also allow site creators to connect app elements to their site’s CMS through the Connect to CMS 
action button. If you choose to do this, note that:
action button. If you choose to do this, note that:- Once the app is installed on people's sites and they connect the element to their collections, if you connect the same element to your collection in Blocks, it will break the app’s functionality on their site.
- If you connected an element to your own collection in Blocks, you will not be able to add this action button to the element's action bar.
To allow site creators to connect the element on their site:
- Go to the Configuration tab.
- Click on the element.
- Click Edit Action Bar.
- Click + Add.
- Add the Connect to CMS
button and accept the notification.
Access the collection data through code
First, write this import statement in your widget code:
1import 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):
1wixData.query("<yourAppNamespace>/<yourCollectionName>")
2 .find()
3 .then( (results) => {
4 //your code using the "results";
5 });Learn more about working with the Wix Data API
Did this help?
|