Composition glossary

Uniform Canvas has a standard nomenclature that's used throughout. Here is what some of these terms mean.

Component#

A component is a basic building block of a digital experience. It represents an abstract notion of some part of a digital experience. This description is, purposefully, quite vague because components can represent almost anything you see a digital experience or anything used to control what you see.

Examples of components include:

• Hero on a landing page
• Product information in a commerce app
• Registration form
• Calendar of events
• Screen in a mobile app
• Page in a website
• Email message
• Settings for a menu or popup message

A practitioner such as a marketer or a merchandiser is able to configure values on a component to control a digital experience.

A component has the following properties:

• Parameters
• Slots
• (Display)Variants

Uniform supports the following types of components:

Component Library#

The component library is where you define your components. Usually, a component definition in the library has a 1:1 mapping with a component in your frontend framework.

For example a "Promo" component in the Canvas component library would define the data structure that a Promo component React would expect to receive as props.

Parameter#

Parameters define the data that a component definition needs, which might be data in some external system or local parameters to influence how the external data appears when rendered. For example a Promo component might have two parameters: content, which is a link to some content in a headless CMS, and alignment, which could be a single select of options for authors. These are the basic building block of what will end up as component props when rendering a Canvas composition.

Slot#

A slot in a component represents a named container where child components can be inserted. Slots allow for greater component flexibility and reusability.

In Uniform, a component slot defines:

• Count: the minimum and maximum number of children components you want to allow in the slot
• Allowed Components: which components can be added as children in the slot. Specifying / restricting what is allowed in a slot help usability and consistency with your style-guide and for combinations you’ve tested for proper rendering.

You can have as many slots as you want in a component, but typically a composition component (for example, Landing Page) has header, main, and footer slots, each configure different set of allowed components, while other non-composition components (for example, Grid) have only one slot.

Slot usage recommendations:

1. adopt a standard naming convention for slots in your project and use them consistently, for example header, content, footer, content-inner, sidebar-left, grid-items, encoding both parent component public id and slot name

2. try to use unique names for slots in your project to avoid conflicts with other components that might use the same slot name.

If you are a web developer, you may find that Slot is very similar to the idea of slots in web components or scoped slots in Vue.js.

Slot section#

A slot section is a named section within a slot of a component pattern which allows additional child components to be added to its containing slot on instances of component patterns. You can further limit the set of allowed components (or component patterns) for the slot section to be optimized for the use case or content requirements of a specific component pattern. For example you can only insert "Product card" component patterns inside the "Products" slot section of a "Product grid" component pattern.

(Display) Variant#

Typically, (Display) Variants are used to configure different visual treatments that use the same content. For example, if you have a component that displays product content, you might create two variants: grid and list. Another conventional example is a Card component that displays a product. You might create variants for different card widths, or different image position (image-left, image-right).

(Display) Variants can be used for testing, personalization, or simply giving authors options to pick a specific visual treatment of a component.

The main difference between creating a new component and a new variant for an existing component is that in case of the variant the component parameters (schema) is the same for all the variants, while in case of a new component the parameter set can be completely different for each instance of the component. If you have a family of the same components in terms of structure - consider using (Display) Variants, otherwise - create a new component type.

Composition#

A composition is a set of components that define a unit of layout. Often this could be considered an analog of a web page, if Canvas were being used to construct a website. Structurally a composition is a tree, with a root component instance selected from the component library. The branches of the tree from the root are created with slots.

Composition state#

Composition state is used to support a basic workflow process. This allows you to make multiple changes to a composition without affecting the "live" version of it. This means a composition may exist in multiple states.

The following is an example of how composition state is set when working in Canvas:

Slug#

A slug is a text string that can be assigned to a composition or content entry to give it an easier-to-remember identifier. In some cases, the slug will be used to represent an URL segment by the consumer of the Canvas API, but this isn't necessarily always the case.

Patterns#

A reusable component instance that can be referenced on one or more compositions. Patterns can be configured to allow partial overriding of their parameter and data resource values to support partially-reused data.

Component pattern#

A reusable component instance that can be referenced on one or more compositions. Component patterns can be configured to allow partial overriding of their parameter and data resource values to support partially-reused data. They can be extended using slot sections to allow additional components to be added to the pattern instances.

Composition pattern#

A pattern that is based on a full composition that can be used to create new compositions that share the structure and data resources of the pattern. Composition patterns can be configured to allow partial overriding of their parameter and data resource values to support partially-reused data. They can be extended using slot sections to allow additional components to be added to the pattern instances.

Data connection#

A data connection is the mappings between a property of an API response (a data element) and the value of a dynamic token which is placed inside a parameter of a component in Canvas. These connections to your UI components are made in the Canvas editor and don't require any code changes.

Data source#

A data instance, such as a CMS or API base URL, that stores secure authentication as needed. For example, the Yelp API.

Data type#

Represents the API query definition for the type of content or data that can be retrieved from a data source, such as a review from Yelp.

Data resource#

The specific instance of the data type which represents the JSON response of an API call, such as a review of a particular coffee shop from Yelp.

Data element#

Individual pieces of data that make up the data resource, like the title of a particular coffee shop review from Yelp.

Dynamic input#

Dynamic inputs represent dynamic path segments or query strings in project map nodes to define dynamic routes. Dynamic inputs can connect to dynamic tokens in data resources and Canvas components for use cases that require data fetching and routing logic which is dependent on external data.

Dynamic token#

A dynamic token is a placeholder for text which stores a data connection. The text of the dynamic token gets replaced with the resolved content or data of its data connection.

Edgehancer#

Uniform-managed fetching, caching, and merging of external data sources into your composition parameters. Edgehancers run at the CDN edge, so they're always close to your visitors for maximum cache efficiency even for regional API data.

To be able to fetch external data on the CDN edge you need to provide the connection and query details by configuring your data sources and data types.

Enhancer#

An enhancer is a function that provides a way to fetch external data referenced in a Canvas composition. For example if a composition contains a component instance with a parameter that refers to content from a CMS, an enhancer will pick that parameter up and fetch the actual CMS data.

There are two types of enhancers: parameter enhancers and data enhancers. A parameter enhancer alters the value of parameters on a component instance, for example to change a CMS content ID into the API response for that CMS' content API. Data enhancers are used to add data to a component that's not based on a specific parameter; for example you might wish to augment component data with customer information from an internal API.

Edition#

Editions are independent versions of a composition or content entry, each with its own content and publishing lifecycle. Derived from the original composition or entry (the "default edition"), they have unique component structures, content, data resources, and locales. Editions are automatically resolved based on the current locale of the attached project map node.

Unpublished content mode#

When enabled, content entities are fetched from an external data source by the edgehancer with an alternative configuration. Often it is content that hasn't been published yet, or that is not in certain workflow step, or that belongs to a different environment.