Roomle Content Naming Conventions

This is a recommendation to prevent unnecessary errors and mental efforts to figure out what is happening in your content. Content creators should avoid using grammar errors in the ids or keys and should follow their common sense to write a clear and understandable code. There is nothing more annoying in coding than to having to follow that in one component you use width and in another component, someone uses Widht, so that everyone needs to remember a case difference and that they should use a typo to write a correct code.

Choosing a Good ID

All IDs should be lower case and should only contain letters, digits and underscores. If the situation requires (due to some matching of imported/exported data), you can also use capital letters, dashes and periods.

catalogId

Always include manufacturer / seller / designer / producer or tenant name of the configured product. If you need to use more than one catalog for that client, use the string as a prefix followed by underscore and then a clear description of the catalogue content.

Example:

• If you want to create one catalog with all products:

  • furnishmyhome - Single catalog of the client company Furnish My Home Ltd.

• If there are more distinctive and little related categories of the products:

  • furnishmyhome_sofas

  • furnishmyhome_shelfsystems

componentId

The external identifier part of the componentId should contain a project, configurator or product name and then a distinguishable identifier, so that it can be guessed easily which part of the configurator the component represents.

Do not include word you have already used in the catalogId.

Use root, main or master for the entry component for the configurator, so that you know which component you need to run. The other components are subComponents

Good examples for a sofa called Celeste

• furnishmyhome:celeste_main

• furnishmyhome:celeste_pillows

• furnishmyhome:celeste_legs

• furnishmyhome:celeste_longchair

• furnishmyhome:celeste_1seater

Bad exmaple:

• furnishmyhome:Base_Celeste

• furnishmyhome:Longchair

• furnishmyhome:Pillow

• furnishmyhome:Leg_Celeste

Usage of capital letters, can not keep convention if another sofa gets added to the catalog. Not clear what the root component is. Also, the product name is not the first word, which makes the file sorting to be of no use.

If you intend to use one component in more projects, you can use common or a pluralized category name to distinguish it belongs

• furnishmyhome:common_calculations for a function library component

• furnishmyhome:sofas_dockingrules for a data component that defines docking rules for all sofas in general

itemId

ItemIds should carry information on which componentId they lead to. It does not have to be equal, but the content creator should understand this from reading the itemId already. Pattern for selecting itemId:

catalogueId:projectname_partname_[distinctiveParameterValue]

Examples:

abcdesign:celeste_longchair_left, abcdesign:celeste_longchair_right (longchair_left and longchair_right are elementType values, we omit the main in itemId)

abcdesign:celeste_1seater_1200 - single seater of width 1200 (you expect that this is width in sofa elements)

shelfmasters:supershelf_frame_800_400 leads to a frame of size 800x400 (probably width x height) -} If there are more dimensions in the itemId, follow the natural width x depth x height order.

materialId

There are two main groups of materials, the ones with an article number, or affecting the article number, and the other ones that don't. Typically, upholstered products or products with a big selection of plain colors, can have a wide selection of such materials.

If the materials are relevant for a single configurator, use the product name prefix in the same way as you would use it for the item or component ids. If they are materials for a whole product range (typically: upholstery and sofa producers have a M:N relation between the sofas and used materials), do not use any prefix.

If the material affects the article number directly (with a suffix, for example), or is even its own part list entry, and this article number is same across a big product range, you can use this code as the external id of the material directly - unless it contains special characters (like space, ä, ö, ü, etc.).

Hint: For storing article number together with the materialId, you can use additional data subcomponent or material properties.

For the non-article number relevant materials, use a clear description of the physical material type, color, or other distinctive property, like plastic_black_rough, bronze_polished, wood_oak_oiled etc. If they are relevant for a single configurator, you can add a product name prefix.

meshId

The Roomle Blender addon will export the meshes with the prefixes matching the txt file and therefore will create the meshIds for you. However, care should be taken if meshes are updated, so that meshes are not overwritten in an unintended way.

tagId

The tagId doesn't add the catalogId. If the tag should be relevant for a single catalog or tenant only, we recommend adding the catatalogId: to the tagId manually, so that no mix of inter-catalog tags can occur.

Otherwise, the same logical rules for tags apply. For product tags, use plural of the product category, like mycatalog:chairs, or sofas. For material tags, you can use the price group or material line group name, like mycatalog:fabric_pg1.

Patterns for Naming Parameters and Variables in Given Situations

Situation	Prefix / Suffix / Rule	Example	Typical type and values
Can change element type to	canBe-	canBeFootstool	Boolean
Can change to a situation	can(Be)-	canBeFreestanding	Boolean
Can have accessory or neighbor of type docked	canHave-	canHaveFootstool	Boolean
Has accessory or neighbor of type docked	has-	hasFootstool, hasLegs	Boolean
Has child behind a dock mask	has{Mask}Child	hasLeftChild, hasTopChild	Boolean
Has accessory of type	{accessory}Type	legsType, handleType	String / matching with that accessory's parameter
The main type of this component	elementType	elementType	String
Is child behind parent's mask	is{Parent's Mask}Child	isLeftChild, isTopChild	Boolean
Is in a situation	is-	isFreestanding, isOnFloor, isRoot, isCorner	Boolean
Is of type	is-	isFootstool	Boolean
Situation of a [neighbor/child] behind a connection mask	{mask}[Neighbor/Child/][Is/Has/CanBe]	leftNeighborElementType, topChildHasBottomShelf, rightNeighborIsCorner	Depends on the situation
Docking mask should be allowed {=} can dock with that mask	allow{mask}Dock	allowLeftDock	Boolean
Count of accessories docked	count${accessoryName}(docked)	countFootstools(Docked), countPillows	Integer
Main component's material	material	material	Material
Distinguish between main component's materials if we can't say one of them is the main	{part}Material	countertopMaterial, sidesMaterial, frontsMaterial	Material
Material of some accessory	{accessory}Material	legsMaterial, handleMaterial	Material
Dimensions	width, depth, height, diameter, radius	width, depth, height, diameter, radius, sizeX	Decimal (!)
Position of docking points or accessories	{situation}Pos[X/Y/Z]	leftDockPosX, topDockPosZ	Decimal (!)
Base dimensions for accessories or dock placement	{situation}[Width/Depth/Height/Length]	legsBaseWidth, dockDepth	Decimal (!)
Sizes of construction elements	{part}[Width/Depth/Height/Length/Thickness]	woodThickness	Decimal (!)
Gaps or distance between, offset of first	{situation}[GapOffset]	freestandingDockGap, holesOffset, holesDistance	Decimal (!)
Any arrays	pluralized form of the elements' meaning	neighbourRuntimeIds, legPositions

Always use camelCase to separate words in variable and parameter names instead of using underscores_to_separate_words. If the identifier has an abbreviation, let only the first character of the abbreviation be uppercase, like weHaveAbcAbbreviation or abcAbbreviation instead of weHaveABCAbbreviation or aBCAbbreviation.

Language Specific Characters for Identifiers

First of all, the recommendation is to always code in English. Do not use words from other languages for parameter and value keys, unless it is a direct technical requirement from the client or to match some other data set in case of imports, etc. If the naming is up to you, always use the English equivalent of the word. If, for any reason, you need to write them in any different language, handle the language-specific characters in a way that is common to that given language, for example:

• German

  • ä, ö, ü -} replace with ae, oe, ue

  • ß -} replace with ss

• Czech

  • ignore diacritic marks ě, š, ž, ý, á, ů -} e, s, z, y, a, u etc.

This is of course not relevant for labels or string content, where you should display the texts correctly.

Naming Docking Masks

The docking masks should contain information about what can be docked behind them. Imagine it as a connector, where you specify the standard you need for the other part to connect. There can be several situations:

• You dock a part of a modular product (sofa, shelf frame) - use the same prefix of the product as you use for the componentId.

• You can dock one concrete part - use a docking mask describing the part.

• You can dock a type of accessories - use an umbrella term of matching accessories.

Use the masks as they are described above in cases where there is only one child docking point on the child side - that means that the child has only one connector and the position of the docking does not influence the child further. However, if you need to distinguish this (generally if the child is not smaller than the parent or is not lower in the product hierarchy), use words like: left, right, bottom, top, back, forward, etc. from the perspective of the parent. Example: sofamoduleLeft, where the parent docking point is on the left in the parent component and on the right in the child component. Be aware that this takes some time to get used to when you work from the child's perspective.

Warning: Because dock masks are scripts, a constant docking mask name should be enclosed in apostrophes:

    "mask": "'LEFT'"