Global Contexts
Global Contexts are React Components that will be used to pass data through all your artboards via context without the need to add it manually. Once you have your app host page set up, you can now tell Plasmic about the custom components you want to use in the Studio, by registering them.
Component registration
The global context components can be registered just like normal code components.
- The actual React component function or class, so that Plasmic can actually instantiate and render those components
- Component metadata, like its name and its props, so that Plasmic can generate the control UI in the right panel for Plasmic users to configure the component props.
For example,
Typically you should perform your registrations in your plasmic-init.ts
file.
import ProductContext from '../components/ProductCard';export const PLASMIC = initPlasmicLoader(...);PLASMIC.registerGlobalContext(ProductContext, {name: "ProductContext",props: {// Simple scalar propstokenId: 'string',darkMode: 'boolean',// Some props can take an enum of optionsproductFilter: {type: 'choice',options: ['shirts', 'boots', 'jackets']}// Some props can take an arbitrary JSON objectconfig: 'object',}});
Visit the Global Context Registration API page to learn more about all the metadata you can specify when you register your component.
Use your global contexts in Studio!
Once you have finished registering your global contexts, make sure your changes are available on your app host, and reload your Plasmic project. You should see your global contexts now show up on the Project Settings tab.
Evolving global contexts over time
You can continue updating the code for your code components, and Plasmic will always use whatever is made available on the app host page.
However, occasionally, you want to evolve the metadata for your code components — its name and its props. To do so, you should make the updates to your registerGlobalContext()
call, deploy your update to your app host, and then reload the Plasmic project using that app host; Plasmic will then read the new metadata, and update accordingly.
There are a few caveats to be aware of as you make your updates:
Renaming components
When you change the name from A to B, the next time you open a project containing A, Plasmic Studio will remove the instance of A and add a new instance of B. Note that this removes all existing arguments/values passed into that prop.
Changing props
Changing the type of a prop will prompt you to confirm removing usages of the old prop. Note that this removes all existing arguments/values passed into that prop.
Changing the type or name of a prop in a way that carries over all old values passed in for that prop is not yet supported. Tell us if that’s something you’d like to see.
Adding new global contexts and props
Since these are non-destructive changes, these will immediately take effect in the project without further user interaction.
Using Global Context in codegen
When generating the code for your project using Codegen, each project that has global contexts will have a PlasmicGlobalContextsProvider
file. By default, each page will be wrapped in the GlobalContextsProvider
from it’s project, but you can change this setting by changing the wrapPagesWithGlobalContexts
flag in your plasmic.json
file.
Prop override
You can override the props that you pass to your global contexts in both the Headless API and in Codegen.
<PlasmicRootProviderloader={PLASMIC}globalContextsProps={{productContextProps: { tokenId: 'token-id' }}}><PlasmicComponent component="YourPage" /></PlasmicRootProvider>