feat: add clickable BigLadder doc links throughout OpenStudioApp UI by Ski90Moo · Pull Request #876 · openstudiocoalition/OpenStudioApplication

Ski90Moo · 2026-05-24T13:13:06Z

Summary

Implements the enhancement requested in #160 — adds clickable hyperlinks from UI section headers and IDD type headers to the relevant EnergyPlus 25.1 Input/Output Reference pages on BigLadder Software. Tooltips show the full URL before clicking.

Inspector / IDD object headers

src/model_editor/IddObjectDocUrl.hpp (new): header-only hash map (QHash<QString, QString>) mapping 300+ OS:* IDD type names to their BigLadder EnergyPlus 25.1 I/O Reference URLs
src/model_editor/InspectorGadget.cpp: renders the locked IDD type header in the right-sidebar inspector as a Qt::RichText hyperlink when a URL mapping exists

Left-sidebar category headers

src/openstudio_lib/OSCollapsibleItemHeader.hpp/.cpp: extends OSCollapsibleItemHeader with an optional URL; when set, the category name renders as a clickable blue link
src/openstudio_lib/ModelObjectTypeListView.hpp/.cpp: adds a new constructor accepting vector<tuple<IddObjectType, string, QString>> to thread URLs through to each header
Loads tab: People, Lights, Electric/Gas/Steam/Other Equipment, Internal Mass, Water Use Equipment, Hot Water Equipment definitions
Constructions subtab: Constructions, Air Boundary, Internal Source, C-factor Underground Wall, F-factor Ground Floor
Materials subtab: all 14 material types (standard, no-mass, air gap, all window material variants)
Other Schedules subtab: Schedule Constant, Schedule Compact, Schedule File

Section headers (SimSettings pattern)

src/openstudio_lib/CollapsibleInspector.hpp/.cpp: extends CollapsibleInspectorHeader with an optional URL; section title renders as a clickable link
src/openstudio_lib/SimSettingsView.cpp: 15 CollapsibleInspector section headers and 3 H1 labels (Run Period, Sizing Parameters, Timestep)
src/openstudio_lib/LocationTabView.cpp: Weather File and Design Days headers
src/openstudio_lib/YearSettingsWidget.cpp: Daylight Savings Time header
src/openstudio_lib/GroundTemperatureView.hpp/.cpp: all 5 Ground Temperatures sidebar entries
src/openstudio_lib/LifeCycleCostsTabView.cpp: Life Cycle Cost Parameters and NIST Fuel Escalation Rates headers
src/openstudio_lib/BuildingInspectorView.cpp: North Axis label (Facility tab)

Build infrastructure

cmake/FindOpenStudioSDK.cmake: defines BIGLADDERSOFTWARE_DOC_BASE_URL as a single versioned CMake variable (EnergyPlus 25.1)
src/model_editor/CMakeLists.txt and src/openstudio_lib/CMakeLists.txt: pass the URL as a compile definition so all files share a single source of truth for the base URL

Test plan

Open a model — confirm IDD type headers in the right-sidebar inspector render as blue hyperlinks and open the correct BigLadder page
Navigate to Simulation Settings — confirm all CollapsibleInspector section headers and H1 labels are clickable links
Check Loads, Constructions, Materials, and Other Schedules sidebar categories render as blue links
Check Site tab (Weather File & Design Days, Ground Temperatures, Life Cycle Costs) section headers are linked
Check Facility tab North Axis label is linked
Hover over any link to confirm the tooltip shows the full URL before clicking
Confirm object types with no URL mapping still display plain text (no broken link rendering)

Closes #160

🤖 Generated with Claude Code

…headers Add IddObjectDocUrl.hpp mapping 300+ OS IDD type names to EnergyPlus 25.1 Input/Output Reference URLs. InspectorGadget::layoutText() now renders IDD type headers as clickable hyperlinks in the right-sidebar inspector. Extend CollapsibleInspector to accept an optional URL parameter, and wire 15 section headers in SimSettingsView (plus the Run Period, Sizing Parameters, and Timestep H1 labels) to their respective BigLadder doc anchors. Closes openstudiocoalition#160 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

macumber · 2026-05-25T16:27:16Z

Looks pretty good, the one thing I would ask for is a tooltip which shows you the url before you click

- Define ENERGYPLUS_VERSION_MAJOR/MINOR and BIGLADDERSOFTWARE_DOC_BASE_URL in FindOpenStudioSDK.cmake (single source of truth for the BigLadder URL base); pass to C++ via target_compile_definitions in model_editor and openstudio_lib; remove hardcoded URL strings from IddObjectDocUrl.hpp and SimSettingsView.cpp - Rename layoutText header overload to layoutHeaderText, drop unused level/ index parameters per macumber's cleaned-up version - Add setToolTip(docUrl) to all clickable doc links so the URL is visible on hover before clicking (InspectorGadget header, CollapsibleInspector section headers, SimSettings H1 labels) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- OS:Schedule:Day - OS:Coil:Cooling:DX:TwoStageWithHumidityControlMode - OS:Coil:Cooling:DX:MultiSpeed:StageData - OS:Coil:Cooling:Water:Panel:Radiant - OS:Coil:Heating:Gas:MultiStage + :StageData - OS:Coil:Heating:LowTemperatureRadiant:ConstantFlow + :VariableFlow - OS:Coil:Heating:Water:Baseboard:Radiant - OS:Coil:WaterHeating:AirToWaterHeatPump - OS:SetpointManager:FollowSystemNodeTemperature Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds BigLadder doc URL mappings for: LowTemperatureRadiant coils, CoilPerformance:DX:Cooling, Coil:Heating:Water:Baseboard, 10 setpoint managers (MultiZone/SingleZone humidity, SingleZone stage, SystemNodeReset), SolarCollectorPerformance x2, Chiller:Absorption, CentralHeatPumpSystem:Module, PlantComponent:TemperatureSource/UserDefined, CoolingTower:VariableSpeed, CoolingTowerPerformance x2, Pipe:Indoor/Outdoor/Duct, TemperingValve, LoadProfile:Plant, Fan:ComponentModel, Site:GroundTemperature:Undisturbed:KusudaAchenbach, SwimmingPool:Indoor, AirTerminal:SingleDuct:ConstantVolume:FourPipeInduction, and 5 new curve types. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Extends OSCollapsibleItemHeader to optionally render its text as a clickable BigLadder hyperlink. Adds a URL-aware constructor to ModelObjectTypeListView. Applies links to four left-sidebar panels: Loads, Constructions (subtab), Materials (subtab), and Other Schedules. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Site / Weather File & Design Days: Weather File, Design Days, and Daylight Savings Time headers link to BigLadder I/O Reference - Site / Ground Temperatures: all five sidebar entries link to their respective Site:GroundTemperature:* and Site:WaterMainsTemperature docs - Site / Life Cycle Cost: Life Cycle Cost Parameters and NIST Fuel Escalation Rates headers link to LifeCycleCost docs - Facility tab: North Axis label links to Building object docs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ski90Moo · 2026-05-31T19:48:05Z

Thanks for the feedback! Tooltips showing the full URL have been added to all clickable doc links — both in the inspector header (via layoutHeaderText) and in the CollapsibleInspectorHeader. Additionally, this branch has been extended to add doc links to several other parts of the UI: the left-sidebar category headers on the Loads, Constructions, Materials, and Other Schedules tabs, as well as section headers on the Site tab (Weather File, Design Days, Daylight Savings Time, Ground Temperatures), Life Cycle Costs tab, and the Facility tab (North Axis).

…function Per PR review feedback: instead of passing the URL via target_compile_definitions, add bigladdersoftwareDocBaseUrl() to OpenStudioApplicationPathHelpers following the existing .cxx.in pattern. The URL is configured from BIGLADDERSOFTWARE_DOC_BASE_URL in FindOpenStudioSDK.cmake — visible alongside EnergyPlus version bumps each release. All call sites updated to use QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ski90Moo · 2026-05-31T20:02:15Z

Addressed the BIGLADDERSOFTWARE_DOC_BASE_URL feedback: removed the target_compile_definitions approach and added a bigladdersoftwareDocBaseUrl() accessor to OpenStudioApplicationPathHelpers following the existing .cxx.in pattern. The URL is configured from BIGLADDERSOFTWARE_DOC_BASE_URL in FindOpenStudioSDK.cmake, so it will be visible alongside the EnergyPlus version bump each release. All call sites updated to use QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()).

Scans IddObjectDocUrl.hpp and all .cpp files that reference bigladdersoftwareDocBaseUrl(), fetches each unique BigLadder page once, and verifies that every anchor ID referenced actually exists in the page HTML. Exits 0 if all OK, 1 if any anchors are missing or pages fail to load. Usage: python scripts/check_doc_urls.py [--repo-root PATH] [--delay SEC] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Identified by scripts/check_doc_urls.py which fetches BigLadder pages and verifies anchor IDs exist in the HTML. Fixes include: - Wrong page: RunPeriod, InternalMass, PlantLoop/CondenserLoop, AvailabilityManagerAssignmentList, HeatExchanger:FluidToFluid, OutdoorAir:Mixer, ZoneMixer/Splitter/ReturnPlenum/SupplyPlenum - Typos: materialaingap→materialairgap, celdeckpad→celdekpad (×2), outdoorarreset→outdoorairreset, multizoneheat/coolaverage→heating/coolingaverage - Sphinx suffixes: lights→lights-000, construction→construction-000, daylightingcontrols→daylightingcontrols-000 - Hyphen removal: buildingsurface-detailed→buildingsurfacedetailed, fenestrationsurface-detailed→fenestrationsurfacedetailed - Renames: Uncontrolled→ConstantVolume:NoReheat, Fuel→Gas-000, ShadingControl→WindowPropertyShadingControl, WaterHeaterHeatPump→WaterHeaterHeatPumpPumpedCondenser, GroundHeatExchanger:Vertical→GroundHeatExchangerSystem - FourPipeBeam coils moved to air-distribution-equipment page 7 anchors remain unverifiable (page too long for fetch tool): HeatPump:PlantLoop:EIR:Cooling/Heating, PLHP:AirToWater (×3), WindowProperty:FrameAndDivider, InteriorPartitionSurface:Detailed. Also updates check_doc_urls.py docstring with rationale for choosing Python script over GTest, and updates OpenStudioApplicationPathHelpers with bigladdersoftwareDocBaseUrl() accessor function. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

macumber · 2026-06-01T01:00:57Z

+  label->setOpenExternalLinks(true);
+  {
+    static const QString url =
+      QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()) + "group-simulation-parameters.html#building";


Suggested change

QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()) + "group-simulation-parameters.html#building";

QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()) + iddObjectDocUrl("OS:Building");

It would be better to handle all of these using iddObjectDocUrl so all the url fragments are in one place.

macumber · 2026-06-01T01:07:50Z

@Ski90Moo one thing I found is that you have to use the same version of clang-format that the CI is using, 18.1.3, other versions of clang-format don't find the same issues as CI.

- WindowProperty:FrameAndDivider: correct page (thermal-zone not surface-construction) - InteriorPartitionSurface: remove (no EnergyPlus object, not user-facing in GUI) - HeatPump:PlantLoop:EIR:Cooling/Heating: correct anchors (#plhp_eir_cooling/heating) - HeatPump:AirToWater / :Cooling / :Heating: remove (no EnergyPlus object) All 384 URL references now pass check_doc_urls.py verification. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Run clang-format -style=file on all C++ files changed relative to develop, to satisfy the Clang Format CI check. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ski90Moo · 2026-06-01T07:34:18Z

Thanks for the heads-up. The clang-format on this machine was the pip-installed 18.1.8 package shadowing the system LLVM install. Switched to 18.1.3 to match CI — both versions produce identical output on the PR-touched files, so the formatting commit pushed in 8a7f8d1 should satisfy the check once the workflows are approved to run.

…InspectorView - Add qWarning log when iddObjectDocUrl cannot find a URL for a type - Use iddObjectDocUrl("OS:Building") in BuildingInspectorView instead of hardcoded URL fragment, consolidating all URL fragments in one place Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… pages Adds a new iddGroupDocUrl(groupName) function to IddObjectDocUrl.hpp that maps OpenStudio.idd \group names to their corresponding BigLadder EnergyPlus I/O Reference page URLs. Groups that span multiple EnergyPlus chapters (e.g. "OpenStudio HVAC") are intentionally omitted. Also updates check_doc_urls.py regex to cover groupMap entries alongside the existing urlMap entries. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ski90Moo · 2026-06-01T09:48:27Z

Addressed the remaining review comments:

layoutHeaderText cleanup — Adopted your refactored version: removed the index parameter, simplified the structure.

BuildingInspectorView.cpp — Switched to iddObjectDocUrl(QStringLiteral("OS:Building")) so the URL fragment lives in one place alongside all the others. Swapped the OpenStudioApplicationPathHelpers include for IddObjectDocUrl.hpp.

Warning log — Added qWarning() << "Cannot find doc url for: " + iddTypeName; before the empty return in iddObjectDocUrl.

Group URL lookup — Added iddGroupDocUrl(groupName) to IddObjectDocUrl.hpp mapping OpenStudio.idd \group names (e.g. "OpenStudio Simulation", "OpenStudio Materials") to their BigLadder page URLs. Groups that span multiple EnergyPlus chapters (e.g. "OpenStudio HVAC") are intentionally omitted. All 395 URL references pass check_doc_urls.py.

macumber · 2026-06-02T03:13:22Z

+  if (it != groupMap.constEnd()) {
+    return base + it.value();
+  }
+  return {};


Suggested change

return {};

qWarning() << "Cannot find doc url for: " + groupName;

return {};

macumber · 2026-06-02T03:20:56Z

+
+  using T = std::tuple<IddObjectType, std::string, QString>;
+  return {
+    T{IddObjectType::OS_Construction, "Constructions", sce + "#construction-000"},


Suggested change

T{IddObjectType::OS_Construction, "Constructions", sce + "#construction-000"},

T{IddObjectType::OS_Construction, "Constructions", iddObjectDocUrl(QStringLiteral("OS:Construction"),

These urls are already defined in IddObjectDocUrl.hpp, we should use those definitions rather than duplicate them here. Same thing for all the other urls in this file and others such as:

https://github.com/openstudiocoalition/OpenStudioApplication/pull/876/changes#diff-041047d3606ed5e7fec54dcfe4e8e7ce2f5720433717aaa1e00936250e7140b6R105

https://github.com/openstudiocoalition/OpenStudioApplication/pull/876/changes#diff-e35d718a8caea938a126dcce1d7f7baae6e2878d2325aa60c129adc74f6254e0R159

https://github.com/openstudiocoalition/OpenStudioApplication/pull/876/changes#diff-25e93e6585f3692c885d623d1223853ca5b3362b49d23fb99e8bbeb6d1ba357dR53

etc

macumber reviewed May 24, 2026

View reviewed changes

Comment thread src/model_editor/IddObjectDocUrl.hpp Outdated

macumber reviewed May 24, 2026

View reviewed changes

Comment thread src/model_editor/InspectorGadget.cpp

Ski90Moo force-pushed the feat/doc-links-inspector branch from 3f0d922 to 453f037 Compare May 26, 2026 15:15

Ski90Moo and others added 3 commits May 31, 2026 11:07

macumber reviewed May 31, 2026

View reviewed changes

Comment thread src/model_editor/CMakeLists.txt Outdated

Ski90Moo and others added 2 commits May 31, 2026 20:45

Ski90Moo changed the title ~~feat: add clickable BigLadder doc links to Inspector and SimSettings headers~~ feat: add clickable BigLadder doc links throughout OpenStudioApp UI May 31, 2026

Ski90Moo and others added 2 commits May 31, 2026 22:20

macumber reviewed Jun 1, 2026

View reviewed changes

Comment thread src/model_editor/IddObjectDocUrl.hpp Outdated

macumber reviewed Jun 1, 2026

View reviewed changes

Comment thread src/model_editor/IddObjectDocUrl.hpp

Ski90Moo and others added 2 commits June 1, 2026 08:22

style: apply clang-format to PR-touched files

8a7f8d1

Run clang-format -style=file on all C++ files changed relative to develop, to satisfy the Clang Format CI check. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ski90Moo and others added 2 commits June 1, 2026 09:43

macumber reviewed Jun 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add clickable BigLadder doc links throughout OpenStudioApp UI#876

feat: add clickable BigLadder doc links throughout OpenStudioApp UI#876
Ski90Moo wants to merge 13 commits into
openstudiocoalition:developfrom
Ski90Moo:feat/doc-links-inspector

Ski90Moo commented May 24, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

macumber commented May 25, 2026

Uh oh!

Uh oh!

Ski90Moo commented May 31, 2026

Uh oh!

Ski90Moo commented May 31, 2026

Uh oh!

macumber Jun 1, 2026

Uh oh!

Uh oh!

Uh oh!

macumber commented Jun 1, 2026

Uh oh!

Ski90Moo commented Jun 1, 2026

Uh oh!

Ski90Moo commented Jun 1, 2026

Uh oh!

macumber Jun 2, 2026

Uh oh!

macumber Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()) + "group-simulation-parameters.html#building";
	QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl()) + iddObjectDocUrl("OS:Building");

	return {};
	qWarning() << "Cannot find doc url for: " + groupName;
	return {};

	T{IddObjectType::OS_Construction, "Constructions", sce + "#construction-000"},
	T{IddObjectType::OS_Construction, "Constructions", iddObjectDocUrl(QStringLiteral("OS:Construction"),

Conversation

Ski90Moo commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Inspector / IDD object headers

Left-sidebar category headers

Section headers (SimSettings pattern)

Build infrastructure

Test plan

Uh oh!

Uh oh!

Uh oh!

macumber commented May 25, 2026

Uh oh!

Uh oh!

Ski90Moo commented May 31, 2026

Uh oh!

Ski90Moo commented May 31, 2026

Uh oh!

macumber Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

macumber commented Jun 1, 2026

Uh oh!

Ski90Moo commented Jun 1, 2026

Uh oh!

Ski90Moo commented Jun 1, 2026

Uh oh!

macumber Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

macumber Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Ski90Moo commented May 24, 2026 •

edited

Loading