Help Center

Menu

Use cases and usage guidelines

The Component Service is flexible and can be used in various ways.

There are, however, some circumstances when the Component Service should not be used or is not supported.

Suitable use cases

The Component Service is designed for the following specific use cases:

  • Creating structured design elements that editors can add to a content page.

  • Implementing design systems that will be used across one or many sites.

  • Components that require more complex server-side code to render a section of a web page.

  • Components that load data from other sources, such as an API, and render it server-side.

  • Interactive components that render both HTML and JSON endpoints and that interact with other services client-side. For example, a carousel slideshow or a video player.

  • Components that package up some useful features and are deployed to other third-party websites. For example, a course finder component was added to a portal not built on the Squiz DXP.

  • Building design system components that display basic structured content.

  • Complex interactive and data-driven elements.

  • Content editing integration within the Squiz Content Management Service.

  • Multi-channel deployment to other websites or channels beyond the Squiz Content Management Service.

  • Design system management across many websites with numerous editors and stakeholders.

  • Stand-alone components designed to be embedded on third-party sites.

  • Local development and testing with preview functionality.

  • Environment-specific behavior using environment variables.

  • Dynamic data retrieval from the Content Management system.

General limitations

You should be aware of the following general limitations of the Component Service. Some limitations are by design, while others will be resolved as features are rolled out to the service.

Service architecture limitations

  • The service communicates with Squiz Content Management Service through the Content API, which offers a read-only interface.

  • Output is cached with a minimum timeout period. Read the Cache headers documentation for more information.

  • Request execution time is limited to five seconds. Read Five-second process execution limitations for specific caveats.

  • The Component Service is not designed to manage inter-component dependencies. Dependency chains should be avoided in components.

  • Squiz Content Management Service keywords and other service-specific syntax are not supported inside the Component Service.

JavaScript execution environment

  • Server-side JavaScript within components runs in a Node.js environment and cannot access browser-specific objects like the window object.

  • Server-side modules adhere to CommonJS conventions, often necessitating the .cjs file extension or specific Node.js module configurations. Read the CommonJS conventions documentation for more information.

Page builder preview behavior

  • Standard DOMContentLoaded and typical script initialization methods might not work as expected within Page Builder’s live preview.

  • Developers should instead listen for the livePreviewUpdated event for reinitialization, although this event is not triggered on the initial page load. Read the Best practices for JavaScript and iFrame implementations inside components documentation for more information.

  • For complex interactive behaviors, such as event handlers on FormattedText fields, a wrapper element must be placed around the field in the Visual Page Builder preview column for the functionality to work correctly.

Component self-containment and file referencing

  • Component files are constrained to reference other files or resources within their own or a child directory.

  • This means shared libraries or external files cannot be directly referenced unless prebuilt or compiled into the component’s directory. Read the Reuse static files across your self-contained components documentation for more information.

Static file support

  • Components deployed using the Components at Edge runtime do not support static files. Read the Remove static files documentation for more information.

Inline editing constraints

  • Fields using the matrix-asset-uri type cannot be edited inline; editors must use the right-side panel to update these fields. Read the Inline editing limitations documentation for more information.

  • When using SquizLink types, only the url field is editable inline, even if the entire anchor is wrapped with data-sq-field="link". Read the Inline editing limitations documentation for more information.

  • Full-area overlays, such as pseudo-elements or absolute-positioned elements covering content, can interfere with inline editing by making fields unclickable or non-editable. It is advised to avoid covering editable text fields with position: absolute layers unless necessary. Read the Inline editing limitations documentation for more information.

  • Building components with inline editing and adding complex actions like event handlers to FormattedText fields will not work in the Visual Page Builder preview column unless a wrapper element is placed around the field and the event handler is attached to the wrapper instead. Read the Inline editing and complex behaviors documentation for more information.

Edge component utility availability

  • Certain advanced utilities, including the Context object (info.ctx) and functions like resolveMatrixAssetById and resolveMatrixAssetByUrl for resolving Matrix assets, are only available for Components at Edge.

  • The use of resolveMatrixAssetById and resolveMatrixAssetByUrl utilities specifically requires session-based authentication to be enabled for the Content Management Content API. Read the Context asset ID and Context URL documentation for more information.

Resource browser functionality

  • The Resource Browser’s operation can be impacted by configuration problems, including missing or invalid API identifiers or tokens, incorrect user or API permissions, or misconfigurations related to Squiz Search integration.

Editing interface customization

  • The editing experience for content editors is automatically generated from the component’s content model.

  • While some field-level display options are available (for example, collapsing fields, prioritizing Quick Edit), extensive UI customizations are impossible.

    There are, however, ways to influence aspects of the interface if we want to consider the following:

  • Use ui:metadata in the manifest.json to collapse non-essential fields by default in the sidebar.

  • Prioritise essential fields for Quick Edit within the single panel to prevent it from becoming crowded.

  • The inlineEditable property can be set within ui:metadata to enable inline editing for specific string fields.

  • Define title and description for fields to provide more context within the editing interface

  • For matrix-asset-uri input types, developers can specify matrixAssetTypes to restrict the valid file types available to be selected via the resource browser, influencing the editor’s choices.

Service operational scope

  • The primary role of the Component Service is the rendering and delivery of components.

  • This implies a read-only nature for data manipulation from within component code.

Unsuitable use cases

Basic text formatting

The WYSIWYG editor in your CMS should handle the output when the output is not complex. For example, basic text formatting. The Component Service is not intended to implement your design system’s more atomic style elements.

Completely bespoke editing interface requirements

The service is not designed to serve custom editing interfaces.

Chaining multiple components together

Loading components from within other components is not supported.

Using server-side code to write data to a persistent datastore

The Component Service is designed to be cacheable and read-only. Any write actions, for example, submitting a form or sending data through an API to be stored, must only be performed client-side if implemented using the Component Service.

Using Content Management Service implementation patterns through the UI

Component Service uses APIs and JavaScript to render your components. With the move to more industry-standard approaches, Squiz Content Management Service keywords, asset listings, and other low-code features are incompatible. Data is loaded through APIs and processed through code. This approach also requires that developers can work on code locally and deploy it.

Components that need to return an uncached response

The Component Service has a five-minute minimum cache timeout.

Direct event handling on formatted text

Directly attaching complex event handlers to FormattedText fields without a wrapper element, particularly for visual Page Builder previews, as this will not work as expected.

Client-side library management (highly shared)

While components can include static files, if your design system uses many components with shared global styling and scripts, it might be less beneficial to make components entirely self-contained. Referencing external static files via global templates or a build process for shared libraries is often more efficient.

Inline editing of specific field types

Attempting to inline edit matrix-asset-uri fields or all aspects of SquizLink fields (only the URL of a SquizLink is inline editable) is not supported.

Overlapping UI elements

Creating full-area overlays (for example, using position: absolute or pseudo-elements) that cover editable text fields, as this can prevent inline editing functionality.

Static files with edge components

Using static files with components deployed using the Components at Edge runtime is not supported.

Reliance on window object

Developing server-side JavaScript that assumes the presence of a window object, as this is unavailable in the Node.js environment, where components are rendered.

Improved editor experience

The Component Service provides several ways to improve the content editor experience:

Collapsing fields

Hiding non-essential fields (internal settings, technical toggles) by default in the sidebar to keep the editing interface clean and focused for Content Editors.

Prioritizing quick edit fields

Including only essential fields in the Quick Edit panel, preventing it from becoming crowded and difficult to navigate.

Meaningful default values

Providing default text values for fields like heading, label, or buttonText makes the initial experience smoother and enables immediate inline editing.

Advanced capabilities

Asynchronous data resolution

Using the matrix-asset-uri format with the info.ctx.resolveUri function to asynchronously resolve content API requests to a Squiz Content Management System and return asset objects.

Local development and testing

  • Allows mocking of URI resolutions for local development using the mockedUris keyword in the manifest file. Read the Preview mock documentation for more information.

  • Provides functionality to create previews with supporting files and data for local testing and demonstrating to stakeholders in the DXP Console.

Environment-specific behavior

Utilizing environment variables allows components to behave or render differently across various component sets or to store sensitive data like API keys securely. Read the Environment variables documentation for more information.

Dynamic data retrieval

  • Accessing the current URL or the Content Management Asset ID of the parent component via the info.ctx (context object) for making content decisions or retrieving additional data from Matrix. Read the Context object documentation for more information.

  • Retrieving additional data from the Content Management system using resolveMatrixAssetById (with asset ID) or resolveMatrixAssetByUrl (with URL). Read the Resolve Matrix Asset ID and Resolve Matrix Asset URL documentation for more information.

  • Building rich content components that retrieve data from other sources through the info.fns (functions object). Read the Functions object documentation for more information.

Five-second process execution limitations

The Component Service has a hard five-second limit on server scripts and processes. This execution limit makes the service unsuitable for use as:

  • A Node.js application platform.

  • A workload runner system.

The time limit also means the following use cases will not work reliably and are therefore considered unsupported configurations.

Loading data from several sources in the same process

The more sources from which your component ingests data, the longer the potential execution time. Consider implementing a method that pre-loads data for your component so you do not encounter the hard execution time limit.

Performing significant computation

If you are doing more intensive computation, consider using another system to generate your output and store it somewhere. Squiz Data Services is worth exploring as a way of storing data so Component Service can retrieve it within the five-second execution window.

Generating large amounts of output

If your component generates large amounts of dynamic output, you might need to use another system to generate your output and store it somewhere, such as Squiz Data Services. This allows the Component Service to retrieve it more efficiently.