Skip to main content

​
How Gradial Identifies Fragments

​
Automatic Fragment Detection

When you request a change on a page, Gradial automatically determines whether the content lives directly on the page or is sourced from a fragment. Example: You request “Update the headline in the hero section.” Gradial detects that the hero content is pulled from an experience fragment and surfaces this information before applying changes.

​
What This Means for You

ScenarioGradial Behavior
Content lives on the pageChange is applied directly to the page
Content is from a content fragmentGradial identifies the fragment and creates a launch or variation
Content is from an experience fragmentGradial identifies the fragment and creates a launch or variation

​
Safe by Default

When using a launches configuration, Gradial’s default behavior for content fragments and experience fragments is to create a launch or variation rather than modifying the original. This ensures:
  • No unintended impact — The original fragment remains unchanged until you explicitly publish
  • Review before propagation — Changes can be validated in the launch before going live
  • Rollback capability — The original version is preserved if changes need to be reverted

​
Content Fragments vs. Experience Fragments

​
Content Fragments

  • What they are: Structured, channel-agnostic content blocks
  • Defined by: Content fragment models (schemas)
  • Best for: Text, data, and content that appears in multiple formats or channels
  • Examples: Product descriptions, author bios, FAQs, legal disclaimers

​
Experience Fragments

  • What they are: Reusable page sections with layout and components
  • Defined by: Component structure and design
  • Best for: Visual page elements shared across pages
  • Examples: Headers, footers, promotional banners, navigation blocks

​
Key Difference

Content fragments manage what the content says. Experience fragments manage how it looks and behaves on the page.

​
Governance Best Practices

​
Establish Ownership and Approval Workflows

Fragments often cross team boundaries. Establish clear governance:
Fragment TypeSuggested Governance
Site-wide experience fragments (headers, footers)Requires senior stakeholder or web governance approval
Campaign-specific fragmentsMarketing team ownership with standard review
Legal/compliance content fragmentsLegal review required before any change
Localized fragmentsRegional team approval plus global oversight

​
Version and Document Changes

  • Use clear versioning for fragments
  • Document the reason for each change
  • Maintain a changelog for high-impact fragments
  • Set review dates for time-sensitive content

​
Coordinate Across Teams

For shared fragments, consider:
  • Notification workflows when changes are proposed
  • Staging or preview environments to test impact
  • Scheduled update windows for high-traffic fragments

​
Where Rules Are Helpful

Gradial allows you to configure rules that simplify fragment management, reducing the need for business users to understand technical details like fragment models or naming conventions.

​
Rule Type: Content Fragment Model Selection

Problem: Business users shouldn’t need to know which content fragment model to use for different content types. Solution: Create rules that automatically select the correct model based on context.
Rule ExampleBehavior
”Product description” content → Product Fragment ModelGradial automatically uses the correct schema
FAQ content → FAQ Fragment ModelEnsures consistent structure for all FAQs
Legal disclaimer → Legal Content ModelEnforces required fields and review flags
Benefit: Users simply describe what they need; Gradial handles the technical mapping.

​
Rule Type: Naming Conventions

Problem: Inconsistent fragment naming makes management difficult over time. Solution: Define naming rules that Gradial enforces automatically.
Rule ExampleGenerated Name
Product fragments[product-line]-[product-name]-[content-type]
Campaign fragments[campaign-id]-[region]-[component]
Experience fragmentsxf-[site]-[section]-[variant]
Benefit: Fragments remain organized, searchable, and consistent.

​
Rule Type: Field Mapping

Problem: Business users don’t know which fragment fields map to which page components. Solution: Create mapping rules that translate user intent to fragment fields.
User InputMaps To
”Update the headline”fragment.title field
”Change the description”fragment.bodyText field
”Update the CTA”fragment.ctaText + fragment.ctaLink fields
Benefit: Users work in natural language; Gradial handles the technical translation.

​
Rule Type: Governance Warnings

Problem: Some fragments require additional review, but users may not know which ones. Solution: Create rules that trigger warning messages when sensitive fragments are being modified.
Rule ExampleWarning Behavior
Any change to legal-* fragmentsWarning: “This fragment contains legal content—ensure compliance review before publishing”
Changes to site-wide experience fragmentsWarning: “This fragment is used across the site—verify changes with governance team”
Updates affecting shared contentWarning: “This content fragment is referenced in multiple locations”
Benefit: Users are informed about the significance of their changes without blocking their workflow.

​
Fragment Embedding Best Practices

​
The Nesting Problem

Fragments can reference other fragments, creating nested structures. While this enables flexibility, excessive nesting creates problems:
  • Performance impact — Deeply nested fragments slow page rendering
  • Debugging difficulty — Hard to trace where content originates
  • Update complexity — Changes cascade unpredictably
  • Author confusion — Users lose track of content relationships

​
The Three-Layer Rule

Best Practice: Limit fragment nesting to a maximum of three layers deep. 
Page
 └── Experience Fragment (Layer 1)
      └── Content Fragment (Layer 2)
           └── Nested Content Fragment (Layer 3) ← MAXIMUM
Beyond three layers, complexity outweighs flexibility benefits.

​
Signs You’ve Over-Nested

  • Authors can’t determine where content comes from
  • Small changes require tracing through multiple fragments
  • Page preview doesn’t match expectations
  • Performance issues on content-heavy pages

​
How to Simplify

If you discover deep nesting:
  1. Audit fragment relationships — Map out the full dependency tree
  2. Flatten where possible — Combine fragments that are always used together
  3. Duplicate intentionally — Sometimes separate fragments are clearer than nested ones
  4. Document the structure — If nesting is necessary, document why

​
Configuring Fragment Rules in Gradial

Work with your Gradial administrator to set up rules for your environment:
  1. Inventory your fragment models — List all content fragment models and their purposes
  2. Define naming conventions — Establish patterns for each fragment type
  3. Map user language to fields — Identify how business users describe content
  4. Set governance triggers — Determine which fragments need elevated review
  5. Document nesting limits — Codify the three-layer rule in your guidelines

​
Key Takeaways

  • Gradial automatically detects fragments and shows impact before changes are applied
  • Governance is critical — fragment changes can propagate widely
  • Rules simplify complexity — business users don’t need to understand models or naming
  • Limit nesting to three layers — deeper structures create maintenance problems
  • Ownership and approval workflows protect shared content from unintended changes