Parameter UI Patterns

This guide summarizes the most useful Fcs.Parameter.Item* patterns for building clean, responsive component UIs.

Design principles

• Use clear HumanName values for the user-facing label.
• Use stable Identifier names because downstream calculations and triggers depend on them.
• Put limits (Min, Max, Step) on numeric inputs whenever possible.
• Use VisibilityCondition to hide irrelevant inputs.
• Use EditabilityCondition to keep values visible but locked when needed.
• Use IsReadOnly = True for computed outputs.

Available item types

ItemDouble

Numeric input with units, limits, and stepping.

Fcs.Parameter.ItemDouble{
   HumanName = "Span",
   Identifier = "span_m",
   DefaultUnit = "m",
   Min = 2.0,
   Max = 30.0,
   Step = 0.1,
   VisibilityCondition = showGeometryInputs,
   EditabilityCondition = !isLocked
}

Use for lengths, loads, slopes, thicknesses, and other continuous values.

ItemInteger

Integer input.

Fcs.Parameter.ItemInteger{
   HumanName = "Number of Bays",
   Identifier = "bayCount",
   Min = 1,
   Max = 20,
   Step = 1,
   VisibilityCondition = True,
   EditabilityCondition = !isLocked
}

Use for counts, levels, rows, and discrete options that should not accept fractions.

ItemString

Text input.

Fcs.Parameter.ItemString{
   HumanName = "Project Name",
   Identifier = "projectName",
   VisibilityCondition = True,
   EditabilityCondition = !isLocked
}

Use for labels, external URLs, notes, IDs, or free text.

ItemList

Dropdown selection.

Fcs.Parameter.ItemList{
   HumanName = "Facade Type",
   Identifier = "facadeType",
   Items = ["Closed", "Openings", "Transparent"],
   VisibilityCondition = showArchitecture,
   EditabilityCondition = !isLocked
}

Use for finite sets of predefined options.

ItemToggle

Boolean toggle.

Fcs.Parameter.ItemToggle{
   HumanName = "Include Windows",
   Identifier = "buildingHasWindows",
   VisibilityCondition = showArchitecture,
   EditabilityCondition = !isLocked
}

Use for simple yes/no decisions that control downstream geometry or visibility.

ItemArray

Repeating table-style input.

Fcs.Parameter.ItemArray{
   HumanName = "Supports",
   Identifier = "supports",
   VisibilityCondition = showAdvanced,
   EditabilityCondition = !isLocked,
   Items = [
      Fcs.Parameter.ItemDouble{ HumanName = "X", Identifier = "x", DefaultUnit = "m" },
      Fcs.Parameter.ItemDouble{ HumanName = "Y", Identifier = "y", DefaultUnit = "m" },
      Fcs.Parameter.ItemString{ HumanName = "Type", Identifier = "type" }
   ]
}

Use for repeated rows such as supports, openings, attachments, or custom load points.

ItemClass

Logical grouping or page-like container.

Fcs.Parameter.ItemClass{
   HumanName = "Geometry",
   Identifier = "geometryPage",
   VisibilityCondition = True,
   Items = [
      Fcs.Parameter.ItemDouble{ HumanName = "Width", Identifier = "width_m", DefaultUnit = "m" },
      Fcs.Parameter.ItemDouble{ HumanName = "Height", Identifier = "height_m", DefaultUnit = "m" }
   ]
}

Use for grouping related controls into sections such as Geometry, Loads, Materials, or Results.

ItemAction

Button that runs a trigger.

Fcs.Parameter.ItemAction{
   HumanName = "Run Recognition",
   Identifier = "runRecognition",
   ValidationTrigger = "recognitionTrigger",
   IsQuick = True,
   IsAuthPost = False,
   VisibilityCondition = showApiTools,
   EditabilityCondition = !isLocked
}

Use for REST calls, recalculation workflows, exports, and custom actions.

ItemComment

Static or computed HTML/text.

Fcs.Parameter.ItemComment{
   HumanName = "Preview",
   Identifier = "previewHtml",
   VisibilityCondition = showPreview
}

Use for explanatory text, warnings, status output, and HTML snippets such as embedded images.

ItemGallery

Gallery display, often hidden until populated.

Fcs.Parameter.ItemGallery{
   HumanName = "Result Gallery",
   Identifier = "resultGallery",
   VisibilityCondition = showGallery
}

Use when the UI should present one or more generated images in a gallery-style view.

Read-only outputs

Computed outputs should generally stay visible but not editable.

Fcs.Parameter.ItemDouble{
   HumanName = "Roof Area",
   Identifier = "outRoofArea_m2",
   DefaultUnit = "m²",
   IsReadOnly = True
}

Typical read-only outputs:

• total weight
• roof area
• utilization ratio
• recognized building height
• URLs or IDs returned by an integration

You can combine IsReadOnly = True with VisibilityCondition when an output should appear only after calculation.

Fcs.Parameter.ItemDouble{
   HumanName = "Predicted Height",
   Identifier = "predictedHeight_m",
   DefaultUnit = "m",
   IsReadOnly = True,
   VisibilityCondition = hasPrediction
}

ValidationTrigger patterns

Action buttons usually work through a trigger variable. The full pattern is:

1. Define the trigger variable
2. Add one or more constraints
3. Point ItemAction.ValidationTrigger at that variable

GET pattern with InitByGet

recognitionTrigger = {
   Constraints = [
      {
         Variable = "reconResponse",
         Condition = False,
         InitByGet = {
            Url = recognitionUrl,
            MediaFormat = "object"
         },
         Explanation = "Recognition done!"
      }
   ]
}

Fcs.Parameter.ItemAction{
   HumanName = "Run Recognition",
   Identifier = "runRecognition",
   ValidationTrigger = "recognitionTrigger",
   IsQuick = True,
   IsAuthPost = False
}

POST pattern with InitByPost

submitTrigger = {
   Constraints = [
      {
         Variable = "submitResponse",
         Condition = False,
         InitByPost = {
            Url = submitUrl,
            MediaFormat = "object",
            Body = requestBody
         },
         Explanation = "Submission complete!"
      }
   ]
}

Fcs.Parameter.ItemAction{
   HumanName = "Submit",
   Identifier = "submitButton",
   ValidationTrigger = "submitTrigger",
   IsQuick = True,
   IsAuthPost = True
}

Trigger design advice

• Use one trigger per business step when possible.
• Chain trigger constraint lists for multi-step workflows.
• Use clear variable names such as reconResponse, downloadResponse, submitResponse.
• Show user feedback with Explanation.

VisibilityCondition and EditabilityCondition

These two conditions solve different UI problems.

VisibilityCondition

Hide the parameter completely when it is irrelevant.

Fcs.Parameter.ItemDouble{
   HumanName = "Window Height",
   Identifier = "windowHeight_m",
   DefaultUnit = "m",
   VisibilityCondition = buildingHasWindows
}

Use when:

• an option is not applicable
• the UI should stay compact
• advanced controls should remain hidden until enabled

EditabilityCondition

Show the parameter, but disable editing when business rules say it should be locked.

Fcs.Parameter.ItemDouble{
   HumanName = "Snow Load",
   Identifier = "snowLoad_kN_m2",
   DefaultUnit = "kN/m²",
   EditabilityCondition = manualLoadsEnabled
}

Use when:

• the user should see the value even if they cannot change it
• an auto-calculated value can optionally become manual
• the field should remain visible for context

Combined pattern

Fcs.Parameter.ItemString{
   HumanName = "API URL",
   Identifier = "apiUrl",
   VisibilityCondition = showAdvanced,
   EditabilityCondition = allowManualApiOverride
}

This is useful for advanced or diagnostic settings.

Common UI patterns

Hide outputs until available

Fcs.Parameter.ItemComment{
   HumanName = "Recognition Preview",
   Identifier = "previewHtml",
   VisibilityCondition = hasRecognitionResult
}

Show always, lock sometimes

Fcs.Parameter.ItemDouble{
   HumanName = "Pitch",
   Identifier = "roofPitch_deg",
   DefaultUnit = "deg",
   EditabilityCondition = !useCatalogPitch
}

Group inputs and outputs separately

Use ItemClass sections like Geometry, Options, Actions, and Results so the UI reads like a workflow.

Checklist

• Give every parameter a stable Identifier.
• Add min/max/step for numeric items.
• Use IsReadOnly for outputs.
• Use VisibilityCondition to simplify the form.
• Use EditabilityCondition to preserve context while locking fields.
• Route actions through named ValidationTrigger variables.
• Use ItemComment for HTML previews and status messages.