And a corresponding C# class.

public class MyTextPage : PublishedContentModel { public MyTextPage(IPublishedContent content) : base(content) { } public string Title { get; set; } public HtmlString BodyText { get; set; } public Image Image { get; set; } }

In this class we have a three properties defined: Title, BodyText, and Image. Each of them when queried will represent the property that you have defined when setting up your DocumentType in the back office. You’ll have noticed that we have set the property type of two of those properties to HtmlString and Image without any extra attribution required.

The BodyText property represents a Richtext editor data type. Ditto will automatically map the property to a HtmlString instance and parse any links for you. The Image property represents a Media Picker, this is mapped to another custom C# class as follows.

[TypeConverter(typeof(DittoMediaPickerConverter))] public class Image : PublishedContentModel { public Image(IPublishedContent content) : base(content) { } [UmbracoProperty(Constants.Conventions.Media.Bytes)] public int Bytes { get; set; } [UmbracoProperty(Constants.Conventions.Media.Extension)] public string Extension { get; set; } }

Note: You could also map the width and height properties using the same approach. I won’t though here so you don’t go code blind.

Type Converters

So there’s a few extra things going on in this class: First thing you’ll spot is a TypeConverter attribute at the top of the class. This tells Ditto what converter to use when creating the property value. There are several built into Ditto available for you.

DittoContentPickerConverter

DittoConverter (Base class for all converters.)

DittoEnumConverter

DittoHtmlStringConverter (Runs automatically.)

DittoMediaPickerConverter

DittoMemberPickerConverter

DittoMultipleMediaPickerConverter

DittoPickerConverter (Super useful and the best choice for inheriting from. )

DittoUltimatePickerConverter (For Umbraco v6)

If you are not familiar with .NET TypeConverters, please read Scott Hanselman’s blog post: TypeConverters: There’s not enough TypeDescripter.GetConverter in the world. This gives a good ‘real-world’ understanding of their purpose.

Then from there, to find out more, refer to the MSDN documentation on How to: Implement a Type Converter

The type converters logic run as follows: If a class is decorated with a TypeConverterAttribute then Ditto will map any reference to that class using the defined converter. If you want to change that behaviour for specific properties you can specify a new attribute declaration on the property on your parent class. Ditto can also handle enumerable properties and will map the correct type parameter when it finds one. It can also tell when you want an enumerable collection or a single item and will return the right thing.

Writing custom type converters is a painless process, especially if you inherit from the ones built into Ditto. Here’s an example one that maps a picker from the awesome nuPickers project.

public class NuPickerPickerConverter : DittoPickerConverter { public override bool CanConvertFrom(ITypeDescriptorContext context, Type sourceType) { if (sourceType == typeof(string) || sourceType == typeof(Picker)) { return true; } return base.CanConvertFrom(context, sourceType); } public override object ConvertFrom(ITypeDescriptorContext context, CultureInfo culture, object value) { Picker picker = value as Picker; if (picker != null) { return base.ConvertFrom(context, culture, picker.PickedKeys); } return base.ConvertFrom(context, culture, value); } }

Not bad eh?

Value Resolvers

The second thing you would have spotted would have been the UmbracoPropertyattribute that decorated the two properties.

[UmbracoProperty(Constants.Conventions.Media.Extension)] public string Extension { get; set; }

This attribute tells something we call a ValueResolver that gives Ditto additional instructions, since we are deviating from normal behaviour, on how to retrieve the untyped property from Umbraco. In this example the property is stored as umbracoExtension (That Constants class is built into Umbraco btw, dead useful!) so we are telling Ditto to map to a property matching that name.

As with the type converters there are some built in for you to use:

DittoValueResolver (Base class all resolvers inherit from.)

UmbracoDictionaryValueResolver (Grabs values from the dictionary)

UmbracoPropertyValueResolver(Maps to different property names and specifies recursion.)

As of writing there is a resolver being written that allows parsing of relations but I don’t know when that will be added to the mix.

Once mapped these properties can be called at will from in your controllers or views as you would in a standard MVC project.

Here is an example of using the As<T> method within your Razor view:

@using Our.Umbraco.Ditto @inherits UmbracoTemplatePage @{ MyTextPage textPage = Model.Content.As<MyTextPage>(); } <h1>@textPage.Title</h1> @poco.BodyText <p> <img src="@textPage.Image.Url" alt="@textPage.Image.Name" /> </p>

As you can see, it really doesn’t take much for you to create your strong typed classes. We’ve worked very hard to ensure that it is very developer friendly.

Other Cool Stuff

Ditto Ignore

For situations where you would rather that Ditto did not attempt to map a DocumentType property with one of your POCO models properties, you can use the DittoIgnore attribute:

[DittoIgnore] public Image Image { get; set; }

Now when you map your content node, the ignored property (in this example, Image) will be set as the default value for that type (in this case it’s null).

The DittoIgnore attribute is useful for when you want to construct more complex POCO models.

DittoPublishedContentModelFactory

As mentioned above (Yeah, I know there’s been a wall of text since then) Ditto offers a package that implements IPublishedContentModelFactory (Umbraco v7.1.4+) which can automate the binding process for you.

The following code demonstrates how to enable that functionality.

using Our.Umbraco.Ditto; public class ConfigurePublishedContentModelFactory : ApplicationEventHandler { protected override void ApplicationStarting(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext) { var types = PluginManager.Current.ResolveTypes<PublishedContentModel>(); var factory = new DittoPublishedContentModelFactory(types); PublishedContentModelFactoryResolver.Current.SetFactory(factory); } }

From there all the properties of your class (including navigation properties) will be automatically mapped to your POCO.

Proxied Classes

This is one of my favourite bit’s of functionality that we’ve built into Ditto and is some of the most complicated code I have ever written. I am super proud of it and you should definitely have a wee look at the source.

A few of you will have been thinking all the while reading this article, “Well that’s all nice James, but what about performance?” and you would have been right in doing so. Converting all the properties does not come for free. However the code linked above (on top of some other super clever performance optimisation code) makes Ditto super snappy when used correctly.

If you’ve ever used Code First with Entity Framework you’ll know that they have the functionality to lazily load properties by marking the properties as virtual. I’ve always been a big fan of that functionality and now you can do the same with Ditto. (Oh freaking yeah!)

Whenever a property is found in a POCO class that is marked virtual Ditto will switch to lazy loading mode. Instead of your POCO being returned, a new proxy class, dynamically generated in memory that inherits your class is returned instead. At runtime this is treated as if it was your POCO class but internally the dynamic proxy class has overridden all your virtually marked properties with versions that are intercepted and lazily invoked using the Lazy<T> class.

If we had marked the Image property as virtual in our class above the output proxy class generated at runtime would look something like this.

public class MyTextPageProxy : MyTextPage, IProxy { private IInterceptor interceptor; public MyTextPageProxy(IPublishedContent content) : base(content) { } public override int get_Image() { IInterceptor interceptor = ((IProxy)this).Interceptor; if (interceptor == null) { throw new NotImplementedException(); } return (Image)interceptor.Intercept(MethodBase.GetMethodFromHandle(typeof(MyTextPage).GetMethod("get_Image").MethodHandle), null); } public override void set_Image(Image image) { IInterceptor interceptor = ((IProxy)this).Interceptor; if (interceptor == null) { throw new NotImplementedException(); } interceptor.Intercept(MethodBase.GetMethodFromHandle(typeof(MyTextPage).GetMethod("set_Image", new Type[] { typeof(Image) }).MethodHandle), image); } public virtual IInterceptor Our.Umbraco.Ditto.IProxy.Interceptor { get { return this.interceptor; } set { this.interceptor = value; } } }

If that isn’t the coolest thing you’ve seen code-wise in a while I envy you and want to see what you’ve been working on.

You don’t have to worry about that complexity at all with Ditto