# workshop-iframe-custom-widget **Repository Path**: mirrors_palantir/workshop-iframe-custom-widget ## Basic Information - **Project Name**: workshop-iframe-custom-widget - **Description**: Create custom widgets from applications that can read from and write to Workshop variables, as well as execute Workshop events - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: develop - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-11-14 - **Last Updated**: 2026-05-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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](https://www.palantir.com/docs/foundry/workshop/overview/) 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](./src/media/workshop-iframe-custom-widget-diagram.png) ## 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](./src/example/Example.tsx) for a complete example, and see [ExampleConfig.ts](./src/example/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
Render something here.
; }, 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. ### Basic Usage ```typescript const workshopContext = useWorkshopContext(CONFIG, { enableSetAutoMaxHeight: true }); return visitLoadingState(workshopContext, { loading: () => <>Loading..., succeeded: (context) => { // Set the maximum height to 500px context.setAutoMaxHeight(500); return
Your content here
; }, 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](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@osdk/client) version < 2.0, and `temporaryObjectSetRid` if you are using [@osdk/client](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@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](https://community.palantir.com) ## License The source code, documentation, and other materials herein are subject to the Palantir License. See [LICENSE](./LICENSE.md).