Documentation

# Environment Setup for Scripting Roomle Content

This document will guide you to setup your environment for the effective scripting of Roomle content.

If you find any inaccuracies in this document, something is not working or you have a problem you need to solve, please, don't hesitate to tell us!

# Visual Studio Code

VS Code a modern, open-source and extendable code editor, which actually has only little in common with Visual Studio. We recommend using it for content creation, because we've prepared a formatter extension and an extensive snippet codebase. We have decided to prepare those tools for VS Code because it is easy to extend, works on most common platforms and we think it is just good. At the moment, we do not have any intention to adjust another code editor. We require our content development contractors store all data in GIT after, in a formatted shape, rendering the VS Code as mandatory for internal and contractor use.

You can get VS Code here: https://code.visualstudio.com/

Please, always open the same working folder so that we keep our offline loader snippets (explained further) unified for the use by everybody involved.

The purpose of this document is not to give you a manual for VS Code. So shortly, as opposed to other editors: Everything you do in VS Code is a command, where not all commands have UI features like buttons etc. To start typing a command, press Ctrl+Shift+P or Cmd+Shift+P to invoke the Command Palette. Please, see internet tutorials to learn the features of the editor by yourself.

# VS Code Extensions

There is an extension menu in VS Code. To open it, click on the squarish button on the left black bar, the 5th from the top. We recommend installing and using the following extensions:

Essential

  • Live Server https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer - essential for testing content, unless you have another means of having a local HTTP server.

  • VS Code Extension: Roomle Json Formatter - our extension, which currently is not in the marketplace. Please, see the entry page in order to get it. With it you can format scripts which helps you with discovering some errors. The current version is 0.4.2. For further documentation, please see its read me file. ** IMPORTANT: ** If you update from a version lower than 0.3.2, you must uninstall the old plugin first

To get the extension, download the latest VSIX file in the plugins folder and run command Extensions: Install from VSIX and select the downloaded file. The extension will appear in the VS Code extensions.

Auxiliary

Some useful extensions from the VS Code marketplace we use as well.

  • Prettify JSON https://marketplace.visualstudio.com/items?itemName=mohsen1.prettify-json - a code formatter for JSON, usage is by running the Prettify JSON command.

  • highlight-words https://marketplace.visualstudio.com/items?itemName=rsbondi.highlight-words - keyword highlighter. Allows you to select a piece of text and have all its occurences highlighted. Usage: commands containing Highlight.

  • Edit csv - renders CSV files as tables

  • Raindow CSV - colors CSV files' columns

# Code Snippets

Code snippets are pre-scribed pieces of code that will help you with writing the code, providing suggestions to autocomplete what you're typing at the moment. If you start typing and the editor finds a match with the snippet identifier, it will allow you to autofill the snippet by selecting the snippet with up/down arrow keys and pressing the Enter/Return or Tab key. Some of the snippets will move the cursor into a grey-marked area, typically inside of a function.

We have prepared code snippets for the Component and Configuration JSON structure, all the identifiers start with roomle - if you start typing roomle, parameter or component, it will offer you to use the code snippets, pre-scribing the code for you. Sometimes, the snippets have marked positions for the cursor with default values, through which you can cycle with the Tab key.

# Code Snippets Installation:

Open file with snippets:

In VS Code open the Command Pallete (Ctrl+Shift+P or Cmd+Shift+P), start typing snippets and soon you should be able to select Preferences: Configure User Snippets. Then, select json.json file, containing snippets for Json files. You can overwrite this file with the snippets file or add our snippets to yours. The snippets will start working after you've saved this file.

# JSON schema

JSON schema will provide you with code completion and validation of the Component's JSON structure. To use the schema, run the Preferences: Open Settings (JSON) command and add the following JSON entry:

"json.schemas": [
    {
        "fileMatch": [
            "*.json"
        ],
        "url": "https://www.roomle.com/e/roomle.schema.json"
    }
]

Note: You can also apply the JSON schema for a specific folder only, using: "fileMatch": ["C:/somepath/*.json"] instead.

Keep in mind, that the schema needs a valid JSON to work, and you invalidate JSON by using a newline in a value. To fully utilize the capabilities of the schema, use our formatter plugin commands (Un)Escape Multiline JSON values.

# Loading Component Definitions from Local Drive

To speed up the component testing process, you can load the components from the harddrive with one click. It needs some preparations, though. We will be using the Chrome Browser, where we open the console. Internet browsers usually do not have access to local files for security reasons, so we need to run a local HTTP server that will provide access to the file system.

1. Run Local HTTP Server

If you do not have any, best install the Live Server extension. Open your working directory (this is important) in VS Code and run Live Server: Open with Live Server. It will open a browser page displaying files you have in the working order.

2. Navigate to the High Speed Configurator Test Site

Ih Chrome, open https://www.roomle.com/t/configurator-testing/

3. Open Chrome Development Console

With the Ctrl+Alt+I or Cmd+Option+J, you will get to Chrome developer view (where you also see the kernel output console, which we recommend having always open in the configurator). Navigate to Sources > Snippets in the developer tab. The snippets must be unfolded in the left part of the menu. Press the new snippet button and insert the code from the file snippets/Chrome_LoadLocalComponents.js.

It will look like this:

You should save snippets for each project you will be working with, in order to quickly switch between the projects.

3. Add component file paths

Insert the components of your project you want to load. They need to have address somewhere in the HTTP server (that's why it was important to open a working folder in VS Code - supposing you are using Live Server) - they will start with the URL of the local server. The file names are in apostrophes and divided by a comma, last entry can not end with a comma.

NOTE: If you are not sure, you can copy the link from the page that showed up in your broswser when you had started the Live Server.

4. Navigate to the test site and run the snippet

Navigate to the Roomle configurator test site (opens new window), run the script by pressing the play button in the bottom right corner of the code view (at the bottom right corner in the image above). It will load the components from the files and run the last component in the list.

Advanced: Notice the argument of the loadConfiguration function at the end of the script. You can change it to any inline configuration JSON (identical to item definition) or componentId, like: RoomleConfigurator.loadConfiguration('{"componentId":"someCatalogue:someComponent","parameters":{"someKey":"someValue"}}');

NOTE: It is better to refresh the whole page before reloading the scripts. If you are not sure the component was updated, check caching of the HTTP server or restart the server (Live Server: Stop Live Server command).