News and Tutorials

Data Moving SPA with a Context-Dependent Menu 2: Url based menu and SEO

Wed, 25 Jun 2014 11:10:54 GMT

Data Moving SPA routing is not based on string Urls but on the “virtualReference” JavaScript class. Each instance of a virtual link contains all information needed to load a new view: view name, module containing the view, view input, and also an optional string property called “role” that has the purpose of giving different names to different instances of the same view. More specifically, the developer has the option to store each view in a page store. This way when the user returns on a previous page he finds it in the same state he left it.: “roles” are needed to distinguish between different stored view instances that play different roles in the interaction with the user.

Usual links are substituted by virtual links containing a virtual references instead of a standard Urls. This solution avoid the burden of encoding all information needed to instantiate a view into a single Url. In fact, the main disadvantages of Url encoding are:

Once view properties have been encoded in a string that is hardcoded in the application sources it becomes difficult to locate them during some re-engineering of the code.
As the application grows a more complex encoding might be required, but locating and substituting Urls spread all over the code is an almost impossible task.

The substitution of Urls with virtual references is acceptable since, usually, we don’t need a SPA be indexed by search engines. However, now the support of search engines for SPAs and for JavaScript is increasing. More specifically:

There is a standard protocol to substitute the dynamic pages of a SPA with static “page snapshots” produced by the server whenever the SPA is visited by a search engine. See here for more details.
Now Google is able to run JavaScript, and to visit also SPA

The above circumstances makes SPA attractive also for standard Web Sites that needs search engines indexing. For this kind of SPAs Urls play the same role they have in standard Web Applications. Namely, they furnish a way to reach all pages that compose the application and, together with all semantic tags, they help search engines to classify properly all pages.

The Url based ko.routing router was conceived as an attempt to keep the SEO advantages of standard Urls while overcoming all disadvantages of keeping information encoded into strings (Urls).

ko.routing may compute dynamically all Urls starting from all parameters that must be encoded in the Urls themselves. This result is obtained by “inverting” the routing rules. The router action method, and the related knockout.js action binding accept the parameters to be extracted from an Url and build the Url that would yield exactly those parameters. They are very similar to the Asp.net Mvc Url.Action method, and have the same purpose of keeping the code completely independent from the routing rules.

The 1.2 release of the Data Moving Controls suite added the support for ko.routing, and offers also SPA project templates based on ko.routing, namely: SPA_Mvc5_ko.routing.vsix and SPA_Mvc4_ko.routing.vsix.

In this post I’ll revisit the Data Moving SPA with a Context-Dependent Menu tutorial with the new ko.routing based visual studio templates. The main difference is that now all menu items will contain actual links with actual Urls.

Building the basic project

You may repeat exactly the same steps of the Data Moving SPA with a Context-Dependent Menu tutorial till the “Defining a Menu to Navigate our SPAViews” section(not included), with the following two differences:

Select the WebApi 2/Mvc 5/ko.routing Single Page Application project template instead of the WebApi 2/Mvc 5/Single Page Application template. Attention: you must install both vsix in VS 2013 since only the second vsix contains the SPAView and SPAModule item templates.
In all Page1.cshtml…Page5.cshtml dynamic JavaScript files supply an appropriate document title: vm._title = “View 1”…vm._title=”View 5”.

Defining a Menu to Navigate our SPAViews

We will add the “Menu” SPAView to the Basic module that is loaded as soon as the application starts, since our menu is needed also in the first loaded page. Right click on the Views/Templates/Basic folder and add a new SPAView called: “Menu”:

In the previous tutorial we built the object tree containing all information to display in the menu on the server side and then we serialized it in JavaScript, in order to take advantage of the Data Moving SimpleMenuBuilder class. Now we can’t do the same since we are going to build all menu Urls with the help of the JavaScript ko.routing action method to keep our code independent from the client side routing rules.

Accordingly as a first step we define a JavaScript menuBuilder class to build our JavaScript object tree with an easy to use fluent interface. We may place this definition at the beginning of the MenuJs.cshtml file:

 <script>
    
    (function () {
        
        function menuBuilder(templateSelection) {
            var currLevel = [];
            var levels = [];
            this.add = function (text, link, target, tSelection) {
                if (mvcct.utils.isObject(link))
                    currLevel.push({
                        Text: text || "",
                        Params: link || null,
                        Link: "/"+ko.routing.action(link),
                        Target: "",
                        UniqueIdentifier: null,
                        Children: null,
                        templateSelection:
                            tSelection || templateSelection
                    });
                else
                    currLevel.push({
                        Text: text || "",
                        Params: null,
                        Link: link || null,
                        Target: target || "",
                        UniqueIdentifier: null,
                        Children: null,
                        templateSelection:
                            tSelection || templateSelection
                    });
                return this;
            };
            this.get = function () {
                return currLevel;
            };
            this.down = function () {
                if (!currLevel.length) return this;
                var father = currLevel[currLevel.length - 1];
                levels.push(currLevel);
                father.Children = currLevel = [];
                
                return this;
            };
            this.up = function () {
                if (!levels.length) return this;
                currLevel = levels.pop();
                return this;
            };
        };
 

The add method adds a new menu item. If just the Text field is passed we define a not clickable Item (typically a father menu item with sub items). If the link target is a string it is interpreted as an Url, otherwise, if it is an object it is interpreted as the set of parameters to be passed to the action method to yield the actual Url. Since all default routing rules patterns contain only the hash part of the Urls(something like #….) and since strings starting with # are interpreted as custom JavaScript click handlers instead of Urls by the menu control we add a leading “/”. The Target parameter is taken into account only for string Urls, since it has no interpretation for the SPA Urls.

Each menu item stores both the computed Url and the original parameters used to compute it, since the parameters are needed to verify if a menu item Url refers to a SPAView the current user has the right to visit or not. Moreover, the original parameters help in verifying if the current SPAView is an instance of the SPAView referenced by an item menu, with some possible input parameter more(simple string comparison between two Urls is able to verify only if both Urls reference the same SPAView with exactly the same input).

The client template used to render each menu item is selected by calling a template selection function that receives the menu data item as argument. In order to ensure the maximum flexibility each menu item has its own template selection function. However if no item specific function is passed, the default template selection function passed as an argument to the menuBuilder constructor is taken.

The down method moves the fluent interface to the definition of the sub-items of the current item, and the up method returns to the definition of the father item.

Finally the get method yields the final object tree.

Now we are ready to build the Menu ViewModel:

 var templateSelection = function (x) {
    if (x.Children.peek()) return 'Basic_MenuItem2';
    var url = x.Link ? x.Link.peek() : null;
    if (url && url.charAt(0) != '@@' && url.charAt(0) != '#') return 'Basic_MenuItem1';
    return 'Basic_MenuItem0';
};
var menuItems = new menuBuilder(templateSelection)
    .add("Home", { module: "Basic", view: "Home" })
    .add("Page 1", { module: "MenuExample", view: "Page1" })
    .add("Page 2", { module: "MenuExample", view: "Page2" })
    .add("Private Area")
        .down()
            .add("Page 3",
                { module: "MenuExample", view: "Page3" })
            .add("Page 4",
                { module: "MenuExample", view: "Page4" })
            .add("Page 5",
            { module: "MenuExample", view: "Page5" })
        .up()
        .add("External Links")
        .down()
            .add("Data Moving Controls",
                "http://www.mvc-controls.com")
            .add("knockout.js",
                "http://knockoutjs.com/", "_blank")
        .up()
    .get();
var viewModelContent = { Children: menuItems};
 

The viewModelContent is the put in place by the standard scaffolded code below:

 vm.Content = ko.mapping.fromJS(viewModelContent);
 

that creates all needed knockout observables an put the new modified model in the ViewModel Content property.

The default template selection function selects 3 different templates: Basic_MenuItem2 for father items with children items, Basic_MenuItem1 for all items that do not contain an Url, and Basic_MenuItem0 for all items containing an Url. Each template name is obtained by chaining a base name declared with the .TemplatesBaseName method of the Menu fluent interface with the the sequence number of the template defined with the Menu fluent interface. Below the content of the Menu.cshtml file:

 @model MVCControlsToolkit.Controls.SimpleMenuItem
 
@{
    var builder = Html.ExtendedClientMenuFor(
        m => m.Children, m => m.Link,
        new { @class = "mainmenu" });
    if (HttpContext.Current.Request.Browser.IsMobileDevice)
    {
        builder = builder.ActiveOnlyOnClick();
    }
    builder.Target(m => m.Target)
    .Radiuses(0.5f, 1f, 0.5f)
    .ItemSelection(structurePathSelectClass: "light-select")
    .TemplatesBaseName("Basic_MenuItem")
    .TemplateSelector(
        "function(x){return x.templateSelection(x);}")
    .AddRowType()
        .StartColumn(m => m.Text)
            .CustomColumnClass(GenericCssClasses.NoWrap)
            .CustomTemplateFixed(TemplateType.Display, 
            @<text>
                <a href="javascript:;">@item._D(m=>m.Text)</a>
            </text>
            )
        .EndColumn()
    .EndRowType()
    .AddRowType()
        .StartColumn(m => m.Text)
            .CustomColumnClass(GenericCssClasses.NoWrap)
            .CustomTemplateFixed(TemplateType.Display, 
            @<text>
                @item.LinkFor(m => m.Text, m => m.Link)
            </text>
            )
        .EndColumn()
    .EndRowType()
    .AddRowType()
        .StartColumn(m => m.Text)
            .CustomTemplateFixed(TemplateType.Display, 
            @<text>
                <a href="javascript:;">@item._D(m=>m.Text)</a>
            </text>
            )
        .EndColumn()
        .ChildCollection(m => m.Children)
    .EndRowType();
 
}
@builder.Render()
 

The ExtendedClientMenuFor Html<T> extension declares the root menu items collection, the property that contains the level 0 menu items, and the menu data item property that contains the “action” to execute when the menu item is selected.Then, ExtendedClientMenuFor returns a fluent interface to continue the menu configuration. The root Menu ul tag contains the mainmenu Css class that defines some <ul> and <li> structural properties, and that removes underlining from all menu links.

The above definitions must be appended to the Content/Site.css file. You may experiment by changing some of them.

As a default sub-menus appear when the mouse hover their father menu item, but If the client device is a mobile device the call to ActiveOnlyOnClick() change this behavior, and sub-menus are open on “click” or “tap”.

Then we declare which item property contains the target where to open links, and the various menu items radiuses (see the picture that shows the three radiuses here ).

The way each menu item is rendered is defined by 3 templates, that are configured inside 3 AddRowType()-EndRowType() blocks. All templates have an unique column based on a custom template. The addition of the GenericClasses.NoWrap Data Moving predefined Css class prevents menu item titles from wrapping. The ChildCollection call in the last template causes the recursive rendering of all children sub items contained in the Children property. All AddRowType blocks define knockout client templates. Their names are obtained by adding the postfixes ‘0’ and ‘1’ and ‘2’ to the template base name “Basic_MenuItem” declared with TemplateBaseName. It is good practice to give names of the type <module name>_<a name> to all client templates used by controls declared inside SPAViews.

The selection of the right template is performed by the template selection function declared with TemplateSelector. In our case a function declared on line recalls the default template selection method previously defined in each menu data item.

That’s enough to see the menu working! Now you may run the application and enjoy your Menu!

Adapting the Menu to the Current Page and to the Current Logged User

Now, our last objective is to adapt the menu to the logged user and to the actual SPAView that is in the main host. More specifically:

Each time the user changes the menu must display just the items the new user has the right to access, that is: if all sub-menus of a father menu item are not visible and if the father menu item itself doesn’t connect to a SPAView the user may access, the father menu item must be invisible
The menu item that connects to the actual SPAView that is in the main host must appear in a “selected state”.

Both requirements may be achieved by letting the content ViewModel of our menu implements an interface, say,IContextDependent with two methods:

authorize(), that adapts the SPAView (our menu SPAView) to the authorizations of the current user.
select(x), that informs the SPAView (our menu SPAView) that the SPAView x is currently in the main host. Where x is a string with the same format of the Link property of our menu data items.

In general we may handle several SPAViews that implements the IContextDependent interface in a modular way as follows:

We define a IContextDependent resource handler with methods to register and unregister IContextDependent implementations for being properly handled by the application.
Each time a SPAView that implements IContextDependent, is loaded it registers itself to the IContextDependent resource handler, and then it unregisters itself when it is unloaded.
Whenever the current user changes, the IContextDependent resource handler is notified and calls the authorize() method of all registered IContextDependent implementations.
Whenever the current SPAView in the main host changes the the IContextDependent resource handler is notified and calls the select(x) method of all registered IContextDependent implementations.

We may define the class that implements the IContextDependent resource handler in the Views/Templates/Application/MainJs.cshtml file next to the definition of the uiBlockInterface class:

 var iContextDependentHandler = function () {
    var registrations = [];
    this.register = function (x) {
        registrations.push(x);
    };
    this.unregister = function (x) {
        var index = -1;
        for (var i = 0; i < registrations.length; i++) {
            if (registrations[i] == x) {
                index = i;
                break;
            }
        }
        if (index > -1) {
            array.splice(index, 1);
        }
    };
    this.select = function (x) {
        for (var i = 0; i < registrations.length; i++) {
            var item = registrations[i];
            if (item.select) item.select(x);
        }
    };
    this.authorize = function () {
        for (var i = 0; i < registrations.length; i++) {
            var item = registrations[i];
            if (item.authorize) item.authorize();
        }
    }
}
 

Then, we add an instance of this class to the applicationModel.interfaces property, so that it is available within the applicationModel itself and to all SPAViews:

 applicationModel.interfaces.uiBlock = new uiBlockInterface();
applicationModel.interfaces.contextHandler = //<-add here
            new iContextDependentHandler();
 

The IContextDependent.select method must be called each time the router selects a new SPAView is placed in the application main host. Accordingly, let open the Views/Templates/Application/RoutingJs.cshtml file that contain the definition of all routing rules and let add the .select call immediately after the the start of a new SPAView loading:

 (function () {
    ko.routing.defaultAction(function (obj, level, hasChildren) {
        vl = new mvcct.ko.dynamicTemplates
                .virtualReference(obj.module, obj.view, obj.role);
            vl.input = obj;
            applicationModel.MainContent(
                mvcct.ko.dynamicTemplates.defaultPageStore.get(vl));
            setTimeout(function () {// <-- added line
                applicationModel.interfaces.contextHandler.select(obj)
            });
    });
    ko.routing.mainRouter = applicationModel.mainRouter =
        new window.ko.routing.router()
        .route("#!/:module/:view")
        .notFound({ module: "Basic", view: "NotFound" });
})();
 

Since all default routing rules use the default action function our call must be placed only there. The default action uses the view, module and role parameters to create a virtual reference and then passes all parameters extracted by the Url as input to the SPAView (Input property of the virtual reference). Then the virtual link is used to fetch the SPAView from the default page store. If an instance of the required SPAView with the specified role(if any) is already stored it is returned, otherwise a new fresh copy is created (and stored) by the page store possibly downloading the required module from the server. Finally, the newly fetched SPAView is inserted in the main page host (applicationModel.MainContent).

The .select call is wrapped inside a setTimeOut to ensure it be executed only after that all IContextDependent implementations (in our case just the menu) have been loaded when the SPA starts.

The right place where to call IContextDependent.register is the processInput method that is called each time a SPAView is loaded, while the right place to call IContextDependent.unregister is the beforeRemove method that is called before the SPAView is unloaded:

 vm.processInput = function (nodes) {
    @* Code here is executed each time the page is loaded.
        Virtual page inputData must be processed here *@
    vm._interfaces.contextHandler.register(vm.Content);
    modifyDomOnLoad(vm, nodes);
};
 
vm.beforeRemove = function () {
    @* Insert here clean up code to be  executed
        when the page is unloaded*@
    vm._interfaces.contextHandler.unregister(vm.Content);
    cleanupDomOnUnload(vm);
};
 

Now our vm.Content ViewModel must implement the IContextDependent interface. You may place the interface definition immediately before the vm.processInput method definition:

 vm.Content.select = function (obj) {
    if (!obj) {
        if (currentSelected)
            mvcct.html.menu.selected(currentSelected, false);
        currentSelected = null;
        return;
    }
    var res =
        selectMenu(
            ko.utils.unwrapObservable(vm.Content.Children),
            obj);
    if (!res && currentSelected)
        mvcct.html.menu.selected(currentSelected, false);
    currentSelected = res;
};
vm.Content.authorize = function () {
    authorizeMenu(
        mvcct.ko.dynamicTemplates.authorizationManager(),
        vm.Content.Children);
}
vm.Content.authorize();
 

Both methods call two private recursive functions that traverse the menu data items hierarchy to do their job. They are exactly the same of the ones defined in the Data Moving SPA with a Context-Dependent Menu tutorial.

The currentSelected private variable contains the menu data item that is currently selected, if any, otherwise, null. If a null action is passed, currentSelected is set to null and any previously selected menu item is unselected by calling mvcct.html.menu.selected(currentSelected, false).

Otherwise the reclusive selectMenu function tries to locate a menu data item matching the action string. If such a data item is found the menu item it is bound to is set in the selected state by calling: mvcct.html.menu.selected(item, true)and the data item itself is returned in the res variable, so it may substitute the previous currentSelected. If the selectMenu recursive search fails, null is returned in res, and any previously selected item is unselected by calling mvcct.html.menu.selected(currentSelected, false).

The authorize method immediately calls the recursive private function authorizeMenu passing it the current authorization manager, and the level 0 menu data items. The authorizeMenu function traverses the menu data items hierarchy and checks possible links to SPAView against the authorization manager to verify if the SPAView may be accessed by the current user. In case the SPAView referred by a menu data item cannot be accessed by the user, the data item rendering is prevented by setting its _destroy property to true. If a menu item x has the only purpose of showing its children sub-items, and if all its children have _destroy set to true also the _destroy property of x is set to true, since it is completely un-useful.

The private functions selectMenu and authorizeMenu may be placed in the read-only private members area immediately before the mvcct.core.moduleResult call. They differ from the analogous function of the Data Moving SPA with a Context-Dependent Menu tutorial only in the way references to SPAViews are compared:

 function selectMenu(children, obj) {
    for (var i = 0; i < children.length; i++) {
        var item = children[i];
        var toTest = ko.utils.unwrapObservable(item.Params);
        var match = true;
        for (var prop in obj) {
            if (!toTest || ko.utils.unwrapObservable(obj[prop])
                != ko.utils.unwrapObservable(toTest[prop])) {
                match = false;
                break;
            }
        }
        if (match) {
            mvcct.html.menu.selected(item, true);
            return item;
        }
        var iChildren = ko.utils.unwrapObservable(item.Children);
        if (iChildren) {
            var child = selectMenu(iChildren, obj);
            if (child) return child;
        }
    }
    return false;
}
function authorizeMenu(authorizationManager, obsChildren) {
    var children = ko.utils.unwrapObservable(obsChildren);
    if (!children || children.length == 0) return false;
    var hasChildren = false;
 
    var aChange = false;
    for (var i = 0; i < children.length; i++) {
        var item = children[i];
        var action = ko.utils.unwrapObservable(item.Params);
        var virtualLink = action;
        var authorized = false;
        if (virtualLink) {
            authorized =
                !authorizationManager.verifyAuthorization(
                    action
                    );
        }
        else authorized = ko.utils.unwrapObservable(item.Link);
        authorized = authorized || false;
        if (authorized) authorized = true;
        var childrenAuthorized =
            authorizeMenu(authorizationManager, item.Children);
        authorized = authorized || childrenAuthorized;
        if ((item._destroy || false) != !authorized) {
            item._destroy = !authorized;
            aChange = true;
            if (item._destroy) mvcct.ko.unfreeze(item);
        }
        if (authorized) hasChildren = true;
    }
    if (aChange) obsChildren.valueHasMutated();
    return hasChildren;
}
 

It is worth to point out that each time we make invisible a menu item we call the mvcct.ko.unfreeze to release any possible cached template, since most of Data Moving controls cache templates instances to improve performance.

The selectMenu function compares the set of parameters of each menu item with the set of parameters that identifies the current SPAView. If the current SPAView contains some parameters more, the comparison is considered successful since those parameters are further specifications of the input contained in the menu item.

Now the context dependent menu is ready. Whenever you navigate to a SPAView that is referenced in a menu item that menu item will become visible and will appear in a selected state:

If a permanently opened sub-menu is not acceptable in your application, you may customize the Css class that is added to all menu items on the path to the selected item by calling the ItemSelection method of the menu fluent interface. In the example below, a yellow border is added to all items on the path to the selected item instead of leaving them permanently in the opened state:

 .Radiuses(0.5f, 1f, 0.5f)
.ItemSelection(structurePathSelectClass: "light-select")//<-
 

 .light-select{
    border:2px solid yellow !important;
}
 

In this case the “selected color” on the menu item linking to “Page 4” becomes visible only if you hover the yellow-border “private area”:

You may also add a breadcrumb and modify the menu select method to update the breadcrumb, too.

That’s all for now! The full code is available in the “ContextDependentMenu_ko_routing” file that may be found here and in the Data Moving Plugin Examples Codeplex site download area. The Visual studio solution must be activated by installing the DataMovingPlugin5Examples.x.x.x.nupkg file you get with the product.

Francesco

Implementing an Owin Globalization Module with Katana

Sun, 23 Feb 2014 12:42:01 GMT

Introduction.

Owin became popular in the Mvc arena with the Mvc5 release whose authentication and authorization components are implemented as Owin application delegates.

An Owin based application is implemented as a pipe composed of transformation modules, the middleware, and application modules. Roughly, the middleware components are equivalent to Asp.net modules, while application components are equivalent to Asp.net Handlers. Both application components, and middleware are implemented as application delegates:

Func<IDictionary<string, object>, Task>

That is, as functions that take a dictionary containing information extracted from the client request and provided by other application delegates as input and that return a task.

The use of tasks avoids that the block of an application delegate waiting for a long-running operation might block the whole Owin pipeline thread.

While Owin is an abstract specification Katana is a concrete implementation. Katana architecture is based on 4 logical layers: the middleware and the application layers that I already mentioned, the host, and the web server.

The host is responsible for creating and orchestrating all underlying processes, and for creating and connecting the pipeline composed by the middleware and the application, while the web server is responsible for opening a network socket, listening for requests, and sending them through the Owin pipeline after having filled the initial IDictionary<string, object>.

We may either use IIS/Asp.net to implement the host/Web Server pair or we may launch a custom host process that calls a web server implementation.

Thus, one of the advantages of implementing our Globalization module as Owin middleware instead of an Asp.net module is that we may use it also with custom-hosted applications(typically WebApi and SignalR custom-hosted applications). Moreover Katana updates are released as Nuget packages that are independent of the Asp.net stack, so we may benefit of more frequent updates and improvements.

Finally, the implicit use of Tasks in the Owin pipeline furnishes an easy way to improve performance, without any supplementary programming effort.

Everything is needed to define and use Katana Middleware is contained in the dlls:

Owin.dll, that contains the abstract definition of Owin
Microsoft.Owin, that contains Katana core
Microsoft.Owin.Host.SystemWeb that contains a Katana server able to interact with Asp.net pipeline.

You may get everything by installing the Microsoft.Owin.Host.SystemWeb Nuget package in your Asp.net project.

If you implement the the middleware in a separate dll you may simply install the Microsoft.Owin Nuget package, since you don’t need the Microsoft.Owin.Host.SystemWeb dll.

The Problem

Typically web site supports just a limited set of cultures since each different language requires specific resources that must be produced manually, such as .resx files and/or whole Views/Pages specific for that language. However, the support of a specific culture based on a supported language typically doesn’t require any specific effort since .Net already contains the numeric formats and date formats for all cultures and one may use a subset of each language that is common to all cultures based on that language.

Thus, for instance, we may use an unique .resx file for the English language while supporting most of the English based culture(en-US, en-CA, en-GB, en-AU,etc.) if we use a subset of the English language that is common to all cultures. Accordingly, we may set the UICulture to en and the Culture to a whole language-country pair.

Any attempt to set a specific culture, must set only of the actually supported cultures, according to a best match algorithm,and when no culture is explicitly set by the user we should extract a culture from the Browser preferences.

Summing up, our specifications are:

The developer may specify a default culture and a list of supported cultures(all cultures that are supported simultaneously by UI widgets like date pickers, and by the the .resx files included in the project).
The selected culture is assigned to the current thread, and stored in a cookie and/or in the Url(http://mywebsite.com/en-US/...).
A culture may be selected either by creating a globalization cookie and adding it to the response, if culture storing in cookies is enabled, or by issuing to the server a request that contains the chosen culture as the first segment of the Url path(http://mywebsite.com/en-US/...), if culture storing in the Url is enabled.
If no culture is selected the culture is extracted from the browser list of preferred cultures with a best match algorithm, and then it is set as the currently selected culture.
If the culture specified in the path is different from the culture specified in the cookie, the module assumes that the user just clicked a link to change the culture, and uses the culture specified in the path as selected culture.
If there is no perfect match between either a selected culture or the browser cultures the module look for a partial match of just the language part (for instance matching en-CA with en-US, or en). In case of ambiguity the first matching supported language is chosen. If no partial match is found, the module reverts to the default culture. In any case the culture computed this way is set as the currently selected culture
When adding a culture to the list supported cultures one may specify to use only the language part asUICulture (the one used to select the appropriate .resx file). This way, for instance, we may specify both en-US, and en-CA, so that dates, numbers and currencies are displayed according to the country, while using an unique en .resx file for the English language.

If possible it is advised to select both cookie and and Url path culture storing (that should be the default), because the cookie is useful to remember the selected language in future visits, while including the culture in the path improves SEO and furnishes an easy way to change the selected culture (it is enough to add links with all supported cultures in their path to the page).

Creating Owin Middleware with Katana

In Katana the whole Owin function delegates pipeline is specified within the static Configure method of a Startup class that is automatically called by the Katana framework. As a default Katana looks for a class named Startup in namespace with the same name of the main assembly. There are several ways to change this default.

Thus, we have something like:

Middleware pipeline
 public partial class Startup
    {
        public void Configuration(IAppBuilder app)
        {
            app.Use<MyModule>(options);
            ...
            ...
            ...
            app.Use<MyModuleN>(optionsN);
 
        }
    }
 

The IAppBuilder interface contains the IDictionary used by all function delegates, some dictionary entries exposed as strongly typed properties, and utility methods like the Use<T> method that inserts middleware function delegates in the pipeline. Each middleware function delegate is implemented by the class passed in the generic T of the Use<T>(…) method and it must inherit from the OwinMiddleware class.

We need to implement just the constructor and the Invoke method:

Middleware module
 public class MyMiddleware : OwinMiddleware
{
    public LoggerMiddleware(OwinMiddleware next, 
        MyOptionType myOptions)
        : base(next)
    {
        _...
         ...
    }
 
    public override async Task Invoke(IOwinContext context)
    {
        ...
        ...
        ...
        await this.Next.Invoke(context);
        ...
        ...
        ...
 
    }
}
 

The constructor is passed the next element in the Owin pipeline, and the same option object we pass to the Use<T>(option) IAppBuilder method.

In the invoke method we first do the job of our module and then we call the Invoke method of the next element in the Owin pipeline.

In order to simplify the Owin pipeline we may group one or several calls to IAppBuilder.Use<T>(object o) into an IAppBulder extension method:

IAppBuilder extension
 namespace MVCControlsToolkit.Owin.Globalization
{
    public static class OwinGlobalizationHelpers
    {
        
          public static void UseGlobalization(thisIAppBuilder app,
            OwinGlobalizationOptions options)
        {
            app.Use<GlobalizationMidlleware>(options);
        }
    }
}
 

After that, in the pipeline definition we may simply call the newly defined extension method instead of IAppBuilder.Use<T>(object o):

Code Snippet
 public partial class Startup
{
    public void Configuration(IAppBuilder app)
    {
        app.UseGlobalization(new OwinGlobalizationOptions("en-US")
            .Add("it-IT", true).Add("en-US", true));
        ...
        ...
        ...
            
    }
}
 

Once the globalization functionality is exposed through the UseGlobalization extension method the globalization module may be declared internal in our Owin globalization library:

Globalization middleware
 namespace MVCControlsToolkit.Owin.Globalization.Modules
{
    internal class GlobalizationMidlleware : OwinMiddleware
    {
        private OwinGlobalizationOptions options;
        ...
        ...
        ...
    }
 

The Globalization Middleware

In the constructor we just store the options object:

The constructor
 public GlobalizationMidlleware(OwinMiddleware next, 
    OwinGlobalizationOptions options)
    : base(next)
{
    if (options == null) throw new ArgumentNullException("options");
    this.options = options;
            
}
 

in the Invoke method:

Extracting selected language
 public override async Task Invoke(IOwinContext context)
{
    string urlLanguage = options.CulturePathEnabled ? getPathLanguage(context) : null;
    string cookieLanguage = options.CulturePathEnabled ? getCookieLanguage(context) : null;
    string currLanguage = urlLanguage ?? cookieLanguage;
 

we extracts the culture from the Url and from the cookie if the associated option is enabled. The Url culture is preferred (see specifications). The extraction is performed by two private methods

If no culture is selected we revert to the Browser culture, otherwise we select the best match between the selected culture and the supported cultures:

Best match
 OwinSupportedCulture chosenLanguage = currLanguage == null ?
    BrowserBestMatch(context) :
    options.ClosestSupported(currLanguage);
 

The OwinSupportedCulture class represents the matched supported culture:

 internal class OwinSupportedCulture
    {
        public string Name { set; get; }
        public string UIName { set; get; }
        public int MatchLevel { get; set; }
    }
 

Where MatchLevel is an integer that encodes the kind of match that took place with the supported culture (perfect match, language part only, no match the default culture was selected)

Then we may set the chosen cultures in the current thread:

Setting cultures
 Thread.CurrentThread.CurrentUICulture = 
    new CultureInfo(chosenLanguage.UIName);
Thread.CurrentThread.CurrentCulture = 
    new CultureInfo(chosenLanguage.Name);
 

Now we must store the selected culture in the cookie, and/or Url if it is not already stored there.

Setting the culture in the Url
 if (options.CulturePathEnabled && 
    options.AlwaysRedirectOnCulturePath && 
    chosenLanguage.Name != urlLanguage)
{
    var Path = context.Request.Path;
    ;
    string fPath = null;
    if (!Path.HasValue) fPath = chosenLanguage.Name;
    else if (urlLanguage == null)
    {
        fPath = chosenLanguage.Name +
            (Path.Value[0] == '/' ? Path.Value :
                "/" + Path.Value
            );
 
    }
    else
    {
        int position = Path.Value.Substring(1).IndexOf('/');
        if (position < 0) fPath = chosenLanguage.Name;
        else fPath = chosenLanguage.Name + Path.Value.Substring(position + 1);
    }
    var builder = new UriBuilder(context.Request.Uri);
    builder.Path = fPath;
    context.Response.Redirect(builder.Uri.AbsoluteUri);
    return;
}
 

If the the culture in the path is handled, if automatic redirect to an Url with a culture in the path is enabled (the default), and if the selected culture is not already contained in the path, then an Url containing the newly selected culture is computed (any previous culture possibly contained in the Url is removed). After that the execution of the Owin pipeline is aborted and a redirect to the newly computed Url is performed by calling the Response.Redirect method of the context object passed as argument to the Invoke method.

If instead culture storing is enabled and cookie doesn’t contain already the newly selected culture, a new cookie is added to the response:

Cookie preparation
 if (options.CookieEnabled && 
    cookieLanguage != chosenLanguage.Name)
{
    context.Response.Cookies
        .Append(options.CookieName, chosenLanguage.Name);
}
 

Finally we call the next element of the Owin pipeline:

 await this.Next.Invoke(context);
 

The OwinGlobalizationOptions.ClosestSupported method that performs the best match between the culture the user is trying to set and any of the supported culture is quite simple:

Best match
 internal OwinSupportedCulture ClosestSupported(string culture)
{
    if (!ValidateCulture(culture, true)) return 
        new OwinSupportedCulture { 
            Name = defaultCulture, 
            UIName = defaultCulture, 
            MatchLevel = 0 };
    culture = culture.ToLowerInvariant();
    OwinGlobalizationCulture res;
    if (supportedCultures.TryGetValue(culture, out res))
    {
        return new OwinSupportedCulture
        {
            Name = res.Name,
            UIName = res.GetUiCulture(),
            MatchLevel = 2
        };
    }
    if (culture.Length > 2)
    {
        culture = culture.Substring(0, 2);
        if (supportedCultures.TryGetValue(culture, out res))
        {
            return new OwinSupportedCulture
            {
                Name = res.Name,
                UIName = res.GetUiCulture(),
                MatchLevel = 1
            };
        }
    }
    return new OwinSupportedCulture { 
        Name = defaultCulture, 
        UIName = defaultCulture, 
        MatchLevel = 0 };
}
 

If the culture string is invalid, the default culture is returned.

Otherwise the method looks in the dictionary of all supported cultures. If no match is found a match with just the language part is tried, and in case of failure the default culture is returned. The GetUICulture method is defined below:

Supported culture class
 public class OwinGlobalizationCulture
{
    public string Name { set; get; }
    public bool UIIsNeutral { set; get; }
    public string GetUiCulture()
    {
        if (UIIsNeutral && Name.Length > 2) 
            return Name.Substring(0, 2);
        else return Name;
    }
}
 

The best match with the cultures supported by the browser is a little bit more complex since the browser may support several cultures and may give a preference (0 to 1 float) to each of them (Accept-Language header):

Browser best match
         }
private OwinSupportedCulture BrowserBestMatch(IOwinContext context)
{
    string[] acceptLanguageHeader = null;
    if (context.Request.Headers
        .TryGetValue("Accept-Language", out acceptLanguageHeader) 
        && acceptLanguageHeader != null)
    {
        float maxVote = -1.0f;
        OwinSupportedCulture maxElement = null;
        foreach (var language in parseLanguages(acceptLanguageHeader))
        {
            OwinSupportedCulture currLanguage = 
                options.ClosestSupported(language.Name);
            if (currLanguage == null) continue;
            float currVote = currLanguage.MatchLevel * 10 
                + language.Q;
            if (currVote > maxVote)
            {
                maxVote = currVote;
                maxElement = currLanguage;
            }
        }
        return maxElement ?? new OwinSupportedCulture
        {
            Name = options.DefaultCulture,
            UIName = options.DefaultCulture,
            MatchLevel = 0
        };
    }
    else return new OwinSupportedCulture
    {
        Name = options.DefaultCulture,
        UIName = options.DefaultCulture,
        MatchLevel = 0
    };
}
 

The “Accept-Language” entry in the context.Request.Headers dictionary contains an array with all preferred cultures. The parseLanguages private method parse each culture entry to extract the current name and the Q 0-1 float representing the preference. A loop is performed to compute the the culture with the maximum vote, where the vote takes into account the match level with the closest supported culture and the Q of each browser culture.

The whole sources are available on Codeplex.

How to use the Owin Globalization Module

Install the MVCControlsToolkit.Owin.Globalization Nuget package in your Mvc 5 project, then open the Startup.cs file located in the Web Site root, and add the Owin Globalization module as follows:

If culture storing in the Url is enabled you need also to add the {language}/ segment to all routing rules. Thus for instance:

becomes:

Owin Globalization Options

The UseGlobalization extension accepts an OwinGlobalizatioOptions object containing all globalization options as its sole argument. In turn, the OwinGlobalizatioOptions constructor accepts the default culture as its first obligatory argument, and a second optional boolean that specifies if the UI culture must use only the language part of the default culture. Further options may be added with a fluent interface:

.Add(string culture, bool uIIsNeutral = false)

Adds a new supported culture. If uIIsNeutral is true only the language part of the provided culture is used to set the UICulture.

As a default the selected culture is stored both in the first segment of the Url path and in a cookie whose name is "preferred_culture". The methods below change these default options:

.DisableCultureInPath()

Disables storing the selected culture in the Url.

.DisableRedirect()

If culture storing in the Url is enabled it disables the automatic redirect to an Url containing the selected culture as first segment of the path when an Url containing no culture in the path is received.

.DisableCookie()

Disables storing the selected culture in a cookie

.CustomCookieName(string name)

If storing the selected culture in a cookie is enabled it changes the globalization cookie default name.

Data Moving SPA with a Context-Dependent Menu

Sat, 08 Feb 2014 20:13:02 GMT

The Data Moving Menu Control may be used to navigate among the virtual pages of a Single Page Application, too. In this step by step tutorial I will show you how to configure the menu control, and how to adapt it to the authorizations of the currently logged user .

The full working code is available in the “ContextDependentMenu” file on this site and on the Data Moving Plugin Examples Codeplex site download area. The Visual studio solution must be activated by installing the DataMovingPlugin5Examples.x.x.x.nupkg file you get with the product.

The result that you’ll obtain is shown in this Video:

As a first step let select the SPA Mvc 5/WebApi 2 SPA project template in visual studio. All SPA visual studio templates may be downloaded from the Data Moving Examples Codeplex Site.

Select File->New->Project in VS 2013:

Then name the new project:, SPAMenuTutorial:

The result should be this one:

Now you need to install the Data Moving Plug-in for Mvc 5. Right click on the “References” and select: “Manage Nuget Packages…”:

In the window that appears, select the local Nuget source on your hard disk where you copied all Data Moving Plug-in Nuget packages:

Now select the “Data Moving Plug-in 5”, and install it.

Before running the initial SPA that the visual studio template created for you, your Product Key must be placed in the application root Web.Config, in the AppSettings section:

 <appSettings>  
    <add key="webpages:Version" value="3.0.0.0" />  
    <add key="webpages:Enabled" value="false" />  
    <add key="ClientValidationEnabled" value="true" />  
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />  
    <add key="DMPDefaultStyle" value="Bootstrap" />  
    <add key="DMPProductKey" value="P-ZzKk-****..........." />  
  </appSettings> 

Now you may run the project:

An essential SPA with just an home page, and Login, Logout, and Unauthorized page is created.

All these SpaViews are placed in the “Basic” SPA Module that is loaded as soon as the application starts:

The Application folder contains just two dynamic JavaScript files:

Application/MainJs. It contains the SPA start-up code and the definition of the application ViewModel.
Application/AuthorizationJs. This JavaScript file is called by the previous Application/MainJs file and contains all authorization rules for the application SPAViews. Initially the rule set is empty, and the file contains just a commented-out example that shows how to define a rule:

 @using MVCControlsToolkit.Controls  
<script>  
    (function () {  
        //Add here authorization rules for each virtual page  
        //(rules may include also the page role)  
        //as the one commented out below  
        @*  
        @(SPAAuthorizations.New().Claims("logged")  
            .Roles("<role1>", "<role2>")  
            .AddTo("<module name>", "<view name>",  
                    "<role name (optional)>"))  
        *@  
  
    })();  
</script> 

All SPA templates use bootstrap for styling, and install a bootstrap Nuget package that provides just the “core” CSS without any specific theme. In order to improve, the appearance of our demo we may download the default bootstrap theme from the bootstrap web site: “bootstrap-theme.min.css “and “bootstrap-theme.css”. Just add these two files to the web site “Content” folder, and then add "~/Content/bootstrap-theme.css", to the "~/Content/css" style bundle definition in the App_Start/BundleConfig.cs file that contains all bundle definitions:

 bundles.Add(new StyleBundle("~/Content/css").Include(  
"~/Content/bootstrap.css",  
"~/Content/bootstrap-theme.css",// <-Add new file reference here  
"~/Content/MVCControlToolkit.ControlsExt.Mobi-" + version + ".min.css",  
"~/Content/Site.css")); 

Without the addition of a theme the appearance of the menu we are going to build would be quite “bad”.

Our plan is:

Defining some users and roles in the application security Database
Defining a new SPA Module with 5 simple SPAViews
Declaring 3 authorization rules that allow just users with the “admins” role to access SPAView 3, 4 and 5
Defining a Menu to navigate our SPAViews
Adapting the Menu to the current page and to the current logged user.

Defining the security Database

The Models/ApplicationDbContext.cs file contains a Database seeding function that defines the “admins” role and two users: an administrator and a normal user. In an actual application we should modify this code to adapt it to our needs. In this simple tutorial we may use the default users and roles.

The seeding function is “activated “ by a few lines of code in the Global.asax that are initially commented-out:

 protected void Application_Start()  
{  
....  
....  
....  
//Uncomment to prepopulate db with sample users  
//See ApplicationDbContext.cs  
/*  
Database.SetInitializer  
   <SPAMenuTutorial.Models.ApplicationDbContext>  
    (new SPAMenuTutorial.Models.ApplicationDbContextInitializer());  
    */  
} 

Let uncomment them, and run the application. Now we may login as “admins” with the credentials:

username: admin, password: padmin, as shown in the previous video.

Defining a new SPA Module with 5 simple SPAViews

Now, in visual studio, right click on the Views/Templates folder and select “new folder”. Name the new folder: “MenuExample”.This folder will contain all files of the new MenuExample SPA Module that we are going to define.

Now, in visual studio right click on the “MenuExample” folder and select: “New Item”:

Select “SPAModule”, and then give to the new SPA module the same name of the previous folder: “MenuExample”:

We should get the following files structure:

The two Main and MainJs files contain the logic to assemble all SPAViews we are going to define into an unique SPAModule. More specifically, Main.cshtml contains the logic to assemble all templates, and to route any incoming View request to the right SPAView template, while MainJS.cshtml contains the logic to assemble the AMD code associated to all SPAViews into the unique JavaScript file associated to the whole “MenuExample” module, and the logic to route any SPAView request to the right chunck of JavaScript code that was previously aggregated to the “MenuExample” module.

Since ,as in most of the cases, we don’t need to modify the default routing rules you don’t need to modify Main, and MainJs.

Now we need to define the Action method that will deploy the “MenuExample” module to the client. Go to the “Controllers/TemplatesController.cs” file, copy the example “MyTemplate” action method…

…paste it, and rename any occurrence of “MyModule” into “MenuExample”:

 public ActionResult MenuExample(bool isJs)  
{  
    string module = "MenuExample/Main";  
    if (isJs) return this.MinifiedJavascriptResult(module + "Js");  
    return PartialView(module);  
} 

Now we may define all SPAViews.

Right click on the “MenuExample” folder, and select again “New Item”. However this time, choose “SPAView”. Repeat the same operation five times, and give to the SPAViews the names:

“Page1”, “Page2”, “Page3”, “Page4”, and “Page5”:

Now open each Page1.cshtml…Page5.cshtml file:

 @*@model MyViewModel*@  
  
  
  <divid="@Html.PrefixedId("pageRoot")"  
                data-helper-prefix="@Html.PrefixedId("")">  
        <h3 >@*View title if any*@</h3>  
  
</div> 

Then add the “main-page” Css class and a different header to each page:

 @*@model MyViewModel*@  
  
  
  <div class="main-page"id="@Html.PrefixedId("pageRoot")"  
                data-helper-prefix="@Html.PrefixedId("")">  
        <h3 >Page 1</h3>  
  
</div> 

You don’t need to define a page ViewModel, since we will use all these pages just to test our menu.

Since pages have no ViewModel wee need to comment-out the instruction that prepare the SPAView JavaScript model in each PagexJs.cshtml file. In each PagexJs.cshtml file locate the instruction:

 vm.Content = ko.mapping.fromJS(viewModelContent); 

and comment it out:

 mvcct.core.moduleResult(function (vm) {  
    if (!vm._initialized) {  
        vm._initialized = true;  
        //vm.Content = ko.mapping.fromJS(viewModelContent); 

Done! Now you may navigate to each of the newly created SPAViews, by adding view and module parameters to the root application url that Visual Studio automatically set in you browser:

http://localhost:3291/?module=MenuExample&view=Page1

Declaring the authorization rules

As already announced pages 3, 4, 5 must be available only for users with the role admins. Open the Views/Templates/Application/AuthorizationJs.cshtml file and add the three rules below:

 @using MVCControlsToolkit.Controls  
<script>  
    (function () {  
        //Add here authorization rules for each virtual page  
        //(rules may include also the page role)  
        //as the one commented out below  
        @*  
        @(SPAAuthorizations.New().Claims("logged")  
            .Roles("<role1>", "<role2>")  
            .AddTo("<module name>", "<view name>",  
                    "<role name (optional)>"))  
        *@  
  
        @(SPAAuthorizations.New().Claims("logged")  
            .Roles("admins")  
            .AddTo("MenuExample", "Page3"))  
  
        @(SPAAuthorizations.New().Claims("logged")  
            .Roles("admins")  
            .AddTo("MenuExample", "Page4"))  
  
        @(SPAAuthorizations.New().Claims("logged")  
            .Roles("admins")  
            .AddTo("MenuExample", "Page5"))  
  
    })();  
</script> 

In this simple example we specified access rules for each single SPAView, but in more complex applications you may write also something like: AddTo(“MenuExample”, “*”), in which case the requirements apply to all SpaViews of the “MenuExample” module. Then, exceptions to this general rule may be applied to specific SPAViews.

Now when you navigate, to Page3-5, the login form appears. Test it with Page4:

http://localhost:3291/?module=MenuExample&view=Page4

After you successfully login, Page4 appears.

Now, try to login with username: normalUser. and password: pnormalUser; you will see the following complaint page:

Wow! We need only a “smart menu” to navigate our application.

Making Room for our Menu

All SPAViews are loaded in the Views/Home/Index.cshtml page. The code in the above page do the following:

 @{var h = Html.SendToClient(m => m, "applicationModel", "");} 

Declares the application ViewModel, and get a client ViewModel aware HtmlHelper<ApplicationModel>, that is then used to declare the SPAViews hosts where all the SPAViews may be loaded:

 <div id="content">  
         
        @h.ClientTreeIteratorFor(m => m.MainContent, null,  
            "mainAfterRender",  
            "mainBeforeRemove",  
            wrapper: ExternalContainerType.div,  
            wrapperAttributes: new{id = "main_host"}  
        )  
          
</div>

Each SPAView host is bound to an applicationModel Property. The initial application ViewModel contains just a single property, called MainContent, used by the main content SPAView host, shown above. mainAfterRender and mainbeforeRemove are applicationModel methods defined in Views/Templates/Application.MainJs.cshtml, that provide respectively content fade-in and content fade-out.

Since we need a further SPAView host for our menu we must add a new property to the application ViewModel:

 public class ApplicationModel  
{  
    //main virtual page host  
    public baseViewModel<SampleClass> MainContent { get; set; }  
    //add here further virtual page hosts  
  
    //Main Menu Host  
    public baseViewModel<SampleClass> MenuContent { get; set; }  
  
    //initial page to load  
    public externalSPALink InitialPage { get; set; }  
} 

Now we may define our Main Menu host. We place it on top of the Main Content:

 <div id="content">  
         
        @h.ClientTreeIteratorFor(m => m.MenuContent, null,  
            wrapper: ExternalContainerType.nav,  
            wrapperAttributes: new { id = "menu_host" }  
        )  
  
        @h.ClientTreeIteratorFor(m => m.MainContent, null,  
            "mainAfterRender",  
            "mainBeforeRemove",  
            wrapper: ExternalContainerType.div,  
            wrapperAttributes: new{id = "main_host"}  
        )  
          
</div> 

We enclose the our main menu in a nav tag to improve the application accessibility. The Main Menu host doesn’t need fade-in, and fade-out capability, since it will never be removed, but only modified to adapt it to the context.

We need some Css to align the menu with the main content. Open the Content/Site.css file and append:

 /*Menu*/  
#menu_host{  
    width:800px;  
    margin: 10px auto 10px auto;  
    min-height: 50px;  
    border: none;  
} 

Defining a Menu to Navigate our SPAViews

We will add the “Menu” SpaView to Basic module that is loaded as soon as the application starts Right click on the Views/Templates/Basic folder and add a new SPAView called: “Menu”:

The Data Moving control suite urnish the default SimpleMenuItem class to be used as ViewModel for each menu item. We may decide to use it, inherit from it or to use a custom class. The definition of the SimpleMenuItemClass is:

 public class SimpleMenuItem  
{  
    public string Text { get; set; }  
    public string Link { get; set; }  
    public string UniqueName { get; set; }  
    public string Target { get; set; }  
    public List<SimpleMenuItem> Children { get; set; }  
} 

When the Menu works in a “standard” Mvc application the Link property contains either an Url or the name of a JavaScript function, preceeded either by @, or # to be executed when the menu item is clicked. Analogously the Target property contains the target where to open the Url.

In the case of a SPA we must supply a function that provides a custom interpretation of both Link and Target. In the simplest case a SPAView may be referenced with a string of the type <module name>.<view name> in the Link, while the host where to load the SPAView may be denotated by its index into an array of possible hosts.

Thus, for Instance, “MenuExample.Page4” denotes the SPAView “Page4” contained in the “MenuExample” module. If needed, the notation may be extended to include also possible roles of the SPAView, and also an input object to pass to the SPAView:

In our simple example the custom Link+Target processing function will accept just the simple notation <module>.<view> plus standard Urls:

 vm.Content.virtualNavigation = function (action, target) {  
    if (!action) return false;  
    if (action.indexOf("/") == 0 ||  
        action.indexOf("http") == 0 ) {  
        if (target) window.open(action, target);  
        else window.location.href = action;  
        return;  
    }  
    var parts = action.split(".");  
    var host = target ? parseInt(target) : 0;  
    vm._interfaces.mainHosts[host](  
        mvcct.ko.dynamicTemplates.defaultPageStore.get(  
        new mvcct.ko.dynamicTemplates.virtualReference(  
            parts[0], parts[1])));  
}; 

Standard Urls are processed first, otherwise we retrieve the SPAView specified in the action parameter from the default page store. The host where to place the SPAView is decided by interpreting the target argument as an index in the array of all application root hosts that is inserted in the _interfaces property of the Menu ViewModel.

The _interfaces property is copied in each SPAView from the interfaces property of the application ViewModel by default context rules that are run each time a SPAView is loaded. All context rules are defined in the file: Script/Modules/contextRules.js. Below the default context rule that provide to each SPAView all interfaces needed to interact with the application:

 mvcct.ko.dynamicTemplates.addContextRule(function (data, cb) {  
    if (mvcct.ko.dynamicTemplates.isBaseViewModel(data)) {  
        data._interfaces = applicationModel.interfaces;  
    }  
    return false;  
}); 

The interfaces property of the application ViewModel is defined in the Views/Templates/Application.MainJs.cshtml file. Below the default definition:

 @* Put here all instances of the interface implementations  
    you need in the application *@  
@* They will be added to all ViewModel by the context rules*@  
applicationModel.interfaces = {};  
  
applicationModel.interfaces.uiBlock = new uiBlockInterface(); 

As a default the interfaces property contains just an implementation of the interface used to “block” the content of a DOM during a communication with the server. We must add also the array of all hosts (in our case there are just 2 hosts):

 @* Put here all instances of the interface implementations  
    you need in the application *@  
@* They will be added to all ViewModel by the context rules*@  
applicationModel.interfaces = {};  
  
applicationModel.interfaces.uiBlock = new uiBlockInterface();  
applicationModel.interfaces.mainHosts =  
    [applicationModel.MainContent, applicationModel.MenuContent]; 

In the same Views/Templates/Application.MainJs.cshtml file we must modify the code that loads the initial SPAViews:

 applicationModel.MainContent(  
    mvcct.ko.dynamicTemplates.defaultPageStore.get(initLink ||  
    new mvcct.ko.dynamicTemplates.virtualReference("Basic", "Home"))); 

…because we must load also our menu:

 applicationModel.MenuContent(  
    new mvcct.ko.dynamicTemplates.baseViewModel("Basic", "Menu"));  
applicationModel.MainContent(  
    mvcct.ko.dynamicTemplates.defaultPageStore.get(initLink ||  
    new mvcct.ko.dynamicTemplates.virtualReference("Basic", "Home"))); 

The Menu SPAView is not handled by any page store, since it will never be removed from its host.

The vm.Content.virtualNavigation method definition may be placed immediately after the ViewModel initialization in the MenuJS.cshtml file:

 mvcct.core.moduleResult(function (vm) {  
    if (!vm._initialized) {  
        vm._initialized = true;  
        vm.Content = ko.mapping.fromJS(viewModelContent);  
        @* Initialization code executed only after View  
            creation or View redirect  *@  
        vm.Content.virtualNavigation = function (action, target) {  
            ...  
            ... 

Now we must define viewModelContent to bethe object hierachy that contains all Menu information.

Usually, the ViewModel content is initialized by serializing in JavaScript a .Net data structure, at the beginning of any …Js file:

 @*  
@Html.JavaScriptDefine("viewModelContent",  
    new <dotnet viewModel here>())  
*@ 

In our case the .Net data structure is a hierarchy of SimpleMenuItem objects that we may build easily with the helper SimpleMenuBuilder class:

 <script>  
    @{  
        var menuItems = new SimpleMenuBuilder()  
            .Add("Home", "Basic.Home")  
            .Add("Page 1", "MenuExample.Page1")  
            .Add("Page 2", "MenuExample.Page2")  
            .Add("private area")  
                .Down()  
                    .Add("Page 3", "MenuExample.Page3")  
                    .Add("Page 4", "MenuExample.Page4")  
                    .Add("Page 5", "MenuExample.Page5")  
                .Up()  
             .Add("External Links")  
                .Down()  
                    .Add("Data Moving Controls",  
                        "http://www.mvc-controls.com")  
                    .Add("knockout.js",  
                        "http://knockoutjs.com/", null, "_blank")  
                .Down()  
            .Get();  
    }  
    (function () {  
  
    @Html.JavaScriptDefine("viewModelContent",  
        new SimpleMenuItem {Children=menuItems })  
        ...  
        ... 

We added also two sub-items that navigate to external pages.

Now it’s finally time to use the Data Moving Menu control. Open the Menu.cshtml file, and substitute its content with:

 @model MVCControlsToolkit.Controls.SimpleMenuItem  
  
@{  
    var builder = Html.ExtendedClientMenuFor(  
        m => m.Children, m => m.Link,  
        new { @class = "mainmenu" });  
    if (HttpContext.Current.Request.Browser.IsMobileDevice)  
    {  
        builder = builder.ActiveOnlyOnClick();  
    }  
    builder.Target(m => m.Target)  
    .Radiuses(0.5f, 1f, 0.5f)  
    .TemplatesBaseName("Basic_MenuItem")  
    .TemplateSelector(  
        @"function(x){  
                    return (x.Children.peek() ?  
                        'Basic_MenuItem1' : 'Basic_MenuItem0');  
                }")  
    .CustomNavigate("Content.virtualNavigation")  
    .AddRowType()  
        .StartColumn(m => m.Text)  
            .CustomColumnClass(GenericCssClasses.NoWrap)  
        .EndColumn()  
    .EndRowType()  
    .AddRowType()  
        .StartColumn(m => m.Text)  
            .CustomColumnClass(GenericCssClasses.NoWrap)  
        .EndColumn()  
        .ChildCollection(m => m.Children)  
    .EndRowType();  
  
}  
@builder.Render() 

The ExtendedClientMenuFor Html<T> extension declares the root menu items collection, the property that contains the level 0 menu items, and the menu data item property that contains the “action” to execute when the menu item is selected.Then, ExtendedClientMenuFor returns a fluent interface to continue the menu configuration. The root menu ul tag contains the mainmenu Css class that defines some <ul> and <li> structural properties:

ul.mainmenu
{
    padding: 0 0 0 0 !important;  
    font-size:1.2em;
    
}  
ul.mainmenu > li
{
  margin:  5px 7px 5px 7px !important;      
}
ul.mainmenu ul {border: none; background-color:transparent; }

The above definitions must be appended to the Content/Site.css file. You may experiment by changing some of them.

Then we declare which item property contains the target where to open links or virtual SPAView references, and the various menu items radiuses (see the picture that shows the three radiuses here ).

The way each menu item is rendered is defined by two templates, that are configured inside two AddRowType()-EndRowType() blocks. Both templates are based on the default menu row template, since no custom row template is defined, and both of them have an unique column that shows the menu item title. Each menu item title is contained in the Text property of the underlying data item. The addition of the GenericClasses.NoWrap Data Moving predefined Css class prevents menu item titles from wrapping. The only difference between the two templates is the ChildCollection call in the second declaration, that causes the recursive rendering o all children sub items contained in the children property. The two AddRowType blocks define two knockout client templates. Their names are obtained by adding the postfixes ‘0’ and ‘1’ to the template base name “Basic_MenuItem” declared with TemplateBaseName. It is good practice to give name of the type <module name>_<a name> to all client templates used by controls declared inside SPAViews.

The first template is used for the menu items that can’t have children (their Children property is a null observable) while the second template is used for the menu items that may have children (their Children property is a possibly empty observable array). The selection of the right template is performed by the template selection function declared with TemplateSelector. In our case the function is declared on line, but it may be also the name of a SPAView ViewModel method.

CustomNavigate declares the custom navigation function we have already defined in the MenuJs file.

That’s enough to see the menu working! Run the application and enjoy your first Data Moving SPA Menu!

Adapting the Menu to the Current Page and to the Current Logged User

Now, our last objective is adapting the menu to the logged user and to the actual SPAView that is in the main host. More specifically:

Each time the user changes the menu must display just the items the new user has the right to access, that is: if all sub-menus of a father menu item are not visible and if the father menu item itself doesn’t connect to a SPAView the user may access, the father menu item must be invisible
The menu item that connects to the actual SPAView that is in the main host must appear in a “selected state”.

Both requirements may be achieved by letting the content ViewModel of our menu implements an interface, say, IContextDependent with two methods:

authorize(), that adapts the SPAView (our menu SPAView) to the authorizations of the current user.
select(x), that informs the SPAView (our menu SPAView) that the SPAView x is currently in the main host. Where x is a string with the same format of the Link property of our menu data items.

In general we may handle several SPAViews that implements the IContextDependent interface in a modular way as follows:

We define a IContextDependent resource handler with methods to register and unregister IContextDependent implementations for being properly handled by the application.
Each time a SPAView that implements IContextDependent, is loaded it registers itself to the IContextDependent resource handler, and then it unregisters itself when it is unloaded.
Whenever the current user changes, the IContextDependent resource handler is notified and calls the authorize() method of all registered IContextDependent implementations.
Whenever the current SPAView in the main host changes the the IContextDependent resource handler is notified and calls the select(x) method of all registered IContextDependent implementations.

We may define the class that implements the IContextDependent resource handler in the Views/Templates/Application/MainJs.cshtml file next to the definition of the uiBlockInterface class:

 var iContextDependentHandler = function () {  
    var registrations = [];  
    this.register = function (x) {  
        registrations.push(x);  
    };  
    this.unregister = function (x) {  
        var index = -1;  
        for (var i = 0; i < registrations.length; i++) {  
            if (registrations[i] == x) {  
                index = i;  
                break;  
            }  
        }  
        if (index > -1) {  
            array.splice(index, 1);  
        }  
    };  
    this.select = function (x) {  
        for (var i = 0; i < registrations.length; i++) {  
            var item = registrations[i];  
            if (item.select) item.select(x);  
        }  
    };  
    this.authorize = function () {  
        for (var i = 0; i < registrations.length; i++) {  
            var item = registrations[i];  
            if (item.authorize) item.authorize();  
        }  
    }  
} 

Then, we add an instance of this classes to the applicationModel.interfaces property, so that it is available within the applicationModel itself and to all SPAViews:

 applicationModel.interfaces.uiBlock = new uiBlockInterface();  
applicationModel.interfaces.mainHosts =  
    [applicationModel.MainContent, applicationModel.MenuContent];  
applicationModel.interfaces.contextHandler = //<-add here  
    new iContextDependentHandler(); 

The iContextDependent.select method must be called each time a new SPAView is placed in the application main host. Accordingly, it may be called in the main host mainAfterRender that is defined as an applicationModel method in the Views/Templates/Application/MainJs.cshtml file:

 applicationModel.mainAfterRender = function (x, y) {  
    //start added code  
    if (y && mvcct.ko.dynamicTemplates.isBaseViewModel(y))  
        applicationModel.interfaces.contextHandler  
            .select(y.module + '.' + y.view)  
    else  
        applicationModel.interfaces.contextHandler  
            .select(null)  
    //end added code  
    $(mvcct.core.filterHtml(x)).fadeOut(0).fadeIn(400);  
}; 

The if checks that the module and view properties are actually defined, otherwise a null value passed to the select method simply de-selects any previously selected SPAView.

The iContextDependent.authorize method must be called each time the logged user changes. The instruction that initializes the authorization system in the Views/Templates/Application/MainJs.cshtml file accepts an array of observables, and functions that are automatically notified whenever the user changes. This is the right place for calling our authorize method:

 mvcct.ko.dynamicTemplates.enableAuthorizationManager(  
    "@Url.Content("~/api/Account/CurrentUser")",  
    "@Url.Content("~/api/Account/Logout")",  
    function () {  
        @* on logout *@  
},  
[applicationModel.MainContent,  
applicationModel.interfaces.contextHandler.authorize//<-add here  
] @*all observables to refresh when the user changes*@  
    ); 

iContextDependent.register and iContextDependent.unregister must be called in the Views/Templates/Basic/MenuJs.cshtml JavaScript file associated with our Menu SPAView.

The right place to call iContextDependent.register is the processInput method that is called each time a SPAView is loaded, while the right place to call iContextDependent.unregister is the beforeRemove method that is called before the SPAView is unloaded:

 vm.processInput = function (nodes) {  
        @* Code here is executed each time the page is loaded.  
        Virtual page inputData must be processed here *@  
    vm._interfaces.contextHandler.register(vm.Content);  
    modifyDomOnLoad(vm, nodes);  
};  
vm.beforeRemove = function () {  
    @* Insert here clean up code to be  executed  
        when the page is unloaded*@  
    vm._interfaces.contextHandler.unregister(vm.Content);  
    cleanupDomOnUnload(vm);  
}; 

Now our vm.Content ViewModel must implement the IContextDependent interface. You may place the interface definition immediately after the vm.Content.virtualNavigation method we defined before:

 var currentSelected = null;  
vm.Content.select = function (action) {  
    if (!action) {  
        currentSelected = null;  
        if (currentSelected)  
            mvcct.html.menu.selected(currentSelected, false);  
        return;  
    }  
    var res =  
        selectMenu(  
        ko.utils.unwrapObservable(vm.Content.Children),  
        action);  
    if (!res && currentSelected)  
        mvcct.html.menu.selected(currentSelected, false);  
    currentSelected = res;  
};  
vm.Content.authorize = function () {  
    authorizeMenu(  
        mvcct.ko.dynamicTemplates.authorizationManager(),  
        vm.Content.Children);  
}  
vm.Content.authorize(); 

Both methods call two private recursive functions that traverse the menu data items hierarchy to do their job.

Otherwise the recusive selectMenu function tries to locate a menu data item matching the action string. If such a data item is found the menu item it is bound to is set in the selected state by calling: mvcct.html.menu.selected(item, true) and the data item itself is returned in the res variable, so it may substitute the previous currentSelected. If the selectMenu recursive search fails, null is returned in res, and any previously selected item is unselected by calling mvcct.html.menu.selected(currentSelected, false).

The private functions selectMenu and authorizeMenu may be placed in the read-only private members area immediately before the mvcct.core.moduleResult call:

 @*Insert private functions and private readonly variables here*@  
function selectMenu(children, action, target) {  
    for (var i = 0; i < children.length; i++) {  
        var item = children[i];  
        if (action == ko.utils.unwrapObservable(item.Link) &&  
            (!target ||  
            target ==  
            (ko.utils.unwrapObservable(item.Target) || "0"))) {  
            mvcct.html.menu.selected(item, true);  
            return item;  
        }  
        var iChildren = ko.utils.unwrapObservable(item.Children);  
        if (iChildren) {  
            var child = selectMenu(iChildren, action, target);  
            if (child) return child;  
        }  
    }  
    return false;  
}  
function authorizeMenu(authorizationManager, obsChildren) {  
    var children = ko.utils.unwrapObservable(obsChildren);  
    if (!children || children.length == 0) return false;  
    var hasChildren = false;  
  
    var aChange = false;  
    for (var i = 0; i < children.length; i++) {  
        var item = children[i];  
        var action = ko.utils.unwrapObservable(item.Link);  
        var virtualLink = action &&  
            action.charAt(0) != '#' &&  
            action.charAt(0) != '@@' &&  
            action.charAt(0) != '/' &&  
            action.indexOf("http") != 0 &&  
            action.indexOf("mailto") != 0;  
        var authorized = false;  
        if (virtualLink) {  
            var parts = action.split('.');  
            authorized =  
                !authorizationManager.verifyAuthorization(  
                    new mvcct.ko.dynamicTemplates  
                        .virtualReference(parts[0], parts[1])  
                    );  
        }  
        else authorized = action;  
        authorized = authorized || false;  
        if (authorized) authorized = true;  
        var childrenAuthorized =  
            authorizeMenu(authorizationManager, item.Children);  
        authorized = authorized || childrenAuthorized;  
        if ((item._destroy || false) != !authorized) {  
            item._destroy = !authorized;  
            aChange = true;  
            if (item._destroy) mvcct.ko.unfreeze(item);  
        }  
        if (authorized) hasChildren = true;  
    }  
    if (aChange) obsChildren.valueHasMutated();  
    return hasChildren;  
}  
@*End of private area*@  
        mvcct.core.moduleResult(function (vm) {  
            ...  
            ...  
            ... 

Now the context dependent menu is ready. Whenever you navigate to a SPAView that is referenced in a menu item that menu item will become visible and will appear in a selected state:

When a menu item get the focus the focus style overrides its “selected color” (this is due to the way bootstrap handles the focus style), if you don’t like this behavior you may change it by appending the following Css rule to the Site.css file:

 .mvcct-menu-item-selected:focus{  
    background-color: #d9edf7 !important;  
    border:2px solid yellow !important;  
} 

Where background-color must match “selected color” that in the case of bootstrap is the “alert-info” Css class background-color.

 @model MVCControlsToolkit.Controls.SimpleMenuItem  
  
@{  
var builder = Html.ExtendedClientMenuFor(  
    m => m.Children, m => m.Link,  
    new { @class = "mainmenu" });  
if (HttpContext.Current.Request.Browser.IsMobileDevice)  
{  
    builder = builder.ActiveOnlyOnClick();  
}  
builder.Target(m => m.Target)  
.Radiuses(0.5f, 1f, 0.5f)  
.ItemSelection(structurePathSelectClass: "light-select")//<-  
  
.TemplatesBaseName("Basic_MenuItem")  
.TemplateSelector(  
    @"function(x){  
                return (x.Children.peek() ?  
                    'Basic_MenuItem1' : 'Basic_MenuItem0');  
            }")  
.CustomNavigate("Content.virtualNavigation")  
.AddRowType()  
    .StartColumn(m => m.Text)  
        .CustomColumnClass(GenericCssClasses.NoWrap)  
    .EndColumn()  
.EndRowType()  
.AddRowType()  
    .StartColumn(m => m.Text)  
        .CustomColumnClass(GenericCssClasses.NoWrap)  
    .EndColumn()  
    .ChildCollection(m => m.Children)  
.EndRowType();  
  
}  
@builder.Render() 

 .light-select{  
    border:2px solid yellow !important;  
} 

In this case the “selected color” on the menu item linking to “Page 4” becomes visible only if you hover the yellow-border “private area”.

You may also add a breadcrumb and modify the menu select method to update the breadcrumb, too.

That’s all for now! The full code is available in the “ContextDependentMenu” file of the Data Moving Plugin Examples Codeplex site download area. The Visual studio solution must be activated by installing the DataMovingPlugin5Examples.x.x.x.nupkg file you get with the product.

Francesco

Data Moving Plug-in SPA View Engine: Handling Contextual Information and User Authorization

Sun, 08 Sep 2013 22:01:36 GMT

Data Moving Plug-in SPA View Engine

This is the second article about new Data Moving Plug-in SPA View Engine, so the previous article is a pre-requisite for reading it.

In any MVVM (Model View ViewModel) SPA (Single Page Applications) dependencies among the View-ViewModel pairs, and dependencies of each View-ViewModel pair on the global state of the application may undermine the modularity and stability of the whole application:

When a View-ViewModel pair is released we MUST be sure that all pointers to data structures inside the pair are removed, otherwise we may cause memory leaks, and hard to find bugs. For instance, if an event handler maintains a reference to a disposed pair, it may trigger unexpected behaviors each time the event is fired.
As a consequence data structures inside a View-ViewModel pair can’t depend on observables that are outside of the pair. Accordingly, external dependencies can’t be updated dynamically by using the observer pattern, but must be copied inside the pair by framework components that are run ONLY on pairs that for sure have not been released. The best time to perform such an update operation is immediately before a pair is rendered since released pairs are not rendered anymore. However, this implies also that we need to force manually re-rendering of pairs displayed on the screen when a dependency changes.
In theory each View-ViewModel pair might contain reference to global application data structures without undermining the application stability, since when the pair is released these references die with the pair. Thus, we might use global data structures for the communication of each View-ViewModel pair with their environment. Unluckily, the use of global variables is an anti-pattern that is known to undermine the modularity of an application. In fact, a change in the global data structures might invalidates all modules! Moreover, modules that depend on global variable are not re-usable in different contexts.

The Data Moving Plug-in View Engine faces all above problems by concentrating the contextual dependencies in context rules that are run immediately before rendering a View-ViewModel pair. Context rules are run on the ViewModel being rendered till a matching rule is found. The matching rule collects global information the View-ViewModel pair might depend on both to build a context object and to fill some ViewModel properties. The information copied by the context rules in the ViewModel may include interface objects that may be used by the ViewModel methods to manipulate the global application state. This way each template ViewModel pair may cooperate with the remainder of the application while keeping its modularity. In case of virtual pages the interface passed to a ViewModel usually depends not only on the module, and local template name, but also on the role assigned to the virtual page by the virtualReference object that required the page to the page store. The virtual page role is available in its role property.

This way all burden of interpreting the external environment falls on the contextual rules and doesn’t undermine the modularity of the View-ViewModel pairs: View-ViewModel pairs may be used in different contexts by simply changing or adding some context rules, without modifying their code.

The purpose of the context object is twofold:

The context object contains all information needed for selecting the right version of the template-AMD module pair to instantiate. In fact, the action methods that deploys both the templates and the AMD of each module may accept parameters such as the name of the logged user and the selected culture, to adapt the module to the context. Such parameters MUST be inserted in the URL because both the AMD and the templates are cached by the browser, thus the insertion of the contextual parameters in the URL is the only way to force the browser to cache different copies for each different set of parameters.
The context object may contain also a redirect directive that forces the loading of a completely different view (belonging to the same module or to a different module). This capability is used to redirect an user to the login virtual page when he/she tries to access a virtual page that is not available for anonymous users. Moreover, after log-in the insertion of the username among the parameters that are sent to the server allows the personalization of the template/AMD modules to the actual privileges of the user.
The context object contains a synthesis of global information the View-ViewModel pair depends on that is used to decide if the pair needs to be re-rendered, or not. In fact, virtual pages retrieved from the page store normally are not re-rendered but used as they were left the last time they were used. However, if the context object created when the pair was rendered differs from the current context the pair is re-rendered to adapt it it to the new context. More specifically, re-rendering forces the re-application of the javascript function defined in the AMD module to the ViewModel, that takes advantage of the information about the external environment written in the ViewModel properties by the context rules to adapt the View-ViewModel pair to the new situation. In case the context rules add different parameters to the URL, or redirect to a different View the ViewModel is completely reset and filled with new content and rendered with a different template.

Below a context rule that handles a page that is available only for logged-in users:

 mvcct.ko.dynamicTemplates.addContextRule(function (data, cb) {
    var currUser = mvcct.ko.dynamicTemplates.authorizationManager().currentUser();
    if (data.module == "People") {
        if (!currUser) {
            cb.redirect("Login", "Home", "Home");
        }
        else {
            cb.add(currUser)
              .addTicket();
        }
        return true;
    }
    return false;
});
 

A new context rule is added by passing a function to the mvcct.ko.dynamicTemplates.addContextRule method. This function receives the ViewModel and a context builder object as parameters. The function is expected to return true when its pre-concitions are satisfied and false otherwise. Inside the context rule we may build the context object by using the fluent interface of the context builder object.

In our case the preconditions of the rules are satisfied only if the module name is “People”. In more complex applications having several modules that require login, a simple solution is to give them a common name prefix: something like “secure_people”, so that context rules may just check this prefix.

In our case the rule verifies if the user is logged in with a call to the authorizationManager. If the user is not logged, we insert a “redirect to the login virtual page” request into the context object by calling the redirect method of the context builder.

If the user is logged, instead, we add the username and the authentication ticket to the url. In this case we don’t write anything in the ViewModel, since the partial views that implement the templates and AMD will take care of adapting the content deployed to the logged user.

The addition of the authorization ticket to the URL must be done if and only if the AMD and template contain sensitive information that must be protected from unauthorized accesses. The insertion of the authorization ticket in the URL DE FACTO prevents the caching of the templates and AMD in the browser cache, since the authorization ticket usually has a short life. Moreover, caching MUST be explicitly prohibited with an adequate OutputCache attribute to protect the sensitive information from malicious users that might manipulate the Browser Cache.

For the above reasons, it is advised to avoid the insertion of the authorization ticket in the URL, and to it is advised to require any sensitive information with a subsequent ajax call to the server. In this case the username passed in the URL may be used just to adapt the graphics of the virtual page to the logged user by removing links to pages that the user is not authorized to visit, and by customizing the virtual page with some user preference the user might have provided someway.

The add context builder method stacks the strings passed as parameters in the URL one after the other, before the module name. For instance if after the add(currUser) we perform another add for the selected culture we get URLs like: …./en-US/john32/People/ for the templates and …./en-US/john32/People.js for the AMD. In case we require also the addition of the authorization ticket, the ticket is appended just to AMD module URL,: …./en-US/john32/People.js?ticket=<authorization ticket>. The request for the templates doesn’t need to include explicitly the authorization ticket in the URL, since this request uses cookies and consequently it is authenticated with the authorization ticket contained in the Asp.net authorization cookie.

The context builder object contains also other two add methods, namely:

addv(x): it stacks the string passed as parameter before the template local name, instead of before the module name. This means that the module request remain unchanged, but a different template that is contained in the same module is requested. For instance if we stack the “Logged” string with addv, to the view named “List” contained in the “People” module, then the request for the People module remains unchanged: …./People/ for the templates and …./People.js for the AMD, but the template used to render the ViewModel will be People/Logged/List instead of People/List.
addc(x): it just modifies the context object without modifying neither the module name nor the view name. All strings passed with addc are stacked together to record a dependency from the environment. This way, when the above strings change the difference in the context forces the re-rendering of the View-ViewModel pair. Normally addc is used together with changes in some ViewModel properties. This way, addc forces the re-rendering of the View-ViewModel pair, and the re-rendering of the pair produces a different result because of the ViewModel modifications.

Below a set of context rules adequate for handling user authorization:

 (function () {
    mvcct.ko.dynamicTemplates.addContextRule(function (data, cb) {
        if ((data.view == "Login" || data.view == "Register" ) && data.module == "Home") {
            if (mvcct.ko.dynamicTemplates.authorizationManager().currentUser()) {
                cb.vadd("Logged");
            }
            return true;
        }
        return false;
    });
    mvcct.ko.dynamicTemplates.addContextRule(function (data, cb) {
        var currUser = mvcct.ko.dynamicTemplates.authorizationManager().currentUser();
        if (data.module == "People") {
            if (!currUser) {
                cb.redirect("Login", "Home", "Home");
            }
            else {
                cb.add(currUser)
                  .addTicket();
            }
            return true;
        }
        return false;
    });
    mvcct.ko.dynamicTemplates.addContextRule(function (data, cb) {
        var currUser = mvcct.ko.dynamicTemplates.authorizationManager().currentUser();
        if (mvcct.ko.dynamicTemplates.isBaseViewModel(data)) {
                          //force re-rendering of all virtual pages 
                          //if logged user changes
            cb.cadd(currUser || '');
            return true;
        }
        return false;
    });
})();
 

The first rule changes the view used to render the Login and Register virtual pages in case the user is already logged, by adding a view prefix with vadd. The second rule is the rule we already analyzed for redirecting anonymous users to the login page when they need to access pages that require login.

Finally, the last rules is fired for all virtual pages that doesn’t satisfy the previous rules. The mvvct.ko.dynamicTemplates.isBaseViewModel verifies that data is a virtual page ViewModel. This rules, requires the re-rendering of a virtual whenever the logged user changes by means of the cadd method. This re-rendering is necessary because of page headers that might depend on the logged use (for instance the login/logout link).

It is worth to point out that re-rendering doesn’t imply necessarily any loss of data that might be contained in the ViewModel. Data are reset just when a virtual page is rendered the first time, or when it has been re-rendered because of a change of the template/javscript selected. Thus, re-rendering caused by a cadd doesn’t cause any loss of data but just a refresh of the contextual information.

The javascript code associated to any template is informed about the need to re-initialize the whole ViewModel through the _initialized boolean property that is added to each ViewModel. When the javascript code initializes a ViewModel it sets this property to true. The property is automatically re-set to false whenever the framework realizes that the ViewModel needs to be re-initialized. Below an example of usage of the _initialized property:

    <script>
    (function () {
        @Html.JavaScriptDefine("viewModel",  new HumanResourcesViewModel()) 
        function afterRender(nodes, vm) {
            vm.updater.options({
                onUpdateComplete: function () {
                    $.unblockUI();
                },
                htmlStatusMessages: function (statusCode, statusText) {
                    if (statusCode == 401) return "@SiteResources.Unauthorized";
                    else return statusText;
                },
                updatingCallback: function () {
                    $.blockUI();
                    return true;
                }
            });
            vm._utilities.humanResourcesRM.options({
                htmlStatusMessages: function (statusCode, statusText) {
                    if (statusCode == 401) return "@SiteResources.Unauthorized";
                    else return statusText;
                }
            });
        }
        mvcct.core.moduleResult(function (vm) {
            if (!vm._initialized) {
                vm._initialized = true;
                vm._utilities = {};
                vm._utilities.clientSubmit = function (id, jTarget, operation) {
                    if (operation == "operation-submit") {
                        var jForm = jTarget.closest('form');
                        if (jForm.validate().form()) vm.updater.update(jForm);
                        return false;
                    }
                    return true;
                };
                vm._utilities.selectItem = function (act) { act.addClass("item-selected"); };
                vm._utilities.unselectItem = function (prev, act) {
                    prev.removeClass("item-selected"); return false;
                };
                vm.Content = ko.mapping.fromJS(viewModel);
                vm._title = "@SiteResources.HumanResourcesListTitle";
            }
            return { afterRender: afterRender };
        });
    })();  
</script>
 

In the example above, if re-rendering is required because of a cadd-only context change the template is re-rendered, and the afterRender function is re-executed on the newly created html, but all ViewModel building is saved because it has been enclosed within an (!vm_initialized) if.

The context object may be accessed also in the javascript code associated to a template by calling the function: mvcct.ko.dynamicTemplates.getContext(vm). In the example below the context object is used to decide which javascript module to call for initializing the ViewModel:

 <script> 
    define(function () {
        @Html.IncludeStaticJsModules("Home/MenuJs", 
            "Home/RegisterJs", "Home/LoginJs", "Home/LogoutJs", "Home/RegistredJs")
        return mvcct.core.withIncludedModules(
            function (menuF, registerF, loginF, logoutF, registredF) {
            return function (vm, viewName) {
                var context = mvcct.ko.dynamicTemplates.getContext(vm);
                vprefix = context ? context.vprefix : '';
                if (viewName == "Menu") return menuF(vm);
                else if (viewName == "Register") return vprefix == "Logged" ? 
                    registredF(vm) : registerF(vm);
                else if (viewName == "Login") return vprefix == "Logged" ? 
                    logoutF(vm) : loginF(vm);
                return null;
            }
        });
    });  
</script>
 

In fact in case the user is logged we not only need completely different templates, but also a completely different initialization code, since the underlying data are completely different.

In order to add multi-lingual support to the context rules of our previous example it is enough to add a .add(<language string>) call to all our context rules. The <language string> may be extracted by the cookie we use to record the user language settings.

In order to add support for user authorization we need also to initialize properly the authorizationManager, and to implement the action methods, to login, logout, register, and to verify the name of the currently logged user. The Register action method is not conceptually different from any standard register method. Below, all other methods:

 [OutputCache(NoStore=true, Duration = 0)]
public ActionResult Logout()
{
    if (HttpContext.User.Identity.IsAuthenticated) FormsAuthentication.SignOut();
    return Json(true, JsonRequestBehavior.AllowGet);
}
[OutputCache(NoStore = true, Duration = 0)]
public ActionResult CurrentUser()
{
    if (HttpContext.User != null && HttpContext.User.Identity.IsAuthenticated) 
        return Json(HttpContext.User.Identity.Name, JsonRequestBehavior.AllowGet);
    return Json("", JsonRequestBehavior.AllowGet);
    
}
public ActionResult Login(LoginModel model)
{
 
    var rb = ResponseBuilder.NewResponseBuilder(model, ModelState);
    string valueToReturn = "";
    if (ModelState.IsValid)
    {
        if (Membership.ValidateUser(model.Username, model.Password))
        {
            SPASecurity.SetAuthCookie(model.Username, false);
            valueToReturn = model.Username;
        }
        else
        {
            ModelState.AddModelError("", 
                "The user name or password provided is incorrect.");
        }
    }
    return Json(rb.GetResponse(additionalData: valueToReturn));
}
 

The first two methods are self-explanatory, while the login action method differs from a standard Mvc Login method just for the use of the SPASecurity.SetAuthCookie method instead of the FormsAuthentication.SetAuthCookie method.

The login model is sent to the server by a viewModelUpdatesManager, that takes care also of dispatching possible server errors(such as the login failure):

 mvcct.core.moduleResult(function (vm) {
    if (!vm._initialized) {
        vm._initialized = true;
        vm.undoRedo = mvcct.core.undoRedo();
        vm.undoRedo.with(function () {
            vm.Content = ko.mapping.fromJS(loginForm);
        });
        var updaterOptions = {
            onUpdateStart: function () {
                $.blockUI();
            },
            onUpdateComplete: function (e, result, status) {
                if (e.success) {
                    vm.undoRedo.reset();
                    vm.Content.Password('');
                    var redirect = vm.hasRedirect();
                    mvcct.ko.dynamicTemplates.authorizationManager()
                        .declareUser(result.additionalData, !redirect);
                    if (!redirect)
                        vm.goTo(new mvcct.ko.dynamicTemplates.virtualReference("Home", "Menu"));
                }
                $.unblockUI();
            }
        };
        vm.updater = mvcct.viewModelUpdatesManager(
            "@Url.Action("Login", "Account")",
            vm,
            "Content",
            vm.Content,
            "",
            updaterOptions);
        vm._title = "@SiteResources.LoginTitle";
    }
    return {afterRender: afterRender };
});
 

In the onUpdateComplete callback, in case of success, we reset the undo-redo stack of the Data Moving Plug-in Form, reset the password property of the ViewModel, then we declare the new user (contained in the additionalData property of the response) to the authorizationManager. If the ViewModel rendered the login page because of a redirect context directive, the ViewModel will be automatically re-initialized to display the original content required as soon as the new user is declared to the authorizationManager. Otherwise, we pass false in the user declaration, which requires a silent user change. As a consequence no re-rendering of the current virtual page is attempted. Then we go manually to the home page by calling the goTo method of the virtual page (see the previous post of the series for more details on the goTo method).

The call to the Logout and CurrentUser action methods are handled automatically by the by the logout(onError) and updateUserFromserver(onServerResponse, onError) methods of the authorizationManager, that are called from within the click hanlders of the logout and refresh links that are in the header of each virtual page:

 vm.refresh = function () {
    mvcct.ko.dynamicTemplates.authorizationManager().updateUserFromserver();
};
vm.logout = function () {
    mvcct.ko.dynamicTemplates.authorizationManager().logout();
};
 

The authorization managers is initialized with the call:

 mvcct.ko.dynamicTemplates.enableAuthorizationManager(
    "@Url.Action("CurrentUser", "Account")",
    "@Url.Action("Logout", "Account")",
    null,
    applicationModel.CurrentPage
    );
 

The first argument is the link of the CurrentUser action method, the second one the link of the Logout method, the third argument, if provided, is an onLogout callback while the fourth argument is a single observable or an array of observables that must be refreshed when the user changes. In our case we passed as fourth argument our unique container of all virtual pages. In a more complex application that hosts several physical pages in the same physical page we might have passed an array containing several observables used as virtual page containers.

In all action methods that deploy templates/AMD only to logged users we must call the method to SPASecurity.ValidatedUser to validated the user received as parameter:

 public ActionResult People(string user, bool isJs, string ticket)
{
    string module = "People/Main";
    if (!SPASecurity.ValidateUser(user, ticket)) return new HttpUnauthorizedResult();
    if (isJs) return this.MinifiedJavascriptResult(module + "Js");
    return PartialView(module, user+"/People");
}
 

The SPASecurity.ValidatedUser method attempts validation with both the asp.net authorization cookie and with the ticket passed as argument.

That’s all for now! A video showing the Data Moving Plug-in SPA View Engine is available here.

Francesco

Data Moving Plug-in SPA View Engine

Sun, 01 Sep 2013 21:34:58 GMT

Data Moving Plug-in SPA View Engine: Handling Contextual Information and User Authorization

The RTM version of the Data Moving Plug-in comes with a sophisticated SPA view engine. Views are downloaded dynamically from the server when they are needed together with Javascript AMD modules containing all code they need to work properly.

Views are developed as Mvc Partial Views and are then compiled into client side templates. Accordingly, they may use all Data Moving Plug-in controls and features.

Also the AMD associated with each View may be developed as Partial Views and may take advantage of the Razor syntax to supply dynamic content to the client. Specifically, the developer may use Html extensions to serialize .Net data structures into their equivalent Javascript data structures, thus avoiding the duplication of the same data structures in both .Net and javascript. Moreover, the AMD content may depend on the language selected and on the user logged – in, and in general it may depend on contextual information, since it is created dynamically.

Both Views and their associated AMD are deployed by Asp.Net Mvc Controllers that take care of verifying user authorizations, of minifying the AMD code, and of handling the caching of both Views and AMD.

Basics

Views are organized into logical units, in the same way as several classes are organized into dlls (dynamic load libraries). In turn, each logical unit is composed of two deployment units: a template module containing all Views of the logical unit compiled into clients templates, and an overall AMD module containing the Javascript code associated with all Views of the template module in a minified format. Thus, Mvc Controllers, actually deploy template modules and overall AMD modules.

The organization of Views and of their associated AMD modules into deployment units increases the modularity of the application and reduces server round trips.

Typically all View related modules are deployed by an unique Controller that has a different action method for each module. In other words each action method is in charge for deploying both the overall AMD and the template module of a single logical unit.

Below a typical action method:

 public ActionResult Home(bool isJs)
{
    string module = "Home/Main";
    if (isJs) return this.MinifiedJavascriptResult(module+"Js");
    return PartialView(module, "Home");
}
 

If the isJs parameter is true the controller deploys the overall AMD module, otherwise it deploys the template module. The overall AMD module is deployed by the MinifiedJavascripResult method that takes care of extracting and minifying all javascript contained in the partial View.

In the example above the template module, and the overall AMD module are contained respectively in the partial views Home/Main.cshtml, and Home/MainJs.cshtml located under the controller folder. Both files don’t contain the whole code but just the code needed to package all Views and all AMD modules into single deployment units. Typically, the code of each view and AMD is contained in a separate partial view that is called by the Main or MainJs partial view.

Below a typical organization of Views and AMD files handled by a controller called TemplatesController:

Each logical unit is contained in a folder with the same name of the unit. All partial views containing code have the same name of their associated Views with a Js postfix. The Main and MainJs partial views of each folder take care of packaging all partial views contained in the folder into the two deployment units called by the controller.

Below a typical MainJs module:

  
<script> 
    define(function () {
        @Html.IncludeStaticJsModules("Home/MenuJs", "Home/RegisterJs", 
                                  "Home/LoginJs", "Home/LogoutJs", "Home/RegistredJs")
        return mvcct.core.withIncludedModules(
            function (menuF, registerF, loginF, logoutF, registredF) {
                return function (vm, viewName) {
                    if (viewName == "Menu") return menuF(vm);
                    else if (viewName == "Register") return registerF(vm);
                    else if (viewName == "Login") return loginF(vm);
                    else if (viewName == "Logout") return logoutF(vm);
                    else if (viewName == "Registred") return registredF(vm);
                    return null;
            }
        });
    });
   
</script>
 

It is an AMD that returns a function of two parameters a data item and a view name. This function will be called with the name of the view to render and with the data item that will be bound to that view. This function just selects a function specific for each view that is defined in a separate partial view. The javascript code in the partial view must be included within <script> tags to get a valid Razor syntax. These tags will be removed by the MinifiedJavascriptResult helper method in the controller.

The partial views containing the view specific javascript code are included statically in the MainJs partial view with the call to @Html.IncludeStaticJsModules. After that , the javascript mvcc.core.withIncludedModules binds the values returned by all view specific modules to the parameters, menuF, registerF,…etc.The structure of a typical view specific module will be descibed later on in this post.

Below also a typical Main partial view:

 @model System.String
@using SPAExample.Models
@{var toRender = Html.DeclareClientTemplates(Model)
      .AddContentPagePartial<FatherVirtualReferenceMenuItem>( "Home/Menu", null, "Menu")
      .AddContentPagePartial<LoginModel>("Home/Login", null, "Login")
      .AddContentPagePartial<LoginModel>("Home/Logout", null, "Logout")
      .AddContentPagePartial<LoginModel>("Home/Registred", null, "Registred")
      .AddContentPagePartial<Person>(
      "Home/Register", null, "Register")
      .AddPartial<VirtualReferenceMenuItem>("Home/MenuItem", null, "MenuItem");
  }
@toRender.Render()
 

It receives as input the module name. In fact the module name is not fixed, but may contain prefixes with the selected language, the user logged in, and other context-dependent information. Thus, in general, a module name has a structure of the type: en-US/john777/Home. The code contained in the view declares the module, adds a template for each view, and finally renders the whole module The rendered content is an Html node containing several client side template inside it. The first argument of each template declaration is the template, while the last argument is the view local name; the view full name is obtained as: <module name>+”_”+<view local name>. In the example above each template is specified with a partial view, so the first argument is just the partial view name. However, templates may be specified also as in-line razor templates. See here fore more details on templates.

The AddContentPagePartial helper is a simplified way to define Views that cover the role of virtual pages. In fact each virtual page has the following standard structure:

 public class baseViewModel<T>
{
    public T Content { get; set; }
    public string view { get; set; }
    public string module { get; set; }
    public bool hasJs { get; set; }
}
 

It contains the view local name, the module the view is in (without any contextual prefix), a boolean that is true if the page has associated javascript code. Then it contains a generic content. The AddContentPagePartial helper specifies a template for just the content of the page.

Below the two routing rules that pass all AMD and template modules requests to the action methods:

 routes.MapRoute(
    name: "Templates",
    url: "templates/{action}/",
    defaults: 
        new { controller = "Templates", action = "Home", isJs =  false}
);
routes.MapRoute(
    name: "templatesAMD",
    url: "templates_amd/{action}.js",
    defaults: 
        new { controller = "Templates", action = "Home", isJs = true }
);
 

Below the action method that deploys the “People” template module and overall AMD only to logged users:

 public ActionResult People(string user, bool isJs, string ticket)
{
    string module = "People/Main";
    if (!SPASecurity.ValidateUser(user, ticket)) return new HttpUnauthorizedResult();
    if (isJs) return this.MinifiedJavascriptResult(module + "Js");
    return PartialView(module, user+"/People");
}
 

It has two more parameters: the user name, and the authentication ticket. In the template module request the authentication ticket is passed in the asp.net authentication cookie, while in the overall AMD request the ticket is inserted in the query string with the format: ?ticket=<auth ticket>, since Javascript file requests typically do not send cookies.

The SPASecurity.ValidateUser static method verifes the authentication ticket, and returns an HttpUnauthorizedResult when the verification fails.

The username is explicitly inserted in the URL so that both template and javascript files may be cached on a user dependent way. In general, context information like the username and the language selected are stacked before the module name in the URL:

../en-US/john122/People.js?ticket=<auth ticket>, and …../en-US/john122/People/.

URLs are built automatically this way on the client side according to context rules provided by the developer. We will discuss these rules in the next post about the SPA engine.

The routing rules for all user dependent modules are :

 routes.MapRoute(
    name: "TemplatesWithUer",
    url: "templates/{user}/{action}/",
    defaults: 
        new { controller = "Templates", action = "Home", isJs = false}
);
routes.MapRoute(
    name: "templatesAMDWithUer",
    url: "templates_amd/{user}/{action}.js",
    defaults: 
        new { controller = "Templates", action = "Home", isJs = true }
);
 

Modules are cached by the browser if we add adequate OutputCache attributes to the action methods that handle the modules. However modules are cached also inside the Html page with a least recently used strategy to improve performance. As a default the framework cache 10 modules, but this value may be changed by calling the javascript method:

 mvcct.ko.dynamicTemplates.cache(<cache size>);
 

The View Engine Cycle

Views are loaded in “placeholders” bound to model properties: each time the a new data item is inserted in the property, a template selection function selects a new view to use for rendering the new data item. Before rendering starts the data item is manipulated, and possibly filled with new content by the AMD associated with the selected view.

More specifically, the following procedure is triggered each time a new data item vm is associated to a “placeholder”:

A template selection function selects the view to render.
If the module the View belongs to has not been downloaded from the server, yet, it is downloaded.
A function func returned as value from the AMD associated with the view is evaluated on the data item, and on the view name: func(vm, viewName).
The result res returned by the function evaluation is possibly stored in a property of the data item, and is used also in the last step of this procedure.
The selected view (which is a client template) is instantiated , bound to the data item using knockout bindings, and inserted in the “placeholder”.
if res contains a property called afterRender, it is assumed to be a function that is evaluated passing it the array of html nodes created by the view instantiation, and the data item vm.

Thus, the developer may modify vm before its rendering with func and immediately after its rendering with the afterRender function. Typically, func fills vm with javascript content while afterRender applies jquery plugins to the rendered content, and specifies options of updatesManagers and retrievalManagers possibly created during the view rendering.

Typically, data items, representing “virtual pages” are initially empty, and contain just the page complete name (module name + view name). The whole page content is put in place by func. The function func is the same for each module and it is the function returned by each MainJs partial view, we discussed before in this post. It just dispatches the call to view specific functions. Below a view specific javascript module that prepares a menu virtual page:

 @{
        var menuItems = new List<BaseVirtualReferenceMenuItem>();
        var menuItem = new VirtualReferenceMenuItem(
            new virtualReference() { module = "Home", view = "Login", }, 
            SiteResources.LinkToLoginText, SiteResources.LoginTitle);
        menuItems.Add(menuItem);
        menuItem = new VirtualReferenceMenuItem(
            new virtualReference() { module = "Home", view = "Register", }, 
            SiteResources.LinkToRegisterText, 
            SiteResources.RegisterTitle);
        menuItems.Add(menuItem);  
        menuItem = new VirtualReferenceMenuItem(
            new virtualReference() { module = "People", view = "List", }, 
            SiteResources.LinkToHumanResourcesListText, 
            SiteResources.HumanResourcesListTitle);
        menuItems.Add(menuItem); 
        var mainMenu = new FatherVirtualReferenceMenuItem()
        {
            Children = menuItems
        };
    }
 
   <script>
    (function () {
        @Html.JavaScriptDefine("mainMenu",  mainMenu) 
        mvcct.core.moduleResult(function (vm) {
            if (!vm._initialized) {
                vm._initialized = true;
                vm.Content = ko.mapping.fromJS(mainMenu);
                vm._title = "@SiteResources.HomeTitle";
            }
            return null;
        });
    })();  
</script>
 

The data structure containing all menu information is built in .Net with the help of the virtualReference class that defines virtual links to virtual pages. Text content is taken from a resource file, so it may depend on the selected language. The VirtualPageMenuItem class is not part of the Data Moving Plug-in, but is specific of the example.

The .Net data structure is serialized in javascript by the JavascriptDefine helper that defines a javascript variable named mainMenu and fills it with the serialized data structure.

The mvcct.core.moduleResult javascript funtion returns the module result to the calling MainJs AMD. The returned value is the function that will be applied to the data item vm in case the view required is a “Menu” view. If vm has not been already initialized this function fills the Content property of the virtual page with the data structure describing the whole menu.

Below a javascript module that uses an afterRender function to apply a jQuery plugin to the submit button:

    <script>
    (function () {
        @Html.JavaScriptDefine("personForm", new Person() ) 
        var afterRender = function (nodes, vm) {
            var root = $(mvcct.core.filterHtml(nodes));
            if (root.length == 0) return;
            var prefix = root.attr("data-helper-prefix");
            
            $('#' + prefix + "_btnSubmit").button().click(function () {
                var form = $(this).closest('form');
                if (form.validate().form()) vm.updater.update(form);
            });
        }
        mvcct.core.moduleResult(function (vm) {
            if (!vm._initialized) {
                vm._initialized = true;
                ...
                ...
                ...
                ...
            }
            return {afterRender: afterRender };
        });
    })();  
</script>
 

It is worth to point out how the button is located in the page. We can’t use a Css class to locate the button since this way we would risk to re-apply the jquery plug-in also to other buttons contained in other instances of the same view that have already been rendered in the Html page. A .find applied only to the newly created content might be too inefficient since it would not use CSS inedexes of the Html page. Thus, the best solution is using ids and Css classes that are specific to the instance of the view. In our case we prefix the button id with an unique identifiers, different for each view instance, with the PrefixedId helper:

 <input id="@Html.PrefixedId("btnSubmit")" 
        type="button" value="@SiteResources.Submit" class ="button"/>
 

The same prefix is added in the data-helper-prefix html5 attribute of the root node of the template:

 <div class="@(JQueryUICssClasses.ContentContainer+" main-page")" 
    data-helper-prefix="@Html.PrefixedId("")">
 

This way the javascript module may read the prefix that uniquely identifies the page instance with:

 var prefix = root.attr("data-helper-prefix");
 

and it may use it to locate all html content in the view instance. The root html node is computed by filtering out all not-Html nodes from the array of all rendered nodes with the helper function: mvcct.core.filterHtml.

The content of each AMD, may depend on parameters like the selected language, or the user logged in, but it can’t depend on the specific database state since, for performance reasons, AMD module must be cached by the browser. Therefore, data coming from the database can’t be added to vm by func, that is part of an AMD, but must be required to the server with a subsequent ajax call placed in the afterRender function or by instructing a retrievalManager to fetch data from the server as soon as it has been created.

Below a retrievalManager instructed to fetch data from the server immediately after it has been created:

 .StartAjaxPostRetrievalManager(true, 
    "@._utilities.humanResourcesRM", 
    1, actionUrl: Url.Action("JsonQuery", "HumanResources"))
 

It is enough to set to true the first parameter passed to the retrievalManager.

The javascript module associated to the view of the retrievalManager above, specifies some options for the retrievalManager and for an updatesManager rendered in the view in its afterRender:

    <script>
    (function () {
        @Html.JavaScriptDefine("viewModel",  new HumanResourcesViewModel()) 
        function afterRender(nodes, vm) {
            vm.updater.options({
                onUpdateComplete: function () {
                    $.unblockUI();
                },
                htmlStatusMessages: function (statusCode, statusText) {
                    if (statusCode == 401) return "@SiteResources.Unauthorized";
                    else return statusText;
                },
                updatingCallback: function () {
                    $.blockUI();
                    return true;
                }
            });
            vm._utilities.humanResourcesRM.options({
                htmlStatusMessages: function (statusCode, statusText) {
                    if (statusCode == 401) return "@SiteResources.Unauthorized";
                    else return statusText;
                }
            });
        }
        mvcct.core.moduleResult(function (vm) {
            if (!vm._initialized) {
                ...
                ...
                ...
            }
            return { afterRender: afterRender };
        });
    })();  
</script>
 

The options passed specify custom error messages in case of unauthorized access to the server methods (status code 401), and apply screen blocking during the communication with the server.

Defining the View Placeholders

Views are loaded into View placeholder, that are bound to model properties. Root placeholders are inserted in the host Html page and each view may, in turn, contain nested view placeholders. Views inserted in root placeholders play the role of virtual pages, while nested views play the role of “widgets”. A physical Html host page may contain several virtual pages, but most of SPA contain just a single root view placeholder that is connected with the back and forward browser buttons to simulate the behavior of a standard Html page.

Root placeholder are defined with the ClientIteratorFor helper extension. Below an example of usage:

 <div class="page-container">
    @h.ClientTreeIteratorFor(m => m.CurrentPage, null, 
      "function(x){ $(mvcct.core.filterHtml(x)).fadeOut(0).fadeIn(500);}",
      "function(x, y, i, f){$.when($(mvcct.core.filterHtml(x)).fadeOut(500)).always(f);}")
</div>
 

The first parameter is the property that will be bound to the view placeholder. Each time a new data item is inserted in this property the view engine cycle is run to load a new view. In SPA applications the second parameter is always null, while the third and fourth parameters specify respectively a before render and an after render functions. They are used to implement transition animations. In the example above the before render function runs a fade-out animation, while the after render function specifies a fade-in animation. When the before render animation completes it MUST call the function f passed as fourth parameter to inform the view engine that it can remove the old view and can insert the new one.

Placeholders for nested views are specified with RecurIterationOnSingle and RecurIterationOn html extensions. The first one adds a single view instance and may be bound to a property containing a single data item, while the second one adds several views, one for each data item contained in the IEnumerable it is bound to. Below a RecurIterationOnSingle renders a widget containing a page header and a RecurIterationOn helper renders all menu item of a menu page:

 <div class="@(JQueryUICssClasses.ContentContainer+" main-page")">
    <h1 class="@(JQueryUICssClasses.HeaderContainer+" main-menu-title")">
            @SiteResources.HomeTitle</h1>
        
    @Html.RecurIterationOnSingle(m => m.Header,
        wrapper: ExternalContainerType.div, wrapperAttributes: 
            new {data_spa_widget="Basic.NavigationHeader.js", @class="header-links"})
        
    @Html.RecurIterationOn(m => m.Children,
        wrapper: ExternalContainerType.nav, wrapperAttributes: 
            new {data_spa_widget="Home.MenuItem", @class="main-menu"})
</div>
 

Their first parameter is the property the placeholder will be bound to, while the wrapper and wrapperAttributes optional parameters specify respectively an html node that will enclose the dynamic content and its Html attributes. The data-spa-widget html5 attribute specifies witch view to render. More details on the use of this attribute are contained in the next section.

Also the RecurIterationOnSingle and RecurIterationOn html extension allow before render and after render animations useful to define transition.

Virtual Pages and Default Template Selection Function

The view to load is decided by a template selection function. The default template selection function is able to select the view to load just for virtual pages and for widgets. Normally, this is enough, but the developer has also the option to specify a custom template selection function to be used for all nested views of a module, as first parameter of the Render function of the module definition:

 @{var toRender = Html.DeclareClientTemplates(Model)
      ...
      ...
      ...
  }
@toRender.Render("$data.myCustomTemplateSelection")
 

The $data bindings variable specifies that the function is contained in the current view model. We may use also $parent, etc. For more details see here.

Virtual pages are data items that works as empty containers and that specify the view they “need” through their view, module, and hasJs properties, so the default template selection needs just to read these properties. The selected AMD module fill the Content property of the empty page with content specific for the selected view and transforms the empty page into a complete working page.

Nested views (views that are not virtual pages) may be selected by the default template selection functions by means of the data-spa-widget html5 attribute that may be placed in the wrapper Html node that encloses the view placeholder. Its format is: <module>.<view>[.js]. The js suffix specifies that the module has an associated AMD module.

Pages are handled by mvcct.ko.dynamicTemplates.pageStore instances. When the application starts a default pageStore instance is created and inserted in the mvcct.ko.dynamicTemplates.defaultPageStore variable. The developer needs to create other pageStore instances only if the host page contains several page placeholders.

Pages are created by passing a virtualReference object to the get method of a pageStore instance. Once we receive the requested virtual page from the get method we may place it in a property associated with a virtual page placeholder. This trigger automatically the view loading procedure.

Below the first page loading that bootstraps an SPA:

 applicationModel.CurrentPage(mvcct.ko.dynamicTemplates.defaultPageStore.get(
    new mvcct.ko.dynamicTemplates.virtualReference("Home", "Menu")));
 

If the stored property of the virtualReference is true (its default) the virtual page is stored in the page store after its creation, while if the stored property is true (its default) an already stored virtual page with the same full name will be returned, if available in the page store. The virtualReference may specify also a role string property. In this case a stored page is returned only if the role specified when it was created matches the role of the virtualReference passed to the get method.

After the SPA bootstrap a new page may be loaded passing a virtualReference directly to the goTo method of current page. If no second argument is passed the page is retrieved from the default page store, otherwise the second argument must be the page store to use. Most of the times, we don’t call directly the goTo method but use the VirtualLink and VirtualLinkFor html extensions that do this job for us:

 @Html.VirtualLinkFor(m => m.Text, m => m.Link, title: m => m.Title)
 

Where the Link property must contain an instance of the virtualReference class.

The main purpose of the page store is to keep the state of each page, so that when the user returns on the same page he finds the page exactly in the same state he left it. This ensures a better user experience, and makes the SPA similar to a native windows application.

A call to the enablePushState method of a pageStore instance connects it to the browser history, so the user may navigate among the virtual pages with the back and forward browser buttons. If the browser doesn’t support pushState, the view engine reverts automatically to a software simulation.

Static Modules

Some modules might be loaded immediately when the SPA starts. For instance it is convenient that widgets used by all pages, such as page headers and footers be loaded as soon as the SPA starts and kept in the page for the whole lifetime of the page. The error page that is shown in case of module loading errors MUST be loaded statically when the SPA starts to ensure that it is always available in case of network problems.

Loading modules statically is straightforward. The AMD module is required with a standard javascript <script> tag:

 <script src="@Url.Content("~/templates_amd/Basic.js")" type="text/javascript"></script>
 

However, in this case the define instruction contained in the module MUST specify explicitly the module name:

 <script> 
    define("Basic", function () {
        @Html.IncludeStaticJsModules("Basic/NavigationHeaderJs")
        return mvcct.core.withIncludedModules(function (navigationHeaderF) {
            return function (vm, viewName) {
                if (vm && viewName == "NavigationHeader") return navigationHeaderF(vm);
                return null;
            }
        });
    });  
</script>
 

The template module, instead, is defined inside the host page in exactly the same way it is defined in a Main.cshtml file:

 @{var errorTemplates = Html.DeclareClientTemplates("Basic")
    ...
    ...
    ...
}
@errorTemplates.Render()
 

The Host Page

The host page must specify the following configuration information:

Possible options of the AMD loader. The Data Moving Plug-in officially supports require.js, but other AMD loaders with the same interface should work as well.
The base url where to download the template modules and the base url where to download the associated AMD modules
Loader callbacks that block/unblock the screen during the module loading, and that specify which view to show in case of load errors.
The template modules cache size, if different from the 10 default.
Some pageStore configuration (typically just if the page store must be connected to the browser history)

Typically all this information is inserted in the page header as shown in the example below:

 @section Header{
    
    <link href="~/Content/Site.css" rel="stylesheet" /> 
    <script src="@Url.Content("~/Scripts/jquery.blockUI.min.js")" type="text/javascript"></script>
    
  <script type="text/javascript">
        var require = {
            baseUrl: "@Url.Content("~/Scripts/Modules")",
            waitSeconds: 10
        };
 
      @Html.JavaScriptDefine("viewModel",  new PageError())  
      mvcct.ko.dynamicTemplates.callBacks({
        onLoad: function () { $.blockUI(); },
        onLoadEnd: function () { $.unblockUI(); },
        onLoadFailed: function (module, nodes, data) {
            data._errorPage = "Basic_defaultError";
            data.Content = ko.mapping.fromJS(viewModel); 
            data.Content.ErrorMessage("@SiteResources.PageLoadError" + module);
        },
      });
      mvcct.ko.dynamicTemplates.defaultPageStore.enablePushState(2);
      mvcct.ko.dynamicTemplates.cache(5);
      mvcct.ko.dynamicTemplates.service(
          "@Url.Content("~/templates")" + '/',
          "@Url.Content("~/templates_amd")" + '/'); 
  </script>
 <script src="~/Scripts/Modules/contextRules.js"></script>
 <script src="~/Scripts/require.js"></script>
<script src="@Url.Content("~/templates_amd/Basic.js")" type="text/javascript"></script>
}
 

Then the host page body must get a client viewmodel aware Html helper:

 @{var h = Html.SendToClient(m => m, "applicationModel", "page-container");}
 

and must use it to render the root view placeholder:

 <div class="page-container">
    @h.ClientTreeIteratorFor(m => m.CurrentPage, null, 
      "function(x){ $(mvcct.core.filterHtml(x)).fadeOut(0).fadeIn(500);}",
      "function(x, y, i, f){$.when($(mvcct.core.filterHtml(x)).fadeOut(500)).always(f);}")
</div>
 

Finally the page host should contain a javascript script tag with the code that bootstraps the SPA by creating its first virtual page, and if the application uses authorization, the code that bootstraps the SPA authorization system:

 <script type="text/javascript"> 
    $(document).ready(function () {
        mvcct.ko.dynamicTemplates.enableAuthorizationManager(
            "@Url.Action("CurrentUser", "Account")",
            "@Url.Action("Logout", "Account")",
            null,
            applicationModel.CurrentPage
            );
        applicationModel.CurrentPage(mvcct.ko.dynamicTemplates.defaultPageStore.get(
            new mvcct.ko.dynamicTemplates.virtualReference("Home", "Menu")));
    });
</script>
 

That’s all for now! In the next post we will see the SPA engine authorization framework, and how the SPA framework handles context-dependent information such as the user logged in and the selected culture. A video showing the Data Moving Plug-in SPA View Engine is available here.

Francesco

The Code of all Data Moving Plug-in Examples is Available on Codeplex

Wed, 19 Jun 2013 07:00:00 GMT

The code of all Data Moving Plug-in examples shown in all previous videos and tutorials is available on the Data Moving Plug-in Examples Codeplex site. All examples require the installation of the Data Moving Plug-in, so at moment only the ones that received an evaluation or complimentary copy of the Data Moving Plug-in may run them. However, it is interesting in any case to inspect the full code for anyone who already read a tutorial or watched a video about the Data Moving Plug-in.