Toolkit Walkthrough

Now its time to create a new MVC project. The new MVC application project template

As the project is created a bunch of items are created for you in ‘Solution Explorer’, that represent an ordinary ASP.NET MVC project, with a few extras.
The contents of the new project

You will also see a new window popup called the ‘Solution Builder’, and in this window you will see the logical structure of an MVC application (i.e. Controllers, Actions, Views, ViewModels etc). This is where you are going to build your solution. How an MVC application is represented to the developer

You will also see another window popup called the ‘Guidance Explorer’, and in this window you will see both informational and instructional guidance on what MVC applications are all about, and how to create one. The contextual guidance presented to the developer

It is this kind of guidance that is critical for developers understanding what the application architecture is, how it works, and furthermore how they can shape it for their requirements on the project. This kind of information is invaluable to developers who may be either new to the organization, new to the toolkit, or new to the MVC technology and architecture. It forms the complete document set for building this kind of application, just where the developer needs it -> right next to what they are doing.

Running the project - where is the Login form?

You will see the standard ‘ASP.NET Development Server’ start up, and the web application starts on the default page, just like a standard ASP.NET MVC 2 application.
The application out of the box

Notice the [Log On] link at the top right of the page. The Login page is not yet implemented!

Creating the login form

In most organizations, to avoid inconsistencies across the web applications they build, and to drive consistency for their users, they tend to want to standardize how standard ‘web application features’ such as logging in and out are implemented. So typically, that kind of organization will want you (the web developer) to use their guidelines for creating a Login form. Creating a new login form

You will notice that a new node is created representing a login form. You may also notice that a bunch of artifacts were added to the solution at the same time.

To view those artifacts, simply double-click on the ‘LogIn’ form and the generated code is opened.

In the ‘Properties Window’ for the new ‘LogIn’ node, take a look at the properties you can configure for all login forms.
The supported properties of the new ‘LogIn’ form

Let’s now start the application again and see what has happened.
You will now notice that clicking the [Log On] link at the top of the home page now takes you to the Log In page!
New login form implemented and wired up

Not only is the log in page implemented for you, but it is wired up in the right place to the application as well! no code required!

Adding a search form

Now let’s do something a little more complex.

Suppose this web application managed a database of customers, and you now want to allow your users to search for and modify customer records. You would need to implement a number of things in the code: a form to capture search criteria, and form to display search results, a layer of the application that fetched data from a data source (i.e. from a DB or data service of some kind). Then you would have to wire it all into the web application.

Remembering that this is an MVC application and remembering that your implementation needs follow some already established MVC architecture rules for this kind of a feature.

Let’s get started using the toolkit to do this. Actually, we will be using multiple toolkits, working together here, to do the work for us. Creating a new custom search form

At this point you will now see a new ‘Search Form’ node appear in the ‘Solution Builder window, but you will also see new guidance appear in the ‘Guidance Explorer’ window specifically for creating search forms. This guidance is especially useful for developers who may not be familiar with either the MVC pattern or ASP.NET post back forms.
Search forms come with their own guidance
What may not be obvious at this point, is that the automation, guidance and code that is generated by the Search Form is provided by another toolkit entirely. You are just seeing that toolkit integrated into the MVCApp Toolkit, where it makes sense in your application.

Form Validation

Now let’s mirror an all too common activity in development. Let’s build the solution at this point, and see what happens. Notice that the ‘Error List’ pops up with some critical errors about the implementation of the web application. Specifically about how the search form is not yet configured correctly. Something is not yet configured correctly

We are missing vital configuration of the search form that is required for correct operation of it, such as: ‘Search Criteria’, ‘Search Columns’ and a ‘Search Provider’

Because the toolkit understands the architecture and requirements of this MVC pattern, through the use of validation rules, it can point out where the developers need to provide input for their specific requirements on the project.
Notice that the ‘View Model’ property is empty. This is a critical error for the search form. The ‘View Model’ is a required piece of configuration that provides the data for the search form to display.
Properties of a new search provider

Let’s now create a ‘View Model’ we can use. A new view model representing a customer

The 'Save' button in ‘Solution Builder’ is provided really just for comfort, as the configuration in solution builder is saved automatically very frequently. Save the solution configuration anytime

Now that we have a view model to work with we can complete the search form configuration, and satisfy the validation errors. Selecting the new ViewModel as the data model for the Search Provider
Let’s now build the solution again.
That configures the ‘Search Provider’, but now we need to configure: the ‘Search Columns’ and ‘Search Results’. Notice that the list of available fields come from the fields of the actual view model that we selected for the ‘Search Provider’.
New search column

Now all that is left is to configure the ‘Search Results’ Notice this time, a wizard appears that can guide us through the process of configuring the properties of the Text Criterion.
A wizard that helps guide you through complex configuration

Wizards are very useful UI guides to help steer developers through complex configuration processes, like this one, where the extra text and layout is more helpful than just a properties grid. Configuring a search criterion

Now that we think we have completed the configuration for a search form, it’s time to build the solution and see if those validation errors are gone. In the process you may notice that a significant amount of new code is added to the solution in the ‘Solution Explorer’ window.

Many of the nodes in solution builder generate and configure multiple artifacts (files) in the solution depending on the configuration of those nodes. There is a many to many mapping from nodes in the Solution Builder to items in the Solution Explorer.

You can always view the code and configuration files associated to a node in the Solution Builder. How to track files controlled by nodes in Solution Builder
You will see multiple (5x) code files open in the IDE that have been generated for you that represent the implementation of the search form.
The search form generates a lot of code integrated into the solution

Wiring up the Search Form

At this point we have configured the search form, it’s time to wire in the search form to the web application to test it.

In this example, we are simply going to add a link in the site master page to display the search form manually. But there are many possibilities in a web application.

The toolkit may or may help you to different levels with things like this wiring using automation, or manual instructions, depending on what the designer of the toolkit wished to focus upon.
<li><%: Html.ActionLink("Search", "Search", "Customers")%></li>


Now you can build and run the web application again and take a look at your search form. The new search form link appears

Now we can test our search form: Notice that the 'Name' (text) search criteria that you configured is displayed. The search criteria page

The search results page is now displayed.
Notice that the 'First Name' result column that you configured is displayed, and that there are no search results.
The search results page

Wiring up the Search Provider - Where are the search results?

You have already seen many examples of automation at work in this toolkit. And you have seen the guidance that can provide high value in the form of documented instructions or information for understanding. In fact, you will probably have noticed that most of the instructions provided in this walkthrough are illustrated in the guidance windows that you may have seen during this walkthrough.

Toolkit users should expect that given any kind of application or architectural pattern, that there will always be custom development activities on a project that are better left to manual coding rather than automated with tools. No toolkit can do everything for you nor presume every aspect and feature of your specific software project.
A toolkit is there to guide you through the 60%-80% of the predictable stuff that is automatable, leaving the 40%-20% manual stuff to your creativity and hand-crafting skills.

You'll notice that there are no search results displayed, because in this toolkit the 'Search Provider' does not implement any data access mechanism to access the data for the search results. In this toolkit, the data access implementation has been deliberately left up the developer to custom code. But the toolkit hasn't quite abandoned the developer to integrate that custom code into what the toolkit has generated. The toolkit has in fact provided some handy hooks for the developer to integrate their data access strategy with the search provider.
Depending on where the data for the search results comes from (i.e. Database, Cloud, service, XML file, etc.), it must be handled by the ViewModel, and presented by the View. This file is one of the files that is generated by the Search Form.
In the file you will find the 'List' method, and if you read the comments you will see what has to be done to integrate your data access strategy with the Model. The overridden method body is generated for you, and the class should look something like this:
namespace MVCApplication1.Providers
{
    partial class CustomerViewModelProvider
    {
        public override IEnumerable<Models.CustomerViewModel> List(Models.FindCustomerModel model)
        {
            return base.List(model);
        }
    }
}

Notice that this method takes a single parameter containing the search criteria (of type 'FindCustomerModel'), and must return a list of search results (of type 'CustomerViewModel').
It is in this method that you would normally write some custom code that does something at minimum like: connect to your data source, construct a query using the parameters in the search criteria, and query the data source. The data source would then return its data in whatever form, and you would likely write some conversion logic to populate a new collection of 'CustomerViewModel' instances.

For this walkthrough, we are simply going to demonstrate this working with some trivial, and nonsense fun code.
            if (!string.IsNullOrEmpty(model.Lastname) 
                && model.Lastname.StartsWith("A"))
            {
                return new[]
                {
                    new Models.CustomerViewModel
                    {
                        CustomerId = "1000", Firstname = "Aaron", Lastname = "Smith", IsManaged = "true"
                    },
                    new Models.CustomerViewModel
                    {
                        CustomerId = "1001", Firstname = "Alice", Lastname = "Jonsson", IsManaged = "false"
                    },
                };
            }
            else
            {
                return new[]
                {
                    new Models.CustomerViewModel
                    {
                        CustomerId = "9000", Firstname = "Peter", Lastname = "Yang", IsManaged = "true"
                    },
                };
            }

You are now ready to try it out in your application. You now see the code you just pasted working for you.
Search results populated

Clearly, this code is nonsense, and would not represent real production code you may need to write. And such code would probably consider aspects like validation of the criteria, and constructing a sensible query etc.
But the point is that to be able to get to the point of writing that code for your application (which is really the interesting stuff), the toolkit has done 95% of the work and plumbing for you.
It is taking care of constructing the OO objects that are used to collect the search criteria, and those which make up the ViewModel. Make a change in the Solution Builder, and the code is adjusted correctly. No manual errors. Not only that but it has generated the right hooks for you to enable you to simply integrate your custom code into the right place in the architecture, making it simple for you to be productive with what the application should be doing.

Wrapping Up

Well, that concludes our walkthrough, we hope you enjoyed using this toolkit, and you could see from this walkthrough the potential value that a toolkit like this can provide (albeit a sample).
We hope you can see ways of improving this experience for other developers yourself, and you may have some good ideas on how you would do it differently if you were to build a toolkit like this.

You may be surprised to know that this toolkit was envisioned, and built to its current level of functionality in about 7-8 days by a developer who had little ASP.NET MVC experience at the time. Although it took a few more days to polish it up with icons, text and guidance, and get and refine with some user feedback.

Where to from here?

You have seen many ideas in this sample toolkit. This one specifically focused on ASP.NET MVC web applications. Remember this is just a sample of some things that a toolkit can do. Not an example of everything a toolkit can do.

So, where to from here? Perhaps the concept of this example really resonated with you but the technology or implementation patterns were not quite right for you or your organization/community. So why not start by creating a toolkit for something that is very familiar for you. Perhaps one based on your own understanding of how components in the types of application you work on should be implemented. There are no rules here. Your toolkits should reflect your learned understanding of what works for you and your organization/community. There is no single right way to do something in software today. But oftentimes a group of developers agree on a way that works for them, and reproducing that across multiple projects consistently is a tedious and error prone process. Why not use automation to help you get it right every time?

Notice how much code you actually wrote to achieve all that you have seen implemented in the Web Application in this walkthrough. That is a huge benefit of toolkits, reducing human error, and enforcing consistency, saving time, money and manual maintenance.

You should get a few tips and pointers to how to implement similar patterns in your own toolkit. And within a few hours or days you could have a similar or better toolkit.

In the Source Code tab of this project you can ‘Download’ or ‘Clone’ the code, open it in Visual Studio, and investigate how this toolkit was created and works.

By using the NuPattern tools you can get started by building your own toolkit. The tools provided to you use the same principles and cues as you have seen in this toolkit: you use Solution Builder to create and configure your toolkit, add the features of your toolkit you want, and add written guidance to help inform and instruct your users on getting their jobs done faster and more consistently with automation and guidance.

Good Luck! and if you have any questions, go ahead and ask them at the Discussion Board of the NuPattern Project.