Velo: Where Do I Put My Code?

Velo is a powerful development platform and sometimes, that makes it a bit confusing. That's especially true if you're starting out and not sure which bits of code go where and why they don't work as you expect them to.

So if you're just starting out, or if you already started coding, this article will help you work out where to put your code.

In general, you can find your site code in the following ways:

• In the Code sidebar (Wix Studio) or the Velo sidebar (Wix Editor), select the Page Code tab for frontend code, and the Public & Backend tab for backend code.

• In your local IDE when using Git integration, in your site repo's src folder.

• In the Wix IDE (Wix Studio), in the src folder.

I want to respond to button clicks and page events

Page elements like buttons, text, and inputs have events that are triggered when you interact with them. The most common is when you click on an element, which triggers the onClick event. The functions that respond to these events are known as event handlers.

So where do you put your code to respond to these events?

There are two options:

• In the onReady code block.
• Using the Properties & Events panel.

onReady

Whenever you create a new page, you automatically get an onReady() code block that looks like this:

1
// API Reference: https://www.wix.com/velo/reference
2
// “Hello, World!” Example: https://www.wix.com/velo/hello-world
3

4
$w.onReady(function () {
5
  // Write your JavaScript here
6
  // To select an element by ID use: $w("#elementID")
7
  // Click "Preview" to run your code
8
});

The onReady event fires when the page has been rendered and is ready for visitor interaction. Whatever you put in the $w.onReady event handler runs when this event fires. This is the place to define your event handlers for elements on your page. Event handlers defined in onReady are known as Dynamic Event Handlers. Dynamic event handlers can be cut and pasted between pages or sites, and will work as long the page element is named correctly.

The simplest example is a button click.

1
$w.onReady(function () {
2

3
    $w('#myButton').onClick((event) => {
4
        console.log("myButton was clicked, just saying");
5
    });
6

7
});

Put this code inside the onReady block so that as soon as the page is ready, it is also ready to handle a click event for the myButton element.

You can also put your code in a separate function, called from the event handler.

1
$w.onReady(function () {
2

3
    $w('#myButton').onClick((event) => {
4
        myButtonWasClicked(event);
5
    });
6

7
});
8

9
export function myButtonWasClicked(event) {
10

11
    console.log("myButton was clicked, just saying");
12
    // add useful code here
13
}

Note that nobody will say anything if you define your event handler outside the onReady block, but it won't work unless it’s in a function, and that function has been run.

Also note that if you define an event handler in a regular function and you run the function twice, you will get two event handlers, and the code inside them will run twice when the event is triggered.

The best practice is to define your event handlers in the onReady block.

Using the Properties & Events Panel

The other way to handle events for page elements is with static event handlers. Set these up by selecting the event handler you want from the Properties & Events panel, which you can find at the bottom of the Code panel, under the code editor in Wix Studio, or to the right of the code editor in the classic Wix Editor.

This will add the following code to your page and can be used instead of the dynamic event handler. These functions are defined outside the onReady block and are “internally wired” via the Properties & Events panel to catch the relevant event. You can’t type these functions directly in the editor—they must be added in the Properties & Events panel to work.

1
/**
2
*  Adds an event handler that runs when the element is clicked.
3
*   @param {$w.MouseEvent} event
4
*/
5
export function myButton_click(event) {
6
 // This function was added from the Properties & Events panel. To learn more, visit http://wix.to/UcBnC-4
7
 // Add your code for this event here:
8
}

I want some code to run on every page

If you have code that you want to run on every page, put that code in the masterPage.js file, located in the Page Code section of the Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor), or in your site repo's src/pages folder in your local IDE when using Git integration.

Code in the masterPage.js is common to all pages on your site. If you want to add processing for your header or footer, this is the place to do it. This is also the place to handle elements that you want to put on every page, like a search bar or shopping cart icon for a store.

The masterPage.js has its own onReady event handler, so be careful not to write code in this event handler that conflicts or overlaps with code in the page onReady, as the event handlers run in parallel.

Retaining an element's state

The state of an element you set on one page does not persist to other pages or when you return to the page.

Let's say you have an image element that is set to Show on All Pages. Then you add a button and an event handler to change the element's source on click. When you navigate to another page on your site, the image reverts back to its original source. This is true even if you navigate back to the page where you initiated the click event.  

To keep the state of an element between pages you need to store its state using wix-storage-frontend:

1. Inside the event handler callback, use setItem to store a key that indicates the state of the element.
2. Inside the onReady callback for masterPage.js, add code that checks the stored key and changes the element's state accordingly.

I want some code to run on multiple but not all pages

You may have a function that you need to use in multiple pages, but you don't want to repeat it on each page. You can write that function once in a public file and then call it from any page, or from any backend or public file as needed.

You need to export the function from your public file, and then import it into the files where you want to use it, public or backend.

Access your site's public files under Public in the Public & Backend section of the Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor). You can also access your site's public files in your local IDE when using Git integration, in your site repo's src/public folder.

Where should I put passwords and sensitive data?

If your code contains something that you don't want anyone to see, like private member details, a password, payment information, or some processing that you want to keep hidden, store it in Backend files, which aren’t visible to the browser. 

The Secrets Manager

For really sensitive information like passwords or keys, you should use the Secrets Manager instead of hardcoding the values in your code. 

I want to use functions from somewhere else

The import statement lets you use objects and functions that have been exported by another module. This is how you include functions from your own backend files and other Wix modules in your code. Best practice is to put the import statement at the top of your code file.

Put in the braces around function names that you are importing. For example:

1
import { myFunction } from 'backend/aModule.web'

If you leave out the curly braces, you import the default function of aModule and it gets called myFunction.

1
import myFunction from 'backend/aModule.web'

This will generally result in the following runtime error if you call myFunction, unless you have specifically exported myFunction as the default.

1
(0 , \_aModule2.default) is not a function

However, if you want to import a full module, then you should import without the curly braces to access all of the module's functions.

1
import wixData from 'wix-data';
2
import wixStoresFrontend from 'wix-stores-frontend';
3
import wixMembers from 'wix-members-backend';

Where do I put Wix backend functions?

Any function from a Wix backend library, like  wix-pay-backend, wix-members-backend, or wix-events-backend, goes into a backend code file.

Code executed on the backend takes the load off the browser and lets you access functions that run on the web server.

Access your site's backend code files under Backend in the Public & Backend section of the Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor). You can also access your site's backend code files in your local IDE when using Git integration, in your site repo's src/backend folder.

When you define a function in a .web.js file you need to import it into your page code before you can call it. 

If you try to import a frontend function, like something from wix-members-frontend, into a backend file, you will get the following runtime error:

1
Error loading web module backend/aModule.web: Cannot find module 'wix-members-frontend'

Backend File Types

There are two file suffixes that can be used in the backend:

• .web.js These are web modules which are accessible to the end and have associated permissions to control who can call each function in the file.
• .js  These files are not directly accessible to visitors or members via frontend code and are therefore more secure.

If you try to import a function from a .js file into your frontend code, you will get the following error at runtime:

1
Access to backend script 'backend/new-file.js' denied! Client-side scripts can only import web-modules from backend code context.

To run a function in a .js file from your page code, import the function from the .js file into a .web.js file, and then import the .web.js function into your page code.

When you use a backend function, don't forget to use an await or a .then to wait for the promise to resolve and give you the function’s return values.

1
//In your page code:
2
import { myBackendFunction } form 'backend/aModule.web'
3

4
export function myFrontendFunction() {
5

6
    // await
7
    const myVariable = await myBackendFunction();
8

9
    //.then
10
    myBackendFunction()
11
        .then((response) => {
12
            const myVariable = response;
13
        });
14
}

Where can I handle incoming HTTP requests or webhooks?

If you want to enable a get, put, post, or other endpoint that can be called from outside your site, create an http-functions.js file under Backend in the Public & Backend section of the Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor), or in your site repo's src/backend folder in your local IDE when using Git integration

When you create the http-functions.js file in Wix Editor, you get some sample code which can help you get going. Check out this article and the http-functions section in the reference guide for more help.

I want to run a function when my data collection changes

You can trigger a function to run each time your data collections change. These are called data hooks and are defined in the data.js file under Backend in the Public & Backend section of the Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor), or in your site repo's src/backend folder in your local IDE when using Git integration. Data hooks run code before or after interactions with your site's data collections. A data hook allows you to intercept the interaction immediately before or after it occurs and make changes or do additional processing.

Check out About Data Hooks and Using Data Hooks to learn more.

Where do I put code for backend events?

Many Velo modules, including universal modules such as wix-pricing-plans.v2 and backend modules such as wix-media-backend, include events that are triggered when the required conditions are met.

Examples include onFileUploaded, which fires when a file has been uploaded to the Media Manager, or onInvoicePaid, which fires when an invoice is paid.

Code for event handlers for backend events goes in the events.js file under Backend in the Public & Backend section of the Code sidebar (Wix Studio), or the Velo sidebar (Wix Editor), or in your site repo's src/backend folder in your local IDE when using Git integration.

Where do I put router code?

The code for both routers and data binding router hooks is defined in the routers.js file. You can find the routers.js file in the following locations:

• Under Backend in the Public & Backend section of the Code sidebar (Wix Studio), or Velo sidebar (Wix Editor).
• In your site repo's src/backend folder in your local IDE when using Git integration.
• In the src/backend folder in the Wix IDE (only available for Wix Studio).

For more information, check out About Routers, and learn how to create a router in Wix Editor or create a router in Wix Studio.

Where do I put HTML code?

Let's get this out of the way - adding HTML directly to the code editor is not supported in Velo.

There are however, a number of places where you can use HTML, with or without Velo:

• Work with Search Engine Marketing (SEM) using Marketing Integration.
• The html property of a text element.
• Using Embed a Site Element.
• Embed custom code snippets to the head or body of your pages.
• Using the Custom element.
• Using the Custom element and Velo.