Recommendations: Extending SXA

Current version: 1.8

You might want to extend SXA, for example, to add your own custom rendering to the SXA toolbox, add a theme, or a template. This topic describes some requirements and recommendations for extending SXA.

Never put custom items in SXA-controlled branches of the tree

When extending SXA, think about where to store your custom items. SXA overwrites the standard SXA sections during SXA updates. Therefore, placing custom items in tree branches controlled by SXA, can result in your instance being broken after an upgrade. We recommend that you:

  • Place custom modules in a branch that is a sibling to the Experience Accelerator module root.

  • Place templates in folders that are siblings to the Experience Acceleratorfolder – never inside.

  • Similarly, you must create a module-specific root item for all other areas, such as Renderings, Branches, Media.

Related topics:

Do not modify OOTB SXA items

When extending SXA , always use the SXA extension points for custom functionality. For example, create a custom data template. If this is not possible and you have a good reason for the extension, contact the SXA team to create extension point for you.

Related topics:

Do not replace the SXA MVC layout

The SXA MVC layout is the basis of grids, themes, and meta components, and SXA can depend on its presence for other common behavior. If you replace the layout with your custom implementation, you risk losing compatibility with future versions of SXA.

If you need to add custom non-visual elements to the layout, consider creating a meta rendering and add it to the Meta Partial Design. If you have visual elements, consider using standard SXA renderings.

 SXA provides multiple possibilities to extend the layout. For example, you can:

  • Add non-visual extensions by using meta-partial designs.

  • Add visual extensions by using regular partial designs.

  • Add JavaScript and styling elements using the assetServicepipeline.

  • Define a custom grid and define your custom markup of the <body> tag.

Create an SXA module for your custom renderings

Place custom renderings in an SXA module that can be added to an existing site or used immediately in newly created sites. 

You must:

  • Provide site/tenant scaffolding integration for your modules.

  • Include data source definitions for your components (or re-use OOTB SXA data sources).

  • Define site-relative queries for your data sources.

Related topics:

Follow Helix principles when adding functionality to your solution

Helix offers a set of official guidelines and recommended practices for Sitecore development. SXA follows the Sitecore Helix principles that contain development process recommendations for building, testing, extending, and maintaining Sitecore implementations.

We recommend that you:

  • Do not add dependencies on SXA feature modules – but rather only on foundation modules. It is permitted to violate the rule while cloning renderings because you use the platform code to provide the new feature. This recommendation applies to the OOTB SXA renderings and not necessarily SXA Storefront renderings. 

  • Separate and divide your features into proper Helix modules.

  • Provide site/tenant scaffolding integration for your modules.

Related topics:

Base your custom templates for pages on the Page template

When you create a custom template that represents a page, you must select the Page template as your base template. Otherwise, certain functionality might not work.

Item ID: Page: {3F8A6A5D-7B1A-4566-8CD4-0A50F3030BD8}.

Item path: sitecore/Templates/Foundation/Experience Accelerator/Multisite/Content/Page.

Consider using existing renderings before building a new one

You can customize existing SXA renderings by using rendering variants and composites. If possible, always consider using variants and composites before building a custom rendering.

For example, with rendering variants you can: use a reference item to display fields, use a query item with a token to render context items.

Related topics:

Consider cloning existing renderings before building a new one

You can easily clone SXA renderings if you want to customize the HTML beyond what is possible using rendering variants. In the process, you can also add to their data sources and rendering parameters. If possible, always consider this approach before building a custom rendering for functionality that you can achieve with SXA OOTB components.

Limit scope of fields linking to items

For fields that support queries, you must limit the scope of items that editors can choose from. 

For example, use:

  • query:$siteMedia – for file or image fields.

  • query:$home – for fields that link to pages.

  • query:$site – for fields that can link to any item within your site.

The description of the SXA pipelines includes a complete list of tokens and how to extend them.

Do you have some feedback for us?

If you have suggestions for improving this article,