Global Contexts API reference
Global Context registration
The registration function takes a component and some metadata about it:
plasmic-init.tsPLASMIC.registerGlobalContext(component: React.ComponentType<any>, meta: GlobalContextMeta): void
The first parameter component
is the React component function or class that you want to register and use in the Studio.
The second parameter meta
is an object containing metadata about the component. The object contains the following fields:
Field | Required? | Description |
---|---|---|
name | Yes | A unique string name used to identify this component. Each component should be registered with a different name. This name should be a valid javascript identifier, and we recommend picking a name that matches the component’s name in code. |
props | Yes | An object specifying the props expected for this component. Each key of the object is the name of the prop, and the value is metadata about the prop. See Property types for more. |
displayName | No | A human-friendly name to be displayed for the component in Studio UI; can contain spaces and punctuations. |
description | No | A human-friendly description for what this component does; will be rendered as a helpful hint to Studio users. |
refProp | No | The prop that receives and forwards a React ref . Plasmic only uses ref to interact with components in the editor, so it’s not used in the generated code. If not provided, the usual ref prop is used. |
Codegen only: | ||
importPath | Yes if using codegen | The path to be used when importing this component in the generated code. It can be the name of the npm package that contains the component (antd ), or the path to the file in the project (relative to the srcDir root directory). |
isDefaultExport | No | If true, then this component is the default export from importPath . |
importName | No | If the component is not the default export, then it is a named export from importPath , named importName . Default to using name if not specified. |
Prop Metadata
You can specify a lot of metadata about each prop of your global context; this helps Plasmic understand what each prop expects as an argument, so that Plasmic can generate the right UI in the Studio for users to configure these props.
Prop types
The main piece of prop metadata is the type of value expected for the prop. Here are the types we currently support:
Type | Prop value type | Description |
---|---|---|
string | string | Configured via a text input box in the Studio |
boolean | boolean | Configured via a toggle switch in the Studio |
number | number | Configured via a number input box or a slider |
code | string | Configured via code editor in the Studio |
object | JSON object or array | Configured via a text editor for arbitrary JSON values, including objects or arrays |
choice | string or string[] | A select dropdown or a multi-select, for picking from an enumeration of possible string choices |
As a convenient shorthand, if you don’t care about other prop metadata, then you can just pass in the type string as the prop metadata:
registerGlobalContext(MyComponent, {name: 'MyComponent',props: {color: 'string'}});
Common options
Here are the common options you can specify in the prop metadata object. Most of them are optional, but specifying them will help Plasmic understand them better, and make them easier to use for Studio users.
Field | Required? | description |
---|---|---|
type | Yes | One of the supported prop types |
defaultValue | No | The default value that should be provided to the prop. If not present, and no value is passed when the component is instantiated, Plasmic won’t provide any value. For slots, the default value can be an “element” or array of elements; see element types. |
defaultValueHint | No | A value that is like a default value, but not actually used. Instead, it is shown as a placeholder when possible in the configuration control. |
editOnly | No; defaults to false | A boolean indicating whether the values passed to that prop should only be used in the Studio, and not in real generated code. For example, you might have props that are only there to support Studio editor usage (like a prop that turns off animations or auto-play in the Studio). Another common example is a prop like value , which “controls” the value of, say, a TextInput component; in the Studio, it may be useful to set the value to something to see how it looks, but you may not actually want to use it in the generated code. Instead, it may make sense to pass on this value along to an uncontrolledProp . Not applicable for slot s. |
uncontrolledProp | No | This is only applicable if editOnly is true. If specified, then the value that is set for this prop will instead be passed on to a prop with this name instead. This is useful when you have a controlled/uncontrolled pair of props, like value and defaultValue ; in the Studio, you’d want to be able to set value to see how it looks, but when generating code, you may want to pass the value as defaultValue instead. |
Type-specific options
Some additional options are only relevant to specific types:
choice
Field | Required? | description |
---|---|---|
options | Yes | Either a string[] that the user can choose from, or a {value: string \| number \| boolean, label: string}[] where the value is what’s ultimately passed into the prop. |
multiSelect | No | If true, then allows selection of multiple options. The selection is to the prop as an array of strings. |
number
Field | Required? | description |
---|---|---|
control | No; defaults to default | Either default or slider . If default , then Studio will render a default number input for configuring this prop. If slider , then Studio will render a number slider. |
min | Yes if slider | Specifies the minimum value allowed. |
max | Yes if slider | Specifies the maximum value allowed. |
step | No | A number to indicate the step between consecutive values in the slider. If not specified, a default value will be computed based on the range [min, max] . |
string
Field | Required? | description |
---|---|---|
control | No; defaults to default | Either default or large . If default , then Studio will render a default text input for configuring this prop. If large , then Studio will render a larger text editor with file uploader. |
code
Field | Required? | description |
---|---|---|
lang | Yes | The code language for syntax highlighting and autocomplete. Allowed values are css , html , javascript and json . |