MvcPowerTools Preview: Html Conventions

By Mike on 11 April 2014

The moment we'll all be waiting for. Well, at least I was... I know this is (was) a Fubu feature that people used with asp.net mvc, but it was simply hat a developer extracted from Fubu then glued with the asp.net mvc. Html Conventions in MvcPowerTools (MvcPT) are a first class citizen, deeply integrated with Asp.Net Mvc. So, now you can use HtmlConventions like in Fubu (well the syntax resemble but it's not 100% identical) as a 'native' asp.net mvc feature.

If you don't know what's the deal with html conventions, let me make you a very short presentation. .Net Mvc templated helpers are great but they're a bit cumbersome if you just want something more of a widget, a mini-template that can be customized in more than 1 step. And sadly the mvc's behaviour is an all or nothing affair: you either use display templates for all properties in your model and you get away with _Html.EditorForModel_ or you have to write manually for every property _Html.EditorFor(m=>m.Property)_ just to have control for one property you want to be rendered differently.

The point of html conventions is to define html rendering 'rules' that will apply to all model matching a criteria. This means you can make bulk changes just changing a few lines of code in a convention. As I've said before, it works at a widget level. It's possible but not recommended to generate ALL the html via conventions. Among the best use cases are form fields (input controls). If you're dealing with many forms and fields, html conventions are a productivity saver. Add/change a convention and all targeted controls are automatically updated. A note about testing, the deep integration with asp.net mvc is both a blessing and a curse, in order to test the conventions you have to mock at least ViewContext (which requires a ControllerContext and so on). For now it's like this, maybe in a future version I can avoid this tight coupling (I wonder if 'integrated' and 'decoupled' are compatible).

In this post I'll show you some interesting examples to show you the possibilities, it's not really meant to be a tutorial. Let's begin!

I happen to use angularjs for my mvc javscript needs and I'm using it when editing a form. So I want that every model that I annotate with [NgModel] to generate html inputs supporting anuglarjs i.e having the _ng-model_ and _ng-init_ attributes set. To define the conventions I recommend the following directory structure (each .cs file is a HtmlConventionsModule)

App_Start - Html - Display - Build.cs
				          - Modify.cs
					  - Ignore.cs		
							
			   - Editors - Build.cs
			                 - Modify.cs
					 - Ignore.cs					
							
			   - Labels  - Build.cs
				          - Modify.cs
					  - Ignore.cs					
                  

				  
     public class NgModelAttribute:Attribute
    {
         
    }
	
	//namespace App_Start.Html.Editors
	
	 public class Modify:HtmlConventionsModule
    {
       
        public override void Configure(HtmlConventionsManager conventions)
        {
            var e = conventions.Editors;
			
			 e.If(m =>
                (!m.IsRootModel && m.ParentType.HasCustomAttribute<NgModelAttribute>() &&
                 !m.HasAttribute<NoAngularAttribute>()) || m.HasAttribute<NgModelAttribute>()
                )
                .Modify((tag, m) =>
                {
                    var input = tag.FirstInputTag();
                    if (input == null) return tag;
                    var ngName = "res." + input.Attr("name").ToLower();

                    input.Attr("ng-model", ngName);

                    if (!m.ValueAsString.IsNullOrEmpty() && !m.Type.IsUserDefinedClass())
                    {
                        if (m.Type.Is<bool>())
                        {
                            input.NgInit("{0}={1}".ToFormat(ngName, m.ValueAsString.ToLower()));
                        }
                        else
                        {
                            input.NgInit("{0}='{1}'".ToFormat(ngName, m.ValueAsString.AddSlashes()));
                        }
                    }
                    return tag;
                });
				
			e.Always.Modify((tag, i) =>
            {
                var input = tag.FirstInputTag(t => t.IsHiddenInput());
                if (input == null) return tag;
                if (input.HasAttr("ng-model"))
                {
                    input.Angular("update-hidden");
                }
                return tag;
            });
        }
	}

	//Setup the conventions
	 public class ConfigTask_HtmlConventions
    {
        public static void Run()
        {
			//predefined modifiers which mimic default asp.net mvc templating behaviour
			HtmlConventionsManager.LoadModule(new DataAnnotationModifiers(), new CommonEditorModifiers(), new SemanticModifiers(), new CommonDisplayModifiers());
					
			//load all conventions defined in the assembly
			HtmlConventionsManager.LoadModules(typeof (ConfigTask_HtmlConventions).Assembly);
			
			//predefined builders for use with model annotations
			HtmlConventionsManager.LoadModule(new DataAnnotationBuilders(),new CommonHtmlBuilders());            
		}
	}

While it looks a bit scary, it's pretty simple. We check that the model is a property and the parent or the property has [NgModel] and if that's the case, we modify the supplied HtmlTag: get the input element then add the ng-model attribute with the property name (made to be angularjs compatible). Then we handle some edge cases (these come out after you're using the app). In the end, we make sure that the hidden fields are updated, by adding the update-hidden directive.

In the view the code looks like this

@Html.EditModel()
<!-- or -->
@Html.Edit(m=>m.MyProperty)

Now, any view model decorated with [NgModel] is automatically angularjs ready.

You can freely mix .Net Mvc's Html.EditorFor() and Html.Edit(), any MvcPT helper which works with properties is compatible with the default html helpers.

Let's see some Twitter Bootstrap integration. This automatically adds the classes form-control and form-group when rendering html text inputs.

e.If(m => !m.IsRootModel)
	.Modify((tag, m) =>
	{
		var input = tag.FirstInputTag();
		if (input != null && input.IsHiddenInput()) return tag;
		var type = input.Attr("type");
		if (type != "checkbox" && input.TagName()!="textarea")
		{
			input.AddClass("form-control");
		}
		return tag;
	});

	e.If(m => 
	!m.IsRootModel && !m.Type.IsUserDefinedClass() && !m.PropertyOrParentHasAttribute<InlineAttribute>())
	.Modify((tag, m) =>

		new HtmlTag("div").AddClass("form-group").Append(tag)
	);

These are example when you want to render input fields, forms but the same thing can be applied when you just want to display things. Here's a simple convention that says to render any property having [Text] as a <pre>

var d=conventions.Displays;
	
	d.If(m => m.PropertyOrParentHasAttribute<TextAttribute>())
                .Build(m =>
                {
                    return new HtmlTag("pre").Text(m.ValueAsString);
                });

Here we're building a display date time widget. Automatically, any DateTime property will be rendered with the widget.

d.ForType<DateTime>()
                .Build(m =>
                {
                    var time = m.Value<DateTime>();
                    var tag = new HtmlTag("div")
                        .AddClass("last-update")
                        .Attr("title", time.ToLocalTime())
                        .Text(string.Format("Updated {0}", DateTime.UtcNow.Subtract(time).ToHuman()));
                    return tag;
                });

In views

@Html.DisplayModel()
	@Html.Display(m=>m.Property)
	
	//want to display a defined template like asp.net mvc does, but for ANY model
	@Html.DisplayTemplate(someModel)
	
	//Now you can do this
	@foreach(var item in Model.Items)
	{
		@Html.DisplayTemplate(item)
		//or if you want to use html conventions 
		@Html.Widget(item)
	}

The cool thing here is that you don't need to create a partial (template) view for List<Bla> just to be able to use the templated html helpers.

Whoa, that's a long post already and I've only scratched the surface of what you can do with html conventions. It's a pretty big and complex feature but it can give you a LOT of power and flexibility when building your views. To give you an idea, you have support for html conventions profiles that can be changed on every request and you can define your own conventions registries besides Editor, Displays or Label (but you need to implement your own html helpers for those).

MvcPowerTools Preview: View Engine Conventions

By Mike on 8 April 2014

What I like the most from FubuMvc (RIP) is the the paradigm of 'make the framework serve you, define your own conventions that suits your style'. Simply put, you decide the way you want to structure and code an app, not some framework. Frameworks are good but they shouldn't be in your way, you shouldn't force your app to comply with the framework, it should be the framework who should comply with your approach.

Asp.Net Mvc is a good, easy to use framework but it still suffers from some 'you have to do things this way' symptoms. One example, why should I always inherit from Controller, instead of using any class and have the dependencies I want (HttpRequest, HttpResponse etc) injected? There's a lot of coupling in asp.net mvc, but this is how it is for now. I'm doing my part with MvcPowerTools to provide SOLID options for some features for when you reach the stage when you begin to fight the framework. I've already written about Routing Conventions and ActionFilters Conventions , now it's time to tackle the view engines a bit.

I'm not really a fan of "~/Views/[controller]/[action].cshtml" . It's a way to structure things but it gets tedious with many controllers and actions. Also throwing everything in Shared is not a good idea either. I like the 'Handler' approach for my controllers (i.e the controller is the action, its methods represent handlers for each supported http method) so the view name is the controller name. And I want that at least for a group of controllers to have the view in the same place as the controller. For other parts of the site, I want the views grouped into a theme/skin with no controller in sight. In a nutshell, I want to name and put my views wherever I need and sometimes that's not a predefined location (think themes, you want the user to copy the theme into directory with whatever name and the app should be able to use it).

How to achieve that with the default aps.net mvc view engine? First of all, let me tell you a little trick: a view engine in asp.net mvc is actually a view locator. Then you have the templating engine (Razor for example) who does the real work. MS decided to couple these 2 so that's why there is an aspx view engine and a razor view engine. It should be one view engine (locator) supporting n template engines, but I digress.

Anyways, if you want to change the view location or even use a different view name convention (not the action name) you can do it by inheriting (yeah...) one provided view engine and then change the paths. What if you want to support themes i.e have another dynamic value (besides controller and action) in a path of a view? Well... you kinda have to rewrite a lot of what the view engine does, because it only provides 2 variables: controller and action name. What if you want (gasp!) different naming and path conventions for your views in the same application? Please, don't say:"Why would you want that? One convention to rule them all is the best". Yeah and one model for everything is also the best.

Long story short, if you truly want to be in control of your views, there's a lot of work and some pain with asp.net mvc. Let MvcPowerTools (MPT) ease that pain with the FlexibleViewEngine. Yeah, it's flexible because YOU decide the conventions it uses. And you can have as many conventions as you need. You can start with one, the add some more. The only effort is to write the convention class. Nothing else.

For this example, I want my views in the same folders with my controllers and the view has the controller name. Let's see how hard it is to implement it.

public class ViewsPolicy:BaseViewConvention
    {
        public override bool Match(ControllerContext context, string viewName)
        {
            return !viewName.StartsWith("_");
        }

               public override string GetViewPath(ControllerContext controllerContext, string viewName)
        {
            var ctrl = controllerContext.Controller.GetType();

            var path = ctrl.ToWebsiteRelativePath(GetType().Assembly);
            return path + ".cshtml";
        }
    }

	//let's enable all conventions defined in the assembly
	 FlexibleViewEngine.Enable(c =>
            {
                c.Conventions.Clear();
                c.RegisterConventions(typeof (ConfigTask_ViewEngines).Assembly);
            },removeOtherEngines:true);

Lots of complicated code here, let me help you understand it: first we decide when to apply the convention, in this case the view which isn't a partial (the underscore prefix designates a partial). Next, we need the path to the controller and we have a nice extension method (part of the tools) that takes a namespace and returns it as a path. We add the desired suffix and that's it.

Now, let's see the code for when I want to have views with the controller name directly in ~/Views but with theme support.

/// <summary>
    /// Used with Handler pattern controllers
    /// </summary>
    public class ViewIsControllerNameConvention:OneLayoutConvention
    {
        public override bool Match(ControllerContext context, string viewName)
        {
            return !viewName.StartsWith("_") && !FlexibleViewEngine.IsMvcTemplate(viewName);
        }

        public override string GetViewPath(ControllerContext controllerContext, string viewName)
        {
            var theme = controllerContext.HttpContext.GetThemeInfo();
            var controller = controllerContext.RouteData.GetRequiredString("controller");
            if (theme==null)
            {
                return "~/Views/{0}.cshtml".ToFormat(controller);
            }

            return "{0}/{1}.cshtml".ToFormat(theme.ViewsPath,controller);
        }
        
    }

I think only one thing needs to be explained: GetThemeInfo() . Theme support is provided by MPT via extension method and configurable structures. You only need a view engine capable to use them.

In conclusion, you get the power to control the view engine and writing a convention is as hard as you've seen above. A word of advice, make separate conventions for views and partials, it's easier this way.

P.S: I do understand if you don't find this feature useful, the point of MPT is to provide options for those who want them. Having alternatives is great, especially for those 1% edge cases asp.net mvc won't play nice with.

MvcPowerTools Preview: Query and Command Controllers

By Mike on 7 April 2014

MPT gives you a helping hand if you want to use Query or Command Handlers  . While not exactly the same implementation as Jimmy's, it's the same idea, only combined with the Handler Controller approach (in a nutshell, the Controller is the action and its methods handle GET/POST, very similar to WebApi or REST approach). It also makes use of the One Model In, One Model Out convention.

Note that these are opinionated choices, alternatives and not yet another silver bullet solution. Just another way to do things, that might suit your style. Enough said, let's see some code (pasted directly from an app I did recently, and yes, that's ALL the controller and handler code).

public class TagsListController : QueryController<PagedInput, TagsListModel>
    {
        public override ActionResult Get(PagedInput input)
        {
            return Handle(input);
        }
    }

 public class TagsListHandler : IHandleQuery<PagedInput, TagsListModel>
    {
        private readonly IQueryTaxonomyStats _stats;

        public TagsListHandler(IQueryTaxonomyStats stats)
        {
            _stats = stats;
        }

        public TagsListModel Handle(PagedInput input)
        {
            var model = new TagsListModel();
            model.Page = input.Page;
            model.Resources = _stats.GetTagList(input.ToPagination());            
            return model;
        }
    }

Let's see: you have an input model (PagedInput) received by the controller. The controller just asks the base QueryController to handle it, in essence, to return the view (output)model for that input. All that the query controller does is to use the Dependency Resolver to invoke the defined handler that accepts PagedInput and returns TagsListModel. In this specific scenario I'm using a repository, but I could have just used an ORM directly. The handler's job is to assemble the view model and here it's quite trivial.

You may ask yourself why should we bother with this when we could've put that handler behaviour directly in the controller. The answer is: decoupling. TagsListHandler is somewhere outside asp.net mvc, UI, in my app is part of the QueryModel project . Also, as you can see, it doesn't depend on asp.net, controllers, HttpContext etc. It's totally decoupled from the UI and this means it easy to test and it can be reused outside asp.net mvc.

So, TagsListController's job is simply to build the input model (in this case it doesn't have to do anything) that will be use by the query handler. And all controller handling queries look like this one. The important part is the query handler itself, which is just a class from a querying layer.

Now let's see a command controller.

public class AddInformationsController : CommandController<AddInformationsModel,NoResult>
    {

        public ActionResult Get()
        {
            var model = new AddInformationsModel();
            return View(model);
        }

        public override ActionResult Post(AddInformationsModel model)
        {
            return Handle(model,
                d =>
                    this.RedirectToController<BrowseResourceController>(
                        c => c.Get(new BrowseResourceInput() {Type = ResourceType.Informations})));           
        }
	}
	
	 public class AddInformationsHandler:IHandleCommand<AddInformationsModel,NoResult>
    {
        private readonly IDispatchMessages _bus;

        public AddInformationsHandler(IDispatchMessages bus)
        {
            _bus = bus;
        }

        public NoResult Handle(AddInformationsModel model)
        {
            //map model to domain entity
			//add entity to storage
			//publish domain event
            return new NoResult();
        }
    }

 So, I want to add an information. The Get method returns a view with an empty view model. Then, the form is submitted and the Post method is invoked. The command controller will use the DependencyResolver to request and execute a handler which takes an AddInformationsModel input (command) and returns NoResult (if you want to return let's say an id, define a class SomethingId encapsulating the id and use that instead of NoResult). Please excuse the pseudocode comments, the actual code is irrelevant here. The controller's Handle method second argument is a lambda for what to do after the command is handled successfully, in this case a redirect. Again, the advantage is that we keep the command handler outside of UI, decoupled from asp.net mvc. In this example, the handler is part of the Domain (I don't have a Services layer).

As you can see, the controllers are as slim as they can get (1-2 lines of code) while the real logic is in the proper layer. And if you followed closely, you could see a convention at work here:  TagsListController, TagsListModel, TagsListHandler. If the input model had more then a 'page' property, I would have had a TagsListInput class as well. It's easy, even now, after a few good months to go directly to the class I need, when I want to change something.

A final note, this approach really require the use of a DI Container and of course, the handlers need to be registered with one.

MvcPowerTools Preview: Action Filters Conventions

By Mike on 3 April 2014

Action filters are a great way to implement some aspect oriented programming and a powerful feature of Asp.Net Mvc. However, in a big application, it can become cumbersome to decorate controllers and methods with every filter you want. You can use global filters but those are .... global, they apply to everything. If you don't want to copy paste annotations every time, a workaround is to define a base class and make the controller inherit from it. But this is a workaround and on the long run, the solution isn't very clean at all. What if you need filters that are present in 2 base classes? Create a third with the common filters? Slowly the ball of mud gets bigger.

MPT gives you the tools to implement this functionality without inheritance or other duct tape solutions. All clean and SOLID. And easy to use. The point is you define conventions based on which filters are applied to actions. Plain and simple. No tower of annotations required.

As an example, I want that all my controllers from the Admin namespace to require authorization i.e use [Authorize] . Also, I want that all actions names prefixed with 'ajax' to accept only ajax requests. And all the POST actions (either prefixed with 'post' or having [HttpPost]) should be the subject of [ValidModelOnly].

public class MyFilterConventions : FiltersConventionsModule
        {
            public override void Configure(IConfigureFilters filters)
            {
                filters
                    .If(a => a.DeclaringType.StripNamespaceAssemblyName().StartsWith("Admin"))
                    .Use<AuthorizeAttribute>()
                    .If(a=>a.Name.StartsWith("ajax"))
                    .Use<AjaxRequestAttribute>() //part of MvcPowerTools
                    .If(a=>a.Name.StartsWith("post") || a.HasCustomAttribute<HttpPostAttribute>())
                    .Use(()=> new ValidModelOnlyAttribute()) //part of MvcPowerTools
                    ;

            }
        }
		
 FiltersConventions.Config.RegisterControllers(Assembly.GetCallingAssembly());
 FiltersConventions.Config.LoadModule(new MyFilterConventions());
 FiltersConventions.Config.BuildAndEnable();

That's all! Easier and clearly more maintainable than using inheritance, right? And your controllers stay clean. Now, one might argue that it is a good thing to have those annotations right on top of the action. Indeed, it's a visual help. However once you have more than 2 annotations, it becomes a clutter. In my opinion, it's much more clean to set up some conventions and respect those. But it's a matter of taste and this is an alternative to the 'standard' asp.net mvc approach. You can use both at the same time, it's a valid choice also.

A note, if using a DI Container. If you're not creating the action filter instance yourself (like in the final convention above), you need to make sure the DI Container knows how to instantiate the filters you want.

MvcPowerTools Preview: Routing Conventions

By Mike on 1 April 2014

MvcPowerTools (MPT) is a library aimed at the experienced asp.net mvc developer. It's meant to give you the power and flexibility when you find the standard asp.net mvc to be too rigid or just in your way. MPT it's deeply integrated with asp.net mvc (5+) and gives you alternate ways to accomplish things. It's heavily inspired from FubuMvc, so if you're familiar with Fubu, you'll find many similar things here.

Today's post is about Routing Conventions. More exactly, MPT allows you to define your very own routing conventions. One thing to note is that it doesn't replace the standard conventions, you can use both the 'old' style and conventions at the same time, because all the conventions do is to allow you to define how the routes are generated for controllers matching a criteria. Once again, it's a way to extend what asp.net mvc already offers.

So, you may not like to write all your routing by hand (for obvious reasons). Or you might want to use a certain routing approach for some controllers, some attribute base routing for others, namespace based hierarchy for some etc. Of course, you can do all this right now, but ... what if you need to change your routes based on the SEO flavour of the day or to accommodate internationalization  or versioning or.. you get the picture. Would you prefer to do it by hand, changing God knows how many routes or modifying tens or hundreds of controllers or you prefer to change a convention in ONE place and that's it?

The point with routing conventions is that allows you to decouple the route generation from the controllers in a very maintainable manner. You can have as many conventions you need for all the edge cases. You don't have to force everything into a one way of doing things.

Enough talk, let's see some code. Let's suppose I want a namespace based hierarchy for all controllers from the "Admin" namespace. And I want that all actions names starting with 'get' to be constrained as GET and what starts with "post" to be constrained as POST (yes, convention not attribute, less clutter). To keep things tidy, I'll define the convention inside a module (there are other ways)

public class AdminConvention : RoutingConventionsModule
        {
            public override void Configure(RoutingConventions conventions)
            {
                conventions.
                    If(action => action.Controller.StripNamespaceAssemblyName().StartsWith("Admin"))
                    .Build(action =>
                    {
                        var url =
                            action.Controller.ToWebsiteRelativePath(GetType().Assembly)
                                .TrimStart('~')
                                .TrimStart('/')
                                .ToLowerInvariant();
                        var rt = action.CreateRoute(url);
                        //todo if you want to add params to url


                        if (action.Method.Name.StartsWith("get", StringComparison.OrdinalIgnoreCase))
                        {
                            rt.ConstrainToGet();
                        }
                        else
                            if (action.Method.Name.StartsWith("post", StringComparison.OrdinalIgnoreCase))
                            {
                                rt.ConstrainToPost();

                            }
                                                       
                        return new[] {rt};

                    });

            }
        }

Next, in the routing config file (from App_Start)

RoutingConventions.Configure(cfg =>
           {
               cfg
                   .RegisterControllers(Assembly.GetCallingAssembly())
                   .HomeIs<SomeController>(c => c.Index(null,"something"));
               
               cfg.LoadModule(new AdminConvention());
           });

Now, just for fun, I want that all CamelCase controller names to be rewritten like "camel-case". I add a modifier.

cfg.Always().Modify((r, action) =>
		   {
			   var con = action.GetControllerName();
			   var i = 0;
			   var final = new List<char>();
			   foreach (var ch in con)
			   {
				   if (char.IsUpper(ch))
				   {
					   if (i > 0)
					   {
						   final.Add('-');
					   }
				   }
				   final.Add(char.ToLower(ch));
				   i++;
			   }
			   r.Url = r.Url.Replace(con, new string(final.ToArray()));
		   });

Now everytime I want to change something, I change it here. Anything else stays untouched. Btw, the register controllers part is required.  While this is only an example, you can create much more specific conventions each in its own class (SRP!).

MPT comes with 2 predefined conventions: HandlerRouteConvention  and OneModelInHandlerConvention. Personally, I prefer the latter one as it's easier to maintain.

OK, thats' it for now, but here's a taste of things to come: view engine conventions, html conventions, apply filters by conventions, command and query controllers. In the mean time you can check the GitHub repo