Velo: Working in the Code Editor
You write the code for your site in the code editor at the bottom of the page in both Wix Studio and Wix Editor.
Tips:
- You can drag the code editor up from the bottom of the page to open it.
- See our list of keyboard shortcuts.
Code Editor Tabs
The code editor displays your site's code files in tabs.
How code files open in tabs depends on the type of file you are opening.
What files can I open in a new tab?
- Page Code files. Because you can't select more than one page at a time to view in the Editor, you also can't have multiple page code tabs open simultaneously. There is one tab that displays the page code for the currently selected page. Selecting a page in the Page Code section opens that page's code in this tab. When you select a different page, this same tab will display the newly selected page's code.
- masterPage.js. You can open masterPage.js alongside page code files.
- Code Files. All the files in the Code Files section can be opened in their own tab.
How do I open a new tab?
When you click a file in the Code sidebar it opens in a new tab in the code editor. When you first open a file, you'll notice that its name is italicized in the tab.
The italics means that the file has not yet been modified. That also means that if you click another file in the Code sidebar it will open in the same tab, replacing the file you first clicked.
The file name will change to being un-italicized when you either:
-
Modify the file
-
Double click the filename in the tab or the Code sidebar
Once the filename isn't italicized, if you click another file in the Sidebar, it will open in a new tab.
Code Editor Toolbar
The Code Editor toolbar is displayed at the top right corner of the code editor. You can click the icons to maximize and minimize the code editor, show or hide the Properties and Events panel, test your code in Preview mode, and display more options. The additional options include links to help content and a list of keyboard shortcuts, plus a button for switching the Velo code editor theme between light (default) and dark.
Right-Click Menu
In addition to the buttons in the code editor toolbar, you can right-click anywhere in the code editor to bring up the right-click menu and display more options.
Velo Syntax and Autocomplete
Selecting a specific element
Velo lets you code using standard JavaScript. It also has a specific syntax, or set of rules, for selecting an element on your page, which is:
1
If you know jQuery, this should look familiar. If you don't, here's what you need to know.
To select an element:
- Type $w.
- Enclose the ID of the element in parentheses and quotes.
- Add a hashtag before the element ID.
Note: You can use either single quotes or double quotes.
To make things even easier, Velo includes code completion. When you type the $, a pop-up window opens listing the elements on your page and the relevant Wix APIs.
Use the up and down arrow keys to select the element you want, and then press Enter. Alternatively, you can click the element in the list. The reference to the element is added to your code with all the necessary syntax.
Tips:
- You can press Ctrl+space at any time to view the code completion pop-up.
- Element IDs are case sensitive. '#Button1' is not the same as '#button1'.
- If you add a new .js file in Public, code completion lists the elements from the last page you were on.
You can find the ID of any element by hovering over it or selecting it. You can change the ID of any element in the Properties & Events panel.
Selecting multiple elements
If you want to select multiple elements by ID, use the same syntax as above to refer to your elements and separate each element with a comma, like this:
1
Selecting all elements of a specific type
To select all the elements of a specific type, use the ID of the element type without the hashtag, like this:
1
The ID of the element type is the name of the element as it appears in the Velo API.
JavaScript Templates
In addition to autocomplete that relates directly to Velo, the code editor also includes autocomplete for standard JavaScript templates and keywords. For example, if you type the word "for," the autocomplete list includes templates for "for statements" as well as the keyword "for." Each template includes a link to a standard JavaScript API where you can read more information.
When you select a JavaScript template, the full syntax for the template is added to the code editor. For example, if you select the "for statement," the following template gets added to your code:
1
All you need to do is to add the code you want to run in the loop.
Making Sure the Element Has Loaded Before You Reference It
When a page loads in a browser, it's possible for the code on the page to run before the page finishes loading. This can cause an error if your code tries to reference an element in the page before it's loaded.
Because of this, you need to make sure that all the elements on your page have loaded before you try to access them using code. You do this is by including all your code that uses the $w
selector in the following function:
1
This is only required if you add code on your own using the $w
selector. Any code you add to a function using the Properties & Events panel runs only after the page loads.
Learn more about $w.onReady
here.
Working with Your Elements
All of the elements in the Editor have properties, methods, and event handlers that you can use to work with your elements and add functionality to your site.
After you select an element, type a period to see the full list of these items.
Use the up and down arrow keys to select the item you want, and then press Enter. The necessary syntax is added to the end of your element selector. As you move through the options, a brief description of the functionality is displayed. Click the "Read more" link for more information.
The autocomplete pop-up also includes standard Javascript methods that you can call on your element.
Properties
Properties contain information about your elements. Some of these are read-only, while others have values you can also set.
For example, the text element has an isVisible
property that returns whether the element is actually visible on-screen. This property is read-only. The text element also has the text
property that contains the current text in the text element. This is a property you can both read and set.
Methods
Methods perform actions on your elements.
For example, the button element has a hide
method that causes the button not to appear on your site.
Some methods have additional options that affect how the action occurs. For example, you can add animation to the hide
method by specifying it in the parenthesis, like this:
1
Here also you'll need to look at the Velo API to learn all the options.
Event Handlers
Event handlers let your elements respond to user actions (events). When you add an event handler to an element, you also need to specify what you want to happen when the event occurs. You do this in the callback function for your event.
For example, let's say you have a button that says "Take the Tour" on it. You want to add functionality so that when a visitor hovers over the button the text changes to "Let's Go!". You would add code to your site that looks like this (we've added comments to explain each part of the code):
1
Don't forget that you can also add event handlers to your elements using the Properties & Events panel. Unless you have a specific reason for wanting to add event handlers manually, we recommend using the Properties & Events Panel.
Note: Event code that you add to your site using the Properties and Events panel will not work if you copy/paste it to any other page or site, even if you copy the associated element.
Warnings and Errors
As you write your code in the code editor, you may see warning and error indications. Warnings are indicated in yellow, and errors in red. The indications take the form of a colored wavy line underneath the relevant code and an icon to the left of the line number.
To view the warning or error message, hover over the icon.
Warnings
A warning in your code is an informational message that brings your attention to some code that you might want to change. Warnings do not stop your code from running and can often be safely ignored. Warnings are indicated by a yellow triangle and yellow wavy underline.
A common warning message occurs when you have an unnecessary 'else' after 'return'. This most often occurs when you use the following coding pattern:
1
If someCondition
is true, the function will return. That means that we don't need the else
to stop the code from executing when someCondition
is true
.
You can safely ignore this warning or change your code to the following pattern:
1
Errors
An error in your code means that your code will not function properly. Depending on the type of error, your code either will not work as expected or might not run at all. Make sure to fix all errors in your code before publishing your site for your site visitors to use.
Here are some common situations where you might find errors in your code.
-
Error message: "#text1" is not a valid selector (see image above)
If you change the ID of an element that you are using in some of your page code, the
$w()
selections in your code will cause errors. For example, if you have a text element with the ID text1 and you change the ID to statusMessage, all instances where you selected the element using$w('#text1')
will now be errors.
Note: you can use the Search and Replace functionality to fix this error throughout your code. -
Error message: 'import' and 'export' may only appear at the top level
When you import an API module, the
import
statement must appear at the top level of your code before the module is used. That means you cannot import the module inside a function as shown below. In general, it is recommended that you place allimport
statements on the first lines of your code, before any variable declarations and function definitions.
- In certain cases, the error indication does not appear at the point of your actual mistake, but occurs on the first line on which your mistake causes an error. For example, if you leave out the closing curly brace (
}
) in one of the functions of your page code, an error will most probably occur on whatever the next line of code happens to be. In the code shown below, a closing curly brace is missing from line 6, but the error does not occur until line 8.
Media Manager Integration
Velo allows you to use images that you've stored in the Wix Media Manager in your code. When you work with elements that include an image property, such as src
, a pop-up window opens, giving you the option to use an image from the Media Manager. This window appears automatically as you type "src".
Testing Your Code
Your code will run on your published site or test site. However, you may want to test your code before publishing it to ensure it works as expected.
You can test your code before you publish by previewing your site or creating a test site. The code runs the same in Preview Mode and Test Site Mode as it does in the published version. You may also want to debug your code before publishing to identify any potential issues.
Saving Versions of Your Code
When you save your site or your site is autosaved, the corresponding code is saved with that version of your site. If you go to the Site History and revert to a saved version of your site, the code that was saved with that version is restored as well.