<ul id="products">
  {% for product in products %}
    <li>
      <h2>{{ product.title }}</h2>
      Only {{ product.price | format_as_money }}
      <p>{{ product.description | prettyprint | truncate: 200  }}</p>
    </li>
  {% endfor %}
</ul>

Simple right? One of the other great features of DotLiquid is also how restrictive it is. That might sound like it should be a negative, with most people thinking flexibility is the key, but in reality it means template development is secure and template designers can only have access to what you want them to.

Whilst playing around with DotLiquid, I thought it would be cool if it could be used as an ASP.NET MVC ViewEngine. After a bit of a search though, I wasn’t able to find one. There were view engines written for Nancy and Jessica, but nothing for ASP.NET MVC. So like any respectable developer, I decided to write one

DotLiquid.ViewEngine

To get started, either download the view engine from the NuGet gallery, or just install it directly in an ASP.NET MVC project by issuing the command:

PM> Install-Package DotLiquid.ViewEngine

Once you have it installed, you are pretty much ready to rock. Simply create your views in your views folder as per normal, but with a .liquid file extension (you’ll need to prefix your partials / masters with an ‘_’ as per the DotLiquid requirement) and just start using the liquid syntax. The rest should just work automatically.

One other important note, and related to the deliberate restrictive nature of DotLiquid, is to make sure that any models passed down to your view, must be ILiquidizable. The simplest way to do this, is to have your ViewModels to just inherit from the DotLiquid Drop class. The ILiquidizable interface simply lets DotLiquid know which properties should be available to the template designer via the Liquid syntax.

It’s as simple as that.

For more information on the Liquid syntax, checkout the documentation on the DotLiquid and Liquid sites, and if you give the view engine a try, be sure to let me know if you have any problems / suggestions. And lastly, if you’d like to have a poke around the code for the view engine, you can find it now over on bitbucket.

As a developer who has been working on the web for over 12 years now, it can become very easy to slip into a comfort zone. I like to think I’ve read all the right articles, and that what I produce is good quality code. And for the most part, it generally is. But there is always room for improvement. As we grow as designers / developers, it’s inevitable that we become specialists in certain areas, and start to fall behind in others. For me, that is when the importance of local events can really shine.

It’s a chance for you to come out of that comfort zone, and to challenge what you think you already know. It’s a chance for you to checkout subjects that you might not ordinarily look into. And it’s a chance for you to get out and meet others with similar interests.

The Digital Barn was a great example of this, with talks on various subjects, with folk from near and far turning out. For me personally, there were 2 talks which really challenged my existing conceptions and really inspired me to make some changes. Harry Roberts, Breaking Good Habbits and Craig Burges, The Mad Scientists of the Information Superhighway.

Harry’s talk discussed some interesting concepts about CSS and creating more maintainable websites by thinking more semanticly and Craig’s talk about reigniting the magic of the information superhighyway by encoraging designers and developers to spend more time working on those fun ideas we all have, but never do anything about, really rang true with me.

So it’s thanks to events like the Digital Barn that we can all take that step out of our comfort zones and open our selves up to ideas we may not have thought of without them.

So with that I’d like to give a big thanks to Matt and Kimb for organizing the event, and I encourage you to search out a local event near you and see if you can find unexpected inspiration. I for one can’t wait for the next one.

Having spent a fair bit of time playing around with Knockout.js recently (If you haven’t done already I urge you to checkout the Introduction to Knockout JS talk I gave at the Umbraco UK Festival back in November), I thought I’d have a go at writing my own plugin for it.

With that in mind, I introduce to you, Knockout Hotkeys.

Knockout Hotkeys is a custom binding plugin for Knockout that allows you to define global hotkeys for elements in your design, allowing you to effectively develop keyboard driven interfaces.

You can define a hotkey by using one of three binding attributes

•     hotkeydown
•     hotkeyup
•     hotkeypress

The actual syntax is then as follows (NB: Modifier keys should be defined in alphabetical order, ie alt+ctrl+shift):

<input type="text" data-bind="hotkeydown: { shift1 : doSomething }" />

If you would prefer your key combinations to be a little more readable, you can also define them in the following format:

<input type="text" data-bind="hotkeydown: { 'shift+1' : doSomething }" />

You can also register multiple hotkey combos within a single binding statement as follows:

<input type="text" data-bind="hotkeydown: [{ 'shift+1' : doSomething }, { 'shift+2' : doSomethingElse }]" />

In addition to the key combination option, you can also provide an if statement which must be met to allow the hotkey to trigger:

<input type="text" data-bind="hotkeydown: { 'shift+1' : doSomething, if: currentItem() == $data }" />

Lastley, you can also use a more verbose syntax to allow the creating of dynamic key combinations:

<input type="text" data-bind="hotkeydown: { key: 'shift+' + $data.substr(0,1).toLowerCase(),  do: doSomething }" />

If you’d like to give Knockout Hotkeys ago, you can grab it now over on bitbucket.

All in all, it’s been a lot of fun creating this plugin. The more I explore Knockout, the more I love it. From the beautiful syntax, to the amazing documentation. I wish more libraries could be like this.

So for for anybody who attended the Umbraco UK Festival this November, you may or may not have seen my talk on An Introduction to Knockout JS. If you did, you made a great choice. If you didn’t, shame on you =)

Anyway, thanks to the guys at The Cogworks, you can now see my talk online. If you came to my talk, you get the chance to relive the wonderment, and if you didn’t come, you can see what a great show you missed.

In addition to the video, you can review my slides over on slideshare…

…try out my demos online…

Demo 1 – Colour Picker
Demo 2 – Todo List

…and download the source code for yourself

Demo 1 – Colour Picker
Demo 2 – Todo List

I hope everyone who was there, or who watches it online, finds it useful, and gives them enough of a intro to make them want to try it out. It really is a great framework.

So what you waiting for, knock yourself out =)

Update – February 13th, 2012 10:32

Have updated both the slides and the demos to use the latest Knockout features as demoed at the Digital Barn event.

NB: Permissions were introduced in Alpha 3, however some of the features listed below are currently only available in the nightly builds.

More Types
In Umbraco v4, if you ever looked at the permissions grid, you’ll notice that each permission related to a context menu item in the content tree. So in v4, permissions basically allowed you to see or not see a specific menu item. In v5, we continue to support this mechanism, but we also allow none menu item related permissions aswell, which pretty much allows us to everything else detailed in this article.

Better Integration
In v5, we not only block access to menu items, but we can also block direct access to the associated controller actions, so even if someone jumps to an editor screen directly, they still can’t get access.

In addition, we also support toolbar buttons to require permissions, which means users only get to see the buttons they have permission to see. Don’t have the publish permission? then you don’t see the publish button =)

And finally, permissions in v5 work with all hive providers, meaning any tree using a hive provider for it’s data source now supports permissions (protected media anybody?), including third party providers. With this addition, it means permissions are no longer just the domain of the content tree.

Multi-User Group Support
In v4, users could only belong to one User Group, meaning that you could end up creating a lot of User Groups with a lot of cross over, just so you could get the right permission level you wanted for a user. Well, in v5, we now have Multi-User Group support, which means a user can now belong to multiple user groups at once. This means you can maintain fewer, more focused user groups, and just add users to, or remove users from, those groups as needed. And if there is any explicit overlap with any given permission, a “Deny” permission, will always take presidence over an “Allow” permission.

Improved UI
We haven’t just looked at the permissions functionality, but also how we go about setting permissions. In v5 we introduced a new permissions grid to make it simpler to see what is going on. On any node in the tree, you can click the permissions option and see the current nodes permissions. The new permissions grid can show you it’s inherited value, and allows you to override a value easily. Additionally, any changes are easily identifiable with the previous value taking on a grey background, and a little icon being added next to the permission name to signify a change.

Custom Permissions
And finally, as with most things in v5, Permissions are extendible. This means, package developers can introduce their own permissions. It’s as simple as creating a class that extends our base permission class, then just use our UmbracoAuthorize attribute on any menu items, controller actions or toolbar buttons you want protected.

Well that’s about it as it stands today, but we are looking to push permissions even further, for example, in the future we’d like to add the possibility of adding permissions to EntitySchemas thus allowing us to allow / deny access to specific properties of an entity.

So hopefully you now see some of the improvements in the permissions model in v5, and how these improvements make the whole system more secure and extendible. And as always, if you do have any questions, don’t hesitate to leave a comment.

With this change, I thought I’d have a go at updating my build scripts so that I can continue to automate the package creation process. After a quick search, I couldn’t find any specific MSBuild tasks for NuGet package creation, so I went and wrote some =)

So here is the updated process.

Prerequisites

As I’m using MSBuild, you’ll obviously need to have the .NET framework installed. In addition, you’ll need to download the NuGet.exe command line executable from Codeplex, and my custom MSBuild.NuGet.Tasks dll and targets file.

Project Structure

Now this is completely up to you, but for this example and for my own projects, this is the project structure I use.

• Lib - Referenced 3rd party libraries
• Src - Source code for your application
  • MyProject - Project folder
    • MyProject.proj - Project file
• Tools - Build tools
  • MSBuildNuGetTasks - The NuGet MSBuild tasks
  • NuGet - The NuGet command line executable
• MyProject.sln – The project solution file
• Package.build.cmd - The command file for triggering the package build process
• Package.build.xml - The package MSBuild script
• Package.nuspec - The package manifest file

Package.nuspec

This is the manifest file for your package. The manifest is responsible for holding all the metadata about your package such as name, version and description aswell as listing the package files and, in the future, your package dependencies.

If you actually looked at the package manifest files in v4, then these will actually look pretty similar. The namespaces might have changed a little, but the function is exactly the same.

What follows is a demo manifest file.

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>MyPackage</id>
    <version>0.0.0</version>
    <title>My Package</title>
    <authors>Matt Brailsford</authors>
    <owners>Matt Brailsford</owners>
    <projectUrl>http://blog.mattbrailsford.com</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>My Package Description</description>
    <summary>My Package Summary</summary>
    <language />
  </metadata>
  <files />
</package>

Package.build.xml

This is the build script for the package, and is responsible for orchestrating the build process. This hasn’t actually changed that much from my original build script, with the only real difference being a different packaging task (the ManifestUpdate task has also been updated, but the signature is pretty much the same as before). The options on the pack task exactly match those of the pack command of the NuGet command line tool.

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" DefaultTargets="Package">

  <!--
  	****************************************
  	* IMPORTS
	****************************************
  -->
  <PropertyGroup>
  	<MSBuildNuGetTasksPath>$(MSBuildProjectDirectory)\Tools\MSBuildNuGetTasks</MSBuildNuGetTasksPath>
  </PropertyGroup>

  <Import Project="$(MSBuildNuGetTasksPath)\MSBuild.NuGet.Tasks.Targets" />

  <!--
  	****************************************
  	* PROPERTIES
	****************************************
  -->
  <PropertyGroup>
	<PackageVersion>1.0</PackageVersion>
  </PropertyGroup>

  <PropertyGroup>
	<RootDir>$(MSBuildProjectDirectory)</RootDir>
	<BuildDir>$(RootDir)\Build</BuildDir>
	<PackageDir>$(RootDir)\Package</PackageDir>
	<ProjectDir>$(RootDir)\Src\Namespace.MyProject</ProjectDir>
  </PropertyGroup>

  <!--
  	****************************************
  	* TARGETS
	****************************************
  -->

  <!-- CLEAN -->
  <Target Name="Clean">
	<RemoveDir Directories="$(BuildDir)" Condition="Exists('$(BuildDir)')" />
  	<RemoveDir Directories="$(PackageDir)" Condition="Exists('$(PackageDir)')" />
	<MakeDir Directories="$(BuildDir)" />
  	<MakeDir Directories="$(PackageDir)" />
  </Target>

  <!-- COMPILE -->
  <Target Name="Compile" DependsOnTargets="Clean">
	<MSBuild Projects="$(ProjectDir)\Namespace.MyProject.csproj" />
  </Target>

  <!-- PREPAIRE FILES -->
  <Target Name="PrepairFiles" DependsOnTargets="Compile">
    <ItemGroup>
      <BinFiles Include="$(ProjectDir)\Bin\Namespace.MyProject.dll" />
      <ViewFiles Include="$(ProjectDir)\Views\*.cshtml" />
      <PackageFile Include="$(RootDir)\Package.nuspec" />
    </ItemGroup>
	<Copy SourceFiles="@(BinFiles)" DestinationFolder="$(BuildDir)\lib" />
	<Copy SourceFiles="@(ViewFiles)" DestinationFolder="$(BuildDir)\content\views" />
	<Copy SourceFiles="@(PackageFile)" DestinationFolder="$(BuildDir)" />
  </Target>

  <!-- MANIFEST -->
  <Target Name="Manifest" DependsOnTargets="PrepairFiles">
	<ItemGroup>
      <ManifestFiles Include="$(BuildDir)\**\*" Exclude="$(BuildDir)\Package.nuspec" />
    </ItemGroup>
	<ManifestUpdate
		ManifestFile="$(BuildDir)\Package.nuspec"
		WorkingDirectory="$(BuildDir)"
		Version="$(PackageVersion)"
	    Files="@(ManifestFiles)" />
  </Target>

  <!-- PACKAGE -->
  <Target Name="Package" DependsOnTargets="Manifest">
	<Pack NuGetExePath="$(RootDir)\Tools\NuGet\NuGet.exe"
		ManifestFile="$(BuildDir)\Package.nuspec"
		BasePath="$(BuildDir)"
		OutputDirectory="$(PackageDir)"
		Verbose="true" />
  </Target>

</Project>

Package.build.cmd

This is a simple command script and is responsible for triggering the build process. Again, this hasn’t changed greatly from before, with the only change being and update to the msbuild executable used.

C:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\msbuild.exe Package.build.xml

Conclusion

All in all, there haven’t been any huge changes to the script from before, with the majority of the changes being hidden away in the MSBuild tasks. Hopefully this will make it easier for people who used my script before to make the leap into v5. As an added bonus, since Umbraco packages in v5 are just plain old NuGet packages, these MSBuild tasks can actually be used for creating any other kind of NuGet packages aswell.

Happy packaging =)

On a few occasions now, I’ve been asked whether it’s possible for the Desktop Media Uploader for Umbraco package could be made to support custom folders, to which, unfortunatley, the current answer is no. Rather than explain the reasons why every time the question pops up, I just thought I’d write a quick blog post instead.

1. Umbraco media has no “Folder” concept
The first reason is that Umbraco doesn’t really have the concept of a “Folder”. In Umbraco Folders and Files are the same, they are all just Media Types with differing “allowed child media types”. Ok, so I could check all media types to see if they allow sub media types, but that leads me on to reason 2.

2. Desktop Media Uploads are created File first 
When uploading a file via Desktop Media Uploader, the server automatically works out what Media Type to create a media item based upon it’s extension. The problem with this is that that it’s not until the file is uploaded that you would be able to discover whether the file can actually be created in the desired location. By only supporting the “Folder” Media Type, we don’t have that problem, as the “Folder” type can handle all Media Types, or, if it can’t, we can be sure at a bare minimum it can support the “File” Media Type as a fall back. With a custom folder, it could be possible to have no fall back media type, leaving us no option to deny the upload and report an error.

3. Folders don’t exist
The final reason, and this is more to do with the actual uploading of folders, is the fact that folders don’t actually have any physical attributes to be able to discover how to handle them. With files, we can check the file extension, and decide how to handle it, but with folders, that’s not possible. Team this then with “File first” upload issue mentioned above, and you can really start to get into a mess. What if you upload a folder that is not allowed in that location? All files in that folder would fail, and it would require the user to then log in to the CMS and rectify the issue.

I’m pretty sure that these things may be possible to fix, but the point of Desktop Media Uploader has always been to suite the largest majority of Umbraco users, and to not over complicate the process. I have made it extendable by supporting custom Media Types for files, but in my honest opinion, supporting custom folders just isn’t worth the payoff.

That said, Desktop Media Uploader is an open source package, and users are more than welcome to look at implementing this themselves, and if anyone was to do this, I’d be more than happy to review the code and merge the changes in if feel they don’t compromise the current  functionality.

http://dmu4umb.codeplex.com/SourceControl/list/changesets

Happy uploading.

Today however, I was helping out a newcomer to Umbraco who asked what to me was a very fundamental question:

@mcDarke is there like a diagram that shows the architecture of umbraco..?

What a great question. Pretty much every Umbraco developer will have asked that question at some point, but yet the answer to his question was “no”. Rather than just just saying no though, and risking the loss of another potential member of the already awesome community, I thought I’d quickly draw one myself, so here it is, the anatomy of an Umbraco page.

Needless to say, it was exactly what he needed.

@mcDarke that is what I wanted basically…lol….THANKS….Umbraco guys are cool

It was only after it got retweeted several times though that I truly realized just how helpful the diagram is, so instead of just letting it get lost in the twittersphere, I thought it would be a good idea to create a blog post around it so that others might find it as they join the community.

I hope this goes some ways to explaining to newcomers what us Umbraco veterans take for granted. And if not, by all means leave a comment and I’ll see if I can improve it.

Update – April 7th, 2011 14:07

If you are after a diagram of the Umbraco database structure, then be sure to checkout Hendy Racher’s posts on the subject:

http://blog.hendyracher.co.uk/umbraco-database-part-1/
http://blog.hendyracher.co.uk/umbraco-database-part-2/

And there is also a really detailed database diagram by the guys at Sniper Systems over here:

http://snipersystems.co.nz/community/umbracodb.png

Update – April 8th, 2011 04:40

Whilst the aim of my diagram was to sum up the core concept of Umbraco as simply as possible, Jesper Hauge has done a nice job of creating a more thorough diagram of all the parts that make up a Document. So if you find my diagram lacking in any way, you may want to head over to his blog and take a look at his version. Nice work Jesper.

Update – June 7th, 2011 07:35

Thanks to Adam Shallcross over at The Cogworks, another version of my diagram has been made available. This one is available in .EPS & .PDF formats, and is a little more presentation friendly. You can grab a copy right here.

After reading a blog post by Aaron Powell, it got me thinking though. Why not use IIS Express to dynamically serve a directory as and when I need it? So with that, I knocked together a simple .vbs script you can drop in your “Send To” context menu folder (C:\Users\[YOUR_USERNAME]\AppData\Roaming\Microsoft\Windows\SendTo\), which will launch an IIS Express instance with it’s path attribute set to the “Sent” folders path, and it’s port attribute set to a random number between 1024 and 9999. The script will also then launch the generated URL in your default web browser. When you want to shutdown the web server, you can stop it using the IIS Express System Tray context menu.

If you’d like to try this yourself, just drop the following into a .vbs file and save it to your “Send To” folder.

' Init randomization
Randomize

' Set random port number
Dim port
port = Int(Rnd() * 8974) + 1025

' Launch IIS Express / Browser
Set WshShell = CreateObject("WScript.Shell")
WshShell.Run """%programfiles%\iis express\iisexpress"" /path:""" & WScript.Arguments.Item(0) & """ /port:" & CStr(port) & " /systray:true", 0, False
WshShell.Run "http://localhost:" & CStr(port), 9, False
Set WshShell = Nothing

UPDATE – March 15, 2011 12:25

As highlighted by Lee Kelleher in the comments, if you are using a 64bit OS, then please make sure to change %programfiles% to %programfiles(x86)%

Within the macro properties tab, simply set the cache duration and optionaly check one or more options on how you want to cache the Macro.

If no options are checked, the Macro will be cached for the cache period regardless. Checking the Cache by Page option, caches the Macros output on a page per page basis, and checking Cache Personlized caches the Macros output per Member. You can also combine the two options to cache on a per page and per Member basis.

For me though, there is one option missing, which is the ability to cache a Macro based upon a QueryString value. This is needed for things like paged lists, or where you have one page, that does multiple tasks based upon a QueryString parameter (You could get around this by using URL rewriting, but that’s not always an option). Recently, a few of us stumbled across a solution.

When you set a Macro to cache, Umbraco generates a key to cache that Macro by.

<umbraco:Macro Alias="TestMacro" runat="server"></umbraco:Macro>

In the example above, because we have the Cache by Page option set, the key is made up of the page id, and the Macro alias. One usefull thing to know about how this key is generated (and what will ultimatley make caching by QueryString possible) is that if we have any parameters defined on the Macro, the value of these will also be included.

<umbraco:Macro Alias="TestMacro" runat="server" TestParam="testparam"></umbraco:Macro>

In the example above, our Macro now has a parameter defined with its value set to “testparam“, which has also been included in the cache key. I know what you are thinking, “but this is a hardcoded value”, and you are right, but there is a way to set a Macro parameter to a QueryString value. This is done using the [@...] Macro parameter syntax.

<umbraco:Macro Alias="TestMacro" runat="server" TestParam="[@MyQueryStringKey]"></umbraco:Macro>

Now when we request our page, the TestParam property is set to the value of the MyQueryStringKey parameter, which in turn is then used as the cache key for the Macro.

Any change to the MyQueryStringKey will result in a new cache key, and will create a new cached instance of the Macro.

One final little tip. The cache key is actually generated based upon the attributes defined on the Macro server contol tag itself, regardless of whether these map to properties defined on the Macro in the Umbraco UI, so if you don’t actually need to know the value of the QueryString parameter, you can just define the attribute on the Macro server control tag, and not define it as an actual parameter for the Macro, and it will still work.

So there we have it, how to cache a Macro by QueryString parameter.