jamovi

Hi everyone,

I'm developing a Jamovi module and trying to understand how Array-type options work, specifically looking at the `refLevels` example from the `jmv` linear regression module:
I have several questions about this structure:

1. Array Type Options
- What is the `template` property and what types can it contain?
- Are there other template types besides `Group`?
- What control types can be used in `elements`?

2. The `items` Property
I thought this creates automatic bindings, but looking at the JavaScript code, I see explicit `setValue()` calls:
If JavaScript explicitly populates the array, what does `items: (factors)` actually do? Is it just metadata, or does it provide some automatic functionality I'm missing?

3. Special Keywords
-$key: What does `content: $key` mean? Is this a placeholder that gets replaced at runtime?
-Level: The ref element uses `type: Level` - is this a special control type for factor levels?
- Are there other "magic" keywords or special types like these that are documented somewhere?


####################
The structure looks like it should auto-populate based on the factors option (via `items`), but the JavaScript code suggests manual population is required. Which is it?

Any clarification on how these pieces fit together would be greatly appreciated!

Thanks in advance!

Hi,

Thanks for reaching out.

The template property of an Array type describes what each item in that array will look like. In your example, refLevels is defined as an array of Group objects. A Group can be thought of simply as an object with specific properties, so refLevels is effectively an array of objects structured like this:

Here, var is of type Variable, and ref is of type Level. Items in an array can be any type that can normally be defined in an a.yaml file. The same logic applies to types defined in elements—the elements section describes the properties that make up a Group object.

The Level type is, under the hood, just a string. However, by declaring it as a Level type, you are signaling to jamovi that this string represents a variable level rather than arbitrary text. This allows jamovi to handle it appropriately and connect it to the levels of a specific variable.

The YAML you provided includes a few legacy properties that are no longer used. Specifically:

items: (factors)
content: $key

These properties were not removed when they should have been and unfortunately have caused some confusion. They no longer do anything and have since been removed from the current a.yaml, so they can safely be ignored.

The refLevels option is populated dynamically in the JavaScript file. Likewise, the relationship between the runtime value of the var property and the corresponding ref property is also managed in the JavaScript code rather than in YAML.

I hope that helps clarify things.

Thanks for this great explanation.
It is clear now.