Connecting the Wix Database to A Custom HTML Element Using Velo - JavaScript
The Wix.com platform has undoubtedly gained unprecedented popularity in the recent few years. Developers are increasingly shifting to this no-code cloud-based option for creating static as well as dynamic web platforms. However, like every other website builder, Wix has its limitations to the in-built functionality that it provides.
I recently faced one such obstruction in one of my projects, where I had to create a custom product order grid/form on the platform, and use data from the Wix Store database, so I had produce a customised JavaScript page. I will share with you all today a very interesting implementation that I performed, and I hope it helps you!
So, in this tutorial, we will be creating a custom HTML table where a user will write down their order by adding rows and selecting the name of our product (or recipe for this tutorial, since we are selling recipes), from a drop-down. Without any further ado, let's dive right in!
Table of Contents:
Introduction to Wix
Getting started with Velo using JavaScript
Creating a custom HTML element
Adding Data to our Database
Creating a Wix-Data function
Send messages to the HTML element
Fixing the Time problem
Introduction to the Wix Platform
Wix.com is an easy-to-use website builder that allows one to develop their own websites, both static and dynamic, without having to explicitly code in it. You can simply drag and drop their built-in element, or graphically create your own custom elements and add Wix in-built functionality to it. It allows you to manage content, build e-commerce, and many more user-interactive features in the website. It is a great option to get started with web development without having to figure out the details of software development.
The Wix Platform also provides you with the option to store data in your site database and manipulate it, which is extremely since it is hosted on the cloud. This feature is very beneficial in platforms like E-Commerce.
However, Wix functionality is not always adequate to fulfil the requirements of every kind of web application. For that wix also allows us to add custom HTML elements in our website, and write personalised JavaScript code. In this tutorial, we will be developing I will be making a mock data collection in a Wix website, and using custom HTML elements and Javascript, I will be making a UI component which displays my collection in a custom form.
NOTE: You will need to use the editor in order to go through with this tutorial, this cannot be done with the Wix ADI.
Diving right into it, let us start by making a new Wix website. Sign up on Wix, and create a basic website (preferably through the Editor).
Once you're done with that, add basic Wix components to it - nothing too elaborate, just enough to prepare a basic User Interface for testing purposes. By now, you should have switched to the Wix Editor if you have not, by going to Site > Go to Editor. My Wix website look something this right now:
With a basic scaffold for our website, we are now ready to start exploring Velo and adding custom code to it.
Getting Started with Velo using JavaScript
Velo is an application module that is a part of every Wix website, no matter whether you've upgraded your site or not. It allows you to create robust elements in your website without having to do any prior set-up. In layman terms, Velo allows with the platform or interface to add custom serverless-code to your Wix website.
Before we get started, I would like remind you that this functionality is available only in the Wix Editor (and Editor X), and not in the ADI. So once you have switched to that, you can click on Dev mode > Turn on, to begin using Velo.
Once you turn on development, you will notice that your interface has changed. You will now be able to view your code files on the left side, and a code editor will appear for you at the bottom along with a getting started page.
Notice that you have been provided with separate code file for each page of your website (just one in our case right now). You can also global files as per requirement. Another option provided to you, is to categorise your distinct code files by 'public' and 'backend' files, which can be seen on the 'Code files' tab. Moreover, you also have the option to explore Velo packages, and install your custom node modules (npm).
A good place to start now would be to explore the tutorials provided by Velo, and to go through their documentation. First, we should go through the API reference and understand how we can work with fetching data from our Wix Collections (which act like data sets in our Wix database).
While going through the documentation, you will notice a lot of functions, event handlers and hooks that we could use, and you should pick whichever is most appropriate for you. However, for this tutorial I will be picking the 'Wix-Data' API, and using the query() function.
As warm up, it might be ideal for us to simply follow the 'Hello World' tutorial provided to us by the Wix, and get a basic idea of using the interface.
Creating A Custom HTML Element
Good work, now that you are comfortable with the Velo interface and have probably acquired a fresh recap of basic JavaScript, it is time for us to begin working on our custom form Element. We will be embedding a personalised HTML element into our Wix website, starting by creating a new blank page for it:
Now, the next step would be to add an HTML embed component into our page, which Wix allows us to do with one if its in-built components by going to Add > Embed > Embed a Widget, as follows:
Once you select that, an HTML widget should appear on your screen as grey box for now, you can resize it as you desire. Once you are done, you can click on it and press edit code. Ensure that you have selected 'Code' in the What do you want to add? option:
Now you can add any basic HTML in this element, including Headers, Body, Scripts, and CSS styling. Let us test this out by simply adding an H1 and pressing update:
<h1> This is a test! </h1>
Voila, it works! We have now obtained the ability to ad custom html to our page. You can multiple such components, but for simplicity's sake, I will be adding just one. In order to implement my form functionality, I will be adding the following code to my HTML element:
Ah, that's a lot, no? You can add all of that if you want to achieve the exact UI as me, otherwise you can add your own custom field. My page looks like this right now:
With our HTML element ready, let us move on to creating some data!
Adding Data to Our Database
Before we can move forward with our JavaScript, we need to actually insert some dummy data into our Wix Website Database. Data is stored in wix inside of collections and datasets. You can determine the fields of a collection, and then add as many entries to it as you want, just like in a SQL data table.
Let us now add a new collection, by going to Content Manager, with the name 'Recipes', you can name it whatever you want. After that, you can set the permission for your collection, where you can decide who all has access to the data stored in the collection. You can choose one of the provided options, or set Custom permissions, but keep in mind the purpose.
Bravo, it is now time to start adding some dummy data to our collection. Select the collection in your content manager, and go ahead with adding as many fields and entries as you want. For the simplicity of this tutorial, I will keep only one visible field 'Title', and add 5 entries to my collection.
Awesome! Now we have our own data on our wix site to work with. We can now move on to learning how we can send this data over to the HTML element we created previously.
Creating a Wix-Data Function
The next step for us is to get started with the Velo by Wix API, and query our collection to fetch the data. Since we are dealing with Wix site data, I will be using the 'Wix-Data' API, but you can through the documentation again to choose your own. With that established, let us move over to our page code file for the page in which we embedded the HTML, and start off by importing the Wix Data API:
import wixData from 'wix-data'; Great, now let us move back to the documentation and identify the API function that we want to use, keeping in mind that our purpose is to fetch all our 'Recipe' entries and determine their titles in our HTML element.
You have probably identified that we could use 'query()' for our purposes, which is exactly what I will do. This function takes as parameter, the name of our collection, and returns it as an Array of JSON objects. We can now create a function and call the query() function, then return our results within a promise:
export function recipes() {
return wixData.query("Recipes")
.find()
.then( (results) => {
return (results.items)
} )
}
Here, I am returning results.items due to the fact that the query returns multiple other attributes, like context for instance, but we are only concerned with the data part of our query, which is stored in the items attribute.
It will be a good practice if we know add an error handler to our function as well:
export function recipes() {
return wixData.query("Recipes")
.find()
.then( (results) => {
return (results.items)
} )
.catch( (err) => {
let errorMsg = err;
return errorMsg
} );
}
Perfect, this function is now ready to be used/called, and can even be utilised in multiple fields, to the 'export' keyword added to it. Note that this function can even be written in a server-side file (.jsw Web Module) under the backend category, but for now I have kept it in the front-end itself, depending upon the architecture of the site.
After we're done with this, the next step would be to go ahead and call this function, and to send the results to our HTML element. So let us see how to do that.
Send Messages to the HTML Element
Hurrah, we're almost at the end of this tutorial, and only one step away from our goal. We will now be communicating with our HTML element through Javascript on the page code file. When I say communicate, we will be using something literally called 'Messages', and share data through them. You can read more about messages.
In order to implement this functionality, we will write a post-message inside of our $w.ready function in our page code, in JavaScript, and test it out:
$w.onReady(function () {
recipes()
.then((results) => {
$w("#html1").postMessage(results)
})
});
Here we are basically calling our recipes() function when our page loads, and sending a message in our promise. And just like that, we can send data over to our HTML element (by selecting its id as can be seen above) as a parameter in our postMessage() function. However, this is not very beneficial to us right now, since our HTML element has no code to handle any incoming message as of now.
For this, we will add a javascript event listener inside of a script tag within our HTML element, which receives the message and displays it as one of the options in the form's select dropdown. So, add the following code inside of our script tag, changing the existing code:
Make sure also to make the following change in the event listener for our add button function, which the user will press to save their field input:
var input = $(this).parents("tr").find('input, select');Perfect, we have just added an onMessage event listener, in the onReady section of HTML page, which will receive the data sent by our page code and save it in the a variable (only if the data exists). We are also changing the event listener for our 'add-new' button a little bit, to display a select dropdown in the 'recipes' column. We have also appended all the entries from all our received data into our select menu, for which we unpacked our json object in the form of a key, value pair.
Unfortunately, even though it might seem like we're done now, but we're not. The problem is that even now, our HTML won't receive our JavaScript message, because of a lag in the timing of deployment and receiving. Since our Wix page and our HTML element load at a very small time difference, the message is deployed early but not captured since our HTML element won't be ready at the time. Due to this, our message is lost.
Let us see how we can solve this problem in our last section for today.
Fixing the Timing Problem
Wow, just when we thought we were done, am I right? Anyway, we've made it so far, let us see this through! So, what we are going to do now, is send a message from our HTML element to our Javascript page code, within the element's onLoad() listener. Then our Javascript will receive this message and inside our Javascript onMessage() event listener, we will then run our function to send our 'Recipes' data to HTML. This way, we know that our data will not be lost, since our HTML element will be loaded and ready to receive the message.
The first step for this is to add an event listener to our Javascript, which runs our recipes query and returns our promise only when it receives a message from the HTML page:
$w.onReady(function () {
$w("#html1").onMessage( (event) => {
recipes()
.then((results) => {
$w("#html1").postMessage(results)
})
} );
});
Wonderful, now we just have one last thing to do, which is send a message from our HTML element whenever it is 'ready'. For our purpose, you can put any message in it (or leave it blank), and for the url, if your site is not published just put '*':
window.parent.postMessage("To page code")
Awesome job! We have now successfully achieved what we wanted. It is now time to remove any redundant code which is not required. We can now go ahead and test out our code to see if it works:
Well, what do you know, we did it! Congratulations, you have now gained the ability to add custom HTML and Javascript to your Wix website, and even deal with data collections!
Conclusion
Well done, you are all now equipped with the tools needed to add custom HTML and JavaScript to your page, along with manipulating data to construct stunning, responsive and interactive web application platforms. If you are a regular Wix user, this information can definitely act as a life-saver. I am sincerely grateful to each of you who made it so far, and if this post really helped, I would request to let me know and motivate me by dropping your likes and comments! Before I sign off, I would like to remind you to keep exploring and to keep persevering; remember there is always a solution to any problem. If there is anywhere specific you are stuck, let me know and I'll try my best to work it out!
Until Next Time ~