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:

Wix Editor:

• In the Velo sidebar, select the Page Code tab for frontend code, or the Public & Backend tab for backend code.
• In your local IDE with Git integration, in your site repo's src folder.

Wix Studio:

• Frontend code: In the Code sidebar, select the Page Code tab for page code files, or the Global Code tab for code that runs on every page.
• Backend and frontend code: In the Wix IDE, in the src folder.
• Backend and frontend code: In your local IDE with Git integration, in your site repo's src folder.

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.

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

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

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

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.

Copy Code
$w.onReady(function () {

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

});

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.

Copy Code
$w.onReady(function () {

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

});

export function myButtonWasClicked(event) {

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

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.

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 to the right of the Code panel (Wix Editor) or at the bottom of the Code panel, beneath the Code editor (Wix Studio).

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.

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

Cut and Paste with Static Event Handlers: You can't cut and paste the code for static event handlers between page files or sites, even if the button or page element has the same name. You must set up the event handler using the Properties & Event panel, for it to respond to events. To learn more about how to wire events with the Properties & Events panel, click here.

If you have code that you want to run on every page, put that code in the masterPage.js file, which you can find in the Page Code tab of the Velo sidebar (Wix Editor), in the Global Code tab of the Code sidebar (Wix Studio), in the src/pages folder in the Wix IDE (Wix Studio), or in your site repo's src/pages folder in your local IDE with 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.

Note: Don't import functions from masterPage.js into the code files of individual pages. Doing this will cause the onReady function in masterPage.js to run twice on that page. If there's a function that you want to use in the code for multiple pages, see the following section.

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.

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 as follows:

Wix Editor: In the Velo sidebar, under Public:

Wix Studio: In the Wix IDE Explorer, in the src/public folder.

Whether you are using Wix Editor or Wix Studio, you can also access your site's public files in your local IDE with Git integration, in your site repo's src/public folder.

Notes:

• Your page code, which is also publicly accessible, does not appear in public files.
• Public files can access some page elements and $w functions. However, the behavior is inconsistent across pages and it is not recommended.

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. 

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

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:

Copy Code
import { myFunction } from 'backend/aModule.jsw'

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

Copy Code
import myFunction from 'backend/aModule.jsw'

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

Copy Code
(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.

Copy Code
import wixData from 'wix-data';
import wixStoresFrontend from 'wix-stores-frontend';
import wixMembers from 'wix-members-backend';

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 as follows:

Wix Editor: In the Velo sidebar, under Backend:

Wix Studio: In the Wix IDE Explorer, in the src/backend folder.

Whether you are using Wix Editor or Wix Studio, you can also access your site's backend code files in your local IDE with Git integration, in your site repo's src/backend folder.

When you define a function in a .jsw 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:

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

Note: This section explains how to work with backend functions. If you're using Wix Studio, learn how to work with web methods.

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

• .jsw 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:

Copy Code
Access to backend script 'backend/new-file.js' denied! Client-side scripts can only import web-modules (.jsw) 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 .jsw file, and then import the .jsw function into your page code.

When you use a backed 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.

Copy Code
//In your page code:
import { myBackendFunction } form 'backend/aModule.jsw'

export function myFrontendFunction() {

    // await
    const myVariable = await myBackendFunction();

    //.then
    myBackendFunction()
        .then((response) => {
            const myVariable = response;
        });
}

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 Code Files section (Wix Editor), in the src/backend folder in the Wix IDE (Wix Studio), or in your site repo's src/backend folder in your local IDE with 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.

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 Code Files section (Wix Editor), in the src/backend folder in the Wix IDE (Wix Studio), or in your site repo's src/backend folder in your local IDE with 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.

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 Code Files section (Wix Editor), in the src/backend folder in the Wix IDE (Wix Studio), or in your site repo's src/backend folder in your local IDE with Git integration.

The code for both routers and data binding router hooks is defined in the routers.js file under Backend in the Code Files section (Wix Editor), in the src/backend folder in the Wix IDE (Wix Studio), or in your site repo's src/backend folder in your local IDE with Git integration.

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

Let's get this out of the way - adding HTML directly to the code panel 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.