Spark view engine

Understanding IViewFolder and IViewFile

The Spark library declares two interfaces which provide the ability to locate view files and load their contents. There are very few methods and several implementations of typical view locations are provided, so in most cases the most you will need to do is provide additional configuration.

Spark file patterns

Spark will locate files using a very conventional pattern. These patterns will not change no matter which view folders are configured.

For controller views, the name of the controller and the name of the view are combined, like home\index.spark. If that file does not exist the name of the view is looked for in the Shared folder, like shared\index.spark.

For master layout templates, the name of the master will looked for in the Layouts folder, like layouts\application.spark. If that file does not exist it too will be looked for in the Shared folder, like shared\application.spark.

These patters will be looked for inside the view folder implementations. The view folders will never alter that part of the Spark file pattern, and the patterns won't affect the location of the view folders. This is very different from the behavior of the WebForms view engine which allows you to provide an array of customized virtual paths.

Sorry, but it was simply impossible to give the view engine full control of the entire path and remain compatible with the different frameworks and existing usage. The customized virtual paths are also incompatible with some of the specialized view folder sources.

Default view folder locations

In a Castle MonoRail application the configured IViewSourceLoader is used by the default IViewFolder implementation. The root location of the default IViewSourceLoader is ~/Views and can be changed with the monorail/viewEngines/@viewPathRoot configuration attribute.

In an Asp.Net MVC applications a view folder based on hosting environment's VirtualPathProvider is used. The root location within this will be ~/Views.

The behavior of those abstractions can be controlled in ways that aren't documented here; custom VirtualPathProviders is a large topic all on it's own. Whatever you do to the framework to alter how files are loaded should work with Spark as expected.

What is documented on this page is how to bring in additional IViewFolder implementations to extend the way spark files can be located.

Adding a view folder to config

The <spark> config section accepts a <views> element which can be used to add additional view folder locations.

<spark>
  <views>
    <add name="{any-unique-name}" 
        folderType="FileSystem|EmbeddedResource|VirtualPathProvider|Custom"
        type="{name, assembly of IViewFolder type}"
        constuctor-param-names="values"
        subfolder="{optional subfolder to target}"/>
  </views>
</spark>

For example:

<spark>
  <views>
    <add name="stuff" folderType="EmbeddedResource" assembly="MyExtraStuff" resourcePath="MyExtraStuff.Views"/>
  </views>
</spark>

Understanding the subfolder parameter

The subfolder parameter will make the contents for a view folder appear at a specific location in the logical views directory. In other words you're adding files, but you're adding them at a subdirectory.

For example if you create a ~/Masters directory in your web app you could expose it in place with the following:

<spark>
  <views>
    <add name="morestuff" folderType="VirtualPathProvider" subfolder="layouts" virtualBaseDir="~/Masters"/>
  </views>
</spark>

Any path can be the target for adding additional files. If no subfolder is provided the contents are added at the root.