Working with Sitefinity MVC (Feather) Source Code

UPDATE:

[Please note that with Sitefinity version 10.0.6403.0 the version of Feather has changed. For each version of Sitefinity there is now a specific version of Feather. To create a custom build of Feather projects please use the corresponding version of Sitefinity. To debug the source code, please put all of the projects in one solution and remove the version specific references. After version 10.0.6403.0 all of the test projects will no longer be available.]

All of Sitefinity’s MVC widgets, packages and functionality are open source and can be found under the codename “Project Feather” or “Feather” framework. Project Feather is “A modern, convention-based, mobile-first UI framework for Progress Sitefinity CMS. It allows developers to build mobile-ready sites using their favorite frameworks and includes MVC widgets, an AngularJS widget designer framework, Bootstrap support, and even more.”

Project Feather is made up of three projects with the source code available on GitHub.You get all the benefits of an open source project. You aren’t tied to release schedules, and new features, components or improvements can be implemented and used immediately. You also have the ability to submit pull requests, which helps contributors to improve the product’s direction.

The easiest way to understand the framework is to take a look at the big picture before starting to dig into the details. In this post, I’ll draw the big picture for you and cover the basic aspects of Feather’s structure.

Before we begin, there are three projects—“Feather”, “Feather Widgets” and “Feather Packages”. Download the source code for all three and we’ll get started with the configuration of our solution.

The Big Picture

Since the Feather framework is MVC-based, we need to know how it works and how it’s different from WebForms.

There are three modes for Page Templates:

1. MVC only - only MVC widgets, which are based on a pure MVC template. When a page is rendered it has the widget’s output without any additional WebForms markup.

2. WebForms and MVC (hybrid) - all widgets are available - WebForms and MVC. The page is rendered as a normal WebForms page

3. WebForms only - no MVC support.

Pages in Sitefinity go through the ASP.NET WebForms lifecycle even when the page template is in MVC mode.

So how do the MVC widgets work? A WebForms control is used and instantiates a MvcControllerProxy which executes an action and renders the output as its own.

Frameworks behind Sitefinity template types.

The “Feather” project is the core infrastructure on which the widgets depend. “Feather Widgets” contains multiple projects generating the widget’s assemblies. They don’t depend on each other, so it makes the development easy and decoupled. Each assembly contains one or more widgets from one domain.

“Feather Packages” contain widget views, layout templates and stylesheets for Bootstrap. Stylesheets for the Semantic UI and Foundation community packages can be found there too. This repo is used as a reference in case you want to override the basic implementation of widget views or revert changes in the default Bootstrap package.

Feather projects interactions.

Debugging the Source Code

There are a few options to debug the projects. Before we go through them there is one thing that is worth mentioning. Your web app and the Feather projects should reference the same version of Telerik.Sitefinity.Mvc. If this is not the case, use nuget to install the correct one to your web app.

Here is an example how the versions can differ. The Sitefinity project is using 1.7.600 and the Feather’s projects are using 1.7.640. In this case, you would have to install the newer version of Sitefinity.Mvc.

The first option is to build all of the projects in Debug mode and reference the generated dlls along with the pdb files manually in the SitefinityWebApp project. This can cause overhead because there are many assemblies (20) and it’s possible to mess something up but the process is straightforward and no additional fine tuning is needed. If you want to add a debugger in the code, go to Debug ->New Breakpoint -> Function Breakpoint and add the full namespace to the method e.g. “Telerik.Sitefinity.Frontend.News.Mvc.Controllers.NewsController.Details”.

The above process could be automated with the help of some scripts. Here you could find two powershell scripts that set the Feather’s project to output the built assemblies into a specific folder and reference all of those libraries in the web app that you develop. The only thing that you have to do is to set the path variables in the scripts. After the scripts are executed all of the solutions should be rebuilt.

The last option to debug the source code is to create one solution that holds all of the Feather projects and the Sitefinity web app.

The first step is to open the web app and save the solution to its root folder. There is one caveat when adding the Feather projects. Since they are part of different solutions and rely on specific setups, you have to add some folders in the web app’s root folder. Go to Feather Core project and copy .nuget, FxCop and StyleCop folders and paste them in the Sitefinity’s web app.

After the folders are properly placed, you can start adding the Feather projects. Once you’re done, remove the references from the web app and reference the corresponding project from the solution. Place the debugger into the source code and enjoy.

Testing the Core Project - “Feather”

Changing the functionality of the Core framework can cause a lot of damage to your sites if you don’t validate your newly written code with tests. For this reason, test projects are included in the Core project under the Test folder. There are three types of tests that you should run:

1. Unit

2. Integration

3. Client

To run the all of the unit tests go to Test -> Windows -> Test Explorer and start them. To add custom class with tests, add a class file in Telerik.Sitefinity.Frontend.TestUnit project and mark it with the TestClass attribute. To execute a test method, put a TestMethod attribute on top of it.

The client tests are in the Telerik.Sitefinity.Frontend.ClientTest project. Go to the root of the Feather Core project, run the command prompt and execute the following commands (if you don’t have npm installed, please review this blog post):

• npm install

• npm install -g grunt

• npm install -g grunt-cli

• npm install -g karma

• npm install -g karma-cli

There is a grunt task that runs the tests using PhantomJS and gives the results in the console. To execute the task, go into the root folder and run the grunt command. If there is a warning about the path use grunt --force. This should be the result in the console:

The next step is to debug the client tests. The caveat here is that, before debugging the test, you have to execute the grunt command described above. It should be executed at least once in order to improve some references. Go to the Telerik.Sitefinity.Frontend.ClientTest folder and run test.debug.bat in the cmd. If everything goes fine, you should receive the following result:

To debug a client test, put the debugger definition in a test and click on the DEBUG button of the loaded page shown above. After this, open the console with F12 and enjoy the debugging.

The last part of the test process is to run the integration tests in order to ensure that the integration between the Feather projects and the web app is working properly. The Telerik.Sitefinity.Frontend.TestIntegration project follows the guidelines that are described here. This kind of test needs a specific test runner and a clean instance of the Sitefinity web app that references the test project and all of the Feather’s dlls. If you aren’t familiar with writing integration tests, download a sample from here.

For the Feather Core project you will need only the test runner exe file.

Create a clean SitefinityWebApp project and reference all of the Feather’s dlls and the Telerik.Sitefinity.Frontend.ClientTest project. To add the test project you have to copy the StyleCop folder from the Feather Core project root folder to the root folder of the web app. When everything is set up, run the web app under IIS or IIS Express, get the URL and start the runner.

Which Test Suite to Run and Why

Implementing new features or changing something in the code base requires you to run all of the tests without exceptions. The integration tests take a lot of time. Be sure that you have run the unit suite before that. This will save you time in case that there is a problem that could be discovered with the unit test.  

Testing the “Feather Widgets” Project

Testing the Feather Widgets is the same as the Core project, except for the integration tests you need to copy the the StyleCop, FxCop and .nuget folders from Feather Widgets root folder to the web app root folder.

Working with Feather Packages Project

The project is provided as a reference for developers to easily look at the default definition of the templates and styles, in case something is amiss  in the default package of the Sitefinity web app.

Beyond the Enterprise Mindset

With Feather it’s possible to develop everything instantly—no release dates are necessary to add or change something. The ability to contribute to that project is a huge opportunity to shape Sitefinity’s future, so take advantage of it. Download the projects and submit your pull requests.

One more thing, don’t forget to add tests!