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.
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.
unstable_CompositionRelationshipClient

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 })
getChannelName(projectId, compositionId, state)
getComponentJsonPointer(ancestorsAndSelf, { withSlots })Returns the JSON pointer of a component based on its location
getComponentPath(ancestorsAndSelf)
localize({ composition, locale, })
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.

Variables

VariableDescription
ATTRIBUTE_COMPONENT_ID
ATTRIBUTE_MULTILINE
ATTRIBUTE_PARAMETER_ID
ATTRIBUTE_PARAMETER_TYPE
ATTRIBUTE_PARAMETER_VALUE
ATTRIBUTE_PLACEHOLDER
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_DEFAULT_L2_CACHE_TTL_IN_HOURSDefault value for Edgehancers Long Term Cache TTL (in hours)
EDGE_MAX_CACHE_TTLMaximal value for Edgehancers Cache TTL (in seconds)
EDGE_MAX_L2_CACHE_TTL_IN_HOURSMaximal value for Edgehancers Long Term Cache TTL (in hours)
EDGE_MIN_CACHE_TTLMinimal value for Edgehancers Cache TTL (in seconds)
EDGE_MIN_L2_CACHE_TTL_IN_HOURSMinimal value for Edgehancers Long Term Cache TTL (in hours)
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_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.
isComponentPlaceholderId
isDismissPlaceholderMessage
isMovingComponentMessage
isReadyMessage
isReportRenderedCompositionsMessage
isSelectComponentMessage
isSelectParameterMessage
isSystemComponentDefinitionDetermines if a given Canvas component type is a system-defined type
isTriggerCompositionActionMessage
isUpdateComponentParameterMessage
isUpdateCompositionInternalMessage
isUpdateCompositionMessage
isUpdateContextualEditingStateInternalMessage
isUpdatePreviewSettingsMessage
nullLimitPolicy
PLACEHOLDER_IDThe ID we give to placeholder components

Type Aliases

Type AliasDescription
AddComponentMessage
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
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
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.
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
CompositionRelationshipsClientOptions
CompositionRelationshipsDDefinitionGetResponse
CompositionRelationshipsDefinitionApi
CompositionRelationshipsDefinitionGetParameters
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
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
EditorStateUpdatedMessage
EnhancerContext
EnhancerError
EntriesGetParametersThe GET response from /api/v1/entries
EntriesGetResponse
EntriesResolvedListResponse
Entry
EventNames
GetContentTypesOptions
GetContentTypesResponse
GetEntriesOptions
GetEntriesResponse
GetParameterAttributesProps
InvalidationPayload
LimitPolicy
LinkComponentParameterValue
LinkParamConfiguration
LinkParameterType
LinkParamValue
LinkTypeConfiguration
MessageHandler
MoveComponentMessage
NonProjectMapLinkParamValue
OverrideOptionsDefines the shape of a component override
PatternIssueAn error that occured resolving a pattern that is referenced on the composition
PreviewEventBus
PreviewPanelSettings
ProjectMapLinkComponentParameterValue
ProjectMapLinkParamValue
PutContentTypeBody
PutEntryBody
ReadyMessage
ReportRenderedCompositionsMessage
ResolvedRouteGetResponseA route API response with edgehancer composition result
RichTextBuiltInElement
RichTextBuiltInFormat
RichTextParamConfiguration
RichTextParamValue
RootComponentInstanceDefines the shape of the root component in a composition
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
TriggerCompositionActionMessage
UnsubscribeCallback
UpdateComponentParameterMessage
UpdateCompositionInternalMessage
UpdateCompositionMessage
UpdateContextualEditingStateInternalMessage
UpdatePreviewSettingsMessage
UsageTrackingApi
UsageTrackingGetParameters
UsageTrackingGetResponse
UsageTrackingPostParameters
UsageTrackingPostResponse
WalkComponentTreeActions