Live search for Umbraco frontend – using AngularJs and json content api

Everyone loves instant / live search, where a preview of the contents show up instantly as you write, right?

Update :
I wrote about an approach to create such a search quite a while ago using Examine. Now I like to write about an experimental, but working, approach that is faster than Examine and at the same time use a little bit of AngularJs.

Now – how is it even possible to be faster than Examine? Okay I cheat, I move the search to the client side, and get rid of the server call for each keypress / set of keypresses. Bad choice for sites with a fair amount of content? Well, if we take the Umbraco4 documentation as an example, last time I checked it was about 700kBs of data (in 236 markdown files). When we gzip compress that amount of text we should get about 175kBs. Which is similar in size as an ordinary – decently sized – image, and takes less than a second to download on a slow internet connection. For 236 pages of text. Let’s load that data on the initial page load, and perform the search with simple javascript functions.

For the actual search I’m going to use Umbraco 6 with the MVC CWS Starter kit , a little bit of AngularJs on the front end and a small json content api I call Tapas.

Install the mentioned packages. Then create a partial view called clientSideSearch.cshtml. Add the following code:

@inherits Umbraco.Web.Mvc.UmbracoTemplatePage

<script src=""></script>
<script src="/scripts/clientsearch.js"></script><!-- scripts placed in partialview for simplicity -->

<div ng-app="liveSearchModule" ng-controller="SearchCtrl">

    <h1>Live search</h1>
    <input id="searchText" type="search" placeholder="live search..." ng-model="searchText" />

    <ul ng-if="searchText">
        <li ng-repeat="child in children | filter:searchText | limitTo: 10">
            <a href="{{child.NiceUrl}}">{{child.Name}}</a>
            <div ng-bind-html-unsafe="child.Properties.bodyText"></div>

A few notes about the code. The Angular module and controller sets the scope in our html view. Then we use Angular built in directives ng-if and ng-repeat to filter the search results. Lastly we use Angular templating and the scoped objects to display the content, name, url and bodytext. The ng-bind-html-unsafe directive tells Angular to render the content as is, without encoding the html (as Html.Raw in Razor).

The “children” objects are returned by Tapas with a straight forward format shown in the docs for Tapas.

Add the render instruction inside your search view, “CWS-Search.cshtml” for example:


Next create the /scripts/clientsearch.js script:

angular.module('liveSearchModule', [])
  .controller('SearchCtrl', function ($scope,$http) {
      $scope.children = $http.get('/umbraco/publishedcontent/nodes/getchildren?path=/'); // get all children from the root document

This controller makes an ajax request (similar to $.getJSON / $.ajax) initially to get content from the content api, in this example all immediate children under root (path=”/”). The request returns a “promise” = an async result. Angular handles that automatically, and we do not need to figure out a way to render the content after the async is finished. The controller does not have any other functionality than to get data on initialization, later on the actual search is performed on the data in $scope.children.

And thats it!


Enter one or more letters in the search box to see the articles with bodytext below. If you like to format the document differently simply change the template. Limit number of search items if you wish. If you like to extend this with pager and change to a server side based service it’s fairly easy aswell. Also we might want to search through the entire tree. If there’s interest I’ll write a follow up later on.

The right amount of separation of concerns in Umbraco Razor?

We hear it’s a good thing to separate view code from logic, and also to separate code into controller, model and view files. What does that actually mean? And why is that a good thing? Also does this mean we need to create model and controller class files for all our Umbraco Razor scripts?

Consider a plain read-only, HTML rendering razor script with a good amount of HTML, over a page long. Nothing unusual and it works perfectly fine as it is:

The code in this post is for Umbraco MVC (4.10+), but it’s concepts apply to all versions of Umbraco.

<...lots of tags above this point...>
<div class="widget">
    <h4>Recent Posts</h4>
        @foreach (var blogPost in Umbraco.TypedContent(1068)
            .Children().Where(t=>t.IsVisible()).OrderByDescending(t => t.CreateDate).Take(10))
            <li><a href="@blogPost.Url">@blogPost.Name</a>
            @foreach (var item in blogPost.GetPropertyValue<string>("categories").Split(','))
                { <span>@item</span> } </li>

<...lots of tags beneath this point...>

A few things that can be made better here as I see it:
– The recent blog posts widget can be separated from the rest of the view into a reusable partial.
– Intentions are not clear, what exactly are we trying to do with the chained methods?
– Hard coded node number 1068, what if we change that one later?
– Lot of C# mixed inside HTML makes both the HTML and the C# harder to read and problems harder to find.

I suggest:
– Separate the code into a partial / separate razor script, give it a name and or a location that both describes the type of HTML it renders aswell as the content, for example “Widgets/RecentBlogPosts.cshtml”.
– Move all C# code, but a bare minimum to the beginning of the script.
– Specify the intent with the code being used by using good names, close to what it is described as on the actual site, or in the specification to the customer.
– Stay away from hard coded node numbers.
– Use C# Linq with Lambdas together with typed content. It’s a great syntax to express Umbraco content queries.
– Use the .Select method, together with anonymous object to return exactly what you need, i.e. arrays and objects with only simple types. This will help you make clear what you need and will show you possible problems early.

Main cshtml:

<...lots of tags above this point...>
<...lots of tags beneath this point...>


  var blogPostsRootNode = Model.Content.AncestorOrSelf(1);
  var recentBlogPosts = blogPostsRootNode.Children
    .OrderByDescending(t => t.CreateDate)
    .Select(p => new
      Categories = 
        (p.GetPropertyValue<string>("categories") ?? "")
<div class="widget">
    <h4>Recent Posts</h4>
        @foreach (var blogPost in recentBlogPosts)
            <li><a href="@blogPost.Url">@blogPost.Name</a>
            @foreach (var category in blogPost.Categories)
            { <span>@category</span> } </li>

What about separate model, view and controller classes?
The C# part of the script is building a ViewModel and, as such, could be placed in a C# model file, which in turn could be instantiated from the controller file firing up the view file.

We certainly could. And we could create a strongly typed view, and unit test the controller and the model. But would it really help us for this kinds of scripts that only show content – and does not deal with posted data?

I don’t think so. I found the approach described in this blog post be good amount of separation of concerns for views like this, I would very much like to hear experiences / opinions / examples from you, dear reader!

Happy coding

Nice and simple Razor templates with the help of RenderPage and some dynamic sugar

Besides saving global helpers in App_Code we have the option to use RenderPage (or Html.Partial) in Razor to reuse code globally.

Both ways helps in making the HTML code DRY and well structured. But an important difference is a RenderPage file can be wherever we want, and changes are fluent (no app restarts). We do loose strongly typed parameters but I think that is a small price to pay when we are doing Html functions. We can still send a typed viewmodel to the rendered page. What about performance? As far as I understand we will get a performance hit the first time we call the page after a save (generally much quicker than a app restart tho). But after that it’s on par with a global helper. Correct me if I’m wrong.

This is the basic syntax :


And in the SomeTypedView.cshtml :

@{var viewModel = (SomeType)PageData[0]; // mimic strongly typed view}

But the RenderPage-code is rather ugly. Let’s make a small global helper to make the syntax nicer:

@helper Display(object value, string templateName="") {
    if (templateName=="") {
        templateName = value.GetType().Name;
    @PageContext.Page.RenderPage("~/Shared/DisplayTemplates/" + templateName + ".cshtml",value)    

It’s using a defined path. And it also checks the type name if we do not specify it. So the two following instructions makes the same result:

@{var myObj = new MyType();}

They both renders /Shared/DisplayTemplates/MyType.cshtml

Introducing RazorTemplates

Can we extend this further, using dynamics to write:


…as a way to render the /DisplayTemplates/MyTemplateName.cshtml with someModel ?

Yes we can, check out DynamicHtmlTemplates in this gist, [Update: or the Umbraco RazorTemplates package which is basically the same, but evolved a little bit to an Umbraco context – also automatically picking up NodeTypeAlias to render file according to document type.]

Put DynamicHtmlTemplates in your App_Code and you can use:


Cool eh?

@using DynamicHtmlTemplates
 var myobj = new MyClass{Name="Someone", Value="123"};   
 dynamic tmpl = new Templates();
 // or dynamic tmpl = new Templates("~/Path/ToTemplates/");
 // or dynamic tmpl = new Templates("SubPathToTemplates");
Rendering /DisplayTemplates/MyClass.cshtml (sending myobj to PageData[0])

Rendering /DisplayTemplates/MyClassAlternative.cshtml  (sending myobj to PageData[0])
@tmpl.Display(myobj, "MyClassAlternative")
... or let it use Dynamic to figure out the template name:
Rendering /DisplayTemplates/MyClassAlternative.cshtml  (sending myobj to PageData[0])

Rendering /DisplayTemplates/MyClassAlternative.cshtml  (sending myobj to PageData[0])
Rendering /DisplayTemplates/Possible.cshtml (sending inline razor item template to PageData[0] and list to PageData[1])
@tmpl.Possible(Templates.ItemTemplate(@<text>this is @item</text>),new List<string>{"one","two"})

Contents of /DisplayTemlpate/Possible.cshtml:        
    @foreach(var item in PageData[1]) {

So with this, a bootstrap form can be created in a much more DRY way:

Tested in Umbraco 4.71 and Umbraco 6.02 as well as a vanilla WebPages site

Fun stuff : node.js in an Umbraco site

Did you ever want to run node.js within your umbraco site, and edit the server side javascript from within your Umbraco backend? Not? Well, it’s still a fun thing to do, don’t you think?

Update 1: I actually think nodejs makes some sense within Umbraco. Why? Well, for example it makes it possible for js-peeps to stay js. And node has a _lot_ of nice plugins (as for example jade and express).

Update 2: I made a first version of a sample of Umbraco running with ExpressJs and Jade, it uses Tapas that serves published content for requested url.

The setup only takes a few minutes to do:

  1. Install NodeJs and IISNode on your computer / server
  2. Install an Umbraco site or use an existing, using WebMatrix
  3. Add the NPM plugin from WebMatrix Gallery
  4. Add the folders iisnode and node_modules for the NPM plugin to show up in the toolbar (and restart WebMatrix)
  5. Add the Express Node module with the help of NPM. It puts the module in a new folder in your root “node_modules”
  6. Add the following lines to your web.config, in the configuration section (at the bottom for example):
    <location path="scripts/node">
                <add name="iisnode" path="server.js" verb="*" modules="iisnode" />

                    <rule name="express">
                        <match url="/*" />
                        <action type="Rewrite" url="/scripts/node/server.js" />


  • Add a new .js file and save it as /scripts/node/server.js
  • var express = require('express');
    var app = express.createServer();
    app.get('/scripts/node/hello/:name', function (req, res) {
    	res.send('Hello ' + + ' from node! [express sample]');

    That’s it! Now you should be able to surf to /scripts/node/hello/world and you should get “Hello world from node!” back.

    Update 2: What about Umbraco content?

    What if we like to do something a little bit more useful – make it possible to get and edit content? Well, our node application does not have the Umbraco contents available, so we need to get it in some other way : I guess http is the standard.

    Currently (in Umbraco 6.0) there is no available Restful Api out of the box (it will be added in 6.1 afaiu). However, the uRest package by Matt Brailsford seems to play nicely with u6 (edit : perhaps not, I could not get it to accept posts). Add that, and then change server.js and add a urest.js file as in this gist to get contents with internal http requests.

        var documentId =;
        requestGetWithToken("/documents/" + documentId, function (response) {
            // just return the content to the response string:

    Now you can browse to the url /scripts/node/documents/{nnnn} to get a particular document.

    Check out the uRest documentation for information about how to create and edit content.

    Update 3: content straight from umbraco context with the help of EdgeJs

    I just managed to get actual content directly from umbraco context into nodejs with the help of the brilliant EdgeJs by Tomasz Janczuk and by Morten Christensen.

    I will blog more details about it, but what I needed to do was this:
    1. Add Edge with the help of NPM.
    2. Create a class libary dll that fires up the Umbraco context (copied from Umbraco console example), with functions returning async Task

    public async Task<object> ListNodes(object input)
      return "nodes: " + listNodes();

    3. Setup functions inside my node app calling the .net functions

    var express = require('express');
    var edge = require('edge');
    var app = express.createServer();
    var listNodes = edge.func({
        assemblyFile: 'C:/harcodedpath-to-my-website/bin/umbracocontext.dll',
        typeName: 'UmbracoContext.Startup',
        methodName: 'ListNodes'
    app.get('/scripts/node/hello', function (req, res) {         

    4. Add a node.exe.config into my node.exe folder with just a connectionstring to begin with:

    <?xml version="1.0" ?>
            <remove name="umbracoDbDSN" />
            <add name="umbracoDbDSN"
                 providerName="System.Data.SqlServerCe.4.0" />

    It’s obviously not ideal to set the connectionstring in the global node.exe folder. I think a good workaround to get local connectionstrings is to copy the node.exe to a folder within the site and set the iisnode handler to use the local node.exe instead.


    Edge does not make it possible (yet) to use the already existing instance of the application (share memory), so if we run umbraco in and node in parallell we will have two context instances.

    If you are concerned about the performance: read this.


    app.get('/scripts/node/getTreeById/:nodeId', function (req, res) {  
    public async Task<object> GetTreeById(int nodeId)
        var node = contentService.GetById(nodeId);
        return nodeToDictionary(node, true);
    private Dictionary<string, object> nodeToDictionary(IContent content, bool includeChildren)
        var nodeData = new Dictionary<string, object>();
        nodeData["Name"] = content.Name;
        nodeData["Id"] = content.Id;
        content.Properties.ForEach(p => { nodeData[p.Alias] = p.Value.ToString(); });
        if (includeChildren)
            nodeData["Children"] = content.Children().Select(child => nodeToDictionary(child, true)).ToList();
        return nodeData;


    A require module pattern in Asp.Net Razor

    Did you ever need to load modules dynamically in Razor? Do you like to write function libraries in pure Razor, and be able to use them from other files without placing that function libraries in App_Code, and without forcing the App to restart?

    Not? Oh, well, anyways – as a friday evening experiment I hacked together a Razor Require Module sample which worked out pretty good.

    I do recommend the regular way to add functionality, in .cs-files. I use Razor mostly as a pure View engine, with no logic other than view logic.

    But Razor can also be a really fun playground to test some ideas in, and with this I can temporarily add functions to for example an Umbraco site directly from within the online Umbraco UI.

    Also – the AppPool will restart after a certain number of “recompiles”, which kind of defeats the purpose with all this.

    Edit : Roslyn will probably be a better suit for this, see David Ebbo’s post. I wrote an experiment with Roslyn as a server scripting tool.

    Here’s the usage:

    Create a module, SomeModule.cshtml:

    @Require.Define("SomeModule", (module) =>
        module.Exclaim = new Func<string, string>((message) => { 
            return message + "!"; 
        module.AddToDatabase = new Func<dynamic, int>((newrecord)=>{
            // some code to add the newrecord to the database        
            // return the created id
            return 0;

    The code is using lambda syntax to add functions to the module. The module name is defined with a string.

    Later you use the module this way:

        var newId = App.SomeModule.AddToDatabase(new { name = "foo", info = "bar" });    
    <p>New database item added with ID : @newId</p>

    The Require.File function checks if SomeModule has been defined already. If not it will define it and add the code dynamically by loading the SomeModule.cshtml.

    Each module is an ExpandoObject, which is added to the global App ExpandoObject. That’s why we use it with “App.ModuleName”.

    The Require code needed for this is only a few lines of code in the file Require.Cshtml in App_Code:

    @helper File(string fileName) {
        var p = (WebPage)WebPageBase.CreateInstanceFromVirtualPath(fileName);
        var ctx = new WebPageContext(new HttpContextWrapper(HttpContext.Current), p, null);
        p.ExecutePageHierarchy(ctx, new StringWriter());
    @helper Define(string moduleName, Action<dynamic> definitions, bool alwaysRedefine = false) {
        if (alwaysRedefine || App[moduleName] == null)
            App[moduleName] = new System.Dynamic.ExpandoObject();

    If you like to add a function to an already loaded module it’s possible to do so. You need to add a parameter to the define to make it redefine the module even if its already defined:

    @Require.Define("OtherModule", (module) =>
           ...  Existing code ...
        module.NewFunction = new Func<string>(()=>{
            return "result";
    }, true);

    A module can require other modules. And, you add modules and their functions dynamically without the need for App restarts.

    I got the final piece to this puzzle to this code from this gist by Niels Kühnel: dynamically render a razor file, thanks Niels.

    Using Require in Umbraco
    I do most my coding in Visual Studio, nothing beats it. But I also like to be able to log into an online site and make a few additions to a running (small, not client) site, just when I have five minutes over from wherever I am. And with the Umbraco UI I can do that. However, until now I haven been able to re-use code easily.

    Tip: Change two settings in web.config to be able to run files from within the api folder directly (“;):

        <add key="umbracoReservedPaths" value="~/umbraco,~/install/,~/macroscripts/api/" />
        <add key="webpages:Enabled" value="true" />

    Simple client side routes and content loading in Umbraco

    Do you like your users to be able to load subcontent on a page dynamically and support client side url’s (which in turn enables browser history, url-copy&pasting and bookmarks)? In this post I will show how you can do it in a very flexible way with the help of Backbone.js and a minimum of code.

    This is what I’m trying to achieve, I have an ordinary page with links to “sub content”, which is supposed to appear on the same page when the user clicks on a link:

    When the user clicks “sub content 2” the url becomes some-page#subcontent-2 and the corresponding content shows:

    To use “client side routes” we need to add some library that handles such. The most commonly used one is probably Backbone.js.

    To use it you will need to add script reference to Backbone.js and to Underscore.js which it has as a dependency.

    Download the files or add reference to CDN-paths, for example:

    Defining our routes and load the asked for content.

    A client side route url part is everything in the url that comes after a hash, i.e. “/some-post#myview/whatever” => “myview/whatever”.

    Backbone is using a straight forward syntax to setup routes, where every route has a url matching route string and a function to call. It handles parameter url parts aswell. The syntax to use a parameter is adding a colon before its name i.e. “myview/:id”

    In our case we’ll use “:urlName” to match every url (“#subcontent-1” and “#subcontent-2”) and pass the url string as the parameter urlName to the route function subContentsRoute.

    The subContentsRoute route function does only one thing : it loads the html content and puts it in the #subcontents div. It’s simply using a fixed url part + the urlName parameter value (i.e. “/some-post/subcontents-2”).

    var SubContentRouter = Backbone.Router.extend({
            routes: {
    		":urlName" : "subContentsRoute",
               	"*actions": "defaultRoute" // matches
            subContentsRoute: function(urlName) {
    		$.get("/some-post/" + urlName, function(data){
            defaultRoute: function( actions ){
        var app_router = new SubContentRouter;
        // Start Backbone history a neccesary step for bookmarkable URL's

    Save it as subcontentBackboneApp.js and add a script reference into the html template :

    <script type="text/javascript" src="/scripts/subcontentBackboneApp.js"></script>

    The rest is common Umbraco usage – create documenttype, template, content and a small macro

    How to make /some-post/subcontent-2 return the right content html? Let’s setup Umbraco with a simple document type with only bodyText as a richtext property, and a template that only returns the html we like to add into our div tag.

    With a document and a template in place we add our documents:

    Lastly we need to create those client side links and add a container for our dynamic content. We do that by adding this macro code in the original textpage template:

          <umbraco:Macro runat="server" language="cshtml">
          @foreach(var child in Model.Children)
    	        <a href="#@child.UrlName">@child.Name</a> 
    	  <div id="subcontents"></div>

    Can I haz images and macros?
    Our subcontent can be anything, styles, tags, images. But if you use a macro, the macro context will be the subcontent node and not the containing node.

    I find this simple approach with a router to be suitable for several similar usages to what I’m showing in this example.
    * Loading “more content”,
    * Loading “next sub article”,
    * Being the base for a small single page application within an Umbraco site

    Sample with Backbone model and view

    	var subContentModel = new Backbone.Model({
    	var SubContentView = Backbone.View.extend({
    		initialize : function () {
    			this.model.on("change",function () {
    			}, this);
    		render : function() {
    			return this;
    	var subContentView = new SubContentView({
    		model: subContentModel, 
    	var SubContentRouter = Backbone.Router.extend({
            routes: {
    			":urlName" : "subcontents",
                "*actions": "defaultRoute" 
    		subcontents: function(urlName) {
    			$.get("/some-post/" + urlName, function(data){
            defaultRoute: function( actions ){
    	var subContentRouter = new SubContentRouter;

    Live notifications on your Umbraco site using SignalR

    Using the SignalR library it’s possible to push notifications from the server to the clients. In this post I’m going to show how you can publish notifications about newly published documents to a site front page.

    For this to happen we need to add four pieces of code:

    1. A SignalR Hub that transports messages between server and client.
    2. An Umbraco event handler that sends message on document publish.
    3. A function that takes necessary information from the document and creates a sendable object.
    4. A client side script that activates SignalR and handles the message from the server.

    I use the terms Document and Node in the same way as the objects are named within Umbraco. The Document is the editable content object, and it has the event we listen to, but to get the properties we use the cached representation of the document = the Node.

    1. The SignalR Hub does not have any additional functionality except for what is built in, so our code is an empty Hub class declaration:

    public class NodePublishingHub:Hub

    2. The after document publish event handler sends a subset of node properties through the SignalR hub to the client:

    public class PublishEventsToHub : ApplicationBase
        public PublishEventsToHub()
            Document.AfterPublish += Document_AfterPublish;
        void Document_AfterPublish(Document sender, umbraco.cms.businesslogic.PublishEventArgs e)
            var context = GlobalHost.ConnectionManager.GetHubContext<NodePublishingHub>();
            // we need to explicitly update the document cache

    3. The node subset function takes a node and returns only the necessary data (I don’t know if there are any built in functions that already does this). We return it as an object. The Hub will convert it to Json automatically for us.

    public object GetNode(int nodeId, bool includeChildren)
        var node = new umbraco.NodeFactory.Node(nodeId);        
        return new
            Properties = node.PropertiesAsList.Select(p => new { p.Alias, p.Value }).ToDictionary(k => k.Alias, k => k.Value),
            ParentId = (node.Parent != null) ? node.Parent.Id : -1,
            ChildIds = node.ChildrenAsList.Select(n => n.Id),
            children = includeChildren ? node.ChildrenAsList.Select(n => GetNode(n.Id, true)) : null

    4. The client side function will initiate SignalR and add the nodePublished function to our client side part of the hub. The function will prepend node information to a ul/li for us (nodepublisher.js):

    $(function () {
          // Proxy created on the fly
          var nodePublishingHub = $.connection.nodePublishingHub;
          // Declare a function on the chat hub so the server can invoke it
          nodePublishingHub.nodePublished = function(node) {		  
             var updateDate = node.UpdateDate.replace('T', ' '); // quick and dirty format date + time		  
             $('#nodePublished').prepend('<li><a href="' + node.Url + '">' + node.Name + '</a>&nbsp;' + updateDate + '</li>');
          // Start the connection

    The Template Html is the Umbraco starter kit with the following additions:

    <script type="text/javascript" src="/scripts/jquery-1.6.4.min.js"></script>
    <script type="text/javascript" src="/scripts/jquery.signalR-0.5.3.min.js"></script>
    <script type="text/javascript" src="/signalr/hubs"></script>
    <script type="text/javascript" src="/scripts/nodepublisher.js"></script>	
    <div class="hotspot">
      <h4>Newly published nodes</h4>
        <ul id="nodePublished">

    Other types of notifications
    You can of course send any kind of notifications through a SignalR hub. I’m going to use it to make live updates on the front page when the site users creates registrations on a system on the site. The things necessary to add is invoking a client side function from the server side


    and having the client side function on the client “part” of the hub:

    nodePublishingHub.nodePublished = function(node) {...};

    For this to work you need to add SignalR to your Umbraco site. And you will also need to add SignalR as a reserved path in your web.config (add key=”umbracoReservedPaths” value=”~/umbraco,~/install/,~/signalr/” ). I tested this on a fresh Umbraco 4.9 site.

    Needs to be fixed
    This is clearly just a demonstration. To make it useful on a real site one would at least need two things.
    The list with newly published pages need to have some initial contents, otherwise the list will be empty when the users arrive, and it will be emptied on page refresh. And also because we use the after publish event we will get notifications also on publish after document edits.