Code Component

Introduction

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 3^rd party service for presenting a widget 
• You want to program your own interactive widget or game 

Concepts

Builder and Settings

The Code Component has a “Builder” configuration and a “Setting” configuration. Only programmers with knowledge of Web Technologies (HTML, CSS and JavaScript) should use the “Builder” configuration. 

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 Building Blocks 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. 

You should use the Render Once mode whenever you want to have full control on how your Code Component behaves. Any updates to the HTML and CSS must be done manually. Moreover, because your JavaScript code only runs once, you can use it to keep the internal state of your Code Component. If you plan to create a game or a more intricate application, this is the mode you should use. 

The Render when Data Fields change will always execute the HTML, CSS, and JavaScript every time a data field changes. Therefore, this mode is much simpler to use than Render Once. For instance, if you have an HTML that prints a data field value, the value in the DOM will update automatically without any JavaScript involved. This, however, comes with a drawback. Because the Code Component will execute your JavaScript code every time a data field changes, if your initial load is heavy, this can slow down the performance of your project. Also, because JavaScript is executed every time a data field changes, you cannot use it to store the internal state. This mode is perfect for simpler UIs where JavaScript is only used to handle Dom events. 

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. 

Define Actions

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. 

To act upon Actions, you need to subscribe to them in the JavaScript code, which will be described later in this article. 

Define Triggers

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

In this section, we are going to explain the specific implementation details on how can you use HTML, CSS, and JavaScript to interact with Data Fields, Actions, and Triggers.

HTML

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

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);. 

JavaScript

The JavaScript code is the most complex, but also the most powerful part of the Code Component. With it, you are able to interact with the DOM element (from your HTML), with data fields, triggers, and Actions. To interact with these, there are several global variables available, which are described next. 

root

The root variable is the ShadowRoot of your Code Component. Since the Code Component is appended into the Dot.vu page as a ShadowDOM, you cannot access your inner elements using the window.document global variable. To do so, you will need to use the root variable accessible through your JavaScript code. For example, if you would like to get an element by id you would need to type: root.getElementById(‘my-id’). 

dataFields

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. 

actions

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. 

Triggers

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(). 

JS Docs

To make it easier, we have created a dynamic documentation panel that lists all data fields, actions, and triggers created in a Code Component.

For each one of these, you can see a snippet of code for each available method. You are welcome to copy and paste the snippets into your JavaScript Code and fill out the values/handler functions. The JS Docs is accessible when focusing on the JS tab.

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:

• Full Code: In this mode, the Code Component will render running your HTML, CSS, and JavaScript Code. Exactly the same as it would in a live page.
• 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:

1. 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.
2. 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.
3. 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.
4. 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.