Using Razor partials (cshtml) with Aurelia components


In this post I would like to demostrate how to use Aurelia with Razor views.
In virtually every Aurelia post (at the time of writing) you see people follow the convention of ./bar/foo.js has a template ./bar/foo.html.

Don't get me wrong it's a great, simple and elegant way of doing things.

But what if you want to mix Server-side code with your template?

Use case: Translations

And immediate use case that comes to mind are .NET Resx files.
Easy to use in your Razor Views or in Server-side code.

Project Setup

The code name for this project will be Sliding Ninth Lantern. We'll create a new ASP MVC application and setup jspm for our packages.

jspm init

We will choose all the default options expect for the ES transpiler,
I'm more in favor of Babel.

Lastly we need to download our aurelia packages.

 jspm install aurelia-framework
 jspm install aurelia-bootstrapper
 jspm install aurelia-logging-console

Create an Aurelia Component

We are going to create a simple component that contains our app. By convention this would be app.js but for this post we are going to create a Lantern class.

Nothing special, just an ES6 class View-Model.

Creating the View

Instead on a html page, let's create a razor partial to represent our view.
We'll be using a poco model object to illustrate the usage of Resources on the server.

Bootstrapping the Aurelia application

Time to configure Aurelia in our _Layout.cshtml.

System.import("aurelia-bootstrapper") will look for an aurelia-app attribute to know which DOM node to host the app in. By convention it will then look for app.js as Root View-Model and app.html as template.

But we want to use our lantern.js View-Model instead. In order to do this we need to bootstrap the app ourselve in a configuration file.

That's where main.js comes in. In configure(aurelia) we set up logging and wire our Root View-Model ./Scripts/lantern up to the <body> node.

When we launch the website, Aurelia will throw an 404 error. By convention it's looking for a view in ./Scripts/lantern.html. Since we don't have that we'll need to find another solution.

Overriding the ConventionalViewStrategy

The Aurelia docs point out that you can modify the View and View-Model-Conventions..

So we will override the ConventionalView.convertModuleIdToViewUrl function to map the view to our TemplateController. The TemplateController is Mvc Controller that will return Partial Views.

Wiring up the TemplateController

No real rocket science going on. We just map the moduleId to our GetTemplate Action.
Inside the controller and in the Partial View, we use a the static Resources class to get our translations. And we just send our html to Aurelia.

Be aware that every template request our app would need, it will go to the controller. If you want to use a mixed model of html and Razor, you would need to put some additional logic in the convertModuleIdToViewUrl function.

And Bobs your uncle


  • You can argue wether your should do your translations clientside. There is indeed a great package for this but resources files just work for me.
  • What if you have a like a hunderd templates? Yeah that would mean a hunderd requests and you probable wouldn't want that. I head throught the grapevine that the Aurelia team is working on this.

The Source

It's on CodePlex. Nah just kidding it on my Github.

Final words

I hope this demonstrates the power and flexibility of Aurelia. If you don't like a certain piece, you can just swap it out and provide your own implementation.

I'm still rather new to Aurelia so if I have missed anything or something isn't quite right please let me know.

Yours truly,

Florian Verdonck
Florian Verdonck

Florian Verdonck is web & .NET developer. He is passionate about clean code and is eager to learn new technologies.