DEV Community: Sebastián Aliaga

Handling Hierarchical Taxonomies in Sitecore Search

Sebastián Aliaga — Fri, 28 Nov 2025 15:32:32 +0000

The Challenge

Sitecore's search functionality doesn't natively support hierarchical facets. When you have taxonomies with parent-child relationships (like "Water → Treatment" or "Infrastructure → Transportation"), the search index treats them as flat values, losing the important hierarchical context that helps users understand relationships and filter content more effectively.

Our Solution: The `Parent__Child` Pattern

To work around this limitation, we've implemented a solution that encodes hierarchical relationships directly into the search metadata using a double underscore (__) separator pattern. This allows us to:

Preserve hierarchy in the search index
Enable frontend parsing to reconstruct parent-child relationships
Maintain backward compatibility with flat taxonomies
Support flexible filtering at both parent and child levels

How It Works

The Architecture

Our solution consists of three key components:

TaxonomyService - GraphQL-powered service for fetching tag relationships
resolveHierarchicalTags - Utility function that resolves parent-child relationships
buildTagMetaProps - Helper function that processes multiple taxonomy groups

Step-by-Step Process

1. Tag Group Definition

In our metadata services (like ProjectsDetailMetadataService), we define tag groups that need hierarchical resolution:

const tagGroups = [
  {
    items: projectDetailPageProps?.practices,
    field: SEARCH_FIELDS.PRACTICES,
  },
  {
    items: projectDetailPageProps?.priorities,
    field: SEARCH_FIELDS.PRIORITIES,
  },
  {
    items: projectDetailPageProps?.technologies,
    field: SEARCH_FIELDS.TECHNOLOGIES,
  },
  {
    items: projectDetailPageProps?.markets,
    field: SEARCH_FIELDS.MARKETS,
  },
  {
    items: projectDetailPageProps?.region,
    field: SEARCH_FIELDS.REGION,
  },
];

Each group contains:

items: Array of tag item references from Sitecore
field: The search field name where the metadata will be stored
mode (optional): Either 'hierarchical' (default) or 'flat' for non-hierarchical tags

2. Hierarchical Resolution

The buildTagMetaProps helper processes these groups and calls resolveHierarchicalTags for each hierarchical group:

export async function resolveHierarchicalTags(
  service: TaxonomyService,
  items: TagItemRef[]
): Promise<string[]> {
  if (!Array.isArray(items) || items.length === 0) return [];

  const results = await Promise.all(
    items.map(async (item) => {
      const childName: string = item?.fields?.tagTitle?.value ?? item?.fields?.title?.value ?? '';
      if (!childName) return null;
      const id = item?.id;
      if (!id) return childName;

      try {
        const parentName = await service.getTagParent(id);
        return parentName ? `${parentName}__${childName}` : childName;
      } catch {
        return childName;
      }
    })
  );

  return results.filter((v): v is string => !!v && v.trim().length > 0);
}

What this does:

Extracts the child tag name from the item's fields
Uses the tag's ID to query for its parent via GraphQL
If a parent exists, returns "Parent__Child" format
If no parent exists, falls back to just the child name
Handles errors gracefully by returning the child name

3. GraphQL Parent Resolution

The TaxonomyService.getTagParent() method uses Sitecore's GraphQL API to fetch parent relationships:

async getTagParent(tagId: string): Promise<string | null> {
  const graphQLClient = this.getClient();

  const query = gql`
    query GetTagParent($tagId: String!, $language: String!) {
      tag: item(path: $tagId, language: $language) {
        parent {
          fields {
            name
            jsonValue
          }
        }
      }
    }
  `;

  const result = await graphQLClient.request<TagParentResponse>(query, {
    tagId,
    language: this.language,
  });

  const tagName =
    result.tag?.parent?.fields?.find(
      (f: { name: string; jsonValue: { value?: string } }) => f.name === 'tagTitle'
    )?.jsonValue?.value ?? null;

  if (tagName && tagName.trim().length > 0) return tagName;
  return null;
}

Key points:

Queries the parent item's tagTitle field
Returns null if no parent exists or if the parent isn't a tag item
Handles language-specific queries automatically

4. Meta Props Generation

The buildTagMetaProps function orchestrates the entire process:

export async function buildTagMetaProps(
  service: TaxonomyService,
  groups: Array<{
    field: string;
    items: unknown;
    mode?: 'hierarchical' | 'flat';
    flatSelector?: (item: { fields?: { [key: string]: { value?: string } } }) => string | undefined;
  }>
): Promise<SimpleMetaProp[]> {
  const meta: SimpleMetaProp[] = [];

  for (const group of groups) {
    const mode = group.mode ?? 'hierarchical';

    if (mode === 'hierarchical') {
      const itemsArray = group.items as TagItemRef[] | undefined;
      if (Array.isArray(itemsArray) && itemsArray.length > 0) {
        const values = await resolveHierarchicalTags(service, itemsArray);
        if (values.length > 0) {
          meta.push({ name: group.field, content: values.join(', ') });
        }
      }
    } else {
      // Flat mode - direct value extraction
      const itemsArray = group.items as
        | Array<{ fields?: { [key: string]: { value?: string } } }>
        | undefined;
      if (Array.isArray(itemsArray) && itemsArray.length > 0) {
        const extractor =
          group.flatSelector ||
          ((i: { fields?: { [key: string]: { value?: string } } }) =>
            i?.fields?.tagTitle?.value ?? i?.fields?.title?.value ?? '');
        const values = itemsArray
          .map((i) => extractor(i))
          .filter((v): v is string => !!v && v.trim().length > 0);
        if (values.length > 0) {
          meta.push({ name: group.field, content: values.join(', ') });
        }
      }
    }
  }

  return meta;
}

Output format:

The function returns an array of meta props like:

[
  {
    name: 'practices',
    content: 'Water__Treatment, Infrastructure__Transportation, Energy__Renewable',
  },
  {
    name: 'technologies',
    content: 'AI__Machine Learning, IoT__Sensors',
  },
];

Example: Real-World Usage

Input Data Structure

A project detail page might have:

projectDetailPageProps = {
  practices: [
    {
      id: '{guid-1}',
      fields: {
        tagTitle: { value: 'Treatment' },
      },
    },
    {
      id: '{guid-2}',
      fields: {
        tagTitle: { value: 'Transportation' },
      },
    },
  ],
};

Processing Flow

Extract child names: ['Treatment', 'Transportation']
Query parents via GraphQL:
- {guid-1} → Parent: 'Water'
- {guid-2} → Parent: 'Infrastructure'
Build hierarchical strings: ['Water__Treatment', 'Infrastructure__Transportation']
Join into meta prop: content: 'Water__Treatment, Infrastructure__Transportation'

Search Index Result

The search index now contains:

{
  "practices": "Water__Treatment, Infrastructure__Transportation"
}

Frontend Handling

On the frontend, you can parse these hierarchical values:

// Parse hierarchical taxonomy values
function parseHierarchicalTags(tagString: string): Array<{ parent: string; child: string }> {
  return tagString.split(', ').map((tag) => {
    const parts = tag.split('__');
    if (parts.length === 2) {
      return { parent: parts[0], child: parts[1] };
    }
    return { parent: null, child: tag }; // Fallback for flat tags
  });
}

// Usage
const practices = parseHierarchicalTags(
  metaProps.find((p) => p.name === 'practices')?.content || ''
);
// Result: [
//   { parent: 'Water', child: 'Treatment' },
//   { parent: 'Infrastructure', child: 'Transportation' }
// ]

This enables you to:

Group filters by parent in the UI
Show hierarchical navigation (e.g., "Water > Treatment")
Filter by parent or child independently
Display relationships visually

Benefits of This Approach

1. Search Engine Compatibility

Works with any search engine that supports string metadata
No special hierarchical facet support required
Simple string matching for filtering

2. Flexible Frontend Implementation

Frontend can parse and reconstruct hierarchy
Supports both parent-level and child-level filtering
Easy to implement UI components like hierarchical dropdowns

3. Backward Compatibility

Falls back gracefully when no parent exists
Works with flat taxonomies (no parent) automatically
Error handling ensures robustness

4. Performance

Parallel processing with Promise.all() for multiple tags
Efficient GraphQL queries (single query per tag)
Caching opportunities at the GraphQL layer

Advanced Features

Flat Mode Support

For non-hierarchical tags, you can use flat mode:

const tagGroups = [
  {
    items: projectDetailPageProps?.location,
    field: SEARCH_FIELDS.LOCATION,
    mode: 'flat', // Skip hierarchical resolution
  },
];

Custom Selectors

You can provide custom value extractors for flat mode:

{
  items: customItems,
  field: SEARCH_FIELDS.CUSTOM,
  mode: 'flat',
  flatSelector: (item) => item?.fields?.customField?.value ?? '',
}

Best Practices

1. Error Handling

Always handle cases where:

Parent lookup fails (GraphQL errors)
Tag has no parent (flat taxonomy)
Tag item is missing required fields

2. Performance Considerations

Use Promise.all() for parallel parent lookups
Consider caching parent relationships if they don't change frequently
Batch GraphQL queries when possible

3. Naming Conventions

Use consistent field names (SEARCH_FIELDS constants)
Ensure parent and child names don't contain __ (reserved separator)
Validate tag names before indexing

4. Testing

Test scenarios:

Tags with parents
Tags without parents (flat)
Tags with missing IDs
GraphQL query failures
Empty tag arrays

Conclusion

This hierarchical taxonomy solution provides a robust, flexible approach to handling parent-child relationships in Sitecore search. By encoding hierarchy directly into search metadata using the Parent__Child pattern, we maintain compatibility with standard search engines while enabling rich hierarchical filtering and navigation in the frontend.

The solution is:

✅ Simple - Easy to understand and maintain
✅ Flexible - Supports both hierarchical and flat taxonomies
✅ Robust - Handles errors gracefully
✅ Performant - Parallel processing and efficient queries
✅ Extensible - Easy to add new taxonomy groups

Advanced Web Crawler 101: Sitemap Trigger Extractors

Sebastián Aliaga — Mon, 25 Aug 2025 23:49:11 +0000

When working with Sitecore Search, the foundation of a good experience is how well your crawler is configured. If the crawler doesn’t discover or properly extract your content, the rest of your search implementation (facets, sorting, widgets, SDK calls) will fall apart.

In this article, we’ll go through the Advanced Web Crawler step by step:

Configure a Sitemap trigger to start crawling.
Use Document extractors (XPath, CSS, JS, JSON-LD) to pull structured data from each page.
Map those fields into Attributes that will power search, filtering, and sorting.

Step 1: Configure a Sitemap Trigger

A trigger is how Sitecore Search discovers new content. The Sitemap trigger is the most common because it gives the crawler a structured list of URLs to fetch.

Go to Sources → [Your Source] → Triggers → Add Trigger.
Select Sitemap as the trigger type.
Add your sitemap URL (https://www.example.com/sitemap.xml).
(Optional) Adjust include/exclude rules if your sitemap covers areas you don’t want indexed.

Step 2: Define Attributes

Attributes are the fields Sitecore Search will index and make available for search, filters, facets, and sorting. They act as the schema of your search index.

Go to Sources → [Your Source] → Attributes.
Click Add Attribute.
For each attribute, define:
- Display name (friendly name in the UI).
- Attribute name (the key you’ll map in extractors and use in queries).
- Data type (string, boolean, array, date, etc.).
- Whether it should:
- Return in API response
- Be available for filtering or facets
- Be sortable

Example attributes might include:

title → searchable
description → searchable
date → sortable
category → facetable
language → filter

This is where you define the “contract” for what data should be stored and how it will be used in queries and widgets.

Step 3: Define Document Extractors

Now that the crawler knows what pages to fetch, we need to tell it what to extract from each page.

Types of Extractors

Sitecore Search supports different types of document extractors depending on how your content is structured:

XPath selectors → great for structured HTML elements like <title> or <meta> tags.
CSS selectors → useful for targeting content by class names or IDs.
JavaScript extractors → advanced, allows you to run custom logic to decide what to index.

Example: JavaScript Extractor

Here’s a real-world example of a JavaScript extractor. This script checks if a page is marked as searchable via a <meta> tag, and then collects metadata, product/event/article details, and page content into fields that will be indexed:

function extract(request, response) {
  $ = response.body;

  // Only index pages that are marked as searchable
  const isSearchable = $('meta[name="searchable"]').attr('content') === 'true';
  if (!isSearchable) {
    return []; // Skip this page
  }

  return [{
    // Primary fields
    name: $('meta[name="name"]').attr('content'),
    navigation_title: $('meta[name="navigation_title"]').attr('content'),
    browser_title: $('meta[name="browser_title"]').attr('content') || $('title').text(),
    breadcrumbs_title: $('meta[name="breadcrumbs_title"]').attr('content'),
    keywords: $('meta[name="keywords"]')?.attr('content')?.split('|'),
    teaser: $('meta[name="teaser"]').attr('content') || $('meta[name="description"]').attr('content'),
    template: $('meta[name="template"]').attr('content'),
    image: $('meta[name="image"]').attr('content'),
    lead_in: $('meta[name="lead_in"]').attr('content'),
    masthead_description: $('meta[name="masthead_description"]').attr('content'),

    // Product details
    pdp_product_name: $('meta[name="pdp_product_name"]').attr('content'),
    pdp_product_style: $('meta[name="pdp_product_style"]').attr('content'),
    pdp_product_description: $('meta[name="pdp_product_description"]').attr('content'),
    product_category: $('meta[name="product_category"]')?.attr('content')?.split('|'),
    product_type: $('meta[name="product_type"]')?.attr('content')?.split('|'),
    product_collection: $('meta[name="product_collection"]')?.attr('content')?.split('|'),

    // Event details
    event_full_date: $('meta[name="event_full_date"]').attr('content'),
    event_date: $('meta[name="event_date"]').attr('content'),
    event_location: $('meta[name="event_location"]').attr('content'),

    // Article details
    article_full_date: $('meta[name="article_full_date"]').attr('content'),
    article_topic: $('meta[name="article_topic"]').attr('content'),
    article_date: $('meta[name="article_date"]').attr('content'),

    // Additional metadata
    language: $('meta[name="language"]').attr('content'),
    url: request.url || $('meta[property="og:url"]').attr('content'),

    // Page content
    page_full_content: $('p').text(),
    page_headers_h1: $('h1').text(),
    page_headers_h2: $('h2').text(),
    page_headers_h3: $('h3').text(),
  }];
}

This pattern gives you fine-grained control:

You can exclude pages dynamically.

Extract different metadata depending on page type (product, event, article).

Return arrays for multi-valued fields like categories or tags.

Validation: Crawl & Verify

Run your crawler manually the first time.
Go to Content Collections.
Open a few sample documents and check that the attributes are populated correctly.

Key Takeaways

The Sitemap trigger ensures you have a complete list of URLs.
Document extractors pull structured fields like title, body, tags, and publish date.
Attributes map those fields into Sitecore Search so they can power search, filtering, and sorting.
A clean extractor + attribute setup = a solid foundation for widgets and SDK queries later.

✅ Next up in this series: Crawling large sites with Sitemap Index triggers and rules.

Preparing Sitecore Data for Search Engine Crawling: A Complete Metadata Implementation Guide

Sebastián Aliaga — Mon, 25 Aug 2025 23:24:51 +0000

Search engine optimization (SEO) is crucial for any modern website, and when working with Sitecore headless implementations, properly structuring your metadata is essential for search engine crawlers to understand and index your content effectively. This comprehensive guide will walk you through implementing a robust metadata system that prepares your Sitecore data for optimal search engine crawling.

Architecture Overview
Core Metadata Service
Template-Specific Metadata
Structured Data Implementation
Integration with Next.js
Best Practices
Implementation Examples

Architecture Overview

The metadata implementation follows a layered architecture that separates concerns and provides flexibility for different content types:

┌─────────────────────────────────────┐
│           Page Rendering            │
├─────────────────────────────────────┤
│      Meta Props Plugin Layer       │
├─────────────────────────────────────┤
│    Search Metadata Service Layer   │
├─────────────────────────────────────┤
│      Constellation Services        │
├─────────────────────────────────────┤
│        Sitecore Layout Data        │
└─────────────────────────────────────┘

Key Components

SearchMetadataService: Core service that extracts and transforms Sitecore field data into search-friendly metadata
MetaPropsPlugin: Plugin that aggregates metadata from multiple sources during page props generation
Template-specific handlers: Specialized logic for different content types (Articles, Products, Events)
Structured Data Schemas: JSON-LD implementation for rich search results

Core Metadata Service

The SearchMetadataService is the heart of our metadata implementation. It processes Sitecore layout data and generates standardized metadata tags for search engines.

Service Structure

export class SearchMetadataService {
  protected layoutData: LayoutServiceData;

  constructor(layoutData: LayoutServiceData) {
    this.layoutData = layoutData;
  }

  getMetaTags(): MetaTag[] {
    const metaTags: MetaTag[] = [];

    if (!this.layoutData) return metaTags;

    // Extract base page fields
    const pageModel = castItem<SearchBasePageFields>(
      this.layoutData.sitecore.route as Item
    );

    // Generate standard metadata
    this.addStandardMetaTags(metaTags, pageModel);

    // Add template-specific metadata
    this.getEventMetaTags(metaTags);
    this.getProductMetaTags(metaTags);
    this.getArticleMetaTags(metaTags);

    return metaTags;
  }
}

Standard Metadata Fields

Every page includes these foundational metadata fields:

// Core identification fields
metaTags.push({
  name: SEARCH_FIELDS.NAME,
  content: pageModel?.NavigationTitle?.value || "",
});

metaTags.push({
  name: SEARCH_FIELDS.NAVIGATION_TITLE,
  content: pageModel?.NavigationTitle?.value || "",
});

// Content classification
metaTags.push({
  name: SEARCH_FIELDS.LANGUAGE,
  content: this.layoutData.sitecore.route?.itemLanguage || "",
});

metaTags.push({
  name: SEARCH_FIELDS.TEMPLATE,
  content: this.layoutData.sitecore.route?.templateName || "",
});

// SEO essentials
metaTags.push({
  name: SEARCH_FIELDS.BROWSER_TITLE,
  content: pageModel?.browserTitle?.value || "",
});

metaTags.push({
  name: SEARCH_FIELDS.TEASER,
  content: pageModel?.metaDescription?.value || "",
});

// Keywords processing
const keywords = pageModel?.keywords?.value?.split(",");
metaTags.push({
  name: SEARCH_FIELDS.KEYWORDS,
  content: keywords?.join("|") || "",
});

Search Field Constants

All metadata field names are centralized in a constants file to ensure consistency:

export const SEARCH_FIELDS = {
  // General fields
  LANGUAGE: "language",
  TEMPLATE: "template",
  NAVIGATION_TITLE: "navigation_title",
  TEASER: "teaser",
  LISTING_IMAGE: "image",
  DATE: "date",
  BROWSER_TITLE: "browser_title",
  SEARCHABLE: "searchable",
  BREADCRUMBS_TITLE: "breadcrumbs_title",
  KEYWORDS: "keywords",
  NAME: "name",

  // Event-specific fields
  EVENT_DATE: "event_date",
  EVENT_LOCATION: "event_location",
  EVENT_FULL_DATE: "event_full_date",

  // Product-specific fields
  PRODUCT_TYPE: "product_type",
  PRODUCT_COLLECTION: "product_collection",
  PDP_PRODUCT_NAME: "pdp_product_name",
  PRODUCT_CATEGORY: "product_category",

  // Article-specific fields
  ARTICLE_TOPIC: "article_topic",
  ARTICLE_DATE: "article_date",
  ARTICLE_FULL_DATE: "article_full_date",
};

Template-Specific Metadata

Different content types require specialized metadata handling. The service uses template ID detection to apply appropriate metadata extraction logic.

Product Detail Pages

Products require rich metadata for e-commerce search optimization:

private getProductMetaTags(metaTags: MetaTag[]): MetaTag[] {
  if (this?.layoutData?.sitecore?.route?.templateId ===
      toGuid(IDS.TEMPLATES.PRODUCT_DETAIL_PAGE)) {

    const productDetailProps = castItem<ProductDetailPage>(
      this.layoutData.sitecore.route as Item
    );

    // Product identification
    metaTags.push({
      name: SEARCH_FIELDS.NAME,
      content: productDetailProps?.productName?.value || '',
    });

    // Product imagery
    if (productDetailProps?.productCardImage) {
      metaTags.push({
        name: SEARCH_FIELDS.LISTING_IMAGE,
        content: productDetailProps?.productCardImage.value?.src || '',
      });
    }

    // Product taxonomy - multiple values joined with pipe
    if (productDetailProps?.productType) {
      metaTags.push({
        name: SEARCH_FIELDS.PRODUCT_TYPE,
        content: productDetailProps?.productType
          .map((type) => type.fields.Title.value)
          .join('|'),
      });
    }

    // Product collections
    if (productDetailProps?.productCollection) {
      metaTags.push({
        name: SEARCH_FIELDS.PRODUCT_COLLECTION,
        content: productDetailProps?.productCollection
          .map((collection) => collection.fields.Title.value)
          .join('|'),
      });
    }
  }

  return metaTags;
}

Event Detail Pages

Events need temporal and location-based metadata:

private getEventMetaTags(metaTags: MetaTag[]): MetaTag[] {
  if (this?.layoutData?.sitecore?.route?.templateId ===
      toGuid(IDS.TEMPLATES.EVENT_DETAIL_PAGE)) {

    const eventDetailProps = castItem<EventDetailPage>(
      this.layoutData.sitecore.route as Item
    );

    // Event identification
    metaTags.push({
      name: SEARCH_FIELDS.NAME,
      content: eventDetailProps?.eventName?.value || '',
    });

    // Temporal metadata
    if (eventDetailProps?.eventDateTime) {
      metaTags.push({
        name: SEARCH_FIELDS.EVENT_FULL_DATE,
        content: eventDetailProps?.eventDateTime.value,
      });

      metaTags.push({
        name: SEARCH_FIELDS.EVENT_DATE,
        content: getEventMonth(eventDetailProps?.eventDateTime.value),
      });
    }

    // Location metadata
    if (eventDetailProps?.eventLocation?.fields.Title) {
      metaTags.push({
        name: SEARCH_FIELDS.EVENT_LOCATION,
        content: eventDetailProps?.eventLocation.fields.Title.value,
      });
    }
  }

  return metaTags;
}

Article Detail Pages

Articles focus on content classification and publication data:

private getArticleMetaTags(metaTags: MetaTag[]): MetaTag[] {
  if (this?.layoutData?.sitecore?.route?.templateId ===
      toGuid(IDS.TEMPLATES.ARTICLE_DETAIL_PAGE)) {

    const articleDetailProps = castItem<ArticleDetailPage>(
      this.layoutData.sitecore.route as Item
    );

    // Article identification
    metaTags.push({
      name: SEARCH_FIELDS.NAME,
      content: articleDetailProps?.title?.value || '',
    });

    // Content classification
    if (articleDetailProps?.topic) {
      metaTags.push({
        name: SEARCH_FIELDS.ARTICLE_TOPIC,
        content: articleDetailProps?.topic?.fields.Title.value,
      });
    }

    // Publication timing
    if (articleDetailProps?.date) {
      metaTags.push({
        name: SEARCH_FIELDS.ARTICLE_FULL_DATE,
        content: articleDetailProps?.date.value,
      });

      metaTags.push({
        name: SEARCH_FIELDS.ARTICLE_DATE,
        content: getEventMonth(articleDetailProps?.date.value),
      });
    }
  }

  return metaTags;
}

Structured Data Implementation

Beyond meta tags, implementing JSON-LD structured data significantly enhances search engine understanding of your content.

Schema Service Architecture

export const getSchemas = (
  layoutData: LayoutServiceData,
  siteSettings: SiteSettingsInfo,
  baseURL: string,
  hospitalitySchemas?: SchemaData[]
): SchemaData[] => {
  const schemas: SchemaData[] = [];
  const { route } = layoutData.sitecore;

  if (!route?.templateId || !route?.fields) return schemas;

  const templateId = toGuid(route.templateId);

  switch (templateId) {
    case toGuid(IDS.TEMPLATES.PRODUCT_DETAIL_PAGE):
      schemas.push(createProductSchema(layoutData, siteSettings, baseURL));
      break;
    case toGuid(IDS.TEMPLATES.ARTICLE_DETAIL_PAGE):
      schemas.push(
        createArticleSchema(
          route.fields as unknown as ArticleDetailPage,
          siteSettings,
          baseURL
        )
      );
      break;
    case toGuid(IDS.TEMPLATES.EVENT_DETAIL_PAGE):
      schemas.push(
        createEventSchema(route.fields as unknown as EventDetailPage)
      );
      schemas.push(createOrganizationSchema(siteSettings, baseURL));
      schemas.push(createWebSiteSchema(siteSettings, baseURL));
      break;
  }

  return schemas;
};

Product Schema Example

export const createProductSchema = (
  layoutData: LayoutServiceData,
  siteSettings: SiteSettingsInfo,
  baseURL: string
): SchemaData => {
  const { route } = layoutData.sitecore;
  const fields = route?.fields as unknown as ProductDetailPage;

  return {
    "@context": "https://schema.org/",
    "@type": "Product",
    name: fields.productName?.value || "",
    image: [fields.productCardImage?.value?.src || ""],
    description: fields.productDescription?.value || "",
    brand: {
      "@type": "Brand",
      name: siteSettings.organizationName?.value || "",
    },
    sku: fields.mikMakProductIds?.value?.split(",")[0] || "",
    url: baseURL,
    offers: {
      "@type": "Offer",
      url: baseURL,
      itemCondition: "https://schema.org/NewCondition",
      availability: "https://schema.org/InStock",
      seller: {
        "@type": "Organization",
        name: siteSettings.organizationName?.value || "",
      },
    },
  };
};

Website Schema with Search Action

export const createWebSiteSchema = (
  siteSettings: SiteSettingsInfo,
  baseURL: string
): SchemaData => {
  const searchPageUrl = siteSettings.searchPage.value?.href || "/search";

  return {
    "@context": "https://schema.org/",
    "@type": "WebSite",
    name: siteSettings.organizationName?.value || "",
    url: baseURL,
    potentialAction: {
      "@type": "SearchAction",
      target: `${baseURL}${searchPageUrl}?q={search_term_string}`,
      "query-input": "required name=search_term_string",
    },
  };
};

Integration with Next.js

The metadata system integrates seamlessly with Next.js through the page props factory pattern.

Meta Props Plugin

class MetaPropsPlugin implements Plugin {
  order = 11;

  async exec(
    props: SitecorePageProps,
    context: GetServerSidePropsContext | GetStaticPropsContext
  ) {
    props.metaProps = [];
    if (!props.layoutData.sitecore.route) return props;

    // Social metadata from Constellation
    const service = new PageTaggingService(props.layoutData);
    const metaProps = await service.getMetaProps();
    props.metaProps = metaProps;

    // Search engine directives
    const searchEngineDirectiveProp =
      await service.getSearchEngineDirectiveProp();
    if (searchEngineDirectiveProp) {
      props.metaProps.push(searchEngineDirectiveProp);
    }

    // Social metadata for Open Graph and Twitter Cards
    const pageMetadata = await service.getSocialMetadataProps(context, {
      languageEmbedding: false,
    });
    if (pageMetadata) {
      props.metaProps = [...props.metaProps, ...pageMetadata];
    }

    // Custom search metadata
    const searchMetadataService = new SearchMetadataService(props.layoutData);
    const searchMetaTags = searchMetadataService.getMetaTags();
    if (searchMetaTags) {
      props.metaProps = [...props.metaProps, ...searchMetaTags];
    }

    return props;
  }
}

Layout Integration

const Layout = ({ layoutData, headLinks, metaProps, siteSettings }) => {
  const canonicalURL = // ... canonical URL logic
  const baseURL = canonicalURL ? new URL(canonicalURL).origin : '';

  return (
    <div>
      {/* Structured data schemas */}
      <Schemas
        layoutData={layoutData}
        siteSettings={siteSettings}
        baseURL={canonicalURL}
      />

      {/* Meta tags rendering */}
      <PageMetadata metaProps={metaProps} />

      <Head>
        <title>{fields?.browserTitle?.value?.toString() || siteName}</title>
        {/* Additional head elements */}
      </Head>

      {/* Page content */}
    </div>
  );
};

Best Practices

1. Field Standardization

Ensure consistent field naming across all Sitecore templates:

export interface SearchBasePageFields {
  NavigationTitle: Field<string>;
  browserTitle: Field<string>;
  searchable: Field<boolean>;
  breadcrumbsTitle: Field<string>;
  keywords: Field<string>;
  metaDescription: Field<string>;
  socialThumbnail: ImageField;
}

2. Fallback Values

Always provide fallback values to prevent empty metadata:

metaTags.push({
  name: SEARCH_FIELDS.BROWSER_TITLE,
  content:
    pageModel?.browserTitle?.value ||
    pageModel?.NavigationTitle?.value ||
    "Default Site Title",
});

3. Data Sanitization

Clean and validate data before including in metadata:

const keywords = pageModel?.keywords?.value
  ?.split(",")
  ?.map((keyword) => keyword.trim())
  ?.filter((keyword) => keyword.length > 0);

metaTags.push({
  name: SEARCH_FIELDS.KEYWORDS,
  content: keywords?.join("|") || "",
});

4. Performance Optimization

Cache computed metadata when possible:

// Cache expensive operations
const templateId = useMemo(
  () => toGuid(this.layoutData.sitecore.route?.templateId),
  [this.layoutData]
);

5. SEO-Friendly URLs

Ensure your metadata includes proper canonical URLs:

// Include canonical URL in structured data
const canonicalUrl = `${baseURL}${route.url}`;

return {
  "@context": "https://schema.org/",
  "@type": "Article",
  url: canonicalUrl,
  mainEntityOfPage: {
    "@type": "WebPage",
    "@id": canonicalUrl,
  },
  // ... other properties
};

Implementation Examples

Complete Product Page Setup

// 1. Define your product template fields
interface ProductPageFields extends SearchBasePageFields {
  productName: Field<string>;
  productDescription: Field<string>;
  productPrice: Field<number>;
  productCategory: Tag[];
  productImage: ImageField;
}

// 2. Implement metadata extraction
private getProductMetadata(pageModel: ProductPageFields): MetaTag[] {
  const metaTags: MetaTag[] = [];

  // Product-specific fields
  metaTags.push({
    name: 'product_name',
    content: pageModel.productName?.value || '',
  });

  metaTags.push({
    name: 'product_price',
    content: pageModel.productPrice?.value?.toString() || '',
  });

  // Category handling
  if (pageModel.productCategory?.length) {
    metaTags.push({
      name: 'product_categories',
      content: pageModel.productCategory
        .map(cat => cat.fields.Title.value)
        .join('|'),
    });
  }

  return metaTags;
}

// 3. Create structured data
const productSchema = {
  '@context': 'https://schema.org/',
  '@type': 'Product',
  name: pageModel.productName.value,
  description: pageModel.productDescription.value,
  image: pageModel.productImage.value.src,
  offers: {
    '@type': 'Offer',
    price: pageModel.productPrice.value,
    priceCurrency: 'USD',
  },
};

Event Page Metadata

// Event-specific metadata with rich temporal data
private getEventMetadata(eventData: EventPageFields): MetaTag[] {
  const metaTags: MetaTag[] = [];

  // Event timing
  if (eventData.eventStartDate?.value) {
    const startDate = new Date(eventData.eventStartDate.value);

    metaTags.push({
      name: 'event_start_date',
      content: startDate.toISOString(),
    });

    metaTags.push({
      name: 'event_month',
      content: startDate.toLocaleDateString('en-US', { month: 'long' }),
    });

    metaTags.push({
      name: 'event_year',
      content: startDate.getFullYear().toString(),
    });
  }

  // Location data
  if (eventData.eventVenue?.fields) {
    metaTags.push({
      name: 'event_venue',
      content: eventData.eventVenue.fields.Name.value,
    });

    metaTags.push({
      name: 'event_city',
      content: eventData.eventVenue.fields.City.value,
    });
  }

  return metaTags;
}

Conclusion

Implementing a robust metadata system for Sitecore headless applications requires careful planning and systematic execution. By following the patterns outlined in this guide, you'll create a foundation that:

Maximizes search visibility through comprehensive metadata coverage
Supports rich search results via structured data implementation
Maintains consistency across different content types
Scales efficiently as your content grows
Integrates seamlessly with modern frontend frameworks

The key to success lies in establishing clear standards, implementing fallback mechanisms, and regularly auditing your metadata output to ensure search engines can effectively crawl and understand your content.

Remember that metadata is not a "set it and forget it" implementation—it requires ongoing maintenance and optimization as search engine algorithms evolve and your content strategy develops. Regular monitoring of search performance and crawler behavior will help you identify opportunities for improvement and ensure your Sitecore content achieves maximum search visibility.

Reducing props size in Sitecore XM Cloud Next.js to improve performance

Sebastián Aliaga — Mon, 09 Jun 2025 14:19:17 +0000

Introduction

In Sitecore XM Cloud projects using Next.js, it’s common to use multilist fields to reference other items like pages. While this offers flexibility, it can sometimes lead to components receiving a large context object when only a few fields are needed impacting performance.

In this post, I’ll walk through how I solved this by creating a plugin that trims the props down to only the necessary fields, reducing payload size and improving performance.

The Problem

We had a component that used a multilist field to reference other pages. Each selected page brought the entire context object in the GraphQL response, even though the component only used the Heading and Description.

// Example of what we were getting in props
relatedPages: [
  {
    id: '...',
    name: '...',
    fields: {
      heading: 'Example Heading',
      description: 'Example description',
      image: { /* full image object */ },
      seo: { /* SEO fields */ },
      ...many more
    }
  }
]

The Goal

Our goal was to return only what we actually needed, not the full page context. In our case: just the heading and description fields. This would make the component faster and lighter to render.

The Solution

In headapps\sxa-starter\src\lib\page-props-factory\plugins, I created a plugin named featured-events.ts.

import { ComponentRendering, Field, LinkField } from '@sitecore-jss/sitecore-jss-nextjs';
import { SitecorePageProps } from 'lib/page-props';
import { EventDetailPage, EventDetailPageCard } from 'src/types/pages/eventDetailPage';
import { EventLocation } from 'src/types/taxonomy/eventLocation';
import { Plugin } from '..';

interface Fields {
  leadIn: Field<string>;
  heading: Field<string>;
  cta: LinkField;
  location?: EventLocation[];
  featuredEventDetailPages: FeaturedEventDetailPage[];
}

export type FeaturedEventDetailPage = {
  id: string;
  url: string;
  name: string;
  displayName: string;
  fields: EventDetailPage;
};

class FeaturedEventsPlugin implements Plugin {
  order = 1.6;

  async exec(props: SitecorePageProps) {
    props.layoutData.sitecore.route?.placeholders['main']?.forEach(
      (rendering: ComponentRendering) => {
        if (rendering.componentName === 'FeaturedEventsRow') {
          const fields = rendering.fields as unknown as Fields;
          if (fields && fields.featuredEventDetailPages) {
            fields.featuredEventDetailPages =
              fields.featuredEventDetailPages.map((page) => {
                return {
                  id: page.id,
                  url: page.url,
                  name: page.name,
                  displayName: page.displayName,
                  fields: {
                    eventName: page.fields.eventName,
                    eventDateTime: page.fields.eventDateTime,
                    eventEndDate: page.fields.eventEndDate,
                    eventAddress: page.fields.eventAddress,
                    eventTeaser: page.fields.eventTeaser,
                    eventImage: page.fields.eventImage,
                    eventLink: page.fields.eventLink,
                    eventBody: page.fields.eventBody,
                    eventLocation: page.fields.eventLocation,
                  } as EventDetailPage,
                } as EventDetailPageCard;
              }) || ([] as EventDetailPageCard[]);
            rendering.fields = fields as unknown as ComponentRendering['fields'];
          }
        }
      }
    );

    return props;
  }
}

export const featuredEventsPlugin = new FeaturedEventsPlugin();

Results

Metric	Before	After
Props size	~24 KB	~4 KB
Fields included	All context	Only needed
Rendering speed	Slower	Faster

We saw reduced data sent to the client, resulting in faster hydration and better Lighthouse scores.

Other use cases

This implementation can also be used when using withDatasourceRendering on components that have as datasource the Page Context, for example, mastheads.

import { ComponentRendering } from '@sitecore-jss/sitecore-jss-nextjs';
import { SitecorePageProps } from 'lib/page-props';
import { EventDetailPage } from 'src/types/pages/eventDetailPage';
import { Plugin } from '..';

class EventDetailMastheadPlugin implements Plugin {
  order = 2.3;

  async exec(props: SitecorePageProps) {
    props.layoutData.sitecore.route?.placeholders['mastheads']?.forEach(
      (rendering: ComponentRendering) => {
        if (rendering.componentName === 'EventDetailMasthead') {
          const fields = rendering.fields as unknown as EventDetailPage;
          if (fields) {
            // Clean up the EventDetailPage fields to only include what the component uses
            const cleanedFields = {
              eventImage: fields.eventImage,
              eventDateTime: fields.eventDateTime,
              eventName: fields.eventName,
              eventLocation: fields.eventLocation,
              eventTeaser: fields.eventTeaser,
            } as EventDetailPage;

            rendering.fields = cleanedFields as unknown as ComponentRendering['fields'];
          }
        }
      }
    );

    return props;
  }
}

export const eventDetailMastheadPlugin = new EventDetailMastheadPlugin();

Wrapping up

This is a small tweak, but it brought meaningful improvements in our XM Cloud implementation. Have you faced similar performance issues with Sitecore XM Cloud and Next.js? Let’s connect — I’d love to hear your thoughts!

Mastering the Pages Editor in Sitecore XM Cloud: Managing Page Content and Datasources

Sebastián Aliaga — Mon, 09 Jun 2025 00:55:57 +0000

Introduction

The Pages Editor (formerly Page Builder) in Sitecore XM Cloud was quite limited in its early stages. Developers had to find creative workarounds to make fields editable, ensuring a smooth experience for content authors. However, with recent updates, Sitecore has significantly improved how we manage content directly within the Pages Editor—bringing it closer to the flexibility we’re used to in the Content Editor.

Types of Editable Content

You can now manage a variety of field types directly through Pages, including:

Single-line text

Multiline text

Rich text

Images

Links

Dropdowns

Checkboxes

Multilist with search (partially—while we don’t yet see the full list of items, IDs are now accessible)

What’s especially helpful is that these fields are editable regardless of whether they are part of the page content or a datasource item.

Page Content

By clicking the three dots next to the current page in the Page Navigator (on the left-hand side), you’ll see options for both Page Content and Page Settings.

Page Settings includes details like the page's design, language, insert options, and metadata such as the page creator.

Page Content brings most of what you’d manage in the Content Editor into the Pages interface. What’s available here depends on how your implementation is configured—but it's designed to give authors more control without leaving the editor.

Datasources

When you select a component and go to the Content tab on the right-hand pane, you’ll find its datasource. From here, you can manage all the previously listed field types, with instant visual feedback.

While some fields—like single-line text, multiline text, and rich text—are still editable directly on the page using Sitecore’s Next.js tags, you now have the option to manage them more cleanly through the right-hand pane. This mirrors the approach taken for images and links, which are also now conveniently editable here.

For fields that aren't yet editable in Pages, there's a helpful “Edit in Content Editor” link at the bottom of the datasource panel. This makes it easier for content authors to navigate and update content without getting lost in the backend.

Conclusion

The evolution of the Pages Editor in XM Cloud has dramatically improved the content authoring experience. By bringing more editable field types into the visual interface and simplifying access to datasources and settings, Sitecore is empowering teams to manage content faster and with greater confidence. As these tools continue to improve, developers can focus more on building great experiences—knowing that authors have the flexibility they need right out of the box.

Sitecore Hackaton 2025

Sebastián Aliaga — Wed, 26 Mar 2025 23:12:03 +0000

Building a Sitecore XM Cloud Component Creator: My Second Hackathon Experience

A few weeks ago, I participated in my second Sitecore Hackathon with team "404 Bugs Not Found". Our mission? Create a VSCode extension that streamlines component creation and deployment in Sitecore XM Cloud. Here's a deep dive into our technical solution.

The Technical Challenge

Sitecore XM Cloud development involves several manual steps when creating components:

Creating the component's TSX/JSX file
Setting up the component's template in Sitecore
Creating placeholder settings
Configuring the component rendering
Linking everything together

We aimed to automate this entire process through a VSCode extension.

Core Technical Features

1. Interactive UI with WebView

We created a sophisticated form interface using VSCode's WebView API. Here's a snippet of our form structure:

<div class="form-group">
    <label for="componentName">Component Name</label>
    <input required type="text" id="componentName" placeholder="Enter component name">
</div>

<div class="form-group">
    <label for="componentType">Component Type</label>
    <select id="componentType">
        <option value="none">None</option>
        <option value="withDatasourceCheck">With Datasource Check</option>
        <option value="withDatasourceRendering">With Datasource Rendering</option>
    </select>
</div>

2. Dynamic Field Management

One of our most interesting features is the dynamic field management system:

function addField() {
    const fieldsContainer = document.getElementById('fields');
    const fieldRow = document.createElement('div');
    fieldRow.className = 'field-row';
    fieldRow.innerHTML = `
        <input type="text" placeholder="Field name" required>
        <select>
            <option value="SingleLineText">Single Line Text</option>
            <option value="RichText">Rich Text Field</option>
            <option value="LinkField">Link Field</option>
            <option value="ImageField">Image Field</option>
            <option value="Checkbox">Checkbox</option>
            <option value="MultilineText">Multiline Text</option>
        </select>
        <div class="checkbox-wrapper">
            <input type="checkbox" id="required-${fieldCount}">
            <label for="required-${fieldCount}">Required</label>
        </div>
        <button onclick="this.parentElement.remove()" title="Remove field">×</button>
    `;
    fieldsContainer.appendChild(fieldRow);
}

3. GraphQL Integration

The most challenging part was integrating with Sitecore's GraphQL API. Here's our template creation mutation:

mutation {
    createItemTemplate(
        input: {
            name: "${templateName}",
            parent: "${templateParent}",
            createStandardValuesItem: true,
            sections: {
                name: "Content",
                fields: [
                    {
                        name: "${field.label}",
                        type: "${field.value === "RichText" ? "Rich Text" : field.value}",
                        required: ${field.isRequired}
                    }
                ]
            }
        }
    ) {
        itemTemplate {
            templateId
            name
            ownFields {
                nodes {
                    name
                    type
                }
            }
        }
    }
}

4. Placeholder Management

We implemented a sophisticated placeholder system that handles both static and dynamic placeholders:

function updatePlaceholderKey(select) {
    const row = select.closest('.placeholder-row');
    const keyInput = row.querySelectorAll('input[type="text"]')[1];
    const currentKey = keyInput.value;

    if (select.value === 'dynamic') {
        if (!currentKey.endsWith('-{*}')) {
            keyInput.value = currentKey + '-{*}';
        }
    } else {
        if (currentKey.endsWith('-{*}')) {
            keyInput.value = currentKey.slice(0, -4);
        }
    }
}

5. Rendering Creation

The final piece was creating the rendering with proper placeholder references:

const renderingQuery = `
    mutation {
        createItem(
            input: {
                name: "${sitecoreName}",
                templateId: "{04646A89-996F-4EE7-878A-FFDBF1F0EF0D}",
                parent: "${renderingParent}",
                language: "en",
                fields: [
                    { name: "componentName", value: "${codeName}" }
                    ${placeholderIds.length > 0
                        ? `, { name: "Placeholders", value: "${placeholderIds.join("|")}" }`
                        : ""
                    }
                ]
            }
        ) {
            item {
                itemId
                name
                path
            }
        }
    }`;

Technical Challenges Overcome

Field Type Mapping: We had to carefully map our field types to Sitecore's expected formats:

switch (field.value) {
    case "RichText":
        return "Rich Text";
    case "SingleLineText":
        return "Single-Line Text";
    case "MultilineText":
        return "Multi-Line Text";
    case "ImageField":
        return "Image";
    case "LinkField":
        return "General Link";
    case "Checkbox":
        return "Checkbox";
    default:
        return field.value;
}

Placeholder Reference Management: Ensuring proper linking between placeholders and renderings required careful handling of IDs and proper mutation ordering.
Type Safety: Implementing proper TypeScript interfaces and type checking throughout the extension.

Future Technical Enhancements

Support for more complex field types and configurations
Enhanced template inheritance capabilities
Integration with Sitecore CLI
Support for component variants
Automated testing infrastructure

Conclusion

This hackathon pushed us to create a solution that not only works but is also maintainable and extensible. The combination of VSCode's WebView API, TypeScript's type safety, and Sitecore's GraphQL API allowed us to create a tool that significantly improves the developer experience.

The code is open source and available for the community to use and enhance. We're looking forward to seeing how it evolves and helps other Sitecore developers streamline their workflow.

Repository
Video Demo

Are you interested in contributing to this project? Check out our repository and let's make Sitecore development even better together!

Understanding Partial Designs and Page Designs in Sitecore XM Cloud

Sebastián Aliaga — Thu, 26 Sep 2024 20:17:03 +0000

Sitecore XM Cloud provides a flexible and scalable way to structure page layouts through Partial Designs and Page Designs. These design tools allow developers and content authors to create reusable templates that help in building consistent layouts across the website while minimizing redundant work. In this guide, we will explore what Partial Designs and Page Designs are, how they differ, and how to configure them for your pages in Sitecore XM Cloud.

What Are Partial Designs?

Partial Designs are reusable design fragments that define specific sections of a page. They allow developers to create common layout structures that can be reused across multiple Page Designs. Examples of Partial Designs include a header, footer, or a sidebar that needs to remain consistent across many pages.

Key Features of Partial Designs:

Reusability: Once created, a Partial Design can be applied to multiple Page Designs, promoting reuse of common elements.
Flexibility: Multiple Partial Designs can be combined to build more complex layouts.
Consistency: By using Partial Designs, you ensure consistency in how common components, like navigation or footers, are applied across your site.

Typical Use Cases for Partial Designs:

Header and Footer sections shared across all pages.
Sidebar layouts used in specific sections of the website.
Common promotional banners or call-to-action elements reused across multiple pages.

What Are Page Designs?

Page Designs are the overall layout structure for a page, which brings together both Partial Designs and component placeholders. A Page Design defines the entire structure of a page, deciding how it is divided and what Partial Designs are applied. You can think of a Page Design as the "master layout" for different types of pages, such as a homepage, product page, or article page.

Key Features of Page Designs:

Complete Page Structure: Page Designs are responsible for determining the full layout and which Partial Designs are included.
Flexible Component Placement: Components can be dynamically inserted into placeholders defined in the Page Design.
Reusable Templates: Like Partial Designs, Page Designs can be reused for multiple pages, ensuring layout consistency. ### Typical Use Cases for Page Designs:
Creating distinct layouts for homepage vs. content pages.
Defining unique designs for landing pages or product pages.
Building a template for blog or news article pages.

Configuring Partial Designs and Page Designs in Sitecore XM Cloud

In the Pages Editor, go the left panel and select "Templates" in there you'll find your partial designs and page designs.
First, we need to create a Partial Design, we can click in the top right corner to create one.

After creating you'll get a blank page with the Placeholders you have configured in the layout.

In there you can add any renderings you want to always appear on your page.
When you add a rendering as a partial design it cannot be clicked on pages, therefore it cannot be edited in any way. To make changes you'll have to go to the partial design configuration

After that, you can go ahead and create a Page Design, in this case we have the Default page design.

Then you select which partial designs to use and that's it.

Adding the Page Design to Page Templates

Go to this path on the Content Editor

/sitecore/content/YourProject/YourProject/Presentation/Page Designs

And click on Content.

There' you'll find the following:

You can select any page template you need and assign it the Page Design we created earlier. That way, any page created with that template will automatically apply that page design.

Conclusion

By using Partial Designs and Page Designs in Sitecore XM Cloud, you can create reusable, modular layouts that simplify site management and ensure consistency across your website. Partial Designs allow you to define reusable components such as headers and footers, while Page Designs give you control over the overall structure of the page. Together, they form the backbone of a scalable and flexible layout system, making it easier to manage large and complex websites.

Understanding Content Resolvers in Sitecore XM Cloud

Sebastián Aliaga — Thu, 26 Sep 2024 17:20:43 +0000

Content Resolvers in Sitecore XM Cloud allow developers and content authors to dynamically determine the source of data for individual renderings. These resolvers provide the flexibility needed to pull content from different areas of the Sitecore content tree based on specific rules or criteria. This guide will explain what each type of content resolver does and how they can be utilized within your project.

Types of Content Resolvers

1. Context Item Children Resolver

The Context Item Children Resolver retrieves all the child items of the current context item. This is useful when you need to display a list of child elements, such as when creating a navigation menu or a list of related articles.

2. Context Item Resolver

The Context Item Resolver pulls content from the current context item, which is typically the item representing the current page. This is the most basic content resolver and is often used when the component should display content directly from the page itself.

3. Datasource Item Children Resolver

The Datasource Item Children Resolver fetches all the children of a specified datasource item. This resolver is ideal when you want to display multiple related pieces of content that are stored under a specific datasource in the content tree.

4. Datasource Resolver

The Datasource Resolver retrieves content from a specific datasource that has been set for a rendering. This is commonly used when you want to specify a static content source (e.g., a folder of reusable content) for a component, such as a promotional banner.

5. Folder Filter Resolver

The Folder Filter Resolver retrieves content from a folder, but with additional filtering criteria. For example, you might use this resolver to pull only items of a certain template type or with specific field values from a folder.

6. Sitecore Forms Resolver

The Sitecore Forms Resolver is specifically designed to retrieve and render Sitecore forms. It’s useful when integrating forms into a page, such as a contact form or feedback form, without manually linking each form to a component.

Experience Accelerator Resolvers

In addition to the default rendering content resolvers, Sitecore XM Cloud offers additional resolvers under the Experience Accelerator section. These resolvers are designed to enhance the flexibility of Sitecore SXA projects by adding specific content-handling capabilities.

7. HTML Variant as JSON Serializer

This resolver serializes HTML variants as JSON. It’s typically used when content needs to be serialized and transferred in a JSON format for use in headless or API-driven applications.

8. Image Contents Resolver

The Image Contents Resolver fetches images from the datasource and is used to display images within components. It simplifies how image assets are linked and managed within components, ensuring they are pulled dynamically from the content tree.

9. Link List Contents Resolver

The Link List Contents Resolver is designed to retrieve a list of links, such as navigation links, social media links, or related content links. It is useful for managing multiple links in a single datasource and displaying them dynamically.

10. Navigation Contents Resolver

This resolver is designed to retrieve content that is used in navigational components, such as menus or breadcrumbs. It can pull items based on their hierarchy in the content tree, ensuring that the site structure is accurately reflected in the navigation.

11. Page List Contents Resolver

The Page List Contents Resolver pulls a list of pages, which can be used to create components like related articles, a blog post list, or category overviews. It retrieves the list of pages based on specific criteria such as templates or fields.

12. Rich Text Contents Resolver

The Rich Text Contents Resolver retrieves rich text content from a datasource. It is typically used for components that need to display formatted text content, such as articles, blog posts, or other content-heavy sections.

Headless Experience Accelerator Resolvers

Lastly, for headless implementations, Sitecore offers additional resolvers under the Headless Experience Accelerator.

13. Navigation Contents Resolver

Similar to the navigation resolver in the Experience Accelerator, this resolver is used specifically in headless environments to retrieve and present navigational content. It ensures that navigation menus and structures are generated dynamically, even in a headless context.

Conclusion

Content Resolvers in Sitecore XM Cloud offer a powerful way to dynamically pull and manage content across your site. By understanding the different types of resolvers, such as those for navigating content trees, retrieving images, or displaying forms, you can optimize how content is handled within your renderings. Whether you are building a static component or a dynamic navigation menu, configuring the right content resolver ensures that the correct data is fetched, leading to a more flexible and scalable website.

XM Cloud: Rendering Variants and Styles

Sebastián Aliaga — Thu, 26 Sep 2024 17:09:00 +0000

Rendering Variants and Styles in Sitecore XM Cloud allow developers and content authors to have more control over the appearance and behavior of components. They enhance flexibility by allowing multiple presentations for a single component, without needing to duplicate the logic. In this guide, we’ll explore how to work with both rendering variants and styles, and how to configure them within the CMS.

What Are Rendering Variants?

Rendering Variants allow you to display the same content in different formats or layouts. A single component can have multiple variants, each defining a different structure or appearance of the same underlying data.

Configuring Rendering Variants

To configure Rendering Variants for you Renderings you need to go to the following path:

/sitecore/content/YourProject/YourProjects/Presentation/Headless Variants

In there you'll be able to create a Variant Item

And inside each Variant Item you can create a Variant Definition, the default, of course is "Default"

For this example we'll use a component that has an image and we want to give the Content Author the ability to select if the image goes in the right or in the left.
For this we can create the two Variant Definitions, Default that's going to be the ImageLeft and WithImageRight.
The names you select here are important, this will later match with the components we export on the code

There's no more configuration needed.

Coding a Rendering Variant

As you can see in the following code snippet, we created a type called VariantParams and in there we defined a boolean. We're adding that to our props and using it to check, in the main if the image is on the right or on the left via classes. Feel free to use any approach you want.

interface Fields {
  heading: Field<string>;
  copy: Field<string>;
  image: ImageField;
}

type VariantParams = {
  imageLeft: boolean;
};

type CTARowWithImageProps = ComponentProps & {
  fields: Fields;
  variantParams: VariantParams;
};

const CTARowWithImage = ({ fields, params, rendering, variantParams }: CTARowWithImageProps) => {
  const ctx = useSitecoreContext();

  const id = params.RenderingIdentifier;
  return (
    <section
      className={`${params.styles} ${variantParams.imageLeft ? 'flex-row' : 'flex-row-reverse'}`}
      id={id ? id : undefined}
    >
      <Image field={fields.image}/>
      <Text field={fields.heading} tag="h2" />
      {hasContent(ctx, fields.copy) && <Text field={fields.copy} tag="p" />}
    </section>
  );
};

After creating our base component that receives the variantParam boolean, we go ahead and create the variants.

const _Default = (props: CTARowWithImageProps) => {
  return <CTARowWithImage {...props} variantParams={{ imageLeft: true }} />;
};

const _WithImageRight = (props: CTARowWithImageProps) => {
  return <CTARowWithImage {...props} variantParams={{ imageLeft: false }} />;
};

You can see that we're returning our base component and changing the variantParams value on each one.

After that we just need to export our components

export const Default = withDatasourceCheck()<CTARowWithImageProps>(_Default);
export const WithImageRight = withDatasourceCheck()<CTARowWithImageProps>(_WithImageRight);

Note that the name we're exporting matches the configuration we did on the CMS.

Moving to the Pages Editor, Content Authors can select which variant to use after adding the rendering and clicking it, on the right side menu.

What Are Styles?

Styles in Sitecore allow content authors to apply predefined CSS classes to components dynamically. This enables the easy application of different styles or visual designs to components without modifying the code.

Configuring Styles

Go to the following path:

/sitecore/content/YourProject/YourProject/Presentation/Styles

And in there you can create a new Style (the blue one)

And inside each styles you can create a style (orange one)

The content tree will look like this:

And inside of the Button Style, we can add the value of the class that will be added along side the Allowed Renderings where this style will appear as an option:

In this case we implement the btn value for the CTA Row Link rendering.

Code configuration

Inside your code you can reference this new value using the params prop that comes from ComponentProps

interface Fields {
  link: LinkField;
}

type CTARowLinkProps = ComponentProps & {
  fields: Fields;
};

const CTARowLink = ({ fields, params }: CTARowLinkProps) => {
  return <Link className={params.styles} field={fields.link} />;
};

export default withDatasourceCheck()<CTARowLinkProps>(CTARowLink);

As you can see in the snippet, I'm adding the params.styles to the classNames.

Moving to the Pages Editor, on the appropiate rendering you can manage if you want to add the class or not on the right side menu.

As you can see the CTA Row Link style configuration is down below and you can check the checkbox, this will ad the btn class.

Conclusion

Rendering Variants and Styles offer a powerful way to extend the flexibility and reusability of components in Sitecore XM Cloud. With rendering variants, you can present the same content in multiple ways, while styles allow for dynamic application of visual designs. Both of these features make it easier to build modular, scalable sites that can be easily customized by content authors. By following the above steps, you can enhance your Sitecore project and ensure that your components remain versatile and easy to manage.

Working with Placeholders in Sitecore XM Cloud

Sebastián Aliaga — Thu, 26 Sep 2024 16:36:21 +0000

Placeholders in Sitecore allow us to define areas within a layout where components can be inserted. They are essential for building flexible, reusable, and modular page layouts. In this guide, we will explore how to work with two types of placeholders: normal placeholders and dynamic placeholders, along with how to configure them in the Sitecore CMS.

In Sitecore, to create both types of placeholders you need to go to the following path:

/sitecore/layout/Placeholder Settings

And in there create your placeholder.
In case it's a Normal Placeholder, not dynamic, you just assign a placeholder key with the following format:

As you can see in the image you need to set the placeholder key and the Allowed Controls, or renderings, that can go into that placeholder.

Same applies to Dynamic Placeholder, but we need to add something more to the placeholder key

As you can see in the image we need that {*} identifier to specify that thi is, in fact, a dynamic placeholder.

Normal Placeholders

A normal placeholder is a static region defined within a layout or component where a specific set of components can be added. These are typically used when you know exactly where a component should be placed in a page or layout.

Adding your placeholder in the code

In your rendering you can add the following jss component

<Placeholder name="placeholder-key" rendering={rendering} />

The rendering prop we're sending comes from ComponentProps, you can extend your rendering type with that and specify it when destructuring your Type in the Rendering declaration

const Rendering = ({
  fields,
  params,
  rendering,
}: FlexibleContainerProps)

Dynamic Placeholders

A dynamic placeholder is more flexible and can handle scenarios where multiple instances of the same placeholder are needed on the page. These placeholders are particularly useful when rendering repeated or nested components.

Adding a dynamic placeholder

In your rendering add the following component:

<Placeholder name=`name-${props.params.DynamicPlaceholderId}` rendering={rendering} />

As you can see, we also added the identifier for dynamic placeholders.

Conclusion

By leveraging both normal and dynamic placeholders, you can build flexible, reusable layouts that allow for dynamic content insertion. Whether you need a static area for content or a more flexible, repeating region, placeholders provide the flexibility needed to build scalable and maintainable websites on Sitecore XM Cloud. Configuring placeholders in the CMS ensures that the right components can be inserted into the correct areas, providing control over the page structure.

Leveraging Sitecore JSS Tags for Seamless Integration with Next.js in XM Cloud

Sebastián Aliaga — Wed, 24 Jul 2024 13:27:38 +0000

In the ever-evolving landscape of web development, integrating content management systems (CMS) with modern JavaScript frameworks has become a crucial aspect of creating dynamic and content-driven websites. Sitecore XM Cloud, paired with Next.js, offers a powerful combination for building scalable and performant web applications. One of the key elements in this integration is the use of Sitecore JSS tags such as , , , and . In this blog, we’ll explore the importance of using these tags and provide practical examples to illustrate their benefits.

Why Use Sitecore JSS Tags?

Seamless Content Integration: Sitecore JSS tags are designed to seamlessly integrate Sitecore-managed content into your Next.js application. These tags automatically handle the complexities of rendering different types of fields, ensuring that content is displayed correctly and consistently.
Enhanced Editor Experience: By using these tags, developers can leverage the full power of Sitecore’s Experience Editor. This allows content editors to see real-time previews and make in-context edits, improving the overall content management experience.
Consistency and Maintainability: Using standardized tags ensures consistency across the application. It reduces the chances of errors and makes the codebase more maintainable, as developers can rely on a common set of components to render Sitecore fields.
Automatic Handling of Attributes: Tags like and automatically handle essential attributes such as src, alt, href, and more, ensuring that accessibility and SEO best practices are followed without additional effort.

Key Sitecore JSS Tags and Their Usage

`<Text>` Tag

The <Text> tag is a versatile component used to render various types text fields, such as single line text or multiline text.

Example:

import React from 'react';
import { Text} from '@sitecore-jss/sitecore-jss-nextjs';

const MyComponent = ({ fields }) => (
  <div>
    <Text field={fields.title} tag="h1" className="page-title" editable={true} />
  </div>
);

export default MyComponent;

In this example, the <Text> tag is used to render a title as an <h1> element and a description as a default paragraph.

`<RichText>` Tag

The <RichText> tag is used to render rich text fields, handling HTML content stored in Sitecore.
Example:

import { RichText } from '@sitecore-jss/sitecore-jss-nextjs';

const MyComponent = ({ fields }) => (
  <div>
    <RichText field={fields.content} />
  </div>
);

export default MyComponent;

Here, the <RichText> tag ensures that the rich text content is rendered correctly, preserving the HTML structure.

`<Image>` Tag

The <Image> tag is designed to render image fields, automatically handling attributes like src, alt, width, and height.

Example:

import { Image } from '@sitecore-jss/sitecore-jss-nextjs';

const MyComponent = ({ fields }) => (
  <div>
    <Image field={fields.image} />
  </div>
);

export default MyComponent;

In this example, the <Image> tag renders an image with all necessary attributes managed automatically.

`<Link>` Tag

The <Link> tag is used to render link fields, ensuring that attributes like href and target are correctly set.

Example:

import { Link } from '@sitecore-jss/sitecore-jss-nextjs';

const MyComponent = ({ fields }) => (
  <div>
    <Link field={fields.link} />
  </div>
);

export default MyComponent;

Here, the <Link> tag renders a link with proper handling of the href attribute and other link properties.

Utilities and Hooks

In addition to the core tags, Sitecore JSS provides various utilities and hooks to enhance the development experience when working with Sitecore XM Cloud and Next.js.

useSitecoreContext Hook

The useSitecoreContext hook provides access to the Sitecore context, including route data, language, and more. This is particularly useful for creating dynamic components that need to react to the context of the current page or item.

import { useSitecoreContext } from '@sitecore-jss/sitecore-jss-nextjs';

const ContextualComponent = () => {
  const { sitecoreContext } = useSitecoreContext();
  return <div>Current route: {sitecoreContext.route.name}</div>;
};

export default ContextualComponent;

componentProps Utility

The componentProps utility is used to fetch component-level data during the build process, ensuring that all necessary data is available for rendering the component.

Example:

import { componentProps } from 'lib/page-props';

export const getStaticProps = async (context) => {
  const props = await componentProps(context);
  return {
    props: {
      ...props
    },
  };
};

Conclusion

Using Sitecore JSS tags like , , , and , along with the provided utilities and hooks, is essential for creating a seamless, maintainable, and editor-friendly web application when working with Sitecore XM Cloud and Next.js. These tags and utilities simplify the integration process and ensure that best practices for accessibility, SEO, and content management are followed. By leveraging these components, developers can build powerful and dynamic web applications that take full advantage of the capabilities offered by Sitecore and Next.js.

Feel free to experiment with these tags and utilities in your own projects to experience the benefits of a streamlined and efficient content integration process. If you have any questions or need further assistance, don’t hesitate to reach out!

Managing JSON-LD Schemas on Sitecore XM Cloud with Next.js and SXA

Sebastián Aliaga — Wed, 24 Jul 2024 12:58:20 +0000

Introduction

In the modern digital landscape, enhancing search engine optimization (SEO) is crucial for the visibility and success of any website. One effective method to improve SEO is by implementing JSON-LD (JavaScript Object Notation for Linked Data) schemas. JSON-LD allows you to embed structured data on your web pages, helping search engines better understand your content and potentially display rich snippets in search results.

This blog post will guide you through the process of managing JSON-LD schemas on Sitecore XM Cloud using Next.js and Sitecore Experience Accelerator (SXA).

Prerequisites

Before we dive into the implementation, ensure you have the following prerequisites:

A Next.js project set up and integrated with Sitecore XM Cloud.
Basic understanding of Sitecore XM Cloud, Next.js, and JSON-LD.
next-seo package installed in your Next.js project.

Setting Up the Next.js Project

First, make sure your Next.js project is set up and integrated with Sitecore XM Cloud. If you haven't done this yet, follow the Sitecore documentation to get started.

Installing Necessary Dependencies

Install the next-seo package, which will help us manage JSON-LD schemas in our Next.js application:

npm install next-seo

Creating a Reusable JSON-LD Schema Component

Create a reusable JSON-LD schema component that can be included in your pages. This component will use the next-seo package to inject JSON-LD data into your pages.

// components/JsonLdSchema.js
import { JsonLd } from 'next-seo';

const JsonLdSchema = ({ type, data }) => {
  return <JsonLd type={type} {...data} />;
};

export default JsonLdSchema;

Defining the Article Detail Component

Next, create the article detail component that will be used on the article detail page template in Sitecore. This component will receive the necessary data from the Sitecore context.

// components/ArticleDetail.js
import { withSitecoreContext } from '@sitecore-jss/sitecore-jss-nextjs';
import JsonLdSchema from './JsonLdSchema';

const ArticleDetail = ({ sitecoreContext }) => {
  const { articleData } = sitecoreContext.route.fields;

  const jsonLdData = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    'headline': articleData.title.value,
    'description': articleData.description.value,
    'datePublished': articleData.datePublished.value,
    'author': {
      '@type': 'Person',
      'name': articleData.author.value
    },
    'mainEntityOfPage': {
      '@type': 'WebPage',
      '@id': articleData.url.value
    }
  };

  return (
    <div>
      <JsonLdSchema type="Article" data={jsonLdData} />
      <h1>{articleData.title.value}</h1>
      <p>{articleData.description.value}</p>
      <p><strong>Published on:</strong> {articleData.datePublished.value}</p>
      <p><strong>Author:</strong> {articleData.author.value}</p>
    </div>
  );
};

export default withSitecoreContext()(ArticleDetail);

Integrating the Component into Sitecore

Define Sitecore Fields: Ensure the Sitecore template for the article detail page includes the necessary fields (title, description, datePublished, author, url). These fields will be populated with data and passed to the component.

Create the necessary Sitecore Components

You can do that following the official sitecore guide for SXA development: Components Design Best Practices

Advanced Usage: Multiple JSON-LD Scripts
If you need to include multiple JSON-LD scripts on a single page, you can use the scriptKey prop to uniquely identify each script tag:

// components/MultipleSchemas.js
import { JsonLd } from 'next-seo';

const MultipleSchemas = () => {
  const personSchema = {
    '@context': 'https://schema.org',
    '@type': 'Person',
    'name': 'John Doe',
    'jobTitle': 'Software Engineer',
    'worksFor': {
      '@type': 'Organization',
      'name': 'Example Inc.'
    }
  };

  const articleSchema = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    'headline': 'Understanding JSON-LD',
    'description': 'A detailed guide on JSON-LD schemas.',
    'datePublished': '2024-07-24',
    'author': {
      '@type': 'Person',
      'name': 'Jane Smith'
    }
  };

  return (
    <div>
      <JsonLd type="Person" scriptKey="person" {...personSchema} />
      <JsonLd type="Article" scriptKey="article" {...articleSchema} />
    </div>
  );
};

export default MultipleSchemas;

Example Output

When rendered, the JSON-LD scripts will be included in the HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Understanding JSON-LD</title>
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Person",
    "name": "John Doe",
    "jobTitle": "Software Engineer",
    "worksFor": {
      "@type": "Organization",
      "name": "Example Inc."
    }
  }
  </script>
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "Understanding JSON-LD",
    "description": "A detailed guide on JSON-LD schemas.",
    "datePublished": "2024-07-24",
    "author": {
      "@type": "Person",
      "name": "Jane Smith"
    }
  }
  </script>
</head>
<body>
  <div>
    <h1>Understanding JSON-LD</h1>
    <p>By Jane Smith</p>
    <p>Published on: July 24, 2024</p>
    <h2>About the Author</h2>
    <p>John Doe is a Software Engineer at Example Inc.</p>
  </div>
</body>
</html>

Conclusion

By following this guide, you can effectively manage JSON-LD schemas in your Sitecore XM Cloud project using Next.js and SXA. Implementing structured data helps search engines better understand your content, enhancing your site's SEO and visibility. Leveraging the next-seo package simplifies the process, allowing you to focus on creating valuable content for your users.

If you have any questions or need further assistance, feel free to reach out in the comments below!

DEV Community: Sebastián Aliaga

Handling Hierarchical Taxonomies in Sitecore Search

The Challenge

Our Solution: The Parent__Child Pattern

How It Works

The Architecture

Step-by-Step Process

1. Tag Group Definition

2. Hierarchical Resolution

3. GraphQL Parent Resolution

4. Meta Props Generation

Example: Real-World Usage

Input Data Structure

Processing Flow

Search Index Result

Frontend Handling

Benefits of This Approach

1. Search Engine Compatibility

2. Flexible Frontend Implementation

3. Backward Compatibility

4. Performance

Advanced Features

Flat Mode Support

Custom Selectors

Best Practices

1. Error Handling

2. Performance Considerations

3. Naming Conventions

4. Testing

Conclusion

Advanced Web Crawler 101: Sitemap Trigger Extractors

Step 1: Configure a Sitemap Trigger

Step 2: Define Attributes

Step 3: Define Document Extractors

Types of Extractors

Example: JavaScript Extractor

Validation: Crawl & Verify

Key Takeaways

Preparing Sitecore Data for Search Engine Crawling: A Complete Metadata Implementation Guide

Table of Contents

Architecture Overview

Key Components

Core Metadata Service

Service Structure

Standard Metadata Fields

Search Field Constants

Template-Specific Metadata

Product Detail Pages

Event Detail Pages

Article Detail Pages

Structured Data Implementation

Schema Service Architecture

Product Schema Example

Website Schema with Search Action

Integration with Next.js

Meta Props Plugin

Layout Integration

Best Practices

1. Field Standardization

2. Fallback Values

3. Data Sanitization

4. Performance Optimization

5. SEO-Friendly URLs

Implementation Examples

Complete Product Page Setup

Event Page Metadata

Conclusion

Reducing props size in Sitecore XM Cloud Next.js to improve performance

Introduction

The Problem

The Goal

The Solution

Results

Other use cases

Wrapping up

Mastering the Pages Editor in Sitecore XM Cloud: Managing Page Content and Datasources

Introduction

Types of Editable Content

Page Content

Datasources

Our Solution: The `Parent__Child` Pattern

`<Text>` Tag

`<RichText>` Tag

`<Image>` Tag

`<Link>` Tag