The Code Component can be seen as another Component of Dot.vu, with the significant difference that its functionality is completely configurable using Web Technologies. This means you can create your Code Component to read and write Data Fields, fire Triggers, and run Actions.
You can use the component when:
- You have specific needs for styling a part of your project which can only be performed using HTML and CSS.
- You want to integrate with a 3rd party service for presenting a widget
- You want to program your own interactive widget or game
Builder and Settings
The “Setting” configuration shall be used by a Content Producer to integrate the Code Component in the Dot.vu project. The “Setting” configuration is where the Content Producer will be able to define the default values and other configuration settings defined in the “Builder”.
Reusing a Code Component
The Code Component is configured independently from the project it sits on. Therefore, if you create a Part with the Code Component, you can reuse it in any of your other (or future) projects. You can think of it like your own private Dot.vu Store for Components!
How to Configure
In this section, we are going to explain how to use the Code Component to create your own components. We will go through all the configuration options you have available to make the most of the Code Component.
Decide how to render
There are 2 modes for rendering the Code Component. Rendering means that the HTML and CSS is added into the DOM and that the JS is executed. The 2 modes are:
- Render Once: In this mode, the Code Component will render whenever the stage loads.
- Render when Data Fields change: In this mode, the Code Component will render when the stage loads (as the render once) and whenever any of its data fields changes their value.
Define Data Fields
Data Fields are the first layer of connection between your Code Component and the Dot.vu project. Although you are always free to read and write your data fields inside the Code Component, from the outside data fields can have various use cases, depending on their Read/Write options.
- Read Only: This means that the Data Field can be read from the Editor, but it cannot be modified.
- Write Only: This means that there will only be an Action to modify its value. The Data Field will not be accessible for printing/reading its value.
- Read and Write: This means that the Data Field can both be read and modified.
It is important to decide what type of Read/Write operations you allow from the outside, as they are an integral part of how your Code Component will be used in a Dot.vu Project.
Your Code Component can also export Actions that can be used by Content Producers to perform commands on your Code Component. For example, if you are creating a game, some examples of Actions could be: Start, Pause, Restart, Set Difficulty Level, Go Right, Go Left, etc.
Actions are identified by their name and can have optional parameters. Parameters are especially useful when you want to receive information together with your Actions. For instance, if you would have an Action to set the difficulty level of your game, you could define the following parameters: Game Speed, Character Speed, etc.
The final layer of connection between the Code Component and the Dot.vu project are the triggers. Triggers are used to announce the Dot.vu project that something happened inside the Code Component. Examples of Triggers are: Game has Started, User Got 1000 points, User Got the Gold Prize, User Clicked Button, Game Over, etc.
Code the Component
The HTML code is, as it says, the HTML that will be added into the DOM. You can use any kind of HTML tags inside it. It is important to refer that you can use data fields inside the HTML, which is often called templating. To use a data field inside your HTML code you would type: [[DATAFIELD_NAME]].
CSS works the same way as HTML, whenever the Code Component is rendered, the CSS code is added into the DOM. Again, you are allowed to use data field values inside your CSS code. Their syntax is the same as using a CSS Variable: var(–DATAFIELD_NAME). For example, if you have a color data field and you want to use for a background color you would type: background: var(–color);.
The datafields variable is an object containing all the created data fields from the Code Component as its keys. If you have a data field called myDataField, you would access it by typing dataFields.myDataField (or dataFields[“myDataField”]). You can then do several operations with it:
- dataFields.myDataField.get(): Gets the current values from the data field
- dataFields.myDataField.set(value): Sets the value of the data field
- dataFields.myDataField.subscribe(myHandler): Subscribes to value changes in the data field. myHandler is then called with the new value for the data field.
- dataFields.myDataField.unsubscribe(myHandler): Unsubscribe to value changes to a previsouly used handler function.
The actions variable is an object containing all the created actions from the Code Component as its keys. If you have an action called myAction, you would access it by typing actions.myAction (or actions[“myAction”]). You can then do several operations with it:
- actions.myAction.subscribe(myHandler): Subscribes to the action. This means that whenever this action is run from outside, the myHandler function is executed. Moreover, if you have added parameters to your action, the parameters would be available as arguments.
- actions.myAction.unsubscribe(myHandler): Unsubscribes myHandler from handling the action.
The triggers variable is an object containing all the created triggers from the Code Component as its keys. If you have an action called myTrigger, you would access it by typing actions.myTrigger (or actions[“myAction”]). Triggers are much simpler than actions and data fields, as the only thing you can do is to fire them. To fire myTrigger you would type: triggers.myTrigger().
To make it easier, we have created a dynamic documentation panel that lists all data fields, actions, and triggers created in a Code Component.
Defining the settings
Lastly, in order to make it easier for Content Producers to configure the Code Component, you can design its settings containing any of the created data fields.
By clicking in the “Configure Settings” button, the Settings Designer will open where you are able to define Tabs and Sections (for each tab). Each Section can then contain any of the data fields you created for your Code Component.
The settings for the Code Component are great for Content Producers to define colors, assets, and even specific features for your Code Component. If you are creating a game, some of the settings could be Avatar Image, Background Image, Number of Rounds, Max Score to Win, Speed, Colors, etc. Content Producers can, then, either fill out a manual value or bind it to another data field in the project (like a session data field).
Render in the Editor
With the Code Component, you are able to define how you want it to render in the Dot.vu Editor. There are 2 options to choose from:
- Image: In this mode, you can choose an image that is displayed in the editor.
It is reasonable to ask why wouldn’t the “Full Code” mode be the only way to render in the editor, as it would have the highest grade of fidelity compared to its live version. There are multiple reasons for choose “Image” mode over the “Full Code” mode:
- Your initial Code Component display state is blank or does not represent its normal state. For example, if you are creating a game, the initial state might be just a “play button” or an empty screen. Only when running a “Start” action you would see the game screen. In this case, in the editor, you would just see a blank screen.
- Your Code Component initialization process is slow and not prepared to run multiple times. Because in the editor, your Code Component can be run lots of times when changing its data field values (colors, texts, etc), this might affect the Editor’s performance.
- Your Code Component is clashing with input events from the editor. In this case, you might be listening for keyboard/mouse events that could the editor to become unresponsive.
- Your Code Component initial render might be distracting Content Producers. If your Code Component is rendering a video or playing an animation, that would not be suitable to render in the editor as it would be distracting users working in the editor.
To change the render in the editor mode, go to Build Settings, and select which render mode you want to use.
In case you use the “Image” mode, select an image that represents a ratio for how the Code Component will look when rendering live. This will help Content Producers design the layout around it.
Locking the Code Component
As mentioned earlier, the Code Component is to be used by 2 types of users:
- Developers: use the Build Settings to program the Code Component (HTML, CSS, and JS)
- Content Producers: use the Settings to configure the Code Component (Define colors, texts, etc)
In order to keep a separation of concerns, developers have the possibility to lock the Build Settings so that Content Producers cannot have access to it. This reduces the probability of mistakes happening.
If your account is part of an Enterprise, you might want to publish a template that features a Code Component. In this case, you don’t want other accounts to be able to change the functionality of the Code Component, but only to style it and configure it for their use cases.
How to lock the Code Component
To Lock your Code Component, go to the Build Settings and click on the ACL Setting, in the top bar. After locking the component you need to specify which account will have access to the Build Settings. Again, if your account is part of an Enterprise, you might only allow users on your account to access the Build Settings.