Home > @uniformdev/canvas

canvas package

Classes

ClassDescription
BatchEntryA single entry in a batch of queued enhancements.
CanvasClient
CategoryClient
ChildEnhancerBuilderBuilds a definition of the enhancers to run on Canvas components to add data from other systems. Note that only the first matching enhancer will be run.
ContentClient
DataSourceClientAPI client to make comms with the Next Gen Mesh Data Source API simpler
DataTypeClientAPI client to make comms with the Next Gen Mesh Data Type API simpler
EnhancerBuilderBuilds a definition of the enhancers to run on Canvas components to add data from other systems. Note that only the first matching enhancer will be run.
LocaleClientAPI client to enable managing project locales
PromptClientAPI client to make comms with the Next Gen Mesh Data Source API simpler
RelationshipClient
RouteClientResolves a route using Uniform Project Map and Uniform Redirects, returning a composition, redirection, or not found result.
UncachedCanvasClient
UncachedCategoryClient
UncachedContentClient
UniqueBatchEntriesGiven a batch of enhancements containing potentially duplicate entries (i.e. several components referencing the same thing), group them together by some unique identifier and enable simpler batch processing.

Functions

FunctionDescription
bindVariables({ variables, value, errorPrefix, handleBinding, })Binds variables to a string that could have variable values in it. Variables are referenced in the string as $}
bindVariablesToObject(options)Binds composition variables to an object whose string keys may have variable expressions in them. Binding is recursive.
convertEntryToPutEntry(entry)Converts a content entry to a put content entry body that has only the properties expected to the PUT API. Removes things like author, stats, etc.
createBatchEnhancer({ handleBatch, shouldQueue, limitPolicy, })Creates an enhancer that batches up all enhancements for a composition into a set of promises, and then handles them all in a single batch. Used to reduce the number of HTTP requests needed to fulfill layout enhancements when a layout uses many resources from other systems.
createEventBus()Creates an event bus client to receive updates from Canvas IMPORTANT: in a server-side context this will always return undefined IMPORTANT: in a browser context this is cached in window and does not create multiple instances
createLimitPolicy({ throttle, retry, })
createVariableReference(variableName)
enhance({ composition, enhancers, context, onErrors, })Applies enhancer functions to a component tree. IMPORTANT: the input composition object is mutated. Plan accordingly. Want immutability? Grab immer :)
extractLocales({ component })
findParameterInNodeTree(data, predicate)Walk a Composition or Entry tree to find parameters or fields based on the predicate returning true
flattenValues(data, options)
flattenValues(data, options)
flattenValues(data, options)
flattenValues(data, options)
flattenValues(data, options)
getBlockValue(component, parameterName)Gets the typed value of a block parameter or block field
getChannelName(projectId, compositionId, state)
getComponentJsonPointer(ancestorsAndSelf)Returns the JSON pointer of a component based on its location
getComponentPath(ancestorsAndSelf)
getNounForLocation(parentLocation)
getNounForNode(node)
getPropertiesValue(entity)Gets the object holding the properties (fields or parameters) of an entry or component instance If no properties are defined, returns undefined.
getPropertyValue(parameter)Get the data stored in the value of a component parameter or a field attached to an Entry, Block or Asset
getPropertyValue(parameter)
getPropertyValue(parameter)
isAssetParamValue(value)A fast, non-exhaustive guard which checks that the value is an array as well as the first item, if there is one, looks like an asset item
isAssetParamValueItem(item)A fast, non-exhaustive guard which checks the required structure of an asset item
isEntryData(entryData)Check to see if some generic composition data structure looks like Entry data
isNestedNodeType(type)Any types which hold an array of nodes and therefore should be iterated over as child nodes
isRootEntryReference(root)When walking a node tree, is the node the root node and look like Entry data
localize(options)
localize(options)<p>Localizes a composition or entry that may contain: * Structural localization with localization components (locale specific layout) * Property localization with localizable property values (translations)</p><p>The result will contain only parameters and localizations that match one of the input locales. Information for other locales will be discarded in the result.</p><p>NOTE: this function mutates its input object for maximum performance. If you desire immutability wrap it in immer.</p>
mapSlotToPersonalizedVariations(slot)Converts components in a slot into personalized variations (based on each component's intent tag in Canvas) suitable to pass to a personalize component Useful when implementing custom personalization settings for Canvas components.
mapSlotToTestVariations(slot)Converts components in a slot into test variations (based on each component's Context tag in Canvas) suitable to pass to a personalize component Useful when implementing custom test settings for Canvas components.
parseVariableExpression(serialized, onToken)Parses an expression that may contain Uniform variables and invokes a callback for each text or variable token found
subscribeToComposition({ projectId, compositionId, compositionState, eventBus: { subscribe }, callback, event, })Subscribes to a composition event
walkComponentTree(component, visitor, initialContext)Walks a composition's component tree, visiting each component instance depth-first, in order.
walkNodeTree(node, visitor, options)Walks a composition's content tree, visiting each component in a slot or block parameter/field depth-first, in order.

Interfaces

InterfaceDescription
FindInNodeTreeReference
FlattenValuesOptions

Variables

VariableDescription
ASSET_PARAMETER_TYPEThis is the type value for the asset parameter or field
ASSETS_SOURCE_CUSTOM_URLThe _source for any assets which have manually set fields
ASSETS_SOURCE_UNIFORMThe _source for any assets coming from the Uniform Asset Library
ATTRIBUTE_COMPONENT_ID
ATTRIBUTE_MULTILINE
ATTRIBUTE_PARAMETER_ID
ATTRIBUTE_PARAMETER_TYPE
ATTRIBUTE_PARAMETER_VALUE
ATTRIBUTE_PLACEHOLDER
CANVAS_BLOCK_PARAM_TYPEParameter type for a block parameter
CANVAS_DRAFT_STATEConstant for a draft composition state. Subject to change.
CANVAS_EDITOR_STATEConstant for editor composition state.
CANVAS_ENRICHMENT_TAG_PARAMPublic ID of the Uniform Context enrichment tag parameter on Canvas components
CANVAS_INTENT_TAG_PARAMPublic ID of the intent tag parameter on the Canvas personalization component type
CANVAS_LOCALE_TAG_PARAMPublic ID of the locale parameter on Canvas components
CANVAS_LOCALIZATION_SLOTName of the slot on CANVAS_TEST_TYPE
CANVAS_LOCALIZATION_TYPEPublic ID of Canvas localization component type
CANVAS_PERSONALIZATION_PARAMPublic ID of the Uniform Context personalization parameter on Canvas components
CANVAS_PERSONALIZE_SLOTName of the slot on CANVAS_PERSONALIZE_TYPE
CANVAS_PERSONALIZE_TYPEPublic ID of Canvas personalization component type
CANVAS_PUBLISHED_STATEConstant for a published composition state. Subject to change.
CANVAS_TEST_SLOTName of the slot on CANVAS_TEST_TYPE
CANVAS_TEST_TYPEPublic ID of Canvas A/B test component type
CANVAS_TEST_VARIANT_PARAMPublic ID of the Uniform Context test variant parameter on Canvas components
CanvasClientError
composeComposes several enhancers into a synchronous chain. Can be used to modify the output of an enhancer. NOTE: only the first enhancer in the chain may use batching (completeAll()).
createCanvasChannel
createUniformApiEnhancerCreates an enhancer based on an API route. This is mainly used to create an enhancer for Contextual Editing, which can be passed to the <code>contextualEditingEnhancer</code> prop of <code><UniformComposition /></code>.
EDGE_CACHE_DISABLEDA value that indicates that Edgehancers caching is disabled
EDGE_DEFAULT_CACHE_TTLDefault value for Edgehancers Cache TTL (in seconds)
EDGE_MAX_CACHE_TTLMaximal value for Edgehancers Cache TTL (in seconds)
EDGE_MIN_CACHE_TTLMinimal value for Edgehancers Cache TTL (in seconds)
EMPTY_COMPOSITIONContextual editing empty composition, used as a placeholder while waiting for the composition to be send by the editor.
generateComponentPlaceholderId
generateHash
getParameterAttributesReturns the attributes needed to annotate a Uniform parameter for inline editing. Supports only text parameters at the moment.
IN_CONTEXT_EDITOR_COMPONENT_END_ROLEThe value of "data-role" in the component end <code><script></code> tag
IN_CONTEXT_EDITOR_COMPONENT_START_ROLEThe value of "data-role" in the component start <code><script></code> tag
IN_CONTEXT_EDITOR_CONFIG_CHECK_QUERY_STRING_PARAMThe name of the query string used to get the config from the preview url
IN_CONTEXT_EDITOR_EMBED_SCRIPT_IDThe ID of the Contextual Editing script that gets embedded in frontend apps
IN_CONTEXT_EDITOR_FORCED_SETTINGS_QUERY_STRING_PARAMThe name of the query string used to detect if we are in contextual editing mode
IN_CONTEXT_EDITOR_PLAYGROUND_QUERY_STRING_PARAMThe name of the query string used to indicate that we want to use the playground for preview
IN_CONTEXT_EDITOR_QUERY_STRING_PARAMThe name of the query string used to detect if we are in contextual editing mode
IS_RENDERED_BY_UNIFORM_ATTRIBUTEThe name of the attribute added to the elements rendered by Uniform. Use to allow interacting with them by default in the preview panel
isAddComponentMessage
isAllowedReferrerChecks if page is opened from inside Uniform Canvas Editor. So if you open preview in incognito or via copy/paste link, it will return false.
isComponentActionMessage
isComponentPlaceholderId
isDismissPlaceholderMessage
isMovingComponentMessage
isOpenParameterEditorMessage
isReadyMessage
isReportRenderedCompositionsMessage
isSelectComponentMessage
isSelectParameterMessage
isSystemComponentDefinitionDetermines if a given Canvas component type is a system-defined type
isTriggerCompositionActionMessage
isUpdateComponentParameterMessage
isUpdateComponentReferencesMessage
isUpdateCompositionInternalMessage
isUpdateCompositionMessage
isUpdateContextualEditingStateInternalMessage
isUpdateFeatureFlagsMessage
isUpdatePreviewSettingsMessage
LOCALE_DYNAMIC_INPUT_NAME
nullLimitPolicy
PLACEHOLDER_IDThe ID we give to placeholder components
SECRET_QUERY_STRING_PARAMThe name of the query string used to set a secret to protect for the preview mode. This is not configurable at the moment.

Type Aliases

Type AliasDescription
AddComponentMessage
AssetParamValue
AssetParamValueItem
BatchEnhancerAn enhancer that queues up promises for each component that needs enhancing, and once all enhancements have been queued handles them all in a batch. Note: this type is adaptable to both ComponentParameterEnhancer and ComponentEnhancer types.
BatchInvalidationPayload
BindVariablesOptions
BindVariablesResult
BindVariablesToObjectOptions
BlockLocationReferenceAncestor location that is in a block on a parameter or field
BlockValueValue type of a block parameter or block field
CanvasDefinitionsDefines single structure to keep all canvas models (used in CLI commands and Starter content generations)
CategoriesDeleteParametersShape of the DELETE request body for /api/v1/category
CategoriesGetParametersQuery parameter options for GET /api/v1/category
CategoriesGetResponseShape of the GET response from /api/v1/category
CategoriesPutParametersShape of the PUT request body for /api/v1/category
CategoryDefines a component type that can live on a Composition
Channel
ChannelMessage
ChannelSubscriptionPusher-js is large (80k) and not tree shakable so it is always bundled if directly referenced, when it's only needed during preview mode. To avoid bundling it for all, we use an old-school write-a-script-tag hack to load it in a poor man's approximation of a dynamic import ;)
ComponentDefinitionDefines a component type that can live on a Composition
ComponentDefinitionDeleteParametersShape of the DELETE request body for /api/v1/canvas-definitions
ComponentDefinitionGetParametersQuery parameter options for GET /api/v1/canvas-definitions
ComponentDefinitionGetResponseShape of the GET response from /api/v1/canvas-definitions
ComponentDefinitionParameterThe definition of a component parameter
ComponentDefinitionPermissionPermission set for a component defintion
ComponentDefinitionPutParametersShape of the PUT request body for /api/v1/canvas-definitions
ComponentDefinitionSlotThe definition of a named component slot that can contain other components
ComponentDefinitionSlugSettingsThe definition of a composition's slug settings
ComponentDefinitionVariantThe definition of a component visual variant
ComponentEnhancerDefines logic to add arbitrary async data to a component's <code>data</code> property. Used to enhance layout data with information from other platforms, such as private APIs, where the value is not tied to a parameter and is intrinsic to the component itself.
ComponentEnhancerFunction<p>A function which is called for each matching component in a composition, which can manipulate the value of a specific key in the component's <code>data</code> property. Used to enhance layout data with information from other platforms, such as private APIs, where the value is not tied to a parameter and is intrinsic to the component itself.</p><p>Note: the configuration of enhancers namespaces component enhancers into a named property on the data object to avoid collisions, thus an enhancer need not worry about merging values with other enhancers, nor which key it has been registered under.</p><p>Return values: TValue - sets the configured key in the component's data value to this value undefined - do not set the component's data key</p>
ComponentEnhancerOptionsOptions passed to a ComponentEnhancer function
ComponentInstanceDefines the shape of a component instance served by the composition API.
ComponentInstanceContextualEditingThe type of the component instance in contextual editing mode.
ComponentInstanceHistoryEntryA historical version of a composition
ComponentInstanceHistoryGetParametersThe GET response from /api/v1/canvas-history (history for one composition)
ComponentInstanceHistoryGetResponseThe GET response from /api/v1/canvas-history
ComponentLocationReference
ComponentLocationReferenceV2Ancestor location that is in a slot on a component
ComponentOverridabilityDefines how a component on a pattern may have its values overridden
ComponentOverrideDefines the shape of a component override
ComponentOverridesDefines a set of component overrides by component ID
ComponentParameterDefines an editable parameter on a component.
ComponentParameterBlockParameter which stores blocks of entry types
ComponentParameterContextualEditingThe type of the parameters in contextual editing mode.
ComponentParameterEnhancerDefines logic to replace the value of a component parameter with arbitrary async data. Used to enhance layout data with information from other platforms, such as CMS, commerce, indexing, etc, where that data is directly expandable from a parameter value.
ComponentParameterEnhancerFunction<p>A function which is called for each component parameter in a component tree, which can manipulate the value of the parameter. Used to enhance layout data with information from other platforms, such as CMS, commerce, indexing, etc.</p><p>Return values: TValue - replaces the original parameter value with this value undefined - do not change the original parameter value null - sets the parameter value to null, replacing any existing value (i.e. if its value could not be resolved in an external system)</p>
ComponentParameterEnhancerOptionsOptions passed to a ComponentParameterEnhancer function
CompositionDataDiagnostic
CompositionDeleteParametersShape of the DELETE request body for /api/v1/canvas
CompositionDiagnostics
CompositionGetByComponentIdParameters
CompositionGetByIdParameters
CompositionGetByNodeIdParameters
CompositionGetByNodePathParametersDefines exact parameters for specific requests getting a single composition
CompositionGetBySlugParameters
CompositionGetListResponseThe GET response from /api/v1/canvas when <code>component</code> or <code>slug</code> are not specified
CompositionGetOrderBy
CompositionGetParametersQuery parameter options for GET /api/v1/canvas
CompositionGetResponseThe GET response from /api/v1/canvas when <code>component</code> or <code>slug</code> params are specified
CompositionGetValidResponsesAll valid response types
CompositionIssue
CompositionPatternIssue
CompositionPutParametersThe PUT request body for /api/v1/canvas
CompositionResolvedGetResponseResponse as it comes from uniform.global/api/v1/composition
CompositionResolvedListResponse
CompositionUIStatus
ContentType
ContentTypeField
ContextualEditingComponentReference
DataDiagnosticDiagnostic data about the load performance of attached composition datas
DataElementBindingIssueAn error while binding a dynamic token from a data resource to a component parameter (i.e. a missing property in the data resource)
DataElementConnectionDefinitionDefines a connection to a dynamic token on a data resource.
DataResolutionConfigIssueError in data resolution configuration (internal error)
DataResolutionIssueTypes of issue that can occur when fetching composition data
DataResolutionOptionSwitches for data resolution
DataResolutionOptionNegative
DataResolutionOptionPositive
DataResolutionParameters
DataResourceDefinitionDefines a data resource, which is a named JSON document, usually from an API response, which may be projected onto parameters
DataResourceDefinitionsData definitions attached to this component. The property name is the key of the data in the data document. Note: data definitions are inherited from ancestors at runtime (and may be overridden by descendants that use the same key).
DataResourceIssueAn error that occurred fetching a data defined on the composition or a pattern within
DataResourceVariablesVariable values for a data resource.
DataSource
DataSourceDeleteParametersShape of the DELETE request body for /api/v1/data-source
DataSourceGetParametersQuery parameter options for GET /api/v1/data-source
DataSourceGetResponseThe GET response from /api/v1/data-sources
DataSourcePutParametersThe PUT request body for /api/v1/data-source
DataSourcesGetParametersQuery parameter options for GET /api/v1/data-sources
DataSourcesGetResponseThe GET response from /api/v1/data-sources
DataType
DataTypeDeleteParametersShape of the DELETE request body for /api/v1/data-types
DataTypeGetParametersQuery parameter options for GET /api/v1/data-types
DataTypeGetResponseThe GET response from /api/v1/data-types
DataTypePutParametersThe PUT request body for /api/v1/data-types
DataVariableDefinition
DataWithProperties
DeleteContentTypeOptions
DeleteEntryOptions
DismissPlaceholderMessage
DynamicInputIssueAn issue that occurred while binding dynamic inputs to composition data resources, specifically when an expected dynamic input did not have a value.
EdgehancersDiagnosticsDiagnostics about edge request processing
EdgehancersWholeResponseCacheDiagnostics
EditorStateUpdatedMessage
EnhancerContext
EnhancerError
EntriesGetParametersThe GET response from /api/v1/entries
EntriesGetResponse
EntriesHistoryGetParametersThe GET response from /api/v1/entries-history (history for one entry)
EntriesHistoryGetResponseThe GET response from /api/v1/entries-history
EntriesResolvedListResponse
Entry
EntryData
EntryList
EventNames
Filters
FlattenProperty
FlattenValues
GetContentTypesOptions
GetContentTypesResponse
GetEntriesOptions
GetEntriesResponse
GetParameterAttributesProps
InvalidationPayload
LimitPolicy
LinkComponentParameterValue
LinkParamConfiguration
LinkParameterType
LinkParamValue
LinkTypeConfiguration
LocaleA locale definition
LocaleDeleteParametersShape of the DELETE request body for /api/v1/locales
LocalePutParametersThe PUT request body for /api/v1/locales
LocalesGetParametersQuery parameter options for GET /api/v1/locales
LocalesGetResponseThe GET response from /api/v1/locales
LocalizeDeprecatedOptions
LocalizeModernOptions
MessageHandler
MoveComponentMessage
NodeLocationReference
NonProjectMapLinkParamValue
OpenParameterEditorMessage
OverrideOptionsDefines the shape of a component override
PatternIssueAn error that occured resolving a pattern that is referenced on the composition
PreviewEventBus
PreviewPanelSettings
ProjectMapLinkComponentParameterValue
ProjectMapLinkParamValue
Prompt
PromptsDeleteParametersShape of the DELETE request body for /api/v1/prompts
PromptsGetParametersQuery parameter options for GET /api/v1/prompts
PromptsGetResponseThe GET response from /api/v1/prompts
PromptsPutParametersThe PUT request body for /api/v1/prompts
PutContentTypeBody
PutEntryBody
ReadyMessage
RelationshipResultInstance
ReportRenderedCompositionsMessage
ResolvedRouteGetResponseA route API response with edgehancer composition result
RichTextBuiltInElement
RichTextBuiltInFormat
RichTextParamConfiguration
RichTextParamValue
RootComponentInstanceDefines the shape of the root component in a composition
RootEntryReference
RootLocationReferenceAncestor location that is the root of a composition or entry
RouteDynamicInputs
RouteGetParametersThe GET response from /api/v1/route
RouteGetResponse
RouteGetResponseComposition
RouteGetResponseEdgehancedCompositionGET response from uniform.global/api/v1/route when result is a composition
RouteGetResponseNotFound
RouteGetResponseRedirect
SelectComponentMessage
SelectParameterMessage
SpecificProjectMap
SubscribeToCompositionOptions
TreeNodeInfoTypes
TriggerComponentActionMessage
TriggerCompositionActionMessage
UnsubscribeCallback
UpdateComponentParameterMessage
UpdateComponentReferencesMessage
UpdateCompositionInternalMessage
UpdateCompositionMessage
UpdateContextualEditingStateInternalMessage
UpdateFeatureFlagsMessage
UpdatePreviewSettingsMessage
WalkComponentTreeActions
WalkNodeTreeActions
WalkNodeTreeOptions