Merge pull request #83 from Namoshek/feature/model-property-aliases

Add new base model for DisplayName support

Author: Amberg

DocxTemplater.Test/DocxTemplateTest.cs

@@ -1,11 +1,12 @@
-using DocumentFormat.OpenXml;
+using System.Collections;
+using System.ComponentModel;
+using System.Dynamic;
+using System.Globalization;
+using DocumentFormat.OpenXml;
 using DocumentFormat.OpenXml.Packaging;
 using DocumentFormat.OpenXml.Wordprocessing;
 using DocxTemplater.Images;
 using DocxTemplater.Model;
-using System.Collections;
-using System.Dynamic;
-using System.Globalization;
 using Bold = DocumentFormat.OpenXml.Wordprocessing.Bold;
 using Break = DocumentFormat.OpenXml.Drawing.Break;
 using Paragraph = DocumentFormat.OpenXml.Wordprocessing.Paragraph;
@@ -1326,6 +1327,31 @@ public void TestWithNestedITemplateModel_AdditionalDataIsNull()
                                                   "</w:r></w:p>"));
         }
 
+        [Test]
+        public void TestWithBaseTemplateModelWithDisplayNames()
+        {
+            using var memStream = new MemoryStream();
+            using var wpDocument = WordprocessingDocument.Create(memStream, WordprocessingDocumentType.Document);
+
+            MainDocumentPart mainPart = wpDocument.AddMainDocumentPart();
+            mainPart.Document = new Document(new Body(new Paragraph(
+                new Run(new Text("{{ds.Vorname}} {{ds.LastName}} aus {{ds.Anschrift}}"))
+            )));
+            wpDocument.Save();
+            memStream.Position = 0;
+            var docTemplate = new DocxTemplate(memStream);
+            docTemplate.RegisterFormatter(new Markdown.MarkdownFormatter());
+            docTemplate.BindModel("ds", new DummyModelWithDisplayNames());
+            var result = docTemplate.Process();
+            docTemplate.Validate();
+            Assert.That(result, Is.Not.Null);
+            result.Position = 0;
+
+            var document = WordprocessingDocument.Open(result, false);
+            var body = document.MainDocumentPart.Document.Body;
+            Assert.That(body.InnerText, Is.EqualTo("John Doe aus Musterstraße 42, A-4242 Musterhausen"));
+        }
+
         private static DriveStudentOverviewReportingModel CrateBillTemplate2Model()
         {
             DriveStudentOverviewReportingModel model = new()
@@ -1492,5 +1518,17 @@ public bool TryGetPropertyValue(string propertyName, out ValueWithMetadata value
                 return false;
             }
         }
+
+        private class DummyModelWithDisplayNames : TemplateModelWithDisplayNames
+        {
+            [DisplayName("Vorname")]
+            public string FirstName { get; set; } = "John";
+
+            public string LastName { get; set; } = "Doe";
+
+            [DisplayName("Anschrift")]
+            [ModelProperty(DefaultFormatter = "md")]
+            public string Address { get; set; } = "Musterstraße 42, **A-4242 Musterhausen**";
+        }
     }
 }

DocxTemplater/Model/TemplateModelWithDisplayNames.cs

@@ -0,0 +1,45 @@
+using System;
+using System.ComponentModel;
+using System.Linq;
+using System.Reflection;
+
+namespace DocxTemplater.Model
+{
+    public abstract class TemplateModelWithDisplayNames : ITemplateModel
+    {
+        public bool TryGetPropertyValue(string propertyName, out ValueWithMetadata value)
+        {
+            var properties = GetType().GetProperties(BindingFlags.IgnoreCase | BindingFlags.Public | BindingFlags.GetProperty | BindingFlags.Instance);
+
+            // Try to find property with the specified display name.
+            foreach (var property in properties)
+            {
+                var displayNameAttribute = property.GetCustomAttribute<DisplayNameAttribute>();
+                if (displayNameAttribute is null || !string.Equals(displayNameAttribute.DisplayName, propertyName, StringComparison.OrdinalIgnoreCase))
+                {
+                    continue;
+                }
+
+                return GetValue(property, out value);
+            }
+
+            // Try to find property with the specified name (case-insensitive) as fallback.
+            var propertyByName = properties.FirstOrDefault(p => string.Equals(p.Name, propertyName, StringComparison.OrdinalIgnoreCase));
+            if (propertyByName != null)
+            {
+                return GetValue(propertyByName, out value);
+            }
+
+            value = new ValueWithMetadata(null);
+            return false;
+        }
+
+        private bool GetValue(PropertyInfo property, out ValueWithMetadata value)
+        {
+            var modelPropertyAttribute = property.GetCustomAttribute<ModelPropertyAttribute>();
+
+            value = new ValueWithMetadata(property.GetValue(this), new ValueMetadata(modelPropertyAttribute?.DefaultFormatter));
+            return true;
+        }
+    }
+}

README.md

@@ -327,6 +327,44 @@ var docTemplate = new DocxTemplate(memStream, new ProcessSettings()
 var result = docTemplate.Process();
 ```
 
+## Advanced Model Binding: `ITemplateModel` and `TemplateModelWithDisplayNames`
+
+### `ITemplateModel` Interface
+
+For advanced scenarios where a standard object or dictionary is not suitable for your data model, you can implement the `ITemplateModel` interface.
+This allows you to control how properties are resolved for template binding.
+
+```csharp
+public interface ITemplateModel
+{
+    bool TryGetPropertyValue(string propertyName, out ValueWithMetadata value);
+}
+```
+
+Implement this interface to provide custom property lookup logic.
+This is useful for dynamic models, computed properties, or when you want to support custom property resolution strategies.
+
+### `TemplateModelWithDisplayNames` Base Class
+
+`TemplateModelWithDisplayNames` is an abstract base class that extends `ITemplateModel` and allows you to bind template placeholders to properties using either their property name or a `[DisplayName]` attribute.
+This is especially useful when you want to use user-friendly or localized names in your templates.
+
+```csharp
+using DocxTemplater.Model;
+using System.ComponentModel;
+
+public class PersonModel : TemplateModelWithDisplayNames
+{
+    [DisplayName("Vorname")]
+    public string FirstName { get; set; }
+
+    [DisplayName("Nachname")]
+    public string LastName { get; set; }
+}
+```
+
+In your template, you can then use either `{{person.Vorname}}` or `{{person.FirstName}}` to access the property.
+
 ## Support This Project
 
 If you find DocxTemplater useful, please consider supporting its development: