Razor Wyam.Razor

Parses, compiles, and renders Razor templates.

Razor is the template language used by ASP.NET MVC. This module can parse and compile Razor templates and then render them to HTML. While a bit outdated, this guide is a good quick reference for the Razor language syntax. This module uses the Razor engine from ASP.NET Core.

Whenever possible, the same conventions as the Razor engine in ASP.NET MVC were used. It's important to keep in mind however, that this is not ASP.NET MVC. Many features you may be used to will not work (like most of the HtmlHelper extensions) and others just don't make sense (like the concept of actions and controllers). Also, while property names and classes in the two engines have similar names(such as HtmlHelper) they are not the same, and code intended to extend the capabilities of Razor in ASP.NET MVC probably won't work. That said, a lot of functionality does function the same as it does in ASP.NET MVC.

Razor is an extremely powerful templating language, especially if you already know C#. Writing a simple Razor template is easy, but there are a lot of ways they can be customized and controlled. If you're not familiar with Razor templates, see here for a great introduction to the syntax.

View Model

The view model for each page is the IDocument of the input document. This allows you to write statements like @Model.Get<string>("MyMetadataKey").

View Properties

You also have access to other Wyam information from your view. The following properties are available on every page:

  • Metadata: Contains the metadata of the current document. This is the same as Model.
  • ExecutionContext: Contains the Wyam IExecutionContext which has information about the currently executing Wyam pipeline.
  • Documents: Contains the Wyam IDocumentCollection which holds all processed documents and provides various means of accessing them.

ViewStart

You can place common Razor code to be executed at the start of every Razor page in a "_ViewStart.cshtml" file. This is typically used to specify a layout page.

Layouts

Layouts function much the same way as they do in ASP.NET MVC. Typically you place your layout code in a "_Layout.cshtml" file (though it can be named anything) and then set it in the "_ViewStart.cshtml" file. You can use @RenderBody() and @RenderSection() just as you would in ASP.NET MVC.

Partials

Partials also work as they do in ASP.NET MVC. Just use @Html.Partial("_PartialName") or @Html.RenderPartial("_PartialName"). Note that you can't pass a model to the partial view (since the model is always set to the current IDocument). To pass data to a partial view, use the ViewData collection, setting a value just before rendering the partial and then getting it within the partial.

HtmlHelpers

It's possible to define custom HtmlHelpers in your configuration file and then use them within your Razor page. This provides a great way to specify common behavior for all your views. In the declarations section of your configuration file, add a static class (the name doesn't matter, but convention suggests you call it HtmlHelperExtensions or HtmlExtensions). Then add static extension methods for HtmlHelper. For example:


public static class HtmlHelperExtensions
{
  public static string HelloWorld(this HtmlHelper helper)
  {
    return "Hello World!";
  }
}

// Configuration code
// Set up your pipelines here
        
Then you can use it from your Razor pages by calling @Html.HelloWorld().

Base Page

You can also specify a different base page for your Razor views. This lets you do things like define additional properties or behavior for every page. In the declarations section of your configuration file, add an abstract class that derives from RazorPage. Then page the Type of your new base class to the Razor module.


public abstract class MyRazorPage : RazorPage
{
  public string HelloWorld
  {
    get { return "Hello World"; }
  }
}

Pipelines.Add("Content",
  ReadFiles("*.cshtml"),
  Razor(typeof(MyRazorPage)),
  WriteFiles(".html")
);
        
Then you can use any methods, properties, etc. you defined in your base class directly within your Razor pages - I.e., @HelloWorld.

Package

This module exists in the Wyam.Razor package which is not part of the core distribution. Add the following preprocessor directive to your configuration file to use it:
#n Wyam.Razor
Alternativly, you can add all modules at once with the following preprocessor directive:
#n Wyam.All

Usage

  • Razor(Type basePageType = null)

    Parses Razor templates in each input document and outputs documents with rendered HTML content. If basePageType is specified, it will be used as the base type for Razor pages. The new base type must derive from WyamRazorPage<TModel>.

    • basePageType

      Type of the base Razor page class, or null for the default base class.

Fluent Methods

Chain these methods together after the constructor to modify behavior.

  • IgnorePrefix(string prefix)

    Specifies a file prefix to ignore. If a document has a metadata value for SourceFileName and that metadata value starts with the specified prefix, that document will not be processed or output by the module. By default, the Razor module ignores all documents prefixed with an underscore (_). Specifying null will result in no documents being ignored.

    • prefix

      The file prefix to ignore.

  • WithLayout(DocumentConfig path)

    Specifies a layout file to use for all Razor pages processed by this module. This lets you specify a different layout file for each document.

    • path

      A delegate that should return the layout path as a FilePath.

  • WithLayout(FilePath path)

    Specifies a layout file to use for all Razor pages processed by this module.

    • path

      The path to the layout file.

  • WithModel(DocumentConfig model)

    Specifies a model to use for each page based on the current input document and context.

    • model

      A delegate that returns the model.

  • WithModel(object model)

    Specifies a model to use for each page.

    • model

      The model.

  • WithViewStart(DocumentConfig path)

    Specifies an alternate ViewStart file to use for all Razor pages processed by this module. This lets you specify a different ViewStart file for each document. For example, you could return a ViewStart based on document location or document metadata. Returning null from the function reverts back to the default ViewStart search behavior for that document.

    • path

      A delegate that should return the ViewStart path as a FilePath, or null for the default ViewStart search behavior.

  • WithViewStart(FilePath path)

    Specifies an alternate ViewStart file to use for all Razor pages processed by this module.

    • path

      The path to the alternate ViewStart file.

Input Metadata

The metadata values listed below apply to individual documents and are typically set from front matter (with just the name of the key) and used as inputs to the module to control behavior.

  • Keys.SourceFileName: Wyam.Common.IO.FilePath

    Used to determine if the source file name contains the ignore prefix.

GitHub