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 Code 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 types of event handlers:

  • Dynamic event handlers (recommended)
  • Static event handlers (legacy)

While static event handlers are still supported for existing sites, we recommend using dynamic event handlers for new development.

Dynamic event handlers

Dynamic event handlers are the preferred method for handling events in Velo. You can define them anywhere in your code, and they can be copied between pages or sites as long as the target element has the same ID.

Notes:

  • If you define a dynamic event handler inside a function, it will only work once the function has been run.
  • If you define an event handler in a regular function and you run the function twice, you will get two identical event handlers, meaning the code inside the event handler will run twice when the event is triggered.

Here's a simple example of a dynamic event handler for a button click:

Copy

Tip: You can quickly add the code for some dynamic event handlers from an element's right-click menu:

  1. Right-click the element.
  2. Select Add Code.
  3. Select the event you want to add.

Note that:

  • This shortcut is not yet available to all users.
  • This shortcut is not available in Wix Editor.
  • This shortcut shows only 4 events, so the event you want to add might not be available in the menu.

Static event handlers

Static event handlers are still supported for existing sites but are not recommended for new development. They are set up using the Properties & Events panel, which you can find at the bottom of the Code panel in Wix Studio or to the right of the code editor in Wix Editor.

When you add a static event handler, Velo generates a function in your page code that looks like this:

Copy

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

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.

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

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.

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:

Copy

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

Copy

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

Copy

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

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 Code 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:

Copy

Backend File Types

Note: This section explains how to work with backend functions. Learn more about working with web modules.

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.

Note: Another suffix worth mentioning for backend files is .jsw. While these files have been deprecated and replaced by .web.js files, they're still supported.

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

Copy

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.

Copy

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 Code 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 Code 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 Code 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 Code 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:

Was this helpful?
Yes
No