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-24T19:25:40Z

+// Returns the BigLadder EnergyPlus 25.1 Input/Output Reference URL for the given
+// OS IDD type name (e.g. "OS:ThermalZone"), or an empty string if none is known.
+inline QString iddObjectDocUrl(const QString& iddTypeName) {
+  static const QString base = QStringLiteral("https://bigladdersoftware.com/epx/docs/25-1/input-output-reference/");


Let's define this base url in one spot, ideally in FindOpenStudioSDK.cmake

Sorry I wasn't more explicit, follow the pattern in https://github.com/openstudiocoalition/OpenStudioApplication/blob/develop/src/utilities/OpenStudioApplicationPathHelpers.cxx.in

Add a method https://github.com/openstudiocoalition/OpenStudioApplication/blob/develop/src/utilities/OpenStudioApplicationPathHelpers.hpp and the value returned gets configured by a CMake variable into the source.

Perfect, thanks!

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>

macumber · 2026-05-31T18:00:04Z

  target_compile_definitions(${target_name} PUBLIC model_editor_EXPORTS)
 endif()

+target_compile_definitions(${target_name} PRIVATE


Set BIGLADDERSOFTWARE_DOC_BASE_URL as a variable in https://github.com/openstudiocoalition/OpenStudioApplication/blob/develop/FindOpenStudioSDK.cmake, we have to update that file for each release so this will be visible when we do that.

Then add an accessor method to get the configured value in https://github.com/openstudiocoalition/OpenStudioApplication/blob/develop/src/utilities/OpenStudioApplicationPathHelpers.cxx.in

Fixed, thanks

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:01:17Z

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


Let's log a warning here if the value is not found like "Cannot find doc url for: " + iddTypeName

macumber · 2026-06-01T01:05:23Z

+// Base URL version is controlled by ENERGYPLUS_VERSION_MAJOR/MINOR in FindOpenStudioSDK.cmake.
+inline QString iddObjectDocUrl(const QString& iddTypeName) {
+  static const QString base = QString::fromStdString(openstudio::bigladdersoftwareDocBaseUrl());
+


IddFile does have a std::vector<std::string> groups() method, can we add a section so we can look up groups like "OpenStudio Simulation" -> "group-simulation-parameters.html"?

https://raw.githubusercontent.com/NatLabRockies/OpenStudio/refs/heads/develop/resources/model/OpenStudio.idd

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>

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

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

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>

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

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!

macumber May 24, 2026

Choose a reason for hiding this comment

Uh oh!

macumber May 31, 2026

Choose a reason for hiding this comment

Uh oh!

macumber Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

macumber commented May 25, 2026

Uh oh!

macumber May 31, 2026

Choose a reason for hiding this comment

Uh oh!

macumber Jun 1, 2026

Choose a reason for hiding this comment

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!

macumber Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

macumber Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

macumber commented Jun 1, 2026

Uh oh!

Ski90Moo commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Ski90Moo commented May 24, 2026 •

edited

Loading

macumber Jun 1, 2026 •

edited

Loading