Installing CobaltMVC

Got an interesting piece of anonymous feedback today reminding me of something rather obvious…

How exactly do you install CobaltMVC?

Oh yeah… That would be handy information… and it probably should have already been released. That said, lets get right to it.

Download CobaltMVC

The new CobaltMVC site is still in beta (like the rest of the framework) but you can still download the libraries you need to get started.

Add CobaltMVC To Your Project

Unpack the files to an easy to reach location and then add them as references to your project. You don’t need to add both, the Cobalt.dll is good enough.

‘Initialize’ CobaltMVC

Next, open up the Global.asax file and include the Cobalt.CobaltConfiguration.Initialize(); call to the Application_Start method. This makes sure that CobaltMVC is set up fully before it begins processing requests.

Update Web.config (sorta optional)

This step can be skipped but it will make coding your pages less convenient since you’ll have to add the namespaces all over the rest of your project. Add the Cobalt and the Cobalt.Web namespaces to your system.web/pages/namespaces section. This opens up the extension methods used to start Cobalt commands from your views.

You’re Done!

At this point we can test CobaltMVC to see if it is working. For example, here is a command you can run on the default MVC Index view.

And you’ll get the following results…

Not bad, huh?

It is worth mentioning that CobaltMVC might have unexpected results if you use .browser files with your project. Why?

Well, part of the Initialize() call actually creates a .browser file that is used to capture rendering for content on the page.

So, if you see this file floating around in your project, don’t delete it.

Who knows what happens when too many .browser files are fighting for the same thing but I doubt it will be a good thing.

Good luck!

Cobalt Progress

CobaltMVC is coming along really well. I’ve been dog fooding it myself for the past few weeks in some projects and it fits nicely. I’ve discovered (and fixed) a lot of flaws and bugs along the way, so overall it has been a good experience.

I started a new site to be the dedicated home for CobaltMVC, which also happens to be on the same domain as my new website, at cobaltmvc.hugoware.com.

The site isn’t complete yet – I have a lot of documentation to write along with getting additional work done on my ‘personal’ part of the website, but overall it is a good example of what the finished site will look like.

Additionally, the site itself is powered by CobaltMVC… what a coincidence!

CobaltMVC and Custom Selectors

CobaltMVC is a server side templating framework that behaves just like jQuery for your Views. CobaltMVC also works in WebForms.

CobaltMVC supports a variety of CSS selectors including pseudo and attribute matching. To keep things flexible, I’ve made it so that you can create or overwrite anything built-in. This post we discuss how to create your own for your project.

Right now, if you wanted to select all of the even rows in a table then you could use the pseudo selector…

this.Find("table > :even");

Cool, but what if we wanted to create our own? Here is an example of a selector that finds ‘numeric’ HTML elements.

//called once to add it to the project
CobaltManagement.RegisterCustomPseudoSelector(
    "numeric", //the name of the selector :numeric
    (nodes, argument) => { //the comparison to use
        decimal container = 0;
        return nodes.Where(node => decimal.TryParse(node.InnerText.Trim(), out container));
    });

//then used from our pages like...
this.Find(":numeric");

You’ll notice there are two arguments for the method you provide – First is a list of the available nodes to compare against. The second is an optional ‘argument’ string. The method should return a list of nodes that should be kept in the selection.

And the argument? That is an optional value in case you want it included in your selector. A good example of using the argument is the nth pseudo selector which returns every x number item.

//Everything within the parens is included as part of the argument
this.Find(":nth(4)");

Note: The argument is passed as a string so you’ll need to perform any parsing before you begin using the value.

Attribute selectors match against the attributes of the HTML elements. CobaltMVC checks the values and makes sure that two string are passed (even if they are empty), but any additional parsing needs to be done as part of the method.

That said, the method you use to perform the comparison is slightly different.

CobaltManagement.RegisterCustomAttributeSelector(
    "%", //the prefix to use for the selector @attr%='value'
    (argument, value) => argument.Equals(value, StringComparison.Ordinal)); //the comparison

The special character is what you want to prefix the attribute selector with (if you plan to override the default = selector then you just pass in an empty string). This needs to be a special character so not to be confused with the name of the attribute.

The comparison method itself is just a pair of strings, the first being the argument provided by the user and the second being the value found on the attribute. If the element doesn’t have the matching attribute then it is skipped entirely.

So, we could use the method we created in the example above by using…

this.Find("[@title%='Hugoware']");

Pretty neat!

If you haven’t downloaded Cobalt then head out to GitHub and download the code!

CobaltMVC – Custom Controls and Dynamic HTML

CobaltMVC is a server side templating frameworks that works a lot like jQuery. You can use it with both ASP.NET MVC and WebForms – (Watch the introduction video)

So far all of the CobaltMVC examples that have been posted have involved selecting existing elements on the page and making changes to them. However, there are times you’d like to generate new elements or wrap the same markup in a reusable control and attach it to the page.

Controls in CobaltMVC are just CobaltElements with properties and methods that you can use to define the behavior of an element. Because of this, a control can be selected against and modified by external selectors. This means that any control can be adjusted and tweaked for your individual needs.

Want to learn more? Check out the screen cast below that explains some of the interesting things you can do with custom controls and dynamically generated HTML elements.

[Watch The Screencast!]

Cobalt Beta – jQuery Style MVC View Templating!

In a recent blog post I shared a preview of the Cobalt project I’ve been working on. Today, the source code has been uploaded to git-hub and the first beta binaries are being released!

Not sure what Cobalt is? Watch a screencast showing how you can use Cobalt in your MVC projects.
Watch the video now!

If you’ve seen any of my previous blog posts then you realize I’m not much of a fan of the current way to populate templates in ASP.NET MVC. I’ve tried a handful of different ways to improve the experience but so far nothing really felt like an improvement.

Cobalt uses CSS selectors to find and update content, much like the way that jQuery works. Cobalt works *with* ASP.NET MVC (and WebForms) so you can include it in an already existing project and use it right away!

So what does Cobalt look like? Here is an example of an MVC View…

<%@ Page Language="C#" 
    Inherits="System.Web.Mvc.ViewPage<IEnumerable<ProductDetail>>" %>
<%  
    this.Ready(() => {

        //select by tag names
        this.Find("form")
            .Attribute(new {
                action = this.Url.Action("CheckOut")
            });
        
        //find and set values for elements
        string current = this.Find("h3").Text();
        this.Find("#title").Text(current.ToUpper());
        
        //select classes and certain pseudo selectors
        this.Find(".list :even").AddClass("alt-item");
        
        //create new elements on the fly
        var link = this.Create("<a/>")
            .Text("Read About Us")
            .Attribute("href", this.Url.Action("AboutUs"));
        this.Find("p").Append(link);
       
        //create custom elements (like CustomControls)
        Stylesheet sheet = new Stylesheet("~/site.css");
        sheet.AddToPage();
        
    });
    
%>

<html>
    <head>
        <title>Sample</title>
    </head>
    <body>
        <form method="post" >
            <h3>Temp Title</h3>
            <p>The description goes here</p>
            <ul class="list" >
                <li>Item 1</li>
                <li>Item 2</li>
                <li>Item 3</li>
                <li>Item 4</li>
                <li>Item 5</li>
            </ul>
        </form>
    </body>
</html>

You can see that much like jQuery we have to queue up the work we need to execute once the document is ready.

I have a lot of documentation to write and a lot of screencasts to record, but don’t forget about the preview video which should get you started. For now, here are a list of the more important details.

The Important Stuff!

• You must call CobaltManagement.Initialize() in your Global.asax file in the Init method (just override it and call it).

  public override void Init() {
      base.Init();
      CobaltManagement.Initialize();
  }
  

• Cobalt uses HtmlAgilityPack to handle parsing of html content. I’m not happy with the framework so it will be one of the first things to be phased out, but for now you need to make sure to download it if you get the source code instead of the binaries.
• You must use this.Ready from your pages and controls to wrap your commands. Otherwise your commands will run before the document is ready and fail.
• Cobalt is aware of context, so if you use this.Find within a UserControl then you’re only going to select elements within that control. If you need to access the Page level from a UserControl then you can call this.Page.Find to change the scope of the command.
• Cobalt supports a decent amount of selectors. Below is a list of currently available options.
• Combinators: ‘ ‘, >, +
• Shortcut Attributes: #elementId, .cssClass, $elementName
• Attribute Matching (ex. [@name=’value’]): equals (=), starts with (|=), ends with ($=), contains (~=)
• Pseudo: first, last, even, odd, nth(#), lt(#), lte(#), gt(#), gte(#), text, password, button, checkbox, radio, submit, file

Keep in mind this is very much beta code – I was literally working on changes today :). If you’re feeling brave then download the source and dig right in!

Download Beta

Cobalt (Source Code)

Cobalt MVC Preview!

Lately, I’ve been working a lot on my project Cobalt which is, more or less, jQuery for server side ASP.NET MVC views. I’ve shown some code examples before but today I have a screen cast of some of the code in action.

Watch the video now!

Hopefully, I’ll have some code released in the next week or two, but for now feel free to give thoughts and feedback!

MVC Templating – jQuery Style!

I’ve messed around with a variety of ways to make MVC templating better but I’ve never really been satisfied with any of my solutions until now.

One of the things that I really like about jQuery is that it allows for better separation of markup from code since you can use CSS selectors to find and change elements on the page. ASP.NET MVC requires server side blocks of code to be mixed into the markup to display content.

The other day I started working on a new project I’ve named Cobalt – A jQuery style, context aware templating framework for ASP.NET MVC. I’m not quite ready to release the code but I wanted to share the idea in advance.

Note: When I say “jQuery Style”, I mean method chaining with css selectors – You can’t use $()… sorry 🙂

Let’s pretend we have the following markup

[Index.aspx (Markup)]

<%@ Page ... %>
<html>
    <head>
        <title>Untitled</title>
    </head>
    <body>
        <h1>Title</h1>
        <div class="content">
            <p></p>
            <ul></ul>
        </div>
        <a id="back" >Previous</a> | <a id="next" >Next</a>
    </body>
</html>

Using Cobalt, we can use jQuery style code to select the correct elements and update content in server side code at the top of the view.

[Index.aspx (Server Code)]

//select tags by their names
this.Find("h1")
    .Text("My Page");

//select tags by name
this.Find("a")
    .Attr("href", this.Url.Action(link.Text())
    .Css(new { color = "#f00" });

//find by ID
this.Find("#back")
    .Remove();

//use other selectors
this.Find(".content > p")
    .Html(this.Model.PostContent);

//select classses and children
this.Find(".content > ul")
    .Remove();

//or perform sub queries
this.Find(".content", content =>
    content.Find("strong")
        .Text(bold.Text().ToUpper())
            .AppendTo(content)
            );

Keep in mind, this code is part of the view and not in a code behind file.

Of course, this view could probably be just as easily updated using a Model and assigning values using server side blocks of code, but consider some of the advantages of keeping our code separated.

1. Markup stays free of server side code blocks so it is easier to pull the content from external resources (for example a database)
2. If the markup is constantly being changed by another team member (for example a designer) we can avoid tinkering with the new HTML and instead make changes to our selectors (if even needed).
3. Many web developers are familiar with CSS selectors – The template could be understood by other team members and developers regardless of programming language choice.

Being Context Aware

The context of a selector is another important part of Cobalt. If you’re working in a UserControl you might changes to stay within the context of the control. At the same time, you might want some of your commands to change other parts of the page.

[SomeControl.ascx]

<@ Control ... %>

<h3>Latest Tweets</h3>
<ul class="tweet-list" ></ul>
<a href="http://www.twitter.com/hugoware" >Follow Me!</a>
<% =this.Html.ActionLink("Rendered Link", "Index") %>

When you use the this.Find(...) command, the actions are queued up and executed only for the calling control. That said, you can use the this.Page or the this.Parent properties to change the context (and scope) of a command.

[SomeControl.ascx (Server Code)]

//context stays inside of the UserControl
this.Find("ul.tweet-list")
    .Html(this.Model.Tweets);

//context stays inside of the UserControl
this.Find("h3")
    .Text("Follow Me!");

//finds both links (static and rendered)
this.Find("a")
    .Attr("href", this.Url.Action("Home"))
    .Text("changed!");

//context changes to the page level
this.Page.Find("head")
    .Append(this.Model.Stylesheet);

//updates the title in the page
this.Page.Find("title")
    .Text("Changed the title!!");

//never finds the title (context is in the control)
this.Find("title")
    .Text("Title not changed!");

Again, this might be a little extra code in some cases, but we are also able to access elements all over the page without needing to apply special WebControls or wire up to the Page life cycle.

It is worth pointing out that both links will be discovered by the a selector since the actions aren’t actually invoked until after the page is rendered. This means you can use MVC like you normally would and still use Cobalt to find and change elements. In fact, as far as I can tell this should work with WebForms as well as MVC, but I’d have to test it before I could say how well it works.

Work In Progress

This project is only a few days old right now but is already coming along very well. I’ll be posting some code soon but till then feel free to share any ideas you have.

ASP.NET 4.0 New Html.Encode Syntax

This post should probably be filed under ‘problems that no one will actually need to Google’ but here goes anyways.

Maybe I’m weird, but I tend to write server side blocks and bindings in ASP.NET like so…

<h1><% =this.Model.Title %></h1>
<span><% =this.Model.Posted.ToShortDateString() %></span>
<div><% =this.Model.Content %></div>

All of my equal and pound signs are placed directly next to the content being written — not the actual server code block. No big deal right? Well… maybe not quite the case in the new ASP.NET…

I started using the new ASP.NET 4.0 stuff today… yeah, I wasn’t much of an early adopter this time… the IDE turned me off too much.

Anyways, when I tried the new HTML encoding syntax I got the following message…

Invalid expression term ‘:’

Apparently, few people write their blocks the same as I do… After poking around for a moment I realized that the parser just simply did not like the colon to be anywhere else except for directly by the percent sign. So just remember…

<%: "OK!" %>
<% :"Crash!" %>

Also, if you do this in Visual Web Developer (Express) then you’ll get the message ‘BC30035: Syntax error.’… but it is the same problem…

Sienna MVC

This last week has been a time of mourning for me but I have reached the acceptance phase. Now, that I’m ready to move on I can share some code I’ve been working on.

I’ve blogged a lot before about using WebForms and more recently using WebControls with ControlAdapters in MVC, but for the most part it was just messing around with small sections at a time. Tonight I published my templating framework on GitHub called Sienna.

Before you read further realize that this is not WebForms in MVC. This is WebControls in MVC — or basically the templating and using code behinds for View logic.

I might be alone on this but I am having a hard time of letting go of using code behinds for separating code from the page markup. No matter how simple a view is server side blocks of code are ugly. They are difficult to read and even harder to refactor, which is something that code behind files still excel at.

Sienna makes it so you can create new instances of Pages, assign to properties and then return them as ActionResults. To take it a step further, Sienna uses ControlAdapters to render cleaner markup and avoid the junk IDs that ASP.NET typically spews out… yes, and it drops the ViewState as well 🙂

Let’s look at an example of how Sienna works. Below is a sample page from a blog engine web application.

[/Views/Index/BlogPost.aspx]

<%@ Page Language="C#" 
    CodeBehind="BlogPost.aspx.cs" 
    Inherits="Site.Views.Home.BlogPost" %>
<html>
    <head runat="server">
        <title></title>
    </head>
    <body>
        <h1 id="name" runat="server" />
        <div id="posted" runat="server" class="date" />
        <div id="content" runat="server" />
        
        <form id="commentBox" method="post" action="[controller:Home][action:Comment]" runat="server" >
            <input id="email" runat="server" type="text" _id="email" _name="email" />
            <textarea id="comment" elementname="comment" runat="server" ></textarea>
        </form>
    </body>
</html>

[/Views/Index/BlogPost.aspx.cs]

using System;
namespace Site.Views.Home {

    //displays a blog post
    public partial class BlogPost : System.Web.UI.Page {

        //the post to publish display
        public Post Post { get; set; }

        //display the content
        protected override void OnLoad(EventArgs e) {

            this.Title = this.Post.Title;
            this.name.InnerText = this.Post.Title;
            this.content.InnerHtml = this.Post.Content;
            this.posted.InnerText = this.Post.Created.ToShortDateString();

            //add the classes for the date
            this.posted.AddClass("newest-post");

            //handle showing comments or not
            this.commentBox.Visible = Visitor.IsLoggedIn;

        }

    }

}

This might be a small amount of code but there are a lot of things to explain about it. I’ll focus in some of the more relevant parts.

• Instead of using the built-in WebControls in ASP.NET we are using regular HTML controls that have been marked to be handled by the server.
• Because ‘id’ and ‘name’ have special meanings to ASP.NET, we can use _id and _name to define the actual IDs to display, otherwise, no ID is shown. This allows a control to be available to the code behind using one ID and then rendered using another (or none at all). You can also use elementid, displayid or actualid if you do not like using underscores.
• Attributes like href and src can use a special format that will be parsed by a URL helper in the background at render time. The format is [name:value][otherName:otherValue].
• Because we use HTML elements for the template, we have access to the InnerHTML and the InnerText properties to assign values. Additionally, Sienna includes additional HTML helper methods for other common functions.
• This example shows a normal Page as the type but you can use anything that inherits from the Page type — including ViewPages, which will give you access to the Url and Html helpers. If you aren’t using a ViewPage, the UrlHelper and Controller instances are stored in the Page.Items property.

Now, how would you actually use this view from a controller? Well, it is really quite easy…

//shows the latest blog post
public ActionResult Index() {

    //get the content
    BlogPost post = BlogPostRepository.GetLatest();

    //create the view and assign the value
    var view = this.CreatePage<Views.Home.BlogPost>();
    view.Post = post;

    //show the page
    return this.Page(view);

}

And that is it – The PageResult is returned and executed normally and the final result is nice and clean HTML output.

<html>
    <head>
        <title>My Post</title>
    </head>
    <body>
        <h1>My Post</h1>
        <div class="date newest-post" >10/15/2009</div>
        <div>
            <!-- snip... -->
        </div>
    </body>
</html>

You can also use this same approach to assign directly to properties on the page. For a second example, let’s say our code behind actually looked like the following.

using System;

namespace Site.Views.Home {

    //displays a blog post
    public partial class BlogPost : System.Web.UI.Page {

        //the name of the post to show
        public string Name {
            get { return this.name.InnerHtml; }
            set { 
                this.name.InnerHtml = value;
                this.Title = value;
            }
        }

        //the content to display
        public string Content {
            get { return this.content.InnerHtml; }
            set { this.content.InnerHtml = value; }
        }

        //the day the blog post was created
        public DateTime Posted {
            get { return DateTime.Parse(this.posted.InnerHtml); }
            set { this.posted.InnerText = value.ToShortDateString(); }
        }
    }
}

The nice thing about this approach is that the View defines which properties need to be encoded by using the InnerText or InnerHTML properties. It also allows us to assign other types like DateTime but then the View determines how to use it. Depending on how you look at it, this approach replaces the ViewModel by filling both roles at once.

Unfortunately when we create this control the links between the HTML elements and the properties are not immediately available. That doesn’t take place until after the page starts to render. So, to solve this we can assign to the Init event as part of when we create the Page.

//shows the latest blog post
public ActionResult Index() {

    //get the content
    BlogPost post = BlogPostRepository.GetLatest();

    //show the page
    return this.Page<Views.Home.BlogPost>(page => {
        page.Name = post.Title;
        page.Content = post.Content;
        page.Posted = post.Created;
    });

}

And our page is correctly created and rendered into view!

Technically, this whole approach should work with existing WebForms pages by allowing you to use MVC Controllers and Routes and then returning the correct page automatically. Of course, this hasn’t been tested and I really don’t recommend that you use it that way… but still interesting to think about 🙂

Sienna works with MVC projects so you don’t need to start anything over. Simply add the files to your project, generate the Browser definitions file (which is part of the ControlManagement class in Sienna) and off you go!

[Source Code: Sienna]

So go try it out and let me know what you think!

Using A Page Control For MVC Templating

In previous posts I’ve talked about using WebControls along with ControlAdapters to have cleaner markup by using the built in ASP.NET page life cycle to assign values to the correct elements on the page. This approach can make views easier to read by removing server side code blocks and allowing logic to be handled within the code behind of the view and not within the page itself.

This post continues the discussion by looking at how you can use a Controller to create instances of views before rendering them to the page.

In previous examples, I used the View method as you normally would in MVC. This worked well enough – We had access to the Model property and the ViewData which gave us enough information to render our page.

However, this example approaches the same problem but a little differently. Instead, we are going to create the view and assign to the properties immediately and then render the content for the view. Below is some code that illustrates the idea.

//Keep in mind, this is sample code and needs more work
//before you plug it into a project but it should give a 
//general idea of how this could work.

using System;
using System.Web;
using System.Web.Compilation;
using System.Web.Mvc;

namespace MvcTemplating.Controllers {

    public class SampleController : Controller {

        /// <summary>
        /// Creates a new instance of a view 
        /// </summary>
        public T CreateView<T>(string path) where T : class {
            return BuildManager.CreateInstanceFromVirtualPath(path, typeof(T)) as T;
        }

        /// <summary>
        /// Renders a handler to the page
        /// </summary>
        public ActionResult Handler(IHttpHandler handler) {

            //update and process the handler
            this.HttpContext.Handler = handler;
            this.HttpContext.Handler.ProcessRequest(System.Web.HttpContext.Current);

            //quit handling this request
            this.Response.End();
            return null;
        }

    }

}

The Handler function takes care of performing the work for the view and then returns a null since the action is still going to be wanting a return value. If you know a better way to handle this please let me know. 🙂

Instead of reading values from the ViewData or the Model we can now just assign them directly to the view.

namespace MvcTemplating.Controllers {

    [HandleError]
    public class HomeController : Controller {

        //displays content using an instance of the view
        public ActionResult Index() {

            //create the view
            var view = this.CreateView<MvcTemplating.Views.Home.Index>("~/Views/Home/Index.aspx");

            //assign to properties
            view.LatestBlogPosts = BlogPosts.Recent(5);
            view.LatestTweet = TweetRepository.GetLatest();
            view.Title = "Welcome Visitor!";

            //and then show the view
            return this.Handler(view);
            
        }
 
    }

}

This sample requires we know the path to the view but that can be fixed by using standard path names or possibly scanning the site in advance and saving the paths in memory (which is something I’ve done before with UserControls)

This approach, combined with ControlAdapters, can result in clean markup and provide additional logical functionality for some of the more complex views in your existing MVC projects.

Of course, this is just “proof of concept” stuff… I’ll hopefully have more code to share before long.