8.4 Parameters and getParameterDefinitions
SLO 3
Describe, design, implement, and test structured programs using currently accepted methodology.
Learning Objectives
By the end of this section, you will be able to:
- explain what makes a JSCAD script parametric;
- write a
getParameterDefinitionsfunction that builds a live control panel; - read parameter values back inside
main(params); - choose the right parameter type for each control;
- group related controls under a panel divider.
A JSCAD script becomes parametric — driven by a live UI panel instead of hard-coded numbers — by exporting a second function alongside main: getParameterDefinitions(). When present, the host app builds a parameter panel from its return value and calls main(params) with the current values every time a control changes.
A parametric script is one you can tweak without editing code. The parameter panel turns your numbers into sliders and boxes, so you (or a user) can change the model live and watch it rebuild.
const { cube } = require('@jscad/modeling').primitives
const getParameterDefinitions = () => {
return [
{ name: 'size', type: 'number', initial: 20, min: 5, max: 100, step: 1, caption: 'Size (mm):' }
]
}
const main = (params) => {
return cube({ size: params.size })
}
module.exports = { main, getParameterDefinitions }
main builds the geometry; getParameterDefinitions builds the controls. The host app calls getParameterDefinitions once to draw the panel, then calls main(params) again every time you move a control, passing the fresh values.
Making a script parametric
To make a script parametric, you add a getParameterDefinitions function that returns an array of control definitions, and you change main to accept a params object. Inside main, you read each value back with params.<name>.
The name field is the link between the panel and your code. Whatever you name a control, you read it back as params.<name> — so the name you choose in the definition must match the name you use in main.
The core of a parametric script is the link between a control in the panel and the value read inside main(params). Build the simplest version: one number control named size that drives a cube. Each comment below is one line for you to write. Press Run when you are done.
Solution
You should see a 20-unit cube, and a panel with a Size (mm) box. Type 30 into it and the cube grows — because main reads params.size and passes it straight to cube. The name you chose in the panel is the exact key you read in main. Change the control's initial to 5 and rerun to see where the model starts.
Write a parametric JSCAD script that builds a cube whose size is controlled by a single number parameter named size, with an initial value of 20.
Solution
Step 1 — import the primitive. We need cube from primitives.
Step 2 — write getParameterDefinitions. It returns an array with one number control named size, with an initial value of 20.
Step 3 — write main(params). It reads the size back with params.size and passes it to cube.
Step 4 — export both functions.
Answer: The script above builds a cube whose size is controlled by a size parameter, starting at 20.
Parameters can do real work, too — one value can feed a calculation that another control uses. Here a radius slider drives how many segments the circle needs: a bigger radius gets more segments so the curve stays smooth.
The parameter fields
Each entry in the returned array is one control. Common fields across every parameter type:
segments is not a control — it is computed from radius inside main. The reader never touches it directly; they move the radius slider and the segment count follows. That is the difference between passing a parameter straight through and letting it do work.
| Field | Meaning |
|---|---|
name |
key main(params) reads it back under (params.<name>) |
type |
which control to render |
caption |
label shown next to the control |
initial |
starting value |
Each field tells the panel one thing: name is the key, type is the kind of control, caption is the label, and initial is where it starts. Together they describe one control in the panel.
Write a getParameterDefinitions function that returns a single number control named radius with an initial value of 10, a minimum of 1, a maximum of 50, and a step of 1.
Solution
Step 1 — return an array with one control. The array holds one object describing the control.
Step 2 — fill in the fields. name is 'radius', type is 'number', initial is 10, min is 1, max is 50, and step is 1.
Answer: The function above returns a number control named radius that starts at 10 and can range from 1 to 50 in steps of 1.
The parameter types
The type field picks which control the panel renders. number is the workhorse, but JSCAD ships several others, each with its own extra fields:
| type | extra fields | what the panel shows |
|---|---|---|
number |
min, max, step |
a number box with a spinner |
checkbox |
checked |
a tick box that is on or off |
choice |
values, captions |
a dropdown list of options |
slider |
min, max, step |
a draggable slider |
text |
placeholder |
a single-line text box |
color |
— | a color picker |
A checkbox suits a yes/no flag, a choice suits a small set of named options, a slider suits a range you want to feel, and a color suits a hex value. The type is not decoration — it decides how the user interacts with the control.
Different types can live in one getParameterDefinitions and be read back together in main(params). Here a checkbox turns a hole on or off, a slider sets its radius, and a choice picks the shape:
A checkbox reads back as a boolean, a slider as a number, and a choice as whatever you put in values. So params.drill is true or false, params.radius is a number, and params.shape is the string 'circle' or 'square'.
Controls are not always numbers — a checkbox flips something on or off, and a choice picks from a short list. Build a small panel with all three, each comment below is one line for you to write. Press Run when you are done.
Solution
You should see a 40-by-40 square and a panel with a dropdown (Drill hole) and a number box (Hole radius). A choice reads back as one of its values strings, and a number reads back as a number — so params.drill is 'yes' or 'no', and params.radius is a number. Switch the dropdown to no and the panel still works; the panel simply holds whatever you choose.
Write a getParameterDefinitions that returns a choice named shape with values ['cube', 'sphere'] and a checkbox named solid that starts checked.
Solution
Step 1 — return an array with two controls. Each control is one object in the array.
Step 2 — write the choice. name is 'shape', type is 'choice', and values lists the two options.
Step 3 — write the checkbox. name is 'solid', type is 'checkbox', and checked: true starts it on.
Answer: The function above returns a dropdown named shape with the options cube and sphere, plus a checkbox named solid that starts checked.
Grouping parameters
As a panel grows, the group type acts as a divider. A group entry has no value of its own — it just labels a section of the panel and collects the controls that follow it.
| Field | Meaning |
|---|---|
name |
a unique key for the group (never read back in main) |
type |
'group' |
caption |
the heading shown above the group's controls |
The group entry sizeGroup never appears in params — it only draws a Dimensions heading in the panel. The controls that follow it are the ones main reads. Grouping keeps a long panel scannable without changing how you read values.
Write a getParameterDefinitions that groups a length number control under a group named sizeGroup with the caption Dimensions.
Solution
Step 1 — write the group entry. name is 'sizeGroup', type is 'group', and caption is 'Dimensions'.
Step 2 — write the control that follows it. The length control comes right after the group, so it appears under the Dimensions heading.
Answer: The function above draws a Dimensions heading, under which the length number control appears.
Problem Set
Problem 1. In your own words, explain what makes a JSCAD script parametric and how it differs from a script with hard-coded numbers.
Problem 2. Name the two functions a parametric JSCAD script must export, and state what each one does.
Problem 3. Write a getParameterDefinitions function that returns a single number control named length with an initial value of 30.
Problem 4. Write a parametric JSCAD script that builds a cube whose size is controlled by a parameter named size with an initial value of 15.
Problem 5. Explain how the name field connects a control in the panel to the value read inside main(params).
Problem 6. Name three parameter types other than number, and state what kind of control each one renders.
Problem 7. Write a getParameterDefinitions function that returns a choice named shape with values ['cube', 'sphere'] and a checkbox named solid that starts checked.
Problem 8. Write a getParameterDefinitions function that groups a length number control under a group named sizeGroup with the caption Dimensions.
Key Terms
parametric — a script whose geometry is driven by parameters from a live UI panel instead of hard-coded numbers.
getParameterDefinitions — the function that returns an array of control definitions for the parameter panel.
params — the object passed to main that holds the current values of every parameter, read back as params.<name>.
control — one entry in the parameter array, describing a single input such as a number box or slider.
parameter type — the type field that decides which control the panel renders, such as number, checkbox, choice, slider, text, or color.
group — a parameter type that acts as a panel divider, labeling a section of controls without holding a value of its own.