With the launch of the CLI, we will start the process of deprecating the Code Editor. For a forward-looking approach, we encourage you to create all new widgets using the CLI. Read more
Step 1 - Create a new Element
Click on New Element in the Welcome Screen.
Step 2 - Give it a name
You will be taken to a vev-manifest.json file, which has a nice UI so you don’t have to edit it in raw text (and potentially get some values wrong).
Step 3 - Build and run
After clicking Run, you should see the Element Preview update accordingly
Once you click on the Run button, you will see a preview in the right panel.
Great — You’ve already created, compiled, and previewed the default custom code Element in Vev!
Wait, where do I actually write code?
You’re right. The above still technically doesn’t qualify as a proper Hello World example. Let’s take a look and figure out how to make it so (and show you around in the process).
Files & Dependencies
When you create an Element we create the necessary files for that Element to function (and for you to change it). These files include:
ElementName (Folder)
form.tsx - Contains the code to render the Elements data form (opened by double-clicking on your Element in the Design Editor mode)
index.tsx - Contains the code to render the Element. This file needs to export a function or instance of React.Component.
styles.scss - Your Elements stylesheet. The .scss filename just means we’re using the Sassy CSS syntax, which is the main syntax for Syntactically Awesome Style Sheets. You can write normal CSS here as well, but Sassy CSS offers so much more. Read more in File: styles.scss.
vev-manifest.json - Configuration file for the Element. Settings to adjust name, description, readme, default sizes, icons, and more.
package.json - Configuration file for your Element Package. Contains the name for your group of Elements and access/sharing settings.
Read more about the Developer File Structure.
Time to do some custom coding!
To see the code for your new Element, click on index.tsx.
The Index File
Once you open your index.tsx file, you will see the default standard code for Elements in Vev.
import { Fragment, useState } from 'react';
import { useEditorState } from 'vev';
export default function ({ text }: Props) {
const [count, setCount] = useState<number>(0);
const { disabled } = useEditorState();
return (
<Fragment>
<h1>{text}</h1>
<p>{disabled ? 'Disabled' : 'Enabled'}</p>
<p onClick={() => setCount(count + 1)}>Counter {count}</p>
</Fragment>
);
}
Let’s strip this down to the bare essentials. Make your index.tsx file look like this:
export default function () {
return (
<h1>Hello World!</h1>
);
}
When rendering your Element on the Canvas, Vev will take your index.tsx default export and run that function for every instance of that Element you have added.
export default function() {}
You can also write this as one of the following:
// name the function
export default function MyCustomComponent() {
return <h1>Hello World</h1>
}
// or ES6 arrow function
const MyCustomComponent = () => <h1>Hello World</h1>
// or the old familiar React component way
class MyCustomComponent extends React.Component {
render () {
return <h1>Hello World</h1>
}
}
Click Run to run your code, your widget preview should update and show your “Hello World!”.
Deploy and use your Code
Let’s deploy this as the first version, and remove that background color in the next step. Click on Deploy and write a commit message, such as “Initial commit!”.
Go to your Design Editor and click Insert. Search for your Hello World widget and draw it on the Canvas.
Adjusting the Look
By default, the container which contains your code has your main palette color set as its background color. This is defined in the styles.scss file, so let’s open that.
the :host {} rule lets you style the container wrapping your Code. The vev()-syntax enables a Style Control for that rule in the Design Editor. $primary3 refers to the Primary Colour #3 in the project’s current palette. Read Using the styles.scss file for more information on the vev()-syntax and available colors and attributes.
Let’s make our Hello World widget look a little bit nicer. Change your styles.scss to the following:
:host{
// Removed the $primary3 color from the background.
// This will make it optional and available in the Design Editor.
background: vev();
display: flex;
justify-content: center;
align-items: center;
}
h1 {
border-bottom: vev(1px solid #666);
}
Save your file, you should see your Preview update
Looks a lot nicer already!
Notice that you now have another Selector for your H1. If you go into your design editor, you will be able to adjust the border with a simple editor.
Adding Controls
Sometimes you want to say something different, Hello World doesn’t always cut it. We can make this text editable by giving the Element some controls.
Open your forms.tsx file, and you will see there’s already a TextField added by default.
There are many fields you can use to create your controls, but for now, we’ll just add a ToggleField. Change your form.tsx to the following:
<TextField name="text" default="Hello World!" />
<ToggleField name="uppercase" label="Caps lock?"/>
Save your code, and go back into the Design Editor. When you double-click one of the instances of your Element, its controls will appear.
You can try changing the values. They are saved, but nothing is happening. For something to happen, we need to use this data. Vev will send the values from the controls into the function we made in the beginning, in the index.tsx file. Open this file now.
The data, among a few other things, are sent into your function as an argument. If you add the Props type to the argument you can hover over it to see which values are coming in through the props object.
Let’s extract the two variables we need now, and use them in our widget.
The code should now be:
export default function ({ text, uppercase }: Props) {
const cl = [];
if(uppercase) cl.push('uppercase');
// In React, you need to use className= instead of class=
// Why? Read: https://reactjs.org/docs/dom-elements.html#classname
return (
<h1 className={cl.join(' ')}>{text}</h1>
);
}
and change your H1 rule in the styles.scss file to:
h1 {
border-bottom: vev(1px solid #666);
&.uppercase {
text-transform: uppercase;
}
}
Go back into the Design Editor, and double-click one of your custom Elements. Toggle the Uppercase on and watch as the text transforms into uppercase.
Make it a Section also
You can make an Element work as a Section too. When it is a section it only takes a height parameter, its width will be 100%.
Open the Code Editor again, and navigate to your vev-manifest.json file. There you will be able to set the Type to be Element, Section, or Both.
Select the “Can be added as both element and section”, and deploy your code.
Remember to Save your file when you make a change (indicated by the white circle next to the filename). Do this with ⌘+S or CTRL+S