Working with Spark

Working with Spark

Spark support in FubuMVC works in a way that follows the FubuMVC mindset yet retains most of the good parts from Spark. In order to have views picked up and attached conventionally by FubuMVC we scan for all files that are of relevance to FubuMVC.Spark during the bootstrapping of a web application and build up a metadata model. This model holds information about the files and their interrelations.

The templates we define as valid views for action calls have a view model type specified. Thus, the reliance on being able to deduce the view model of a Spark view is crucial. We require that a <use viewdata model="..."/> is specified in a view. See the section about "Views" for the particulars.

Spark support encompasses both views from a web application and views from its installed packages. A web application with multiple packages entails some restrictions on how views are organized and picked up, i.e. some sort of isolation is needed. In order to avoid template conflicts the following isolation rules are applied:

• A web application picks up templates from its own folders excluding all package folders.

• A package picks up templates from its own folders plus from dedicated shared folders in the web application. This means templates like master page, bindings, macros and so on.

• Templates are not shared among packages.

Note that we do not support all features mentioned in the Spark documentation - The general idea is support what we find most useful and natural in a FubuMVC environment. If you encounter some parts that are lacking then please feel free to contact us on the mailing list and we might be able to figure something out :)

How to use it

In order to enable Spark support for your web application you have two choices. You can either choose to use FubuMVC.Spark by adding a project reference to it and specify the following in of your FubuRegistry class:

this.UseSpark();

The second approach is to install the FubuMVC.Spark package into your web application - this approach does not require explicit reference to the FubuMVC.Spark project nor changes to your FubuRegistry. [TODO: clarify steps to create and/or use a package - or to get our provided package]

Views

The central piece in view attachment is the view model type (corresponding output type on action call). We require that you specify the full type name of a view model in your view, e.g. <use viewmodel="full.type.name"/>. This causes it to be picked up if some action call has that output type. [TODO: mention action less views (Josh)]

Given that views are picked up by view model type enables support for built-in view attachment conventions in FubuMVC:

• by_ViewModel_and_Namespace_and_MethodName()
• by_ViewModel_and_Namespace()
• by_ViewModel()

You are free to organize your views at will. For instance, place them in the same folder as their corresponding controller or in a folder that contains all your views. If you have multiple views with same view model type then placement of your ".spark" matters.

When views are registered by FubuMVC.Spark, a log that records the process is available from diagnostics (/_fubu/fulllog). The log records information about each view with regards to master page, view model and bindings available.

Master pages

• Master page search algorithm: [describe generally then package behavior]

Master page declaration in your view:

• Implicit master page : Assumes "Application.spark".

• Explicit master page : E.g. <use master="Admininistration"/>

• Suppressing master page : <use master=""/> entails that no master page is used.

• Packages

Bindings

• Bindings search algorithm:...[describe generally then package behavior]
• Packages
• Overrulings

Render strategies:

• Normal rendering - master page, if any, is used.
• Nested rendering (invoked via Partial) - master less version is used.
• Ajax request rendering - master less version is used.
• Custom strategy...

Configuration

• Parts that you can configure via DSL [master name, bindings name, shared folder names]
• Pluggable parts you can replace...

##Caveats

• [Describe assembly name + view folder approach for namespace and its limitations]

• If you have two output types with the same full type name then we do not attempt to create a viewtoken of it. This is reported in the log.

• Implicit master page is "Application.spark" - We will allow for DSL overruling on this.

• Currently we just look for bindings called "bindings.xml" - We will allow for DSL overruling.

• You need to specify full type name. We do not (currently) account for <use namespace="..."/>.

Not supported

• We only support C# for view generated code.
• Support for including files with <include href=""> in ".spark" templates (medium effort needed).
• Dynamic viewdata in the form of <use viewdata Caption="string"/> is currently not supported (low effort needed).
• Caching in the form of is not currently supported (low effort needed).