feat: Add customization URL parameter (#5992)

* Add customization URL parameter

* fix: Preserve should be customizeable

* Update customizations docs

* fix: Overlay items on patient name

* Add customization test

* Fix resolve to absolute path

* fix: Warn on no data in load

* Remove unused customization stuff

* fix: PR comments

* Update stored parameters to only use an array for mulitples

* Remove requires ohif.* special call out

* Remove strict mode

* PR comments

* Document segmentation examples

* Add three examples as requested

* PR comments

* lock

* Remove old customizatoin export

* fix: Ordering issues on customization loads

* fix: Use correct default for dev builds app config

* Fixes for conflicts

* chore: restore pnpm-lock.yaml to match master

The lockfile diff was incidental peer-descriptor churn and carried no
functional dependency change. It tripped the CircleCI security-audit gate
(which only runs when pnpm-lock.yaml is in the PR diff), surfacing a
pre-existing critical `decompress` transitive vuln that also exists on
master. Restoring master's lockfile removes the audit trigger.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(ci): restore json5 lockfile entry; ignore unfixable decompress GHSA

The previous commit restored pnpm-lock.yaml from master, which dropped the
json5@2.2.3 entry that platform/core legitimately depends on (JSONC parsing
for the customization feature). That broke `--frozen-lockfile` install
(ERR_PNPM_OUTDATED_LOCKFILE). This restores the correct lockfile.

Because the lockfile must change (json5), the CircleCI security-audit gate
runs and previously failed on a critical `decompress` <=4.2.1 zip-slip
advisory. This is a pre-existing transitive vuln (present on master too) with
no published patch — decompress's latest release is 4.2.1, so no version
bump/override can resolve it. It reaches the tree only via @itk-wasm/dam, a
build/data-asset extraction tool under @cornerstonejs/labelmap-interpolation.

Add GHSA-mp2f-45pm-3cg9 to the existing pnpm-workspace.yaml auditConfig
ignoreGhsas accepted-risk list, matching how the repo already exempts other
build-tooling advisories. `pnpm audit --audit-level high` now passes locally
(1 critical ignored, 0 high).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(e2e): fix visitStudy URL encoding that broke mpr2 study load

The visitStudy rewrite (added for the ?customization= option) built the URL
with new URLSearchParams({ StudyInstanceUIDs: studyInstanceUID }), which
percent-encodes the value. mpr2.spec.ts embeds an extra param in the UID
string ('<uid>&hangingprotocolid=mpr'), so the & and = were encoded and the
whole thing collapsed into one invalid StudyInstanceUIDs value -> the study
could not be found ('studies are not available'), the viewer never rendered,
and the side-panel-header-right click timed out.

Restore master's raw concatenation for StudyInstanceUIDs (so embedded params
survive as separate query params) while still appending the customization
option separately. Only mpr2 embeds & in the UID, matching the single failure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* PR comments

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bill WallaceandClaude Opus 4.8 authored and GitHub committed 2026-07-07 15:30:27 -04:00
1 parent 3d9a17bc0c
commit 3dd5c70cb2
58 files changed
+3411 -586

No files matched your search

+2 -3
View File
@@ -110,7 +110,6 @@ function App({
cineService,
userAuthenticationService,
uiNotificationService,
customizationService,
} = servicesManager.services;
const providers = [
@@ -142,8 +141,8 @@ function App({
let authRoutes = null;
// Should there be a generic call to init on the extension manager?
customizationService.init(extensionManager);
// customizationService.init(extensionManager) runs in appInit after extensions register;
// do not call init again here — repeated init would duplicate-merge unless guarded (see CustomizationService.init).
// Use config to create routes
const appRoutes = createRoutes({
+18 -1
View File
@@ -28,7 +28,7 @@ import loadModules, { loadModule as peerImport } from './pluginImports';
import { publicUrl } from './utils/publicUrl';
/**
* @param {object|func} appConfigOrFunc - application configuration, or a function that returns application configuration
* @param {object|function} appConfigOrFunc - application configuration, or a function that returns application configuration
* @param {object[]} defaultExtensions - array of extension objects
*/
async function appInit(appConfigOrFunc, defaultExtensions, defaultModes) {
@@ -91,8 +91,25 @@ async function appInit(appConfigOrFunc, defaultExtensions, defaultModes) {
* Example2: [[ext1, config], ext2, [ext3, config]]
*/
const loadedExtensions = await loadModules([...defaultExtensions, ...appConfig.extensions]);
const { customizationService } = servicesManager.services;
// Resolve every customization module up front — from
// `appConfig.customizationService.requires` and the `?customization=` URL
// parameter — long before any mode loads, then apply the `bootstrap` phase
// BEFORE extensions register so it is in place while they initialize. Modules
// are only loaded when `appConfig.customizationUrlPrefixes` allows their
// prefix; the feature is off by default, and a value with an unconfigured
// prefix throws here (aborting startup) rather than being silently ignored.
await customizationService.loadAndApplyBootstrapCustomizations(extensionManager);
await extensionManager.registerExtensions(loadedExtensions, appConfig.dataSources);
// Merge extension default/global modules, then layer on the `global` phase of
// the structured config + the URL modules resolved above (so `$apply`-style
// overrides see the extension-provided defaults they build on).
customizationService.init(extensionManager);
customizationService.applyGlobalCustomizations();
// TODO: We no longer use `utils.addServer`
// TODO: We no longer init webWorkers at app level
// TODO: We no longer init the user Manager
@@ -175,7 +175,9 @@ function parseFiltersFromURL(params: URLSearchParams): ColumnFiltersState {
* Build URL query string from study list state preserving key query parameters.
*/
function buildQueryFromState(state: StudyListState): string {
const query: Record<string, string> = {};
// preserveQueryStrings may write repeated values as arrays, so the value type
// must allow string[] in addition to string.
const query: Record<string, string | string[]> = {};
// Sorting
if (state.sorting.length > 0) {
+6
View File
@@ -221,6 +221,12 @@ export default function ModeRoute({
appConfig,
});
// `extensionManager.onModeEnter` resets the customization mode scope via
// `customizationService.onModeEnter`; now layer on the `mode` phase blocks
// for this mode — the general (`*`) block first, then any block keyed by
// this mode's id / routeName so a single mode can override the general one.
customizationService.applyModeCustomizations([mode.id, mode.routeName]);
// use the URL hangingProtocolId if it exists, otherwise use the one
// defined in the mode configuration
const hangingProtocolIdToUse = hangingProtocolService.getProtocolById(
+10 -1
View File
@@ -51,7 +51,16 @@ export default function WorkList({
// `workList.columns` is registered as a value (StudyList.defaultColumns) and
// merged via customization commands, so we read the result directly.
const customized = customizationService.getCustomization('workList.columns');
return Array.isArray(customized) ? customized : StudyList.defaultColumns;
const resolved = Array.isArray(customized) ? customized : StudyList.defaultColumns;
// Expand data-only column specs. A `?customization=` JSONC file (or any
// serializable source) cannot carry render functions, so an entry that has
// an `id` but no `accessorFn`/`cell` is turned into a display-only text
// column that reads `row[id]` — matching `StudyList.textColumn`.
return resolved.map((col: any) =>
col && typeof col === 'object' && col.id && !col.accessorFn && !col.cell
? StudyList.textColumn(col.id, col.meta?.label ?? col.id, col.meta)
: col
);
}, [customizationService]);
const logoComponent = appConfig?.whiteLabeling?.createLogoComponentFn?.(React) ?? (
+1 -1
View File
@@ -14,7 +14,7 @@ workbox.core.clientsClaim();
// Cache static assets that aren't precached
workbox.routing.registerRoute(
/\.(?:js|css|json5)$/,
/\.(?:js|css|json5|jsonc)$/,
new workbox.strategies.StaleWhileRevalidate({
cacheName: 'static-resources',
})
@@ -0,0 +1,102 @@
// query-string is the stringifier used by the worklist navigation callers
// (useStudyListStateSync, LegacyWorkList); test against it, not the `qs` library.
import qs from 'query-string';
import { preserveQueryParameters, preserveQueryStrings } from './preserveQueryParameters';
describe('preserveQueryParameters', () => {
it('preserves base keys as query arrays', () => {
const current = new URLSearchParams();
current.append('configUrl', 'foo.js');
const out = new URLSearchParams();
preserveQueryParameters(out, undefined, current);
expect(out.getAll('configUrl')).toEqual(['foo.js']);
});
it('preserves all repeated values for the customization key', () => {
const current = new URLSearchParams();
current.append('customization', 'a');
current.append('customization', 'b');
const out = new URLSearchParams();
preserveQueryParameters(out, undefined, current);
expect(out.getAll('customization')).toEqual(['a', 'b']);
});
it('does not preserve unrelated keys', () => {
const current = new URLSearchParams();
current.append('foo', 'bar');
const out = new URLSearchParams();
preserveQueryParameters(out, undefined, current);
expect(out.get('foo')).toBeNull();
});
it('uses customization service values for multi-key preservation', () => {
const customizationService = {
getValue: jest.fn().mockReturnValue(['customization', 'customizationAlt']),
};
const current = new URLSearchParams();
current.append('customizationAlt', 'c');
const out = new URLSearchParams();
preserveQueryParameters(out, customizationService, current);
expect(out.getAll('customizationAlt')).toEqual(['c']);
expect(customizationService.getValue).toHaveBeenCalled();
});
});
describe('preserveQueryStrings', () => {
it('keeps single values as strings and repeated values as arrays', () => {
const current = new URLSearchParams();
current.append('configUrl', 'foo.js');
current.append('customization', 'a');
current.append('customization', 'b');
const out: Record<string, string | string[]> = {};
preserveQueryStrings(out, undefined, current);
expect(out.configUrl).toBe('foo.js');
expect(out.customization).toEqual(['a', 'b']);
});
it('keeps a single customization value as a string', () => {
const current = new URLSearchParams();
current.append('customization', 'only');
const out: Record<string, string | string[]> = {};
preserveQueryStrings(out, undefined, current);
expect(out.customization).toBe('only');
});
it('uses customization service values for query string preservation', () => {
const customizationService = {
getValue: jest.fn().mockReturnValue(['customization', 'customizationAlt']),
};
const current = new URLSearchParams();
current.append('customizationAlt', 'c');
const out: Record<string, string | string[]> = {};
preserveQueryStrings(out, customizationService, current);
expect(out.customizationAlt).toBe('c');
expect(customizationService.getValue).toHaveBeenCalled();
});
it('serializes single preserved values as plain query keys with default options', () => {
const current = new URLSearchParams();
current.append('configUrl', 'foo.js');
const out: Record<string, string | string[]> = {};
preserveQueryStrings(out, undefined, current);
// Default options only — no arrayFormat. Single values are plain strings, so
// they round-trip unchanged regardless of arrayFormat.
const search = qs.stringify(out, { skipNull: true, skipEmptyString: true });
expect(search).toBe('configUrl=foo.js');
expect(search).not.toMatch(/configUrl\[/);
});
it('serializes repeated preserved values as duplicated keys with default options', () => {
const current = new URLSearchParams();
current.append('customization', 'a');
current.append('customization', 'b');
const out: Record<string, string | string[]> = {};
preserveQueryStrings(out, undefined, current);
// query-string's default arrayFormat already produces duplicated keys, so callers
// need no arrayFormat option for repeated preserved keys to round-trip.
const search = qs.stringify(out, { skipNull: true, skipEmptyString: true });
expect(search).toBe('customization=a&customization=b');
});
});
@@ -1,26 +1,63 @@
function preserve(query, current, key) {
const value = current.get(key);
if (value) {
query.append(key, value);
}
}
import type CustomizationService from '@ohif/core/src/services/CustomizationService';
export const preserveKeys = ['configUrl', 'multimonitor', 'screenNumber', 'hangingProtocolId'];
/**
* Keys preserved when navigating between worklist and viewer modes.
* Each key may repeat in the URL; a single occurrence is preserved as a string and
* multiple occurrences as an array (see preserveQueryStrings).
*/
export const PRESERVE_CUSTOMIZATION_KEYS_KEY = 'ohif.preserveCustomizationKeys';
export const preserveKeys = [
'configUrl',
'multimonitor',
'screenNumber',
'hangingProtocolId',
'customization',
];
export function preserveQueryParameters(
query,
current = new URLSearchParams(window.location.search)
) {
for (const key of preserveKeys) {
preserve(query, current, key);
}
}
export function preserveQueryStrings(query, current = new URLSearchParams(window.location.search)) {
for (const key of preserveKeys) {
const value = current.get(key);
function preserveKey(query: URLSearchParams, current: URLSearchParams, key: string) {
const values = current.getAll(key);
for (const value of values) {
if (value) {
query[key] = value;
query.append(key, value);
}
}
}
function getPreserveKeys(customizationService?: CustomizationService): string[] {
const customKeys = customizationService?.getValue?.(PRESERVE_CUSTOMIZATION_KEYS_KEY, []) || [];
if (!customKeys?.length) {
return preserveKeys;
}
return [...preserveKeys, ...customKeys];
}
export function preserveQueryParameters(
query: URLSearchParams,
customizationService?: CustomizationService,
current: URLSearchParams = new URLSearchParams(window.location.search)
): void {
for (const key of getPreserveKeys(customizationService)) {
preserveKey(query, current, key);
}
}
export function preserveQueryStrings(
query: Record<string, string | string[]>,
customizationService?: CustomizationService,
current: URLSearchParams = new URLSearchParams(window.location.search)
): void {
for (const key of getPreserveKeys(customizationService)) {
const values = current.getAll(key).filter(Boolean);
if (!values.length) {
continue;
}
// A single value is stored as a plain string and repeated values as an array.
// The worklist stringifier (query-string) serializes both correctly with its
// default arrayFormat: a string becomes `key=value` and an array becomes
// duplicated `key=a&key=b` keys — no arrayFormat option required by callers.
// Keeping single values as strings also keeps them safe under stricter
// serializers (e.g. the `qs` library, whose default would index arrays).
query[key] = values.length === 1 ? values[0] : values;
}
}