Custom Content Resolver Support (#14)

<!-- Provide a general summary of your changes in the Title above -->
<!-- Apply the label "bug" or "enhacement" as applicable. -->

## Description / Motivation
<!-- Describe your changes in detail -->
<!-- Why is this change required? What problem does it solve? -->
<!-- If it fixes an open issue, please link to the issue here. -->

This modifies the FieldParser to support Custom Content Resolvers
returning modified JSON.
This fixes #8 

Added missing CONTRIBUTING file.

Removed `AddSystemTextJson` which should not be used or needed as it
pollutes the DI.

## Testing
Added integration tests both for layout client and rendering engine
binding leveraging the "Navigation" component from Headless SXA.

- [X] The Unit & Intergration tests are passing.
- [X] I have added the necesary tests to cover my changes.

## Terms
<!-- Place an X in the [] to check. -->

<!-- The Code of Conduct helps create a safe space for everyone. We
require that everyone agrees to it. -->
- [X] I agree to follow this project's [Code of
Conduct](CODE_OF_CONDUCT.md).

---------

Co-authored-by: Ivan Lieckens <[email protected]>

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contribution to the Sitecore ASP.NET Core SDK
+
+Thank you for your interest in contributing to our project. You can contribute with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.
+
+## Code of Conduct
+Please read the [Code of Conduct](./CODE_OF_CONDUCT.md) before participating, all contributors are expected to uphold this code. Please report unacceptable behavior to [[email protected]](mailto:[email protected]).
+
+## Reporting Issues
+
+We always welcome bug reports, feature requests and overall feedback. Here are a few tips on how you can make reporting your issue as effective as possible.
+
+### Finding Existing Issues
+
+Before filing a new issue, please search our [open issues](https://github.com/Sitecore/ASP.NET-Core-SDK/issues) to check if it already exists.
+
+If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (reaction) the original post, as this helps us prioritize popular issues.
+
+### Use the right template
+
+When creating a new issue, please use the appropriate template. We have the following templates available:
+
+| Template                        | Description                                                                                                                                 |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bug Report                      | Use this template to report a bug.                                                                                                          |
+| Feature Request                 | Use this template to request a new feature.                                                                                                 |
+| Question                        | Use this template to ask a question. For implementation specific questions please use [StackExchange](https://sitecore.stackexchange.com/). |
+| Report a security vulnerability | Use this template to report a security vulnerability.                                                                                       |
+
+### Writing a Good Bug Report
+
+Good bug reports make it easier for maintainers to verify and root cause the underlying problem. The better a bug report, the faster the problem will be resolved. Ideally, a bug report should contain the following information:
+
+* A high-level description of the problem.
+* A _minimal reproduction_, i.e. the smallest size of code/configuration required to reproduce the wrong behavior.
+* A description of the _expected behavior_, contrasted with the _actual behavior_ observed.
+* Information on the environment: Sitecore XM version, SDK version, etc.
+* Additional information, e.g. is it a regression from previous versions? are there any known workarounds?
+
+#### Why are Minimal Reproductions Important?
+
+A reproduction lets maintainers verify the presence of a bug, and diagnose the issue using a debugger. A _minimal_ reproduction is the smallest possible application demonstrating that bug. Minimal reproductions are generally preferable since they:
+
+1. Focus debugging efforts on a simple code snippet,
+2. Ensure that the problem is not caused by unrelated dependencies/configuration,
+3. Avoid the need to share production codebases.
+
+#### Are Minimal Reproductions Required?
+
+In certain cases, creating a minimal reproduction might not be practical (e.g. due to nondeterministic factors, external dependencies). In such cases you would be asked to provide as much information as possible, for example by sharing a memory dump of the failing application. If maintainers are unable to root cause the problem, they might still close the issue as not actionable. While not required, minimal reproductions are strongly encouraged and will significantly improve the chances of your issue being prioritized and fixed by the maintainers.
+
+#### How to Create a Minimal Reproduction
+
+The best way to create a minimal reproduction is gradually removing code and dependencies from a reproducing app, until the problem no longer occurs. A good minimal reproduction:
+
+* Excludes all unnecessary types, methods, code blocks, source files, nuget dependencies and project configurations.
+* Contains documentation or code comments illustrating expected vs actual behavior.
+* If possible, avoids performing any unneeded IO or system calls.
+
+## Contributiting Code
+All code contributions must be submitted by the standard GitHub pull request flow, or by logging an issue.
+
+### Accepting Contributions
+Sitecore has a _"No commitment"_ approach to this repository. The required functionality of the SDK and related XM Cloud features will be the driver for acceptance decisions. We are open to contributions from the community, but make no commitment to accept or incorporate changes.
+
+### Guidelines
+* Create a [fork of the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)
+* Create a branch for your changes. Use /feat/ for new features, /fix/ for bug fixes and /new/ for breaking changes.
+* We observe strict code style rules, please ensure your changes follow the guidance provided by the analyzers.
+  * [StyleCop](https://github.com/DotNetAnalyzers/StyleCopAnalyzers)
+  * [File Scoped Namespaces](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-10.0/file-scoped-namespaces)
+  * Do not use `var`
+* We require all changes to be covered by tests.
+* When you are ready to submit your changes, [create a pull request from your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) into this repository.
+* This repository is configured to use `Squash Merges` for all accepted contributions. This decision has been made to keep the commit history clean and concise.

Sitecore.AspNetCore.SDK.sln

@@ -89,7 +89,11 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Sitecore.AspNetCore.SDK.Tra
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "GitHub", "GitHub", "{5FE82369-DEF2-4136-B74F-6E86DB91050E}"
 	ProjectSection(SolutionItems) = preProject
+		CODE_OF_CONDUCT.md = CODE_OF_CONDUCT.md
+		CONTRIBUTING.md = CONTRIBUTING.md
+		LICENSE.md = LICENSE.md
 		.github\pull_request_template.md = .github\pull_request_template.md
+		README.md = README.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{1706E43D-AC19-4FBB-9BFB-18A8B195580A}"

src/Sitecore.AspNetCore.SDK.LayoutService.Client/Extensions/SitecoreLayoutClientBuilderExtensions.cs

@@ -99,7 +99,7 @@ public static ILayoutRequestHandlerBuilder<GraphQlLayoutServiceHandler> AddGraph
                 request.Language(defaultLanguage);
             }
         });
-        return builder.AddHandler(name, (sp)
+        return builder.AddHandler(name, sp
             => ActivatorUtilities.CreateInstance<GraphQlLayoutServiceHandler>(
                 sp, client, sp.GetRequiredService<ISitecoreLayoutSerializer>(), sp.GetRequiredService<ILogger<GraphQlLayoutServiceHandler>>()));
     }
@@ -151,23 +151,6 @@ public static ISitecoreLayoutClientBuilder WithDefaultRequestOptions(this ISitec
         return builder;
     }
 
-    /// <summary>
-    /// Configures System.Text.Json specific features such as input and output formatters.
-    /// </summary>
-    /// <param name="builder">The <see cref="ISitecoreLayoutClientBuilder"/> being configured.</param>
-    /// <returns>The <see cref="ILayoutRequestHandlerBuilder{THandler}"/> so that additional calls can be chained.</returns>
-    public static ISitecoreLayoutClientBuilder AddSystemTextJson(this ISitecoreLayoutClientBuilder builder)
-    {
-        ServiceDescriptor descriptor = new(typeof(ISitecoreLayoutSerializer), typeof(JsonLayoutServiceSerializer), ServiceLifetime.Singleton);
-        builder.Services.Replace(descriptor);
-
-        builder.Services.AddSingleton<IFieldParser, FieldParser>();
-        builder.Services.AddSingleton<JsonConverter, FieldConverter>();
-        builder.Services.AddSingleton<JsonConverter, PlaceholderFeatureConverter>();
-
-        return builder;
-    }
-
     /// <summary>
     /// Registers a HTTP request handler for the Sitecore layout service client.
     /// </summary>

src/Sitecore.AspNetCore.SDK.LayoutService.Client/Serialization/Converter/FieldParser.cs

@@ -7,27 +7,44 @@ namespace Sitecore.AspNetCore.SDK.LayoutService.Client.Serialization.Converter;
 /// <inheritdoc cref="IFieldParser"/>
 public class FieldParser : IFieldParser
 {
+    /// <summary>
+    /// Field key for custom content created by Custom Content Resolvers.
+    /// </summary>
+    // ReSharper disable once MemberCanBePrivate.Global - Must be accessible for people using the SDK.
+    public const string CustomContentFieldKey = "CustomContent";
+
     /// <inheritdoc cref="IFieldParser.ParseFields"/>
     public Dictionary<string, IFieldReader> ParseFields(ref Utf8JsonReader reader)
     {
-        if (reader.TokenType != JsonTokenType.StartObject)
+        Dictionary<string, IFieldReader> result = [];
+        switch (reader.TokenType)
         {
-            throw new JsonException();
+            case JsonTokenType.StartObject:
+                result = ParseStandardFields(ref reader);
+                break;
+            default:
+                result.Add(CustomContentFieldKey, new JsonSerializedField(ParseField(ref reader)));
+                break;
         }
 
-        Dictionary<string, IFieldReader> fields = [];
+        return result;
+    }
+
+    private static Dictionary<string, IFieldReader> ParseStandardFields(ref Utf8JsonReader reader)
+    {
+        Dictionary<string, IFieldReader> result = [];
         while (reader.Read() && reader.TokenType != JsonTokenType.EndObject)
         {
             string? key = reader.GetString();
             reader.Read();
             JsonDocument value = ParseField(ref reader);
             if (key != null)
             {
-                fields.Add(key, new JsonSerializedField(value));
+                result.Add(key, new JsonSerializedField(value));
             }
         }
 
-        return fields;
+        return result;
     }
 
     private static JsonDocument ParseField(ref Utf8JsonReader reader)

tests/Sitecore.AspNetCore.SDK.LayoutService.Client.Integration.Tests/FieldsFixture.cs

@@ -493,4 +493,30 @@ public void Component_RichTextField_CanBeRead(ISitecoreLayoutSerializer serializ
         resultField!.Value.Should().Be(expectedField.value.Value);
         resultField.EditableMarkup.Should().Be(expectedField.editable.Value);
     }
+
+    [Theory]
+    [MemberData(nameof(Serializers))]
+    public void HeadlessSxa_CanBeRead(ISitecoreLayoutSerializer serializer)
+    {
+        // Arrange
+        string json = File.ReadAllText("./Json/headlessSxa.json");
+        dynamic jsonModel = JObject.Parse(json);
+
+        // Act
+        SitecoreLayoutResponseContent? result = serializer.Deserialize(json);
+
+        // Assert
+        TextField? resultField = result?.Sitecore?.Route?
+            .Placeholders["headless-header"].ComponentAt(0)?
+            .Placeholders["sxa-header"].ComponentAt(0)?
+            .Fields["Text"]
+            .Read<TextField>();
+
+        dynamic? expectedField = jsonModel.sitecore.route
+            .placeholders["headless-header"][0]
+            .placeholders["sxa-header"][0]
+            .fields.Text;
+
+        resultField!.Value.Should().Be(expectedField.value.Value);
+    }
 }

tests/Sitecore.AspNetCore.SDK.LayoutService.Client.Integration.Tests/Sitecore.AspNetCore.SDK.LayoutService.Client.Integration.Tests.csproj

@@ -17,6 +17,10 @@
       <Link>Json\edit-in-horizon-mode.json</Link>
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </Content>
+    <Content Include="..\data\json\headlessSxa.json">
+      <Link>Json\headlessSxa.json</Link>
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </Content>
   </ItemGroup>
 
 </Project>

tests/Sitecore.AspNetCore.SDK.LayoutService.Client.Tests/Serialization/Converter/FieldParserTests.cs

@@ -27,23 +27,22 @@ public class FieldParserTests
     };
 
     [Fact]
-    public void ParseFields_IncorrectJsonNotObject_ShouldThrowJsonException()
+    public void ParseFields_JsonNotObject_ShouldWrapAsCustomContent()
     {
         // Arrange
-        void Read()
-        {
-            const string json = "[]";
-            byte[] bytes = [.. Encoding.UTF8.GetBytes(json)];
-            Utf8JsonReader reader = new(bytes);
-            reader.Read();
-            _sut.ParseFields(ref reader);
-        }
+        const string json = "[]";
+        byte[] bytes = [.. Encoding.UTF8.GetBytes(json)];
+        Utf8JsonReader reader = new(bytes);
+        reader.Read();
 
         // Act
-        Action result = Read;
+        Dictionary<string, IFieldReader> result = _sut.ParseFields(ref reader);
 
         // Assert
-        result.Should().Throw<JsonException>();
+        result.Should().ContainSingle();
+        (string key, IFieldReader value) = result.First();
+        key.Should().Be(FieldParser.CustomContentFieldKey);
+        value.Should().BeOfType<JsonSerializedField>();
     }
 
     [Fact]

tests/Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests/ComponentModels/CustomResolver.cs

@@ -0,0 +1,10 @@
+using Sitecore.AspNetCore.SDK.LayoutService.Client.Serialization.Converter;
+using Sitecore.AspNetCore.SDK.RenderingEngine.Binding.Attributes;
+
+namespace Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests.ComponentModels;
+
+public class CustomResolver
+{
+    [SitecoreComponentField(Name = FieldParser.CustomContentFieldKey)]
+    public CustomResolverModel[]? CustomContent { get; set; }
+}

tests/Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests/ComponentModels/CustomResolverModel.cs

@@ -0,0 +1,17 @@
+using Sitecore.AspNetCore.SDK.LayoutService.Client.Response.Model.Fields;
+
+namespace Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests.ComponentModels
+{
+    public class CustomResolverModel
+    {
+        public List<string>? Styles { get; set; } = [];
+
+        public List<CustomResolverModel>? Children { get; set; } = [];
+
+        public string? Href { get; set; }
+
+        public string? Querystring { get; set; }
+
+        public TextField? NavigationTitle { get; set; }
+    }
+}

tests/Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests/ComponentModels/PartialDesignDynamicPlaceholder.cs

@@ -0,0 +1,9 @@
+using Sitecore.AspNetCore.SDK.RenderingEngine.Binding.Attributes;
+
+namespace Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests.ComponentModels;
+
+public class PartialDesignDynamicPlaceholder
+{
+    [SitecoreComponentParameter(Name ="sig")]
+    public string? Sig { get; set; }
+}

tests/Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests/Controllers/HomeController.cs

@@ -14,7 +14,8 @@ public IActionResult Index(Route route)
         {
             TestConstants.NestedPlaceholderPageLayoutId => "NestedPlaceholderPageLayout",
             TestConstants.VisitorIdentificationPageLayoutId => "VisitorIdentificationLayout",
-            _ => nameof(Index),
+            TestConstants.HeadlessSxaLayoutId => "HeadlessSxaLayout",
+            _ => nameof(Index)
         };
 
         return View(view);

tests/Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests/Fixtures/Binding/CustomResolverBindingFixture.cs

@@ -0,0 +1,86 @@
+using System.Net;
+using FluentAssertions;
+using HtmlAgilityPack;
+using Microsoft.AspNetCore.TestHost;
+using Sitecore.AspNetCore.SDK.LayoutService.Client.Extensions;
+using Sitecore.AspNetCore.SDK.RenderingEngine.Extensions;
+using Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests.ComponentModels;
+using Xunit;
+
+// ReSharper disable StringLiteralTypo
+namespace Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests.Fixtures.Binding;
+
+public class CustomResolverBindingFixture : IDisposable
+{
+    private readonly TestServer _server;
+    private readonly HttpLayoutClientMessageHandler _mockClientHandler;
+    private readonly Uri _layoutServiceUri = new("http://layout.service");
+
+    public CustomResolverBindingFixture()
+    {
+        TestServerBuilder testHostBuilder = new();
+        _mockClientHandler = new HttpLayoutClientMessageHandler();
+        testHostBuilder
+            .ConfigureServices(builder =>
+            {
+                builder
+                    .AddSitecoreLayoutService()
+                    .AddHttpHandler("mock", _ => new HttpClient(_mockClientHandler) { BaseAddress = _layoutServiceUri })
+                    .AsDefaultHandler();
+                builder.AddSitecoreRenderingEngine(options =>
+                {
+                    options
+                        .AddModelBoundView<PartialDesignDynamicPlaceholder>("PartialDesignDynamicPlaceholder")
+                        .AddModelBoundView<CustomResolver>(name => name.Equals("Navigation", StringComparison.OrdinalIgnoreCase), "CustomResolver")
+                        .AddDefaultComponentRenderer();
+                });
+            })
+            .Configure(app =>
+            {
+                app.UseRouting();
+                app.UseSitecoreRenderingEngine();
+                app.UseEndpoints(endpoints =>
+                {
+                    endpoints.MapDefaultControllerRoute();
+                });
+            });
+
+        _server = testHostBuilder.BuildServer(new Uri("http://localhost"));
+    }
+
+    [Fact]
+    public async Task SitecoreLayoutModelBinders_BindDataCorrectly()
+    {
+        // Arrange
+        string json = await File.ReadAllTextAsync("./Json/headlessSxa.json");
+        _mockClientHandler.Responses.Push(new HttpResponseMessage
+        {
+            StatusCode = HttpStatusCode.OK,
+            Content = new StringContent(json)
+        });
+
+        HttpClient client = _server.CreateClient();
+
+        // Act
+        string response = await client.GetStringAsync(new Uri("/", UriKind.Relative));
+
+        HtmlDocument doc = new();
+        doc.LoadHtml(response);
+        HtmlNode? sectionNode = doc.DocumentNode.ChildNodes["head"].ChildNodes.First(n => n.HasClass("custom-resolver"));
+
+        // Assert
+        sectionNode.ChildNodes["ul"].ChildNodes.Count(c => c.Name.Equals("li")).Should().Be(1);
+        sectionNode.ChildNodes["ul"].ChildNodes["li"].ChildNodes.Count(c => c.Name.Equals("span")).Should().Be(1);
+        sectionNode.ChildNodes["ul"].ChildNodes["li"].ChildNodes["span"].InnerText.Should().Be("Home");
+
+        sectionNode.ChildNodes["ul"].ChildNodes["li"].ChildNodes["ul"].ChildNodes.Count(c => c.Name.Equals("li")).Should().Be(1);
+        sectionNode.ChildNodes["ul"].ChildNodes["li"].ChildNodes["ul"].ChildNodes["li"].ChildNodes["span"].InnerText.Should().Be("About");
+    }
+
+    public void Dispose()
+    {
+        _server.Dispose();
+        _mockClientHandler.Dispose();
+        GC.SuppressFinalize(this);
+    }
+}

tests/Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests/Sitecore.AspNetCore.SDK.RenderingEngine.Integration.Tests.csproj

@@ -18,4 +18,11 @@
     <ProjectReference Include="..\Sitecore.AspNetCore.SDK.AutoFixture\Sitecore.AspNetCore.SDK.AutoFixture.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Content Include="..\data\json\headlessSxa.json">
+      <Link>Json\headlessSxa.json</Link>
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
+
 </Project>