Embed Workshop modules（嵌入 Workshop 模块）¶
Workshop offers two features that support embedding another Workshop module: the Embedded Module widget and the Loop section layout ("loop layout").
These features allow building Workshop modules that can be embedded within other Workshop modules. Embedded modules support all features offered by Workshop, though there are some limitations to the interaction of the embedded and embedding modules. This documentation will at times refer to a module that embeds another module as the "parent" module, and the module that is embedded as the "child" module. When this documentation refers to an "embedded module", the reference applies to both the Embedded Module widget, and the module embedded in the Loop layout, unless otherwise indicated.
Use cases¶
Embedded modules have a number of use cases, including:
- Reuse across many modules
- Reuse within a single module
- Maintainability
- Marketplace customization
- In-place replacement of a Workshop module
Reuse across many modules¶
Embedded modules allow a single child module to be configured and reused in many parent modules. Some examples of the types of embedded modules that can be built include:
- A configured object view
- A single widget with a complex configuration
- A set of widgets backed by complex variable logic
- Complex variable logic with no widgets at all
Reuse within a single module¶
Embedded modules can be used many times in a single parent module, either through the loop layout, or individual embedded module widgets. Some examples of a child module that would be embedded many times in the same parent module include:
- A custom card view derived from provided variables
- A set of widgets that will be displayed one time per tab, or page
Maintainability¶
Embedded modules can be used to break up a larger parent module into many child modules for better maintainability. This allows each child module to have its own variable scope, and for each child module to be edited at the same time by different Workshop builders.
Marketplace customization¶
An embedded module can be used to provide an area of customization when packaging a Workshop module with Marketplace. The embedded child module will be packaged as a dependency, and at installation time, a Marketplace user may select a module with the same module interface variable type signature to customize part of the installed parent module.
In-place replacement of a Workshop module¶
Embedded modules can be used to deploy a new Workshop module implementation without changing the Workshop resource that your users are already using. You can do this by using an embedded module as the only widget in the module. This allows you to make large changes to a module without requiring your users to migrate to a new Workshop resource.
Communicating across embedded modules¶
Use module interface variables to communicate between a parent and child module or between sibling modules. For example, these shared interface variables can back shared state, such as a selected object, a selected tab, or whether an overlay is shown. Embedded modules may modify the value of interface variables through events, allowing other places that reference these variables to respond according to the updated value.
:::callout{theme="neutral"} Workshop always uses the parent module's variable definition and ignores the embedded module's interface variable definition. The embedded modules interface configuration documentation contains more information about this behavior. :::
When you open an embedded child module in edit mode (for example, via Open referenced module from the Embedded Module widget or a Loop instance), the child module editor opens with the current values of any mapped module interface variables applied. This mirrors view-mode behavior and makes it easier to debug embedded modules with the same state that is present in the parent.
Limitations¶
No module settings inheritance of child modules¶
Configuration at the module level for child modules, such as routing, state saving, and auto-refresh, is not used. This means auto-refresh must be explicitly configured for every module that you intend to use auto-refresh with, and auto-refresh will not work specifically within the context of the embedded module. To embed a module that will auto-refresh inside a parent module that does not auto-refresh, you can use the iFrame widget to embed a separate module that acts as a sandboxed environment that will auto-refresh. You can set a URL query parameter embedded=true to hide the Foundry sidebar.
Should your workflow require, you can configure these settings at the parent module level, with variables passed down to child modules through the module interface.
Event passing¶
Embedded modules do not support the concept of event passing. Event passing would allow a builder to pass an event configuration from the parent module to the child module, allowing the child module to call an event that references configuration from the parent module (for example, the child module calling an event that opens an overlay in the parent module).
To communicate across embedded modules, a parent module may pass variables backing layout state to module interface variables of the child module as a way for the child to modify the layout state of the parent.
Embedded module provenance¶
Similar to other "Foundry apps" widgets in Workshop, the provenance of embedded modules used by other Workshop modules is not reported by Data Lineage.
Self-referential embedded modules¶
A module may not embed itself, either directly or through a chain of child modules. If a self-reference is configured, the module will display a warning to builders and render nothing to viewers in order to prevent a possible infinite chain of embedded modules. Contact your Palantir representative if you have a use case that requires recursive or self-referential embedded modules.
Permission of embedded modules¶
Embedded modules are separate resources with their own permission settings. If a user has permission to view a parent module that embeds a child module for which they lack permission to view, the user will see a "failed to load module" error.
Performance¶
Embedded modules should have similar performance characteristics to that of normal Workshop modules. One notable difference is that initialization of embedded modules is delayed until the embedded module is displayed in view. Once initialized, the embedded module is expected to run as if the entire module had been configured in the same place.
Note that the child module configuration will be initialized one time per instance, which comes with a cost to initialize its variables, but the child module configuration will only need to be loaded a single time if reused across many instances.
Usage of embedded modules and loop layouts make it much easier for builders to configure very large, complex modules. Builders should be aware of the total number of widgets and variables being displayed at once, particularly ones that are expensive to load.
Mobile mode¶
The Embedded Module widget and Loop layout can only embed other mobile modules when the module is in mobile mode.
中文翻译¶
嵌入 Workshop 模块¶
Workshop 提供两个支持嵌入其他 Workshop 模块的功能：嵌入式模块(Embedded Module) 组件和 循环(Loop) 章节布局（"循环布局"）。
这些功能允许构建可嵌入其他 Workshop 模块的 Workshop 模块。嵌入式模块支持 Workshop 提供的所有功能，但嵌入模块与被嵌入模块之间的交互存在一些限制。本文档有时会将嵌入其他模块的模块称为"父模块"，将被嵌入的模块称为"子模块"。除非另有说明，本文档中提到的"嵌入式模块"同时适用于嵌入式模块(Embedded Module) 组件和嵌入在循环(Loop) 布局中的模块。
使用场景¶
嵌入式模块有多种使用场景，包括：
跨多个模块复用¶
嵌入式模块允许配置单个子模块并在多个父模块中复用。可构建的嵌入式模块类型示例如下：
- 配置好的对象视图
- 具有复杂配置的单个组件
- 由复杂变量逻辑支持的一组组件
- 不包含任何组件的复杂变量逻辑
在单个模块内复用¶
嵌入式模块可以在单个父模块中多次使用，既可以通过循环布局，也可以通过单独的嵌入式模块组件。在同一个父模块中多次嵌入的子模块示例如下：
- 基于提供的变量派生的自定义卡片视图
- 每个标签页或页面显示一次的一组组件
可维护性¶
嵌入式模块可用于将较大的父模块拆分为多个子模块，以提高可维护性。这样每个子模块可以拥有自己的变量作用域，并且不同的 Workshop 构建者可以同时编辑各个子模块。
Marketplace 定制化¶
在使用 Marketplace 打包 Workshop 模块时，嵌入式模块可用于提供定制化区域。被嵌入的子模块将作为依赖项打包，在安装时，Marketplace 用户可以选择具有相同模块接口变量类型签名的模块，以定制已安装父模块的某一部分。
原地替换 Workshop 模块¶
嵌入式模块可用于部署新的 Workshop 模块实现，而无需更改用户正在使用的 Workshop 资源。具体做法是将嵌入式模块作为模块中唯一的组件使用。这样可以在不要求用户迁移到新 Workshop 资源的情况下，对模块进行大幅更改。
跨嵌入式模块通信¶
使用模块接口变量在父模块与子模块之间或同级模块之间进行通信。例如，这些共享的接口变量可以支持共享状态，如选中的对象、选中的标签页或覆盖层是否显示。嵌入式模块可以通过事件修改接口变量的值，从而使引用这些变量的其他位置能够根据更新后的值做出响应。
:::callout{theme="neutral"} Workshop 始终使用父模块的变量定义，并忽略嵌入式模块的接口变量定义。嵌入式模块接口配置文档包含有关此行为的更多信息。 :::
当您在编辑模式下打开嵌入式子模块时（例如，通过嵌入式模块(Embedded Module) 组件或循环(Loop) 实例中的"打开引用的模块"），子模块编辑器将应用任何已映射模块接口变量的当前值打开。这模拟了视图模式的行为，使调试具有与父模块相同状态的嵌入式模块更加容易。
限制¶
子模块无模块设置继承¶
子模块在模块级别的配置（如路由、状态保存和自动刷新）不会被使用。这意味着自动刷新必须为每个打算使用自动刷新的模块显式配置，并且自动刷新在嵌入式模块的特定上下文中将无法工作。要在不自动刷新的父模块中嵌入一个会自动刷新的模块，可以使用 iFrame 组件嵌入一个独立的模块，该模块作为沙盒环境运行并支持自动刷新。您可以设置 URL 查询参数 embedded=true 来隐藏 Foundry 侧边栏。
如果工作流需要，您可以在父模块级别配置这些设置，并通过模块接口将变量传递给子模块。
事件传递¶
嵌入式模块不支持事件传递的概念。事件传递允许构建者将事件配置从父模块传递给子模块，使子模块能够调用引用父模块配置的事件（例如，子模块调用在父模块中打开覆盖层的事件）。
要跨嵌入式模块通信，父模块可以将支持布局状态的变量传递给子模块的模块接口变量，作为子模块修改父模块布局状态的一种方式。
嵌入式模块来源¶
与 Workshop 中的其他"Foundry 应用"组件类似，其他 Workshop 模块使用的嵌入式模块的来源不会由数据沿袭(Data Lineage)报告。
自引用嵌入式模块¶
模块不能直接或通过子模块链嵌入自身。如果配置了自引用，模块将向构建者显示警告，并向查看者不渲染任何内容，以防止可能出现的无限嵌入式模块链。如果您有需要递归或自引用嵌入式模块的使用场景，请联系您的 Palantir 代表。
嵌入式模块的权限¶
嵌入式模块是具有各自权限设置的独立资源。如果用户有权查看嵌入了其无权查看的子模块的父模块，用户将看到"加载模块失败"的错误。
性能¶
嵌入式模块的性能特征应与普通 Workshop 模块类似。一个显著的区别是嵌入式模块的初始化会延迟到嵌入式模块在视图中显示时才开始。一旦初始化，嵌入式模块的运行方式应与整个模块在同一位置配置时相同。
请注意，子模块配置将在每个实例中初始化一次，这会带来初始化其变量的成本，但如果跨多个实例复用，子模块配置只需加载一次。
使用嵌入式模块和循环布局使构建者更容易配置非常大且复杂的模块。构建者应注意同时显示的组件和变量的总数，特别是那些加载成本较高的内容。
移动模式¶
当模块处于移动模式时，嵌入式模块(Embedded Module) 组件和循环(Loop) 布局只能嵌入其他移动模块。