This is not only formatter and language support extension for creation of Roomle Rubens Configurator components, but also a development environment which provides further functionalities. Read through this file to learn about features and tools this extension provides.
Features and Documentation
All commands start with the Roomle: label or roomletool. key prefix. All settings start with Roomletool and can be filtered.
RC-JSON Language Support
The extension provides a new language, the RC-JSON. If a JSON file is open, the language is automatically switched if the file is in a parent folder of a name components and there is a folder called content in the path. This can be changed in the settings under Open JSONs as RC-JSON setting.
The RC-JSON language is proprietary and is derived from the JSON. It differs mainly in using newlines in string values, which is not a defined JSON feature and therefore, all JSON features break. However, if you wish, you can still apply operations for JSONs provided by VS Code or other languages, if you switch the language between the JSON and RC-JSON using buttons in the status bar that say >JSON and >RC-JSON. This converts the component definition by switching newline characters to \n and back and switching the language.
- Note: The native language switch using the language panel will not work. VS Code treats the language change in the same way as file opening, which is already used to autodetect, if the file is a Roomle component definition. This causes immediate switch to the RC-JSON language.
If the language is switched to RC-JSON, problem panel shows static code errors, syntax highlighting, formatting and code snippets are provided.
You can control most of the extension features using VS Code commands from the Command palette (Ctrl+Shift+P / Cmd+Shift+P). All commands provided by this extension start with Roomle in the label or roomletool in the key. All settings also start with the roomletool
You can format code by using the key combination to format a document (Alt+Shift+F or Cmd+Shift+F) or with RML-format button at the lower right corner in the status bar, if allowed in the Show format button setting or automatically on file save if Autoformat on save mode is set. Formatting applies formatting both to the JSON structure and to the values of the script or expression type in the component definition.
There is another format mode, the normalize operation. This applies the formatting as usual, but also sorts the attributes of all objects in the JSON in an unified way, so that versioning systems do not show a change of order as a difference. This highly declutters work and is a recommended operation before every commit. You can normalize by the key combination (Alt+Shift+N or Cmd+Shift+N), automatically on save depending on the Autoformat on Save setting or with the RML-norm status bar button if Show format and normalize button is set. Normalizing also removes attributes with empty string, array or object values.
The squash feature can be used to minify the scripts and expressions, considerably lowering file size. This removes all non-semantic whitespaces, but keeps newlines, comments etc. In certain cases, this can reduce loading times of the Rubens configurator (less download size, less parsing). This operation is fully reversible by formatting. You can squash using the Roomle: Squash component JSON command.
The deformat feature goes further than the squash. It removes all newlines from the code and effectively minifies the scripts. Since the newlines are removed, this operation is partially reversible with the rescript operation. You can deformat with the command Roomle: Deformat component JSON_`
The rescript feature removes all newlines and returns them after semicolons, opening and closing braces etc. This partially reverses the deformat and is highly useful when analysing components that are generated, like the ones that are converted from the IDM data.
You can mass-apply the format, normalize, squash, deformat and rescript operations from the file explorer of VS Code by right clicking a folder that is called components. A prompt will show, where you can write comma-separated list of those operations. In such a case, a MASS PROCESSING label shows at the right end of the status bar. If there are many components or it takes a lot of time, a progress counter is displayed next to it. You can also use Roomle: Run a modifier on all components in current workspace
If a blank file is open in the RC-JSON language, a simple component definition is scaffolded. If you want to create a new component, simply create a file in a components folder and call it with the externalId part of the id and use the .json extension.
Component definitions will fill the VS Code native code outline for an easy navigation through the file. You can tag code by using a #tag ${tag name} comment in a script to display it as an outline entry. You can mark your individual features in the code like this. You can create code folding regions by using the #region ${region name} / #endregion comments. The begin of the region is shown in the outline, as well as the TODO and FIXME words in the comments.
Autocomplete works in three ways: The autocomplete for the JSON structure, autocomplete for RoomleScripts and code snippets.
- To use autocomplete for the JSON structure, apply the formatting first and then start typing the attribute key. Do not write the commas, they are already included in the autocomplete results and are therefore enetered automatically for you. The autocomplete will show possible attributes based the cursor position in the component definition.
- Autocomplete for RoomleScripts analyses the whole component for identifiers and functions you already have in the current component definition. There is a documentation about origin of the entry in the dropdown with the autocomplete entries. All used identifiers are shown in all scripts, including unavailable
_. context keys etc. This will be improved in undisclosed future.
- Code snippets provide native RoomleScript function calls. In some cases, it will insert more than just the function in order to help you with the coding as much as possible.
- Autocomplete also provides content labels of parameters, parameter groups and value objects in the preview. You can set the preferred
Autocomplete Label Language in which those labels are shown.
If you are using loader snippets or single line comments pose a different problem, you can set Convert Single-Line Comments to Multi-Line Comments to convert all // style comments to /* */ style comments.
Analysis features
Extension provides content analyses messages in the VS Code Output channel under the name roomletool. You can activate it in the menu View / Output and then switch to it using the dropdown at top right corner of the output panel. Errors, analyse results and error messages coming from a mass operation are printed there. Certain commands that print out results to the channel automatically open the channel. There is a setting Show Output Channel on Start of VS Code.
Errors and problems are shown in the Problems panel. The list of the errors is updated after every format operation or on file open. A red highlight will appear at the position of where the error happened, if the position is relevant and available.
If you are not interested in seeing certain problems, you can ignore errors by their error code in the Ignore Error settings.
To show a dependency tree of your current open component, you can use the Roomle: Get SubComponent Dependencies command, which will print out a dependency tree to the output channel. You can also use Roomle: Check Component Dependencies with Script Analyzer command to run the code check. The dependencies include subComponents and possible children with componentId and itemId. Item definitions should be available in the json files or in the general items response file, which you can get by downloading data from the Rubens Admin (see below).
- Warning: If you are using the
requestDockItem function to dock a component which can not be accessed via subComponents or possible children, you should add all possible dependent components into the possible children list with a false condition.
Content Project Settings (Metadata)
- The current content project settings are stored in the
./content/metadata.json file. This files contains tenant information for accessing Rubens Admin, projects compilation settings and server-side settings for the Rubens Local Content Server.
{
/*
* Set tenant account name under which the catalogs reside in the Rubens Admin.
* If missing, your workspace folder name is used.
*/
"tenant": "your_tenant_accound_name",
/*
* If you hold catalogs that reside in different tenants, you can define
* a different tenant account for each of those catalogs. Drafts of the
* catalog are also affected.
*/
"catalogToTenantOverride": {
"someCatalog": "another_tenant_account_name"
},
/*
* Information about individual projects for compilations, which means
* building a ready-to-upload ZIP file.
*/
"projects": [
{
/*
* List of target catalogs of the compiled project. If used, all items'
* and components' catalogIds will be changed. If more are defined,
* one copy for each of those catalog entry will be generated.
* This is useful if you want to publish to a draft.
*
* Cross-catalog component dependencies are not supported - everything
* will end in one catalog.
*
* Other content than items and components is unaffected.
*/
"compileCatalogs": ["your_catalog", "your_catalog_draft6"],
/*
* Define your project entry components. Dependencies of the components
* will be crawled and necessary IDs are collected.
*/
"rootComponentIds": [
"your_catalog:shelf_root",
/*
* if unreachable through possibleChildren or subComponents, like
* when using requestDockItem, add them to this list
*/
"your_catalog:component_docked_by_request"
],
// project label to show in the list. If undefined, first root componentId is used
"name": "Nobilia - minifabrik",
// If true, will be preselected in the list or target of the quick build command
"quickBuild": true
}
],
// Server side settings for Rubens Local Content Server
"contentServer": {
// Change in the files of matching patterns will not trigger hot reload.
"excludedComponentIdPatterns": ["templates:*"],
// Server port to use.
"port": 55002
}
}
Rubens Admin interaction features
If you have projects defined in your metadata.json file, you can use the Roomle: Compile Projects for Upload to Rubens Admin or Roomle: Quick Compile Marked Projects for Upload to Rubens Admin to quickly build a ZIP file with components and CSVs which you can drop into the components section of the target catalog.
- You can also use this without setting the project in the metadata. Then, the currently open component is taken as the root component.
- You can build the project using the first of the two presented commands. A selection will show up, giving you the possibilities to select what should be bundled.
- All projects flagged with the
quickBuild will be preselected.
- When you confirm the operation, a pop up will show in the lower right corner once this is finish. You can open the import/export page of the target catalog, reveal the folder in the file explorer or both.
- By default, the target folder is
_upload in your open project. You can change this in Compile Output Path to a different path, absolute or relative (i.e. ../_uploads)
- The second preseneted command (Quick Compile) automatically performs all the above mentioned steps without any further action. Projects marked with the
quickBuild will be compiled.
When using the compile project commands, you can change the catalogId using the target catalog lists. If these are present in the project settings, all components and items will change the catalog to the target catalog. You can build more copies into different catalogs at once. If this is used and components and items are from multiple catalogs, all will end up in the single target catalog.
Another option to prepare components upload ZIP file is via the right click at the context menu of components folders in the file explorer. You will be prompted to define a prefix by which all components should get into the bundle. You can use nothing to target all components. In the second step, a regex based on the previous step is created. You can use this to further modify the components selection. A ZIP file will be generated in the catalog folder, containing a components uploader CSV and the component JSON files. Maximum limit of files count can be defined in the Max Components in ZIP setting. If this limit is reached, the payload is split into more ZIP files. As of 2024, Rubens Admin should be able to accept even huge payloads of components. Adjust this as needed.
Similarly, you can prepare an items upload CSV file in the right-click contenxt menu at a folder called items. A CSV with the item_id and configuration column will be generated.
You can define the tenant account name for your open project using the Roomle: Set tenant account for this project. This will set the tenant value in the metadata.json. Similarly, you can set a catalogToTenantOverride using the Roomle: Set tenant account for catalogue of current open component command. If you don't do this, your workspace parent folder name is used as the tenant account in all operations that open Rubens Admin entry pages in the web browser.
If a component JSON file is open, you use Roomle: Open Import/Export page of the current component's catalogue to open the uploads section of a catalog in your web browser.
If a component JSON file is open, you can open its Rubens Admin page by the Roomle: Open component definition entry in the Rubens Admin command. If you use this often, you can enable a button in the status bar with this function with the Show Open Component in Rubens Admin Button setting.
Hovering over an ID in the code will attempt to guess the type of the ID and offer you a possibility to open the Rubens Admin item, material, component or mesh entry from the mouse hover. ComponentIds also offer you to navigate to the their component definition JSONs in a new tab of VS Code.
You can download components and items from a catalogue from the Rubens Admin with the Roomle: Download catalogue data command. You will get prompted for the catalogId and then you get prompted, if you want to fill your components and items folder with the JSON definition files. Because this overwrites your existing files, you have to type in yes in another step to confirm that you know what you're doing and accepting a possible loss of your working changes by overwriting the files.
The Download Catalogue Data will also download so-called catalog response JSONs. Those are useful when sideloading content. Those are the same files as those you'd download by exporting JSONs in the catalog import/export section. However, since they are using the public access, they do not contain labels but the english labels and also no prices.
Configurator interaction features
- If a component definition JSON file is open, you can open the component in configurator in the web browser using Ctrl+Alt+R or Cmd+Alt+R. If neither RubensCLI nor the Rubens Local Content Server is running, it will be open in the live configurator using the live version of the component in the live catalog. You can set the
Configurator URL and the init data Configurator Arguments in the settings.
- If RubensCLI or Rubens Local Content Server are running, the open component in configurator command opens the current local version of the component definition in the browser.
Rubens Local Content Server
The Rubens Local Content Server is a way to load your current working data in the configurator. It is a server running at localhost with a defined Rubens Local Content Server Default Port Number setting, which serves an index.html file and JavaScript files that manage a local configurator instance with a local content.
Currently, the RLCS supports sideloading of component, item and material JSON definitions from your content folder. If either of those three assets are requested by the configurator and the asset file is found at the expected path based on its type and id, the file is loaded to the configurator instance.
The RLCS supports the following file structure. This structure is strict and if files are misplaced, they will be ignored.
{project-root}/ <--- your working folder
├── content/ <--- folder storing all catalogs
│ ├── {catalogId}/ <--- folder with name matching a catalogId
│ │ ├── _responses/ <--- created by the Download Catalog Data command, optionally git-ignored
│ │ │ ├── catalogId_allItems.json
│ │ │ ├── catalogId_allTags.json
│ │ │ ├── catalogId_catalog.json
│ │ │ ├── catalogId_components.json
│ │ │ ├── catalogId_materials.json
│ │ │ └── catalogId_textures.json
│ │ ├── components/ <--- folder with component definitios
│ │ │ └── *.json <--- component definitions as JSON files
│ │ ├── items/ <--- folder with component definitios
│ │ │ └── *.json <--- item definitions as JSON files
│ │ └── materials/ <--- folder with component definitios
│ │ ├── {materialId_1} <--- folder with the same name as the externalId of the material
│ │ │ └── data.json <--- material definition as JSON file (must be called data.json)
│ │ └── {materialId_2}
│ │ └── data.json
│ ├── {catalogId}_draft{N}/ <--- draft catalogs are handled as any other catalog
│ │ └── ...
│ ├── {anotherCatalogId}/ <--- another catalog in its own folder
│ │ └── ...
│ └── metadata.json <--- data about the project and RLCS server-side settings
└── rubens_content_server/ <--- override RLCS local files and settings; see docs below
Example data paths relative to your {project-root}:
- component
sofas:exampla_main: ./content/sofas/components/exampla_main.json
- item
sofas:exampla_corner: ./content/sofas/items/exampla_corner.json
- material
sofas:leather_325: ./content/sofas/materials/leather_325/data.json
Component definition will be scaffolded for you when creating a new blank file. For an example item and material definitions, reach out to the response files. Every entry in the items or the material array should be one file.
Multiple instances of the RLCS can be created as long as the server is open at a different port number. If you need to use more projects simultaneously, you can set their port numbers in the metadata.json path under contentServer.port setting.
The RLCS can start and end using the Roomle: Start Rubens Local Content Server and Roomle: Stop Rubens Local Content Server commands. The server can start automatically based on the Automatic Rubens Local Content Server Start setting. By default, the server will start automatically as long as you have your port defined in the project metadata.json file and the port number is different from the default port number of the settings.
Server will run on the address http://localhost:{port}. You can add initData arguments behind it, therefore your address could look like: http://localhost:55000/?id=component@your:component&highlighting=always. To launch a component, just open a component definition and use the Roomle: Run Configurator with current componentId (which is assigned to defualt hotkeys Ctrl+Alt+R) or use the server address with an id argument.
If you save a component, item or material definition time, the content server will send a message to all open browser to clear the configurator cache and reload current running configuration. There is a Rubens Local Content Server Reload Collision Timeout value in the settings which ensures that unnecessary high amount of reloads is triggered at once. File save operation will trigger a reload even if the file is unchanged.
You can ignore certain components by their ids from being watched for changes in the metadata's contentServer.excludedComponentIdPatterns. Use a componentId with a * wildcard to represent any substring.
You can expose client-side source into your working directory using the Roomle: Get Rubens Local Content Server Local Files. This will offer you to download the files from the extension package. If a file is non-existent in your working directory, it will be taken from the package. Those files include:
index.html: Entry file at the client side.favicon.jpg: Web browser title icon.roomleconfigurator.js: Contains core client-side logic, like instantiating configurator, receiving events, etc.utils.js: Helper functions used by the client-side logic.settings.project.js: Project-relevant settings. Use to fill in your configurator ID, launch componentId/itemId, content modifiers etc. This file should be included in your version control.settings.user.js: User-relevant settings. Exclude this from version control (gitignore etc.).- All those files contain further documentation in their comments explaining how to use them. 3 levels of settings are merged in the following priority: user > project > fallback, where fallback contains a minimum working setting for the configurator.
- You can modify all those files based on your needs. However, keep in mind, that the files might undergo breaking changes and that you might have to download the files from a newer extension package and reimplement your changes.
Components can be modified during the sideloading. See the settings.project.js file. You can define a setting in the settings object and use it in the applyComponentModifier function.
The Rubens Local Content Server client has some extra functions to the standard configurator implementation. Those include:
- Configuration:
- Show: Calls
await RoomleConfigurator.getCurrentConfiguration() and pretty-prints it into a new tab. The children arrays are also moved to the end of the objects to improve legibility as opposed to the default getCurrentConfiguration call.
- Copy: Like show, but puts the configuration string into your clipboard. Also stores the configuration into an internal variable for later retrieval.
- Paste: Gets the stringified configuration from the clipboard and calls
RoomleConfigurator.loadConfiguration({clipboard});.
- Paste Last Copied: Pastes the last configuration that has been copied using the Copy button. Useful if you put something else into the clipboard in the meantime. This is reset with the client page refresh.
- Part List:
- You can retrieve the last part list status coming from the
onPartListUpdate callback in the (window.)RoomleConfigurator.partList value.
- Show: Shows the prettified part list as JSON in a new tab.
- Copy: Copy the part list to the clipboard.
- Display: Displays the part list content in the background of the configurator. This is useful for seeing how the part list reacts to the changes in real time. Part list entries show their componentId and runtimeId and are colored red if the entry contains either of
settings.partListWarnKeywords.
- status: If part list contains a substring (JavaScript
substring function implementation, case sensitive) defined in client settings at settings.partListWarnKeywords, a red warning shows. This means there is either a value, articleNr or label present with such a substring. Green OK shows if no such word is contained.
- Random Interaction:
- This is useful for quick testing.
- Once: Collects all possible values of all parameters of all components and the global context in the configurator scene, randomly chooses one value and sets it. Selected parameter and value is shown in the label next ot the buttons.
- Loop: Does the same in a loop in an interval defined in the
settings.randomInteractionsLoopInterval (3 seconds by default). You can watch as the configurator changes or for console errors (no further functionalities are implemented at this point).
- Scene:
- When you select a component, its component and runtime ids are shown in the label inside the scene.
- Based on the
watchers in the setting files, you can display certain parameters with matching keys of components with matching ids. See example in the settings.project.js file. This can show values of visible parameters of the selectable component, not its subComponents. Improvements to this function will be made in an undisclosed future.
Component Modifiers can be used to inject some code to the components on the fly. We provide two basic ones, where you can use a debugGeometry next to the standard geometry and they are merged together (debugGeometry is not a Rubens feature, it is ignored in live data - you can safely keep it in your component definitions, although it adds to file size). Another modifier is to display parameter keys in front of parameter labels and values of valueObjects in front of their labels. This is highly useful in development. More modifiers will come in the next versions of the extension. You can also write your own modifier, where the function provides a component definition as a JSON object which you can process using vanilla JavaScript.
Rubens CLI integration
- Because of development of the Rubens Local Content Server, RubensCLI will be deprecated and will be kept as it is. You can, however use the
Roomle: Install Rubens CLI and Roomle: Update Rubens CLI commands to use it. Support for RubensCLI, including handling of its lockfile, will be deprecated in undisclosed future from the VS Code extension. If RubensCLI stops working due to release of a major update of any dependency or the Roomle product, it will be removed in the next version of the extension.
Errors and Feature Suggestions
If you have any suggestions or find any errors, we'll be glad Roomle ServiceDesk.
| |
