Workshop Iframe Custom Widget

Description

A plugin to be used in custom applications to enable bi-directional communication between the iframed react app and Palantir's Workshop parent. The two way communication includes the following:

- Workshop can pass variable values to the iframed app
- The iframed app is able to set variables' values in Workshop
- The iframed app is able to execute events configured in Workshop

How does it work?

!Diagram of how this package works

When should I use this?

So why might you use this new option OSDK + custom iframe widget and why are we so excited about it? If you are a customer builder, this is the first time Palantir Workshop supports creating a new custom Workshop widget from a custom application. This is the recommended path for custom widgets and we’re hoping it unlocks what can be created in Workshop!

Limitations

- When a user opens the iframe for the first time they might see a login screen to authenticate. The iframe is responsible for going through the necessary authentication flow.
- ObjectSet variables require specifying a concrete ObjectType for a given variable. Additionally, the current limit is 10,000 objects primaryKeys/objectRids that can be passed back and forth between Workshop and the iframed app. Any more and they will be cut off at the first 10,000. This limitation will be removed once OSDK is able to support loading ObjectSets from temporary objectSetRids.
- Struct variable are not currently supported, but they are coming soon.

Install

``
npm install @osdk/workshop-iframe-custom-widget
`

Use

See Examples.tsx for a complete example, and see ExampleConfig.ts for a comprehensive example using all config field types.

A basic config definition:

`typescript
export const BASIC_CONFIG_DEFINITION = [
{
fieldId: "stringField",
field: {
type: "single",
fieldValue: {
type: "inputOutput",
variableType: {
type: "string",
defaultValue: "test",
},
},
label: "Input string (title)",
},
},
{
fieldId: "workshopEvent",
field: {
type: "single",
label: "Events",
fieldValue: {
type: "event",
},
},
},
{
fieldId: "listOfField",
field: {
type: "listOf",
label: "A list of fields",
addButtonText: "Add another item to these listOf fields",
config: [
{
fieldId: "booleanListField",
field: {
type: "single",
label: "Boolean list in a listOf",
fieldValue: {
type: "inputOutput",
variableType: {
type: "boolean-list",
defaultValue: [true, false, true, false],
},
},
},
},
],
},
},
...
] as const satisfies IConfigDefinition;
`

It is imperative to declare the config as a const. In order to transform the config into a context object where each fieldId becomes a property in the context object, the input config to useWorkshopContext must be declared as an object literal using as const.

Here is an example React component that shows how to call useWorkshopContext with the config above:

`typescript
const ExampleComponent = () => {
const workshopContext = useWorkshopContext(BASIC_CONFIG_DEFINITION);

return visitLoadingState(workshopContext, {
loading: () => <>Loading...,
// Must explicitly declare type for the loaded context value
succeeded: (loadedWorkshopContext: IWorkshopContext) => {
const { stringField, workshopEvent, listOfField } = loadedWorkshopContext;

// Examples of retrieving single field values.
const stringValue: IAsyncValue = stringField.fieldValue;

// Examples of retrieving listOf field values.
listOfField.forEach(listItem => {
const booleanListValue: IAsyncValue = listItem.booleanListField.fieldValue;
});

// Examples of setting single field values.
stringField.setLoading();
stringField.setLoadedValue("Hello world!");
stringField.setReloadingValue("Hello world is reloading.");
stringField.setFailedWithError("Hello world failed to load.");

// Examples of setting listOf field values.
listOfField.forEach((listItem, index) => {
listItem.booleanListField.setLoading();
listItem.booleanListField.setLoadedValue([true, false]);
listItem.booleanListField.setReloadingValue([false, true]);
listItem.booleanListField.setFailedWithError(Failed to load on listOf layer ${index});
});


// Example of executing event. Takes a React MouseEvent, or undefined if not applicable
workshopEvent.executeEvent(undefined);


return

;
},
reloading: _reloadingContext => <>Reloading...,
failed: _error => <>Error...,
});
};
`

Dynamic Height Control

You can dynamically control the maximum height of your iframe when embedded in Workshop using the setAutoMaxHeight function that's returned as part of the workshop context when passing enableSetAutoMaxHeight: true in the options argument of calling useWorkshopContext. This allows your application to adjust its container height based on content changes, user interactions, or any other factors, and results in useWorkshopContext returning two fields: context which has all the config fields, and
setAutoMaxHeight, a method to set the height.

Important Note: The setAutoMaxHeight function only works when the Workshop widget's height is set to "Auto (max)" in the Workshop widget's "Display" settings. If the max height configured in Workshop is less than the height sent by setAutoMaxHeight, the Workshop max height will override it, and the custom application widget will likely include a scroll bar to account for the overflow.

$3

`typescript
const workshopContext = useWorkshopContext(CONFIG, { enableSetAutoMaxHeight: true });

return visitLoadingState(workshopContext, {
loading: () => <>Loading...,
succeeded: (context) => {
// Set the maximum height to 500px
context.setAutoMaxHeight(500);

return

;
},
reloading: _reloadingContext => <>Reloading...,
failed: _error => <>Error...,
});
`

This approach gives you complete control over when and how to adjust the iframe's height. The setHeight function only has an effect when your application is running inside an iframe in Workshop.

FAQ's

1. For Ontology object set fields, should I use objectSet or temporaryObjectSetRid?

It depends on what version of @osdk/client you are using to query the Ontology from your app. You should use objectSet, which gives you the value of a objectTypeId with up to 10,000 primary keys if you are using @osdk/client version < 2.0, and temporaryObjectSetRid if you are using @osdk/client >= 2.0 as higher versions have the capabilities to materialize object sets from a temporary objectSet RID, and vice versa generate a temporary objectSet RID given a set of Ontology objects. Using temporaryObjectSetRid also removes the 10,000 objects per object set limit.

Note that we will soon be making a major bump to 2.0, due to this package deprecating the option to use objectSet fields, as we encourage consumers to move to using temporaryObjectSetRid to query from the Ontology allowing the ability to pass to and from Workshop object sets of size over 10,000 objects.

To resolve a temporaryObjectSetRid into an object set, use hydrateObjectSetFromRid, and vice versa to convert an object set to a temporaryObjectSetRid, use createAndFetchTempObjectSetRid from @osdk/client.

2. Where in my app should I call useWorkshopContext?

useWorkshopContext should be called from the route that you plan to embed in Workshop. Each call of useWorkshopContext should map to one instance of the bidirectional iframe widget. For example, if you would like to set up your app such that route /app1 and route /app2 are each two distinct custom widgets, you should call useWorkshopContext per component rendered at those routes (a total of two calls).

Alternatively, if you want to set up your app such that your widget navigates to multiple routes, you will want to call useWorkshopContext once in the main component and pass the context fields to each route. An example of this is below:

In main.tsx:
`typescript
import ReactDOM from "react-dom/client";
import { RouterProviderWrapperWithWorkshopContext } from "./MainComponent";

ReactDOM.createRoot(document.getElementById("root")!).render(
,
);
`

In RouterProviderWrapperWithWorkshopContext.tsx:
`typescript
import { createBrowserRouter, RouterProvider } from "react-router-dom";
import { IWorkshopContext, useWorkshopContext } from "@osdk/workshop-iframe-custom-widget";
import React from "react";
import { HomeComponent, RouteOneComponent, RouteTwoComponent } from "./routes";

export const RouterProviderWrapperWithWorkshopContext = () => {
const workshopContext = useWorkshopContext(CONFIG);
return visitLoadingState(workshopContext, {
loading: () => <>Loading...,
succeeded: loadedContext => ,
reloading: _reloadingContext => <>Reloading...,
failed: _error => <>Error...,
})
}

const LoadedRouterProviderWrapperWithWorkshopContext = (props: { loadedContext: IWorkshopContext }) => {
const router = createBrowserRouter(
[
{ path: "/", element: },
{ path: "/route1", element: },
{ path: "/route2", element: },
...,
]
)
return ;
}
`

3. Why is the context object returned by useWorkshopContext wrapped in an async loading state?

Please refer to the diagram Figure 1.a and 1.b. When your custom app is iframed inside of Workshop, the context object will not exist until Workshop accepts the config parameter and as such will be in a loading state until it is accepted. It may also be rejected by Workshop and as such will be wrapped in a failed to load async state with an accompanying error message.

4. Why should I provide default values when defining the config passed to useWorkshopContext?

During development when your custom app is not iframed in Workshop, its not receiving any values and as such it would make development difficult if all you had to work with were a forever loading context object or a loaded context object with null values. Allowing you to provide default values when defining the config that gets translated to the context object returned by useWorkshopContext helps you during development when the app is not being iframed, as the plugin will detect whether your app is being iframed and if not, will return a loaded context object populated with your default values.

5. Why is each value inside the context object returned by useWorkshopContext` wrapped in with an async loading state?

Workshop's variables each have an async loading state, as variables could come from asynchronous execution, such as a function that takes 10 seconds to return a value. Having a 1:1 match between the types in the context object and Workshop means that the two have a consistent view of variable values. If a variable in Workshop goes into a loading state or fails to load, this async state is passed to the iframed app allowing you to decide how to handle cases where one of the parameters is not available or currently might be re-loading. For example when implementing a custom submission form, you might want to disable the submission button if some of the inputs to your form hasn't loaded yet or are currently re-loading.

Questions/Support

Please post to https://community.palantir.com

License

The source code, documentation, and other materials herein are subject to the Palantir License. See LICENSE.