chore(version): move to the next beta version [BUMP BETA] (#4939)

This commit is contained in:
Alireza authored and GitHub committed 2025-04-09 23:25:30 -04:00
1 parent e1e9b5ccb1
commit e37168094a
374 files changed
+6978 -1721

No files matched your search

@@ -0,0 +1,4 @@
{
"label": "Managers",
"position": 10
}
@@ -0,0 +1,175 @@
---
sidebar_position: 4
sidebar_label: Commands Manager
---
# Commands Manager
## Overview
The `CommandsManager` is a class defined in the `@ohif/core` project.
The Commands Manager tracks named commands (or functions) that are scoped to
a context. When we attempt to run a command with a given name, we look for it
in our active contexts, in the order specified.
If found, we run the command, passing in any application
or call specific data specified in the command's definition.
The order specified is the REVERSE of the order the modules are registered in
for the mode dependency. That is, the last module registered has the highest priority
and will be searched first for commands. This has nothing to do with when the
command itself is registered, although registrations for the same command in different
modules in the same context will also use last registration wins.
> Note: A single instance of `CommandsManager` should be defined in the consuming
application, and it is used when constructing the `ExtensionManager`.
A `simplified skeleton` of the `CommandsManager` is shown below:
```js
export class CommandsManager {
contexts = {};
contextOrder = [];
constructor(_ignoredConfig) {}
getContext(contextName) {
const context = this.contexts[contextName];
return context;
}
/**...**/
createContext(contextName) {
/** ... **/
this.contexts[contextName] = {};
this.contextOrder.push at beginning(contextName)
}
registerCommand(contextName, commandName, definition) {
/**...**/
const context = this.getContext(contextName);
/**...**/
context[commandName] = definition;
}
getCommand(commandName, contextName) {
const useContext = contextName || first context having commandName in contextOrder
return useContext[commandName];
}
runCommand(commandName, options = {}, contextName) {
const definition = this.getCommand(commandName, contextName);
/**...**/
const { commandFn } = definition;
const commandParams = Object.assign(
{},
definition.options, // "Command configuration"
options // "Time of call" info
);
/**...**/
return commandFn(commandParams);
}
/**...**/
}
```
### Instantiating
No methods or configuration is used within the construction.
## Commands/Context Registration
The `ExtensionManager` handles registering commands and creating contexts, so you
don't need to register all your commands manually. Simply, create a `commandsModule`
in your extension, and it will get automatically registered in the `context` provided.
A *simplified version* of this registration is shown below to give an idea about the process.
```js
export default class ExtensionManager {
constructor({ commandsManager }) {
this._commandsManager = commandsManager
}
/** ... **/
registerExtension = (extension, configuration = {}, dataSources = []) => {
let extensionId = extension.id
/** ... **/
// Register Modules provided by the extension
moduleTypeNames.forEach((moduleType) => {
const extensionModule = this._getExtensionModule(
moduleType,
extension,
extensionId,
configuration
)
if (moduleType === 'commandsModule') {
this._initCommandsModule(extensionModule)
}
/** registering other modules **/
})
}
_initCommandsModule = (extensionModule) => {
let { definitions, defaultContext } = extensionModule
defaultContext = defaultContext || 'VIEWER'
if (!this._commandsManager.getContext(defaultContext)) {
this._commandsManager.createContext(defaultContext)
}
Object.keys(definitions).forEach((commandName) => {
const commandDefinition = definitions[commandName]
const commandHasContextThatDoesNotExist =
commandDefinition.context &&
!this._commandsManager.getContext(commandDefinition.context)
if (commandHasContextThatDoesNotExist) {
this._commandsManager.createContext(commandDefinition.context)
}
this._commandsManager.registerCommand(
commandDefinition.context || defaultContext,
commandName,
commandDefinition
)
})
}
}
```
If you find yourself in a situation where you want to register a command/context manually, ask
yourself "why can't I register these commands via an extension?", but if you insist, you can use the `CommandsManager` API to do so:
```js
// Command Registration
commandsManager.registerCommand('context', 'name', commandDefinition);
// Context Creation
commandsManager.createContext('string');
```
## `CommandsManager` Public API
If you would like to run a command in the consuming app or an extension, you can
use `runCommand(commandName, options = {}, contextName)`.
```js
// Run a command, it will run all the `speak` commands in all contexts
commandsManager.runCommand('speak', { command: 'hello' });
// Run command, from Default context
commandsManager.runCommand('speak', { command: 'hello' }, 'DEFAULT');
// Returns all commands for a given context
commandsManager.getContext('string');
```
@@ -0,0 +1,65 @@
---
sidebar_position: 2
sidebar_label: Extension Manager
---
# Extension Manager
## Overview
The `ExtensionManager` is a class made available to us via the `@ohif/core`
project (platform/core). Our application instantiates a single instance of it,
and provides a `ServicesManager` and `CommandsManager` along with the
application's configuration through the appConfig key (optional).
```js
const commandsManager = new CommandsManager();
const servicesManager = new ServicesManager();
const extensionManager = new ExtensionManager({
commandsManager,
servicesManager,
appConfig,
});
```
## Events
The following events get published by the `ExtensionManager`:
| Event | Description |
| ---------------------------- | ------------------------------------------------------ |
| ACTIVE_DATA_SOURCE_CHANGED | Fired when the active data source is changed - either replaced with an entirely different one or the existing active data source gets its definition changed via `updateDataSourceConfiguration`. |
## API
The `ExtensionManager` only has the following public API:
- `setActiveDataSource` - Sets the active data source for the application
- `getDataSources` - Returns the registered data sources
- `getActiveDataSource` - Returns the currently active data source
- `getModuleEntry` - Returns the module entry by the give id.
- `addDataSource` - Dynamically adds a data source and optionally sets it as the active data source
- `updateDataSourceConfiguration` - Updates the configuration of a specified data source (name).
- `getDataSourceDef` - Gets the data source definition for a particular data source name.
## Accessing Modules
We use `getModuleEntry` in our `ViewerLayout` logic to find the panels based on
the provided IDs in the mode's configuration.
For instance:
`extensionManager.getModuleEntry("@ohif/extension-measurement-tracking.panelModule.seriesList")`
accesses the `seriesList` panel from `panelModule` of the
`@ohif/extension-measurement-tracking` extension.
```js
const getPanelData = id => {
const entry = extensionManager.getModuleEntry(id);
const content = entry.component;
return {
iconName: entry.iconName,
iconLabel: entry.iconLabel,
label: entry.label,
name: entry.name,
content,
};
};
```
@@ -0,0 +1,80 @@
---
sidebar_position: 5
sidebar_label: Hotkeys Manager
---
# Hotkeys Managers
## Overview
`HotkeysManager` handles all the logics for adding, setting and enabling/disabling
the hotkeys.
## Instantiation
`HotkeysManager` is instantiated in the `appInit` similar to the other managers.
```js
const commandsManager = new CommandsManager(commandsManagerConfig);
const servicesManager = new ServicesManager(commandsManager);
const hotkeysManager = new HotkeysManager(commandsManager, servicesManager);
const extensionManager = new ExtensionManager({
commandsManager,
servicesManager,
hotkeysManager,
appConfig,
});
```
## Hotkeys Manager API
- `setHotkeys`: The most important method in the `HotkeysManager` which binds the keys with commands.
- `setDefaultHotKeys`: set the defaultHotkeys **property**. Note that, this method **does not** bind the provided hotkeys; however, when `restoreDefaultBindings`
is called, the provided defaultHotkeys will get bound.
- `destroy`: reset the HotkeysManager, and remove the set hotkeys and empty out the `defaultHotkeys`
## Structure of a Hotkey Definition
A hotkey definition should have the following properties:
- `commandName`: name of the registered command
- `commandOptions`: extra arguments to the commands
- `keys`: an array defining the key to get bound to the command
- `label`: label to be shown in the hotkeys preference panel
- `isEditable`: whether the key can be edited by the user in the hotkey panel
### Default hotkeysBindings
The default key bindings can be find in `hotkeyBindings.js`
```js
// platform/core/src/defaults/hotkeyBindings.js
export default [
/**..**/
{
commandName: 'setToolActive',
commandOptions: { toolName: 'Zoom' },
label: 'Zoom',
keys: ['z'],
isEditable: true,
},
{
commandName: 'flipViewportHorizontal',
label: 'Flip Vertically',
keys: ['v'],
isEditable: true,
},
/**..**/
]
```
### Global vs Mode specific hotkeys
You can can set the global hotkeys and override them using the `$set` method
in the customization service.
@@ -0,0 +1,76 @@
---
sidebar_position: 1
sidebar_label: Introduction
---
# Managers
## Overview
`OHIF` uses `Managers` to accomplish various purposes such as registering new
services, dependency injection, and aggregating and exposing `extension`
features.
`OHIF-v3` provides the following managers which we will discuss in depth.
<table>
<thead>
<tr>
<th>Manager</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<a href="./extension">
Extension Manager
</a>
</td>
<td>
Aggregating and exposing modules and features through out the app
</td>
</tr>
<tr>
<td>
<a href="./service">
Services Manager
</a>
</td>
<td>
Single point of registration for all internal and external services
</td>
</tr>
<tr>
<td>
<a href="./commands">
Commands Manager
</a>
</td>
<td>
Register commands with specific context and run commands in the app
</td>
</tr>
<tr>
<td>
<a href="./hotkeys">
Hotkeys Manager
</a>
</td>
<td>
For keyboard keys assignment to commands
</td>
</tr>
</tbody>
</table>
<!--
LINKS
-->
<!-- prettier-ignore-start -->
[core-services]: https://github.com/OHIF/Viewers/tree/master/platform/core/src/services
[services-manager]: https://github.com/OHIF/Viewers/blob/master/platform/core/src/services/ServicesManager.js
[cross-cutting-concerns]: https://en.wikipedia.org/wiki/Cross-cutting_concern
<!-- prettier-ignore-end -->
@@ -0,0 +1,204 @@
---
sidebar_position: 3
sidebar_label: Service Manager
---
# Services Manager
## Overview
Services manager is the single point of service registration. Each service needs
to implement a `create` method which gets called inside `ServicesManager` to
instantiate the service. In the app, you can get access to a registered service
via the `services` property of the `ServicesManager`.
## Skeleton
_Simplified_ skeleton of `ServicesManager` is shown below. There are two public
methods:
- `registerService`: registering a new service with/without a configuration
- `registerServices`: registering batch of services
```js
export default class ServicesManager {
constructor(commandsManager) {
this._commandsManager = commandsManager;
this.services = {};
this.registeredServiceNames = [];
}
registerService(service, configuration = {}) {
/** validation checks **/
this.services[service.name] = service.create({
configuration,
commandsManager: this._commandsManager,
});
/* Track service registration */
this.registeredServiceNames.push(service.name);
}
registerServices(services) {
/** ... **/
}
}
```
## Default Registered Services
By default, `OHIF-v3` registers the following services in the `appInit`.
```js title="platform/app/src/appInit.js"
servicesManager.registerServices([
CustomizationService,
UINotificationService,
UIModalService,
UIDialogService,
UIViewportDialogService,
MeasurementService,
DisplaySetService,
ToolBarService,
ViewportGridService,
HangingProtocolService,
CineService,
]);
```
## Service Architecture
If you take a look at the folder of each service implementation above, you will
find out that services need to be exported as an object with `name` and `create`
method.
For instance, `ToolBarService` is exported as:
```js title="platform/core/src/services/ToolBarService/index.js"
import ToolBarService from './ToolBarService';
export default {
name: 'ToolBarService',
create: ({ configuration = {}, commandsManager }) => {
return new ToolBarService(commandsManager);
},
};
```
and the implementation of `ToolBarService` lies in the same folder at
`./ToolbarSerivce.js`.
> Note: The create method is critical for any custom service that you write and
> want to add to the list of services
> Note: For typescript definitions, the service type should be exported
> as part of the Types export on the module. This is recommended going forward
> and existing services will be migrated. As well, the capitalization of the
> name should be lower camel case, with the type being upper camel case. In
> the above example, the service instance should be `toolBarService` with the
> class being `ToolBarService`.
## Accessing Services
Throughout the app you can use `services` property of the service manager to
access the desired service.
For instance in the `PanelMeasurementTableTracking` which is the right panel in
the `longitudinal` mode, we have the _simplified code below_ for downloading the
drawn measurements.
```js
function PanelMeasurementTableTracking({ servicesManager }) {
const { MeasurementService } = servicesManager.services;
/** ... **/
async function exportReport() {
const measurements = MeasurementService.getMeasurements();
/** ... **/
downloadCSVReport(measurements, MeasurementService);
}
/** ... **/
return <> /** ... **/ </>;
}
```
## Registering Custom Services
You might need to write you own custom service in an extension.
`preRegistration` hook inside your extension is the place for registering your
custom service.
```js title="extensions/customExtension/src/index.js"
import WrappedBackEndService from './services/backEndService';
export default {
// ID of the extension
id: 'myExtension',
preRegistration({ servicesManager }) {
servicesManager.registerService(WrappedBackEndService(servicesManager));
},
};
```
and the logic for your service shall be
```js title="extensions/customExtension/src/services/backEndService/index.js"
// Canonical name of upper camel case BackEndService for the class
import BackEndService from './BackEndService';
export default function WrappedBackEndService(servicesManager) {
return {
// Note the canonical name of lower camel case backEndService
name: 'backEndService',
create: ({ configuration = {} }) => {
return new BackEndService(servicesManager);
},
};
}
```
with implementation of
```ts
export default class BackEndService {
constructor(servicesManager) {
this.servicesManager = servicesManager;
}
putAnnotations() {
return post(/*...*/);
}
}
```
with a registration of
```ts title="types/index.ts"
import BackEndService from "../services/BackEndService/BackEndService";
export { BackEndService };
```
# Service Mode Lifecycle
Services may implement initialization and cleanup for mode specific data.
In order to prevent defects where there are differences between initial
and subsequent displays of a study, the contract of the service is that the
state the service is in on mode entry shall be the same whether the mode was
entered or was exited and entered again.
To implement storage/recovery of state, the mode must store the data on
exiting the mode, and restore the data in it's onModeEnter. For example,
the mode may decide to preserve measurement data in the onModeExit, and
to restore it in the onModeEnter. This does not violate the contract since
it is the mode's decision to apply the stored state, and to cache it.
## onModeEnter
A service may implement an onModeEnter call to initialize the service to
be ready for entering a mode.
This is called before the mode `onModeEnter` is called.
## onModeExit
When entering a mode, the service contract states that the service needs to
be in the same state whether it is a fresh load or has previously entered the mode.
The onModeExit allows a service to clean itself up after the mode 'onModeExit'
has stored any persistent data.