Connect Wix External Collections with Reshuffle
Reshuffle can connect an external database to your Wix website. The connector exposes the HTTP endpoint Wix requires to connect to the external collection.
Join the DZone community and get the full member experience.Join For Free
Wix is a great service that lets you develop your website quickly and securely. It provides a large arsenal of widgets and capabilities to make life easy and shorten development cycles.
The system is so good that businesses all over the world have developed their entire IT infrastructure on top of it, including content management systems, CRMs, and even online shopping and fulfillment.
Most of these capabilities store their data in a database, and while Wix offers data storage as an integrated part of its platform, this may not be the perfect solution in some cases.
Imagine, for example, that you have an existing database you’d like to use. Or perhaps your data has to be stored at a specific location; for legal reasons, regulatory, security, or privacy. How would you achieve that?
To address this need, Wix came up with the concept of external database collections.
As the name suggests, these are data stores external to Wix. You can configure your Wix website to use such an external data source to store and retrieve data.
In this article, we will use Wix and Reshuffle to connect an external database to your Wix website.
The code demonstrated in this article can be found on our Github Repository.
To connect your Wix website to an external collection, you’ll need some understanding of Wix’s SPI, which is the specification describing how Wix connects to external collections. The gist of it is:
- You provide Wix with connection details (an HTTP endpoint to hit).
- Wix connects to your external collection using the connection details.
- Wix uses a set of predefined HTTP calls to exchange data with the external collection.
To connect Reshuffle to Wix, you’ll need to use Reshuffle’s Wix connector. The connector exposes the HTTP endpoint Wix requires to connect to the external collection (your data source).
The following is a Hike List example, which demonstrates the integration of Wix, Reshuffle, and a Postgres database.
The Hike List application is used to manage a list of hikes we want to complete in New Zealand. For each hike, the application will store the following details:
- Date Completed
Wix provides a web-based user interface to manage the data.
Postgres provides a data store.
Reshuffle provides the means to connect the two systems.
The following SQL code can be used to create the table for this example:
By the end of this article, we will want Wix to create items in this database. Therefore, we will define the id and owner fields as 36 characters each. This matches the schema for the auto-generated Wix item ids and owners.
The previous code is only a few lines long, but it sets up the plumbing we need to create a link between Wix and the database.
Comments in code:
Reshuffle is a framework that uses connectors in order to standardize the programming paradigm across diversified systems. In this code, we use connectors for Wix and PostgreSQL. Both are available as Reshuffle npm packages.
You’ll notice we also get some functions from the Wix connector. They will be used later on.
When configuring Wix to use an external collection, you can provide a ‘secret key’ to pass along to your application. This is a means of securing the tunnel (alongside other attributes listed here). Reshuffle’s Wix connector expects each request to provide a secret inside the settings object it contains (see Step 3 below for details of Wix-side configuration).
The Wix connector also accepts an optional parameter to define the path it listens to (and exposes as the endpoint to Wix itself). The default path is
Reshuffle’s Postgres connector requires only a database URL. It abstracts a connection to the database provided. If the database runs on your localhost, the URL will resemble this:
Step 3: Configuring the External Collection on Wix
Head over to Wix to create a new external collection. You’ll need to navigate into your site editor and click on the databases icon from the left-sidebar and then click on the small + icon next to ‘content collections’ to add an external collection.
You’ll need to enter the following details into the configuration pop-up:
- A name for your collection.
- The endpoint URL; this is your Reshuffle’s runtime URL, with the Wix’s webhook path appended to it. In our example above, we left the webhook path to the default, and it will hence be
- The secret ‘API key’ to use in order to authenticate to the Wix connector. This needs to be the same key and value pair configured when the connector is instantiated.
If you click Add right now, Wix will complain:
This is because the code we currently have does not comply with the specification. Remember: it only sets the plumbing to create the link between Wix and your database. It doesn’t really do anything. Yet.
Wix SPI is the specification detailing how Wix communicates with external collections. It is a database-agnostic specification, which the provider of an external collection needs to implement.
So far, we saw how Reshuffle uses connectors to connect to various systems. Connectors in Reshuffle provide events and actions to let the developer program the flows and integrations they need.
Connectors trigger events when something of interest occurs in the external system they connect to. They also expose actions to let the developer make requests to these systems.
Viewing Reshuffle as an event-based system allows us, as developers, to focus on the business logic we need to address specific events.
The Wix connector listens to HTTP Post requests arriving from Wix and exposes all of them as events. The list of requests Wix expects an external collection endpoint to serve can be found in the documentation.
Let’s begin by writing scripts to respond to the six mandatory requests:
Comments in code:
This is the handler we use for the provision call. With other implementations, you may want to ensure that you can reach the database and that the relevant table exists. But for brevity’s sake, we just return a 200 Http Status here, signaling to Wix that the database is provisioned and ready.
You’ll note that the event object received by the handler (which is the piece of code a developer writes to handle an event) contains the HTTP response object, which is required because you’ll want to use it to return to Wix.
This is the call Wix makes to figure out what schemas the external collection exposes. As we only have one table, return the schema itself.
The find schemas call is only interested in specific schemas. It lists these schemas on the HTTP request body (which, like the response object, is found on the event itself).
When constructing the response, the code first tests whether the Hike schema was requested and will only return it when asked.
The count call is used to, well, return the count of items in the external collection. If a filter is provided, the result will reflect that and only count items matching the filter.
Note: The filter provided by Wix is database agnostic. When using Postgres, the filter needs to be translated into a SELECT statement. This is achieved by the parseFilter function provided by the Wix Connector.
The find items call is used by Wix to retrieve a number of items from the external collection. The request may apply a filter and may use limit and skip to request a specific page of results.
Note that Wix expects dates to be wrapped in a specific way. We can use the
wrapDatesfunction from the Wix Connector to achieve that.
Because the data returned from the PG connector is pure JSON, we will need to convert some fields. In this case, we only convert the numeric field ‘distance’ to a Number, as per the schema we provide Wix.
The last mandatory call is the get item call. Wix uses this to retrieve an item by id from a specific collection. Note that, again, we use
wrapDatesto ensure Wix receives date objects in the format it likes.
General note: Error handling code was stripped away to keep the listing brief. The full code can be found on Github.
If you only want Wix to display your data, then that is really all you need.
To test this out, you’ll need your Reshuffle instance running with the code above, and you need Wix to be able to POST to it through an HTTPS endpoint (See here, or here, for how to expose your localhost over SSL if you need to).
Once you provide Wix with the public endpoint (as described in step 3 above), Wix will make a series of calls and create a rudimentary (but powerful!) data viewing grid. If you insert some data into your hike table and refresh the Wix page, you’ll see your data inside this grid:
Notice the ‘read-only’ tag near the collection name at the top of the screenshot above. This is due to the
allowedOperations entry in our schema:
Step 5: Closing the Loop
So far, we only saw how to let Wix read your external collection. We will now close the loop and develop the code that allows Wix to create, update, and remove items as well. We will need to implement three more actions, to insert, update, and delete items.
To start with, you’ll need to add these operations to the
This will tell Wix that your external collection allows for more operations.
The code that deals with inserting, updating, and deleting an item from the database can be found in the Github repository and follows the same logic as the code we have already seen.
It is worth explaining the logic behind converting between the JSON Wix produces and expects, and the SQL used.
Comments in code:
- Wix sends extra fields when it creates or updates an item. Namely, these are the
_updatedDatefields. These are not listed in the documentation but are found as Hidden Fields in the User Interface automatically generated by Wix:
Extracting the names of the fields from the schema ensures that we only deal with the fields we expose in the database. This lets us write concise code (as can be seen in #2 below)
When updating the table, we are interested in all fields that are defined in the schema, sans the
_idfield (as we would not like to update the
_idfield itself under any case).
This code creates a valid SQL Update command by filtering the fields sent from Wix to only use the fields that our database actually provides. By limiting the fields to those exposed by the schema, the code can use
map()rather than address each field individually.
In SQL, numeric values should appear as-is, text values should have quotes surrounding them, and date values should be either null or quoted. The
getValuefunction deals with that.
The article and the accompanying Github repository provide a good starting point for using Reshuffle to connect a data store of any kind to Wix.
Using Reshuffle’s Wix connector and the events it exposes allows you to connect Wix to any external data source you control. This can be a database or Redis, but even a file system or a different service altogether.
(Originally published on Reshuffle’s blog.)
Opinions expressed by DZone contributors are their own.