Launch groups
You already know that you can use Finsemble workspaces to help your users with their workflows. A company or an assembler can deliver predefined workspace layouts to users b using config. This works well but sometimes a workspace is not enough.
For example, you might want your users to be able to add their own group of components that work together to perform a certain task. The user might never need individual apps in such a group to be available separately. In such a case you can define a launch group that contains all the components needed for this task.
A launch group can contain diverse components coming from different sources. And so, you can have a component that your own company developed, two components from two different vendors, and a chart from Cosaic. Even though each comes from a different source, they can all work together in one predefined layout.
For example, you want to launch (we sometimes also say spawn) a chart, a blotter, and a news feed component together as a unit. You want your chart to always appear in the same location and be one specific size. Similarly, you want the news component to appear next to the chart and have the predefined size. You want the blotter to fit under these two. You don’t want to use a predefined workspace because your users use this group in several different situations or may need to have multiple copies of it on their desktop at once.
A launch group allows you to define a group of apps or components that a user launches as a unit, using one action, such as clicking an icon on the taskbar. A user can also resize the entire group as a unit, provided the space that the group occupies is rectangular. Closing one of these apps or components will close them all if you specify that this is what you want. Alternatively, you can do nothing, which allows the user to close these individually.
There is no limit to how many launch groups you can have. They are independent of one another, but they can include the same component apps. In this case, each component app is an independent instance.
How to specify a launch group
You define your launch group the same way you define apps in your Finsemble configuration: you add it to public/configs/application/apps.json. Here's an example:
{
...
"apps": [
...
{
"appId": "LaunchGroupPixels",
"name": "LaunchGroupPixels",
"description": "An example launch group",
"title": "My launch group example",
"type": "other",
"details": {},
"hostManifests" : {
"Finsemble": {
"window": {
/* Identifies this as a Launch Group */
"windowType": "launchGroup",
/* Default position settings for the group */
"top": 0,
"left": 0,
"width": 1000,
"height": 1000,
/* Composition and behavior of the group */
"toSpawn": [
/* Launch Group component definitions */
],
"closeComponentsTogether": false
},
"foreign": {
"components": {
/* Behavior in launcher menus and toolbar */
"App Launcher": {
"launchableByUser": true
},
"Toolbar": {
"iconClass": "ff-adp-workspace"
}
}
},
"interop": { /* Auto-associate group components */ }
}
}
}
]
},
You must specify in the toSpawn element of the config not only which components participate in the group, but also their sizes and their locations with respect to your group's position on the screen and to one another. You specify the position of each component individually in the appD entry for the launch group.
To specify a component app, add an object to the group's toSpawn array and set its componentType to the appId of the component application you want to add:
{
"componentType": "FDC3 workbench",
"spawnOptions": { ... }
}
Alternatively, to specify a tabbed group of component apps, set a components array and add elements to it in the same order as they should appear in the tabbed group:
{
"components": [
{
"componentType": "ChartIQ Example App",
"spawnOptions": { ... }
},
{
"componentType": "AG-Grid Example Blotter",
"spawnOptions": { ... }
}
],
"spawnOptions": { ... }
}
Next, you specify spawnOptions for each component application, which allow you to specify the location (with respect to the upper left corner of the group) of each component, along with other spawn parameters that can be passed to LauncherClient.spawn to override settings in manifest.window configuration of the component app).
For example, if you want your component to appear in the upper left corner, you specify:
"top": 0,
"left": 0,
Next, you specify the size, either in pixels or in percentages. Here is an example in pixels:
"height": 250,"width": 600,
Alternatively, you can use percentages, where the height and width of your screen are 100%. Here is an example of a component that takes exactly a quarter of your screen:
"height": 50%,
"width": 50%,
You can use either pixels or percentages, but not both, to specify the sizes. Make sure to not mix these in one launch group. Otherwise some component, or perhaps even the entire launch group, might fail to launch.
It’s perfectly fine to have 2 different launch groups and to use pixels for one and percentages for the other. You just don’t mix these within one group.
The components always launch together, but their behavior on closing is up to you. If you do nothing, the user will be able to close components individually. If you want them to close as a group, you need to set "closeComponentsTogether": true. This way, closing one component will also close all the other components in the launch group.
Finally, if the components of the group will share context with each other using FDC3 user channels, there is one more thing you can specify. You can add all the components to the same channel by setting the autoAssociate property under selectConnect:
"interop": {
"selectConnect": [
{
"autoAssociate": {
"allChildren": true
}
}
]
}
We recommend that you always specify this property if the component apps need to all be on the same channel. Otherwise, your users will need to assign each component to a channel individually, which takes time and can cause mistakes. If the components need to be on different channels, omit this property.
Examples
In our examples, we use the ChartIQ Example App, the AG-Grid Example Blotter and the FDC3 workbench configured in Finsemble appd.json.
We show 2 launch groups, each using a different method of specifying sizing. Here is an example where we use pixels for sizing. Notice that these components don’t need to be on the same channel. Also, the user needs to close the components individually.
{
...
"apps": [
...
{
"appId": "LaunchGroupPixels",
"name": "LaunchGroupPixels",
"description": "An example launch group",
"title": "My launch group example",
"type": "other",
"details": {},
"hostManifests" : {
"Finsemble": {
"window": {
"windowType": "launchGroup",
"top": 0,
"left": 0,
"width": 1000,
"height": 1000,
"closeComponentsTogether": false,
"addToWorkspace": true,
"toSpawn": [
{
"components": [
{
"componentType": "ChartIQ Example App",
"spawnOptions": {
"data": {}
}
},
{
"componentType": "AG-Grid Example Blotter",
"spawnOptions": {
"data": {}
}
}
],
"spawnOptions": {
"top": 0,
"left": 0,
"height": 700,
"width": 700,
"position": "available"
}
},
{
"componentType": "FDC3 workbench",
"spawnOptions": {
"top": 0,
"left": 700,
"height": 700,
"width": 300,
"data": {},
"position": "available"
}
},
{
"componentType": "ChartIQ Example App",
"spawnOptions": {
"top": 700,
"left": 0,
"height": 300,
"width": 1000,
"data": {},
"position": "available"
}
},
]
},
"foreign": {
"components": {
"App Launcher": {
"launchableByUser": true
},
"Toolbar": {
"iconClass": "ff-adp-workspace"
},
}
}
}
}
}
]
},
For the next launch group, we use percentages for both the size of the group and for its component apps. We also want the user to be able to connect all the apps in this group to the same channel in one operation. The final thing to notice in this example is that we configured it so that all components close when the user closes one.
{
...
"apps": [
...
{
"appId": "LaunchGroupPercentage",
"name": "LaunchGroupPercentage",
"description": "An example launch group based on percentage sizing",
"title": "My percentage launch group example",
"type": "other",
"details": {},
"hostManifests" : {
"Finsemble": {
"window": {
"windowType": "launchGroup",
"top": "0%",
"left": "0%",
"width": "100%",
"height": "100%",
"closeComponentsTogether": true,
"addToWorkspace": true,
"toSpawn": [
{
"components": [
{
"componentType": "ChartIQ Example App",
"spawnOptions": {
"data": {}
}
},
{
"componentType": "AG-Grid Example Blotter",
"spawnOptions": {
"data": {}
}
}
],
"spawnOptions": {
"top": "0%",
"left": "0%",
"height": "70%",
"width": "70%",
"position": "available"
}
},
{
"componentType": "FDC3 workbench",
"spawnOptions": {
"top": "0%",
"left": "70%",
"height": "50%",
"width": "30%",
"data": {},
"position": "available"
}
},
{
"componentType": "FDC3 workbench",
"spawnOptions": {
"top": "70%",
"left": "0%",
"height": "30%",
"width": "70%",
"data": {},
"position": "available"
}
},
{
"componentType": "Tour",
"spawnOptions": {
"top": "50%",
"left": "70%",
"height": "50%",
"width": "30%",
"data": {},
"position": "available"
}
}
]
},
"foreign": {
"components": {
"App Launcher": {
"launchableByUser": true
},
"Toolbar": {
"iconClass": "ff-adp-workspace"
},
}
},
"interop": {
"selectConnect": [
{
"autoAssociate": {
"allChildren": true
}
}
]
}
}
}
}
]
}
Gotchas
A launch group behaves as a unit in terms of launching and closing it (when you set hostManifests.Finsemble.window.closeComponentsTogether: true). However, it doesn’t behave as a unit for the purposes of interop. So, for example, you can’t define intents or interop for the entire group. You configure these for individual components as you normally would.
Your component applications also have their own appD entries and will appear in launcher menus independently of the group. If you don't want them to appear separately, set hostManifests.Finsemble.foreign.components["App Launcher"].launchableByUser: false in their configuration.