Lars-Erik's blog

Morphing UCommerce Products

Tue, 30 Jan 2018 23:48:27 Z

The problem

Today I had a new but fun challenge with UCommerce. Turns out, as usual, it's a great fit for my whims with architecture. I was stuck between a rock and a hard place when I was looking at adding a custom pricing algoritm. I can't go into details, but there's custom client pricing involved of course. To add to the fun, we're mapping UCommerce products to DTOs for wire transfer. We could aslo have been mapping to view models or something else. To map we're using AutoMapper with quite a few configurations and jumps-through-hoops.

I had this code (ish):

var products = productRepository.Select().Where(SomePredicate);
var mapped = products.Select(Mapper.Map<ProductDto>);
return mapped;

I immediately thought of a few options:

Iterate over the products and change prices here
Create a Product adapter with additional logic and map from that
Execute the pricing logic from AutoMapper configuration

They all seemed weird and out of place though. None seemed like they would be easy to find for the next developer. Not even with unit tests. It just didn't seem right. Changing data on the entities would mean I'd have to go out of my way to ensure nobody went and saved those products later in the request. Creating an adapter would mean loads of new instances, bloated wrapper classes and weird names. And finally executing business logic from AutoMapper configuration means I'd been mixing responsibilities en mass.

UCommerce & NHibernate to the rescue

Luckily I've been using EntityFramework a lot and tried to force it into my Domain Driven Design patterns since it's infancy. I've been through the lot (and I enjoy it). So I kind of know what to expect from an ORM. When using UCommerce I'm stuck with NHibernate, but I haven't really been doing it justice by just leaving it in the background. (And fiddling with Entity Framework - which is just as good!) Together the two systems are extremely powerful. UCommerce have even documented the possibilities, though the documentation fails to point out the really juicy benefits.

We have ProductDefintion, right? It allows us to set up product types with different properties and variant options. It even supports inheritance. But we're still stuck with the Product class and its GetProperty() overrides. In my case, I'd like to have ProductWithFancyPricing so I could override that GetPrice() method. If I could have ProductWithFancyPricing and ProductWithEvenFancierPricing that would be totally awesome.

Turns out you can have your cake and eat it too. When properly using an ORM you can exploit OOP like it's supposed to and use polymorphism for varying behavior. It's possible to set up an inheritance tree so the mapper automatically handles creation of different types for you. You've basically got three options:

Table per concrete class (type)
- All classes have a table of their own
- Useful when base classes don't have (much) data
Table per hierarchy
- One table per base class
- Useful when all data is on the base class
Table per subclass
- One common table for base data
- Individual tables per derived class with only additional data
- Useful when there are some data in both classes. (Think umbracoNode)

In my case, I don't need any new data on the derived classes. It's all there in GetProperty() anyway. (I will add some getters though. ModelsBuilder, anyone? )
So for me it's going to be Table per hierarchy. The rest of the options are all viable for this technique if you have other requirements. You can read a bit about it in the UCommerce docs.

Mapping some product types

(I inadvertently wrote document types there. ModelsBuilder, anyone?)

In order to have NHibernate treat products as subclasses with the Table per hierarchy strategy it needs a way to pick the right class for each record. That way is known as discriminator columns. I first thought I could just discriminate by the ProductDefinitionId, but it turns out NHibernate doesn't support discriminating on a column already in use for associations (foreign keys) or other means.
We have to add a column. I just call it "Discriminator" and make it a varchar.

alter table uCommerce_Product add Discriminator nvarchar(max)

Then we need some entities. I added a couple of docu... product types:

public class ProductWithFancyPricing : UCommerce.EntitiesV2.Product
{
    public override Money GetPrice(PriceGroup priceGroup)
    {
        var price = base.GetPrice(priceGroup);
        if (IsChristmas())
        {
            price = new Money(price.Value * 2, price.Culture, price.Currency);
        }
        return base.GetPrice(priceGroup);
    }
}

public class ProductWithEvenFancierPricing : UCommerce.EntitiesV2.Product
{
    public override Money GetPrice(PriceGroup priceGroup)
    {
        var blackMarket = ObjectFactory.Instance.Resolve<IBlackMarketService>();
        var priceValue = blackMarket.GetPrice(Sku);
        return new Money(priceValue, priceGroup.Currency);
    }
}

The next thing you need is to tell NHibernate that these are our new product classes:

public class ProductWithFancyPricingMapping : FluentNHibernate.Mapping.SubclassMap<ProductWithFancyPricing>
{
    public ProductWithFancyPricingMapping()
    {
        DiscriminatorValue("Product with fancy pricing");
    }
}

public class ProductWithEvenFancierPricingMapping : FluentNHibernate.Mapping.SubclassMap<ProductWithEvenFancierPricing>
{
    public ProductWithEvenFancierPricingMapping()
    {
        DiscriminatorValue("Product with naughty pricing");
    }
}

We also need to subclass UCommerce's mapping for Product in order to tell UCommerce which column to use as the discriminator:

public class ProductMap : global::UCommerce.EntitiesV2.Maps.ProductMap
{
    public ProductMap()
    {
        DiscriminateSubClassesOnColumn("Discriminator");
    }
}

Finally we need a class in the same assembly with a tag on it. More on that in the UCommerce docs.

public class MappingMarker : IContainsNHibernateMappingsTag
{
}

To have NHibernate pick the right classes now, we just need to fix the existing products if we have any. I have called my discriminator values the same as my document types, so I can easily construct a query as such:

update
    ucommerce_product
set 
    discriminator = case productdefinitionid
        when 10 then 'Product with fancy pricing'
        when 11 then 'Product with naughty pricing'
        else null
    end

Now if we go...

var products = productRepository.Select();

...we'll get a bounch of ProductWithFancyPricings and ProductWithEvenFancierPricing. If you have more types, you might get into trouble though. You need to have a discriminator on them all.

The final hurdle

So that's cool. That's really cool. But there's one hurdle we have to jump over before we can cross the goal line. From very nasty experiences I knew I had to test everything manually and integrated. So I went and tried to see what happened if I added a product through the UCommerce Admin UI.

boom :)

'Course it didn't work. It actually did, and didn't. Several weird things happened ranging from strange NHibernate mapping exceptions to products getting the discriminator "UCommerce.EntitiesV2.Product". (Which makes a lot of sense if you think about it)

The @#¤%& CreateCategoryOrProduct.as[p|c]x WebForms control is in our way. It instantiates a Product and saves it. It's completely sealed and unconfigurable. We could overwrite it with a custom one, but that would open another can of worms with regards to upgrading, source control and what-not. Luckily it's going away very very soon in UCommerce V8. (2018?)

After hacking at it a bit my final resolve was to add a step right after save in the product saving pipeline. Again, UCommerce is so versatile that even when it sucks, it's got a golden workaround right up its arm. If you're not familiar with UCommerce Pipelines, go read about it here.

Here's the extra configuration. (In a .config file included from UCommerce's custom.config)

<!-- PRODUCT CLASS FIX -->
<component id="SaveProduct"
           service="UCommerce.Pipelines.IPipeline`1[[UCommerce.EntitiesV2.Product, UCommerce]], UCommerce"
           type="UCommerce.Pipelines.Catalog.ProductPipeline, UCommerce.Pipelines">
  <parameters>
    <tasks>
      <array>
        <value>${Product.UpdateRevision}</value>
        <value>${Product.Save}</value>
        <value>${FixProductClass}</value>
        <value>${Product.IndexAsync}</value>
      </array>
    </tasks>
  </parameters>
</component>

<component id="FixProductClass"
           service="UCommerce.Pipelines.IPipelineTask`1[[UCommerce.EntitiesV2.Product, UCommerce]], UCommerce"
           type="My.Awesome.Site.Persistence.FixProductClassTask, My.Awesome.Site.UCommerce"/>

A pipeline task gets a reference to the entity being handled, so we can't just go and replace the entire product with an instance of the right type. But we can fake it and force the database value to be correct after saving. UCommerce uses NHibernate level 2 cache, so we need to flush that as well, but we'll get to that.

Forcing the database is fairly easy. We have to resort to good old ADO code, which was actually a joyful little deja-vu experience (although I'm glad it was brief):

public class FixProductClassTask : IPipelineTask<Product>
{
    private readonly IStatelessSessionProvider sessionProvider;

    public FixProductClassTask(IStatelessSessionProvider sessionProvider)
    {
        this.sessionProvider = sessionProvider;
    }

    public PipelineExecutionResult Execute(Product subject)
    {
        var command = sessionProvider.GetStatelessSession().Connection.CreateCommand();
        command.CommandText = "UPDATE uCommerce_Product SET Discriminator = @discriminator WHERE ProductId = @productId";
        command.CommandType = CommandType.Text;
        var discriminatorParam = command.CreateParameter();
        discriminatorParam.ParameterName = "discriminator";
        discriminatorParam.Value = subject.ProductDefinition.Name;
        var idParam = command.CreateParameter();
        idParam.ParameterName = "productId";
        idParam.Value = subject.Id;
        command.Parameters.Add(discriminatorParam);
        command.Parameters.Add(idParam);
        command.ExecuteNonQuery();

        // TODO: Clear cache

        return PipelineExecutionResult.Success;
    }
}

I'm sure a lot of sazzy devs out there could prettify this a bit, but it does the job. Insert a switch/case (please don't) or whatever you fancy if the product definition name isn't what you discriminate by. I'll leave it up to you to choose between strings, ints or even enums for performance vs. readability.

If you've turned off the level 2 cache, you might be fine with this. Otherwise we'd better "evict" the entity from the cache. We need to do that in order for the cached instance to change type from Product to ProductWithFancyPricing. Sadly the NHibernate SessionFactory in charge of doing this is hidden in an internal static field in UCommerce, so we need to resort to some nasty reflection to do it:

// ...
command.ExecuteNonQuery();

var fieldInfo = typeof(SessionProvider).GetField("_factory", BindingFlags.Static | BindingFlags.NonPublic);
if (fieldInfo == null) throw new Exception("SessionFactory instance has moved in this UCommerce version. %(");
var sessionFactory = (ISessionFactory)fieldInfo.GetValue(null);
sessionFactory.Evict(typeof(Product), subject.Id);

return PipelineExecutionResult.Success;
// ...

Et voilá! We can now save new products, and they immediately morph into the correct derived type. (Except for when being saved to RavenDB for the first time, ref. the config).

I'm now free to go back into the instances and implement however naughty pricing I fancy. \o/

Added bonuses

I already have a custom entity in the database and NHibernate model. It has two associations to Product. Had I realized what I had under my fingertips it would already have been collections on my new shiny subclasses.

I recon you noticed I referenced ModelsBuilder a couple of times. How 'bout having all your properties statically typed on your product instances. How about some interfaces?

I'm sure you're getting the drift.

I for one am quite embarrased I didn't think of this before. I've had the knowledge and tools for years. But there you go. We learn something every day. And I love doing it with Umbraco, UCommerce, EntityFramework and apparently now also... NHibernate. :)

UmbracoSupport got typed content

Tue, 17 Oct 2017 21:18:06 Z

What's UmbracoSupport?

UmbracoSupport is a class I've been introducing to my unit tests over the last year or so. It allows me to have my own hierarchy for tests, as well as re-using all of Umbraco's own stubbing code. I've written about it in a post called Unit testing Umbraco just got simpler, and its gut's code is described in details in The basics of unit testing Umbraco.

A quick primer on what's already available

The BaseDatabaseFactoryTest in Umbraco.Tests has a method called GetXmlContent. It replaces the umbraco.config file that acts as the cache at runtime. It makes UmbracoContext.Current.ContentCache tick in unit tests. The base tests out of the box has a small flaw though. They can't "popuplate" properties. All you get is the hierarchy.

Usually I've injected an IPublishedContentCache to my controllers. When testing them, I've created a mock instance of the IPublishedContentCache. However, all my code has to use the non-context aware overloads. For instance cache.GetById(umbracoContext, false, id). There's also a whole lot of ugly mocking code going on to set up queries and stubbed content. How to stub properties on stubbed content is described in Slides from CG 2016 and testing IPublishedContent properties.

So what's new?

As mentioned, I've been throwing around all kinds of ugly stubbing code for content and I've also been tampering with Umbraco.Tests's GetXmlContent() to use the "built-in" content stubs. It's all been done before in misc. tests in Umbraco. I finally got my s**t together and refactored all my setup spaghetti into a few small helpers on the UmbracoSupport class.

Let's go over them in increasing "integrationness".

Pure hierarchy

Your basic hierarchy structure can be set up by simply returning a string from an overload of BaseDatabaseFactoryTest.GetXmlContent. UmbracoSupport overloads this method and returns whatever you've set on the UmbracoSupport.ContentCacheXml property. I recommend using the technique described in Automating creating of source data for tests with this. You can even extend that code to have fixture specific content caches.

In any case, to make this work, you just need to set the XML in the setup method.

Note: I've got some probs with the markdown parsing here, imagine the CDATA parts of the XML is correctly written.

[SetUp]
public void Setup()
{
    umbracoSupport = new UmbracoSupport();
    umbracoSupport.SetupUmbraco();

    // This XML is what the ContentCache will represent
    umbracoSupport.ContentCacheXml = @"
        <?xml version=""1.0"" encoding=""utf-8""?>
        <!DOCTYPE root [
          <!ELEMENT contentBase ANY>
          <!ELEMENT home ANY>
          <!ATTLIST home id ID #REQUIRED>
          <!ELEMENT page ANY>
          <!ATTLIST page id ID #REQUIRED>
        ]>
        <root id=""-1="""">
          <home id=""1103="""" key=""156f1933-e327-4dce-b665-110d62720d03="""" parentID=""-1="""" level=""1="""" creatorID=""0="""" sortOrder=""0="""" createDate=""2017-10-17T20:25:12="""" updateDate=""2017-10-17T20:25:17="""" nodeName=""Home="""" urlName=""home="""" path=""-1,1103="""" isDoc="""" nodeType=""1093="""" creatorName=""Admin="""" writerName=""Admin="""" writerID=""0="""" template=""1064="""" nodeTypeAlias=""home="""">
            <title>Welcome!</title>
            <excerptCount>4</excerptCount>
            <page id=""1122="""" key=""1cb33e0a-400a-4938-9547-b05a35739b8b="""" parentID=""1103="""" level=""2="""" creatorID=""0="""" sortOrder=""0="""" createDate=""2017-10-17T20:25:12="""" updateDate=""2017-10-17T20:25:17="""" nodeName=""Page="" 1="""" urlName=""page1="""" path=""-1,1103,1122="""" isDoc="""" nodeType=""1095="""" creatorName=""Admin="""" writerName=""Admin="""" writerID=""0="""" template=""1060="""" nodeTypeAlias=""page="""">
              <title>Welcome!</title>
              <excerpt>[CDATA[Lorem ipsum dolor...]]</excerpt>
              <body>
                [CDATA[<p>Lorem ipsum dolor...</p>]]
              </body>
              <image>123</image>
            </page>
            <page id=""1123="""" key=""242928f6-a1cf-4cd3-ac34-f3ddf3526b2e="""" parentID=""1103="""" level=""2="""" creatorID=""0="""" sortOrder=""1="""" createDate=""2017-10-17T20:25:12="""" updateDate=""2017-10-17T20:25:17="""" nodeName=""Page="" 2="""" urlName=""page2="""" path=""-1,1103,1123="""" isDoc="""" nodeType=""1095="""" creatorName=""Admin="""" writerName=""Admin="""" writerID=""0="""" template=""1060="""" nodeTypeAlias=""page="""">
              <title>More welcome!</title>
              <excerpt>[CDATA[More lorem ipsum dolor...]]</excerpt>
              <body>[CDATA[Even more lorem ipsum dolor...]]</body>
              <image>234</image>
            </page>
          </home>
        </root>
    ".Trim();
}

In our tests, we can now query by anything. The returned content has the hierarchy and everything, so we can traverse it with Children(), Parent() and whatnot. The only missing piece is the properties. Here's a test showing that we have everything but the title property of Page 1:

const int Page1Id = 1122;

[Test]
public void Returns_Empty_Documents()
{
    var contentCache = umbracoSupport.UmbracoContext.ContentCache;
    var page1 = contentCache.GetById(Page1Id);

    Assert.That(page1, Is
        .Not.Null
        .And
        .InstanceOf<PublishedContentWithKeyBase>()
        .And
        .Property("Name").EqualTo("Page 1")
        .And
        .Matches<IPublishedContent>(c => c["title"] == null)
        .And
        .Property("Parent")
            .Property("Children")
                .With.Count.EqualTo(2)
    );
}

Don't be discouraged though. This method is excellent for testing URL providers, ContentFinders, Menus, Sitemaps. You name it. I know I've written my fair share of hierarchy traversing code or fancy XPath queries. Unless of course, you need property values.

Instead of pulling your leg about it, here's how we fix that.

Put some meat on the content

The reason the properties are not there isn't because they weren't read. It's because the XmlPublishedContent that we get out ultimately relies on the PublishedContentType for it's respective document type. Luckily, all Umbraco's services are already stubbed up for us, so we can give it what it needs.

The gory guts of it is that it needs an IContentType from the ContentTypeService. We can easily stub one up with Moq: var contentType = Mock.Of<IContentType>(). Further, it uses the IContentType.CompositionPropertyTypes collection to iterate the properties. These PropertyType instances are actually completely dependency-less, so we can just create some:

Mock.Get(contentType)
    .Setup(t => t.CompositionPropertyTypes)
    .Returns(new[] {
        new PropertyType("Umbraco.TinyMCEv3", DataTypeDatabaseType.Nvarchar, "body")
    });

Finally, we set it up on the ContentTypeService stub:

Mock.Get(umbracoSupport.ServiceContext.ContentTypeService)
    .Setup(s => s.GetContentType(alias))
    .Returns(contentType);

If only it were so easy. We depend on the BaseWebTest class from Umbraco.Tests. It sets up a content type factory that's being used somewhere in the hierarchy. It feeds AutoPublishedContent instances instead of what we've stubbed up. We need to turn that off. There's a trick here. UmbracoSupport should now live in an assembly called Umbraco.UnitTests.Adapter. If you're pre 7.6.4 you need to go with Umbraco.VisualStudio. This is because the factory we need to reset is internal to Umbraco. By having UmbracoSupport in an assembly with one of these two names, we're able to do it. (Otherwise, you use reflection.) By no means do this with production code. Just... forget it!
This paragraph should also get it's own blog post. :)

But I digress. Here's the line you need to have the content use the ContentTypeService to fetch its type:

PublishedContentType.GetPublishedContentTypeCallback = null;

It's tempting to leave setup code like this lying around in all our SetUp methods or even in our "Arrange" sections. I've sinned too much, so those few lines are now part of UmbracoSupport and can be used to set up multiple types for your fixture or test.

Here's a test that fetches the same document as before, but can now read properties:

[Test]
public void With_DocumentTypes_Setup_Returns_Full_Blown_Documents()
{
    umbracoSupport.SetupContentType("page", new[]
    {
        new PropertyType("textstring", DataTypeDatabaseType.Nvarchar, "title"),
        new PropertyType("textarea", DataTypeDatabaseType.Nvarchar, "excerpt"),
        new PropertyType("Umbraco.TinyMCEv3", DataTypeDatabaseType.Nvarchar, "body"),
        new PropertyType("media", DataTypeDatabaseType.Integer, "image")
    });

    var page1 = contentCache.GetById(Page1Id);

    Assert.Multiple(() =>
    {
        Assert.That(page1["title"], Is.EqualTo("Welcome!"));
        Assert.That(page1["excerpt"], Is.EqualTo("Lorem ipsum dolor..."));
        Assert.That(page1["body"].ToString(), Is.EqualTo("<p>Lorem ipsum dolor...</p>"));
        Assert.That(page1["image"], Is.EqualTo(123));
    });
}

Notice the .ToString() on the body. It's actually not a string, but some weird dynamic Umbraco thingy. I never saw that type before, but I didn't pursue it in time for this post. I don't want anything to do with it though, so let's storm on to the grand finale.

Let's make them strong already!

We're finally there. The last piece of the puzzle. Strongly typed content!

It's managed by two resolvers: PublishedContentModelFactoryResolver and PropertyValueConvertersResolver. I won't go into details about those now, but suffice to say all resolvers have to be initialized before BaseWebTest.Initialize and its ancestors. I've added an InitializeResolvers method to the UmbracoSupport class where these two are initialized. The PublishedContentModelFactoryResolver is set to a FakeModelFactoryResolver that lets you register constructors for document type aliases. The code for this is available in my "Umbraco unit testing samples" repo on github.

To set up property value converters, we also need to do that before registering the resolver. The resolver takes all the converters as constructor arguments. I've added a list of those types as a property on UmbracoSupport, so we can add IPropertyValueConverter implementing types before calling UmbracoSupport.SetupUmbraco:

[SetUp]
public void Setup()
{
    umbracoSupport = new UmbracoSupport();

    // Converter types need to be added before setup
    umbracoSupport.ConverterTypes.Add(typeof(TinyMceValueConverter));

    umbracoSupport.SetupUmbraco();

    //...
}

To register the typed model, there's just one line you can do in your setup, or even in your tests. Here I've refactored out the setup for the content type from earlier, and I register a model type for the document type alias:

private void SetupContentType()
{
    umbracoSupport.SetupContentType("page", new[]
    {
        new PropertyType("textstring", DataTypeDatabaseType.Nvarchar, "title"),
        new PropertyType("textarea", DataTypeDatabaseType.Nvarchar, "excerpt"),
        new PropertyType("Umbraco.TinyMCEv3", DataTypeDatabaseType.Nvarchar, "body"),
        new PropertyType("media", DataTypeDatabaseType.Integer, "image")
    });
}

[Test]
public void With_DocumentTypes_And_Models_Setup_Returns_Fully_Functional_Typed_Content()
{
    SetupContentType();

    // Register strongly typed models with the ModelFactory
    umbracoSupport.ModelFactory.Register("page", c => new Page(c));

    var page1 = contentCache.GetById(Page1Id);

    Assert.That(page1, Is
        .InstanceOf<Page>()
        .And.Property("Body")
            .Matches<IHtmlString>(s => 
                s.ToString() == "<p>Lorem ipsum dolor...</p>"
            )
    );
}

public class Page : PublishedContentModel
{
    public Page(IPublishedContent content) : base((IPublishedContentWithKey)content)
    {
    }

    public string Title => Content.GetPropertyValue<string>("title");
    public string Excerpt => Content.GetPropertyValue<string>("excerpt");
    public IHtmlString Body => Content.GetPropertyValue<IHtmlString>("body");
    public int Image => Content.GetPropertyValue<int>("image");
}

There you go! There's nothing more to it. Well, there is...

The Page class here is bundled with the test. If we use a common interface both for our runtime model and our test model, we're safe. But we should really use the runtime models. This means you shouldn't use runtime generated models. Go through the instructions for ModelsBuilder to have your models compiled and accessible from the tests.

Conclusion

And although the XML is pretty ugly, you can flush it out into files bundled with your tests. You can also exploit the umbraco.config file and just copy segments from there into your test source files. That way, you spend no time writing the stubs, and the content is cleanly separated from your tests.

That's really all there is to it! It is. Now go test a bit, or a byte, or a string, or even a view.

The new version of UmbracoSupport including the fake model factory is available here.

Marrying Ditto with ModelsBuilder

Sat, 05 Nov 2016 17:00:29 Z

I was happy to be allowed to speak at this years Umbraco UK Festival.
The topic was based on my previous post where I compare Ditto and ModelsBuilder. While preparing for that talk, I couldn't help but notice that the tools and techniques aren't mutually exclusive at all. On the contrary, they can compliment each other in a really nice way.
Slides and video from presentation linked further down.

I won't dive into too many details in this article, I recommend you read the previous article, and take a swim through the code at the github repository.

Cleaning up the processors

In the Dittoified TXT site Matt Brailsford made, we saw a bunch of processors querying the hierarchy. In my Modelsbuilderified version, we do nice and clean domain oriented queries.

Take for instance the top navigation on the site, where we look up all the visible children of the home page. The Ditto processor looks as such:

public class MainNavAttribute : DittoProcessorAttribute
{
    public override object ProcessValue()
    {
        var content = Value as IPublishedContent;
        if (content == null) return Enumerable.Empty<NavLink>();

        var homePage = content.AncestorsOrSelf(1).First();
        return new[] { homePage }.Union(homePage.Children.Where(x => x.IsVisible()));
    }
}

With ModelsBuilder, we point to the homepage from the base document type, and implemented the navigation items query on the homepage:

public partial class UmbHomePage
{
    IEnumerable<INavigationContent> INavigation.MenuItems
    {
        get
        {
            return new[] { this }
                .Union(
                    Children
                    .OfType<INavigationContent>()
                    .Where(c => c.IsVisible)
                );
        }
    }
}

What we keep forgetting though, is that the ModelsBuilder models are created before the content leaves the cache. If we install Ditto in the ModelsBuilderified version, or vice versa, we can actually use that MB query in the processor. Whether we'd like to keep the query and interface segregation on our ModelsBuilder classes, or we'd like to put most logic in the Ditto processors is still a matter of taste.

However, by just letting MB generate its models in the Dittoified project, not writing one single interface, we can refactor the MainNavAttribute as such:

public class MainNavAttribute : DittoProcessorAttribute
{
    public override object ProcessValue()
    {
        var content = Value as IPublishedContent;
        if (content == null) return Enumerable.Empty<NavLink>();

        var homePage = content.AncestorOrSelf<UmbHomePage>();
        return new[] { homePage }.Union(homePage.Children.Where(x => x.IsVisible()));
    }
}

The same can be done to the BaseNewsProcessorAttribute with even more "domain language":

public abstract class BaseNewsAttribute : DittoProcessorAttribute
{
    protected IEnumerable<UmbNewsItem> GetNews()
    {
        var content = Value as UmbMaster;
        if (content == null) return Enumerable.Empty<UmbNewsItem>();

        var newsArchive = content.Home.FirstChild<UmbNewsOverview>();
        if (newsArchive == null) return Enumerable.Empty<UmbNewsItem>();

        return newsArchive.Children<UmbNewsItem>()
            .OrderByDescending(x => x.DisplayDate);
    }
}

You'll notice I've added the DisplayDate implementation to UmbNewsItem so we don't need to think about the PublishDate and CreateDate properties every time we do ordering.

Where to start

I'd recommend that if you don't use either tool today, you should really just start using ModelsBuilder. It will improve your code immensly over using magic strings, level-based queries and all that comes with the basic IPublishedContent implementation. When you start to see that you want more separation of concerns and interfaces don't do that for you, look into adding Ditto on top.

Serialization

The main pain point of using ModelsBuilder today is that IPublishedContent implementations lend themselves badly to serialization. Serializing it without care will lead to cyclic references and/or super big graphs of parents and children.

By mapping the content to POCOs with Ditto, you don't have to care about this.

Strike a balance

In my opinion, one can go way too far with the processors in Ditto. Separation of concerns is good, but not at the cost of having to wade through 10-20 classes for one coherent piece of functionality.

The same can be said about ModelsBuilder. Creating too many compositions, adding to many interfaces, creating too many extensions can be just as overwhelming.

It basically boils down to the good old YAGNI principle.

Further exploration

The examples in this article is avaiable in a branch on GitHub.
I also did a presentation comparing the two tools, and marrying them at last at this years Umbraco UK Festival.
The presentation can be seen on YouTube.
The slides from the presentation are available here.

Getting real business value from strongly typed models in Umbraco

Sun, 08 May 2016 19:02:56 Z

Unmasking "Code First"

There was a thread on twitter the other day where someone had asked someone about "Code First" in Umbraco. "Code First" has been something like a holy grail for many developers, including me. The thread ended with a conclusion that nobody wants it. But that discussion reminded me of something. how my own attempts at "round-trip engineering" document types in Umbraco just faded. I even made a tool that does it, but neither did it get many users, nor did I actually use it for "Code First" myself. What I used my tool for was generating strongly typed models for Umbraco, and all the benefits it brings.

With Umbraco 7.4, Umbraco ModelsBuilder is now built-in to Umbraco. It does what my tool does, and is now available to all Umbraco developers with the flip of an appSetting. If you'd like to tag along with this article, you should make sure it's set to PureLive mode.

So what does generated strongly typed models enable us developers (and designers) to do? Ignoring the elevator answer "IntelliSense and compiler errors when we make a typo". Why would you use this, unless you're one of those guys who come back from conventions full of "good ideas"? Turns out it opens up a plethora of useful techniques to use and squeeze for value. Business value!

Not only that! By leveraging compositional document types, you actually may do a kind of "Code First".
There's only thing associated with "Code First" that you won't get. It is something that updates the document models in Umbraco, based on your code.

But why would you want that? There's an excellent UI that lets you annotate and describe all the fields for the editors. You also get to preview the editor experience. And you get to configure stuff using well crafted tools.

Coding your document types would mean messing around with loads of ugly metadata attributes. In the end your business artifacts would drown in irrelevant data. Not to mention you'd have to remember all the bloody editor aliases and types and everything.

Real value, with a sprinkle of code first on top

So how do we use these techniques, and how do we get value from them?

Some of you are probably familiar with the SOLID programming principles. Leveraging the I and the D is what gets things going with typed models. The I stands for "Interface Segregation" and the D stands for "Dependency Inversion".

The Dependency Inversion principle states that you should depend on abstractions, not on concretions. In the "typed model world" it means that you don't use instances of the generated type Article. You code against an interface IArticle said class implements. You can also one of the compositions the document type is built from.

The Interface Segregation principle states that you should make fine grained interfaces that are client specific. Again, in a "typed model world" this can be applied as "compose your document types of several types, each relevant for a specific use in the site".

Let's have a look at how we can extract value from these patterns. We'll try to apply it to a simple feature most of us have in all our sites.

Prototyping

With all sites, I'm sure we promote some content in a more or less generic way. While prototyping and wireframing we sketch it. We use static HTML, PowerPoint or some other tool.

What if we could already prepare a Razor file that would still work when the site is live? Before we even set up the Umbraco site. With or without Umbraco, you can quickly create what you need to get started. Just to really prove the point that we're prototyping here, let's just start with a view:

// ~/Views/Partials/Promotion.cshtml
<div class="promotion">
    <a href="/promoted-content">
        <img src="/media/1001/fancy-picture.jpg" />
        <h2>Lorem Ipsum</h2>
        <p>More lorem ipsum with sugar on top.</p>
    </a>
</div>

So that's more or less what we've imagined we're gonna use for promotions for now. Maybe we'll add a col-md-x later, but for now, the HTML is good. Of course it can't stay like that. We need to show some Umbraco data. So we need a model to bind to. It could be an IPublishedContent, or it could be a dynamic object like before. However, the markup would prabably be ugly, and either way you'd need to remember all the aliases. I'll just remind you before we continue:

<h2>@(Model.Content.GetPropertyValue<IHtmlString>("summray"))</h2>

We need something to help us out. So we create an interface:

// ~/Models/IPromotable.cs
namespace YourWeb.Models
{
    public interface IPromotable
    {
        string Title { get; }
        object Image { get; }
        IHtmlString Summary { get; }
        string Url { get; }
    }
}

Now we can revisit the view and use some @ markup without getting complaints from our IDE. If you type this, you'll even get help along the way:

// ~/Views/Partials/Promotion.cshtml
@model YourWeb.Models.IPromotable
<div class="promotion">
    <a href="@Model.Url">
        <img src="@Model.Image" />
        <h2>@Model.Title</h2>
        <p>@Model.Summary</p>
    </a>
</div>

Now it's actually in a form where it doesn't have to change at all until the requirements actually change.
But we haven't viewed it yet. Let's do that too without bringing Umbraco into the picture.
We'll create a simple controller:

// ~/Controllers/PrototypingController.cs
public class PrototypeController : Controller
{
    public ActionResult Promotion()
    {
        return View(
            "~/Views/Partials/Promotion.cshtml",
            new Promotable
            {
                Title = "Here's a fake promotable",
                Image = "/media/1001/fancy.jpg",
                Summary = new HtmlString("<p>Fancy markup</p>"),
                Url = "/fancy-url"
            }
        );
    }

    class Promotable : IPromotable
    {
        public string Title { get; set; }
        public object Image { get; set; }
        public IHtmlString Summary { get; set; }
        public string Url { get; set; }
    }
}

I'll let the simplicity of the code speak for itself.

To actually get to run and view this, we just need one more step.
Depending on whether you've installed Umbraco, used an MVC template or have a blank project, we need to get the route configured. I say we bring Umbraco into the picture now. We can still prototype peacefully alongside it.
Above or below the PrototypeController, just add a simple ApplicationEventHandler:

public class PrototypeRouting : ApplicationEventHandler
{
    protected override void ApplicationStarted(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext)
    {
        RouteTable.Routes.MapRoute("prototyping", "prototype/{action}", new { controller = "Prototype" });
    }
}

Now build, and navigate to:
http://localhost:nnnn/prototype/promotion

You should see something like:

Here's a fake promotable

Fancy markup

So we've got a live Razor view with a server-side model. This is a simple sample, but imagine modifying or adding to the model. Imagine using logic in your view (or controller) to test different behavior.

Now let's boot up Umbraco and add some real content. We'll create a re-usable composition type called Promotion to match our partial.

Name	Property Editor
Title	Textstring
Image	Image picker
Summary	Rich text editor

Then we'll create a promotable Article type to use as our first real content type. Make it usable on root for our current purposes. Add Promotable as a composition.

Name	Property Editor
Body	Rich text editor

Go ahead and create one article while you're at it. It should get the URL "/".

Now if you go back to your project and have a look in the ~/App_Data/Models folder, you'll see that there's a few generated files there.
You've got all.generated.cs, models.generated.cs and models.hash. Go ahead and open the models.generated.cs file. This code is actually being compiled at runtime and loaded into your application. Now look closer at the (hopefully) top type. It's a partial interface called IPromotable. Does it look familiar?

Add a file to the ~/App_Data/Models folder:

namespace Umbraco.Web.PublishedContentModels
{
    public partial interface IPromotable : YourWeb.Models.IPromotable
    {
    }
}

Now go over to the Article.cshtml template Umbraco generated for you in the ~/Views folder. Add a line to it:

@inherits UmbracoTemplatePage<ContentModels.Article>
@using ContentModels = Umbraco.Web.PublishedContentModels;
@{
    Layout = null;
}
@Html.Partial("Promotion", Model.Content) // < this one

Don't even care to build. Navigate to http://localhost:nnnn.

You should see something similar to this:

Here's a real promotable

Here's some real markup.

Seem familiar? It's our prototype view! Unchanged! And it's working with real Umbraco content!

( If you've gotten this far you're probably swearing at me for putting an integer in the image source attribute. To the best of my knowledge, there's a lack of good built-in property value converters for images. I'll leave it up to you as an excercise to figure out how to expose a URL. )

We showed the promotion on the content itself now, but in the real world, we'd probably be using it from the front-page or some area node in our web. Well, there's not much to that. If you'd like to show anything that has the composition Promotable now, you'll just query for it:

@Html.Partial("promotion", Umbraco.TypedContent(Model.Content.PromotedId))

You might have to check for the type, though, but let's not think about that yet.

Re-using our logic

So how about keeping this HTML snippet and promotional logic around for the next web that needs promoted content?
We'll need to move the code out of the site itself. (I'll assume you're using Visual Studio from now)
For now, create a new Class Library project in your solution. Name it something nice, personal and re-usable.
You'll also have to add a reference to System.Web.Mvc.
Move the IPromotable interface over to that project and adjust its namespace.

namespace YourReusableLibrary
{
    public interface IPromotable
    {
        string Title { get; }
        object Image { get; }
        IHtmlString Summary { get; }
        string Url { get; }
    }
}

Let's also be so naive to believe we'll never change the markup of a promotion.
Create another class in the library called PromotableExtensions:

public static class PromotableExtensions
{
    public static IHtmlString Promotion(this IPromotable promotable)
    {
        return String.Format(@"
            <div class=""promotion"">
                <a href=""{0}"">
                    <img src=""{4}"" />
                    <h2>{2}</h2>
                    <p>{3}</p>
                </a>
            </div>
            ",
            promotable.Url,
            promotable.Image,
            promotable.Title,
            promotable.Summary
            );
    }
}

Let's go back to our partial again. It can now be modified as follows:

@model YourWeb.Models.IPromotable
@using YourReusableLibrary
@this.Promotion()

That's it! I'd say we'll just scrap it and revisit the article view:

@inherits UmbracoTemplatePage<ContentModels.Article>
@using ContentModels = Umbraco.Web.PublishedContentModels;
@using YourReusableLibrary
@{
    Layout = null;
}
@this.Promotion()

What? Right! We need to do it from our grid-editor view, property editor or whatever:

@using YourReusableLibrary
@(((IPromotable)Umbraco.TypedContent(Model.Content.PromotedItemId)).Promotion())

Bah, it's to verbose. Back to PromotableExtensions and add:

public static IHtmlString Pomotion(IPublishedContent candidate)
{
    var promotable = candidate as IPromotable;
    if (promotable != null)
        return promotable.Promotion();
    return new HtmlString("");
}

And our view:

@using YourReusableLibrary
@Umbraco.TypedContent(Model.Content.ProbablyAPromotedItemId).Promotion()

Now we have an extension that assumes we have a composition called Promotable. It assumes said promotable has a title, an image and a summary. If we call .Promotion() on any content, it'll return a nice promotion snippet if it's promotable, or blank if not. All we have to do is add the tiny partial in ~/App_Data/Models. We can re-use our logic in any site.

We made the whole thing in a "code-first" sense, and we never have to create a promotional HTML snippet again.

Now that's what I call value for coding!

Applying to "real business logic"

The example in this article is dead simple. You won't save hours with it.
However, the principles it demonstrates can be applied to almost any use-case.
Coupled with property value converters and well thought through compositional models, you create rich code that clearly states it's purpose. As well as code that is re-usable and simple.

A final point that we haven't touched upon, but is at least as valuable, is unit testing.
All the code we've written for promotional content is completely testable. It has no dependencies, except MVC for the IHtmlString, but that's also a solvable issue using the exact same principles.

With that, happy modeling, and happy "code-firsting". :)