john coder

I uploaded a NuGet package for a C# library called Mimeo. It is a templating library that allows you to define a template language from a type. The project is open source, and you can find it on bitbucket.

This post is a part of a series:

1. Introducing: Mimeo
2. Mimeo - Block Tokens
3. Mimeo - Conditional Tokens
4. Mimeo - Interpolation
5. Mimeo - Theming Your ASP.NET MVC3 Application
6. Mimeo - Design Philosophy

installation

To install the project, type "mimeo" into the "Add Library Package Reference" dialog search box and click install. Or, if you prefer the command line, enter this command:

PM> Install-Package Mimeo

Installing the package adds a reference to your project for Mimeo.dll. Now, you're ready to get started using the templating engine.

defining tokens

The example will be a simple command line application. In that application, we have a class called Person:

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}

It would be nice to have an instance of Person, and say "Render this person, please." That's where the templating engine comes in. Using the Person type, we are able to define a set of tokens that can be used inside of a template. The library has a Mimeographs class that stores a bunch of Mimeograph objects. Each Mimeograph object has a collection of stencils (generated from templates) that can be used to render an object.

var mimeographs = new Mimeographs();

Then, define a new Mimeograph for the Person type:

var mimeograph = new Mimeograph<Person>(builder =>
{
    builder.Tokenize(p => p.FirstName, "@FirstName");
    builder.Tokenize(p => p.LastName, "@LastName");
    builder.Tokenize(p => p.Age.ToString(), "@Age");
});
mimeographs.Add(mimeograph);

In this snippet the builder represents a TokenBuilder object, which has methods for tokenizing values using the model type of the Mimeograph object. Let's hone in on the Tokenize calls a bit.

builder.Tokenize(p => p.FirstName, "@FirstName");

This line is saying that whenever you see "@FirstName" in the template, replace it with the value of the Person object's FirstName property. You might notice that the token for "@Age" is mapped to p.Age.ToString(). Since all of the replacements are done using strings, explicit conversions are necessary. This is tokenizing in its simplest form. More complicated tokenizing scenarios exist, such as conditional, blocking, and interpolated tokens (I'll soon cover each of those in greater detail).

templates

Now that we've expressed a set of tokens for templating the Person object, let's use those tokens in a custom template.

==========
@FirstName @LastName is a Person who is @Age years old.
==========

You can read the template from a file (or wherever), and create a stencil from it.

mimeographs.CreateStencil<Person>("person-template", template);

The template was created with the name "person-template". Many stencils can be created for the same type, as long as they have a unique name. If the name exists, it will be overwritten with the newly created stencil.

If we instantiate a person like this:

var person = new Person
{
    FirstName = "John",
    LastName = "Nelson",
    Age = 24
};

We are now able to render that person:

var result = mimeographs.Render("person-template", person);
Console.WriteLine(result);

Executing that code will print this message to the screen:

==========
John Nelson is a Person who is 24 years old.
==========

Summary

Defining custom templates and rendering objects with them is easy with Mimeo. It has a lot more functionality, which I will cover in blog posts to come.

Here is a listing of the complete console program code used in this post:

using System;
using Mimeo;

namespace ConsoleApplication1
{
    class Program
    {
        static void Main(string[] args)
        {
            const string template = @"==========
@FirstName @LastName is a Person who is @Age years old.
==========";

            var mimeographs = new Mimeographs();

            var mimeograph = new Mimeograph<Person>(builder =>
            {
                builder.Tokenize(p => p.FirstName, "@FirstName");
                builder.Tokenize(p => p.LastName, "@LastName");
                builder.Tokenize(p => p.Age.ToString(), "@Age");
            });

            mimeographs.Add(mimeograph);
            mimeographs.CreateStencil<Person>("person-template", template);

            var person = new Person
            {
                FirstName = "John",
                LastName = "Nelson",
                Age = 24
            };

            var result = mimeographs.Render("person-template", person);

            Console.WriteLine(result);

            Console.ReadKey();
        }
    }

    public class Person
    {
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public int Age { get; set; }
    }
}