Documentation.xml

<?xml version="1.0" encoding="utf-8" ?>
<Documentation>
  <Razor>
    <remarks>
      <para>
        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, <a href="http://haacked.com/archive/2011/01/06/razor-syntax-quick-reference.aspx/">see here for a great introduction to the syntax</a>.
      </para>
      
      <h2>View Model</h2>
      <para>
        The view model for each page is the <c>IDocument</c> of the input document. This allows you to write statements like <c>@Model.Get&lt;string&gt;("MyMetadataKey")</c>.
      </para>

      <h2>View Properties</h2>
      <para>
        You also have access to other Wyam information from your view. The following properties are available on every page:
      </para>
      <list type="bullet">
        <item>
          <description>
            <c>Metadata</c>: Contains the metadata of the current document. This is the same as <c>Model</c>.
          </description>
        </item>
        <item>
          <description>
            <c>ExecutionContext</c>: Contains the Wyam <c>IExecutionContext</c> which has information about the currently executing Wyam pipeline.
          </description>
        </item>
        <item>
          <description>
            <c>Documents</c>: Contains the Wyam <c>IDocumentCollection</c> which holds all processed documents and provides various means of accessing them.
          </description>
        </item>
      </list>

      <h2>ViewStart</h2>
      <para>
        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.
      </para>

      <h2>Layouts</h2>
      <para>
        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 <c>@RenderBody()</c> and <c>@RenderSection()</c> just as you would in ASP.NET MVC.
      </para>

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

      <h2>HtmlHelpers</h2>
      <para>
        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 <c>HtmlHelperExtensions</c> or <c>HtmlExtensions</c>). Then 
        add static extension methods for <c>HtmlHelper</c>. For example:
        <code>
public static class HtmlHelperExtensions
{
  public static string HelloWorld(this HtmlHelper helper)
  {
    return "Hello World!";
  }
}

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

      <h2>Base Page</h2>
      <para>
        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 <c>RazorPage</c>. Then page the <c>Type</c> of your new base class to the <c>Razor</c> module.
        <code>
public abstract class MyRazorPage : RazorPage
{
  public string HelloWorld
  {
    get { return "Hello World"; }
  }
}

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