Views #187

Open
wants to merge 3 commits into
from

Projects

None yet

2 participants

@MisterJames
Collaborator

Mostly done, just have to add a few words on passing in data.

@MisterJames MisterJames changed the title from DNM: Views to WIP: Views (do not merge) Jan 8, 2017
@MisterJames MisterJames changed the title from WIP: Views (do not merge) to Views Jan 9, 2017
@MisterJames MisterJames assigned MisterJames and ardalis and unassigned MisterJames Jan 9, 2017
@MisterJames
Collaborator

Should be ready for review.

+
+## Rendering Web Pages With the Razor View Engine
+
+By default in ASP.NET Core MVC view rendering is the job of the Razor view engine. Razor views are typically composed of interleaved HTML and c# code, the lines of which are run through a parser to generate a class at run time. If we think of our view as a class that has properties and methods on it, we can start to see how some of the elements of the view work. Even our file extension - .cshtml - makes a little more sense as it represents what's in the file - a combination of c# and HTML.
@ardalis
ardalis Jan 9, 2017 Collaborator

c#->C# (throughout)

+
+## The Mechanics of a View
+
+The primary function of the `ViewImports.cshtml` is to provide a mechanism for us to pull in any namespaces that we want available to all our views. This facilitates bringing in a namespace that contains your view models, rather than having to declare them in each of your views (or reference those classes explicitly by their fully qualified name). The other thing you can do here is to manage the tag helpers that Razor is aware of either individually or by namespace.
@ardalis
ardalis Jan 9, 2017 Collaborator

"of the ViewImports.cshtml file"

+
+The primary function of the `ViewImports.cshtml` is to provide a mechanism for us to pull in any namespaces that we want available to all our views. This facilitates bringing in a namespace that contains your view models, rather than having to declare them in each of your views (or reference those classes explicitly by their fully qualified name). The other thing you can do here is to manage the tag helpers that Razor is aware of either individually or by namespace.
+
+`ViewStart.cshtml` is semantically different from `ViewImports.cshtml` in that it can be used as a starting point for view-related logic. You typically use it to set a default layout for you views, but you can also use it to change the layout based on a user's role or to inspect and manipulate the request. A word of caution here, however, for it is as easy to over-reach inside of the `ViewImports` as it is in a view and to start writing business logic in the wrong places. `ViewImports` is likely not the best place to call out to services or enforce business rules.
@ardalis
ardalis Jan 9, 2017 Collaborator

"for you views" -> "for your views"

@ardalis
ardalis Jan 9, 2017 Collaborator

"A word of caution: it is easy to overreach inside of ViewImports and start adding business logic."

+
+`ViewStart.cshtml` is semantically different from `ViewImports.cshtml` in that it can be used as a starting point for view-related logic. You typically use it to set a default layout for you views, but you can also use it to change the layout based on a user's role or to inspect and manipulate the request. A word of caution here, however, for it is as easy to over-reach inside of the `ViewImports` as it is in a view and to start writing business logic in the wrong places. `ViewImports` is likely not the best place to call out to services or enforce business rules.
+
+Finally, the `_Layout.cshtml` is used as a template for rendering your web pages and is located in the `Views\Shared` folder of your project. Layouts allow you to define mandatory and optional sections of what will become your rendered page that can be later filled in by your views. A default layout is created in the project template complete with common styles and page head information, a navigation bar, a footer, a section stubbed in for the body of the page as well as an optional section to add scripts to the final output in your views. You can have as many layouts as are needed, perhaps to enable specific functionality for a subset of users or to provide a different experience in an administration area in your site.
@ardalis
ardalis Jan 9, 2017 Collaborator

Perhaps end this section with a link to learn more:
https://docs.microsoft.com/en-us/aspnet/core/mvc/views/layout

+
+## Using Razor View Engine Features
+
+When you employ these features in unison it is important to remember a few of the rules that govern their use by the view engine. Razor looks for direction on layouts and imports at each level in the folder structure. `Using` statements that bring in a namespace at the root level will be available in all subfolders. Likewise, tag helpers that are brought in at a subfolder level will not be available to other "sibling" folders unless you explicitly declare them there as well. Finally, `ViewImports` are additive and allow you to add or remove namespaces and tag helpers, but declaring imports at a subfolder level will not override or clear out previously imported components.
@ardalis
ardalis Jan 9, 2017 Collaborator

tag helpers should probably be capitalized (throughout).

@ardalis
ardalis Jan 9, 2017 Collaborator

"Razor looks for direction on layouts and imports at each level in the folder structure." This doesn't seem very clear to me - I suspect it will be unclear to readers new to ASP.NET Core as well. Is there a better way to describe this process?

+@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
+```
+
+The `ViewStart` is also pretty straightforward in the template, but its use helps us to understand a little better what is going on. You can think of this code as the code that will be appended to the start of each class that is generated when our views are compiled. In this case, the layout that will be used for all views is assigned to the Layout property of the class. This can be overridden in views if needed. This would also be a good place to evaluate if a different layout should be used for the properties associated with the request, namely a user claim or perhaps the host name.
@ardalis
ardalis Jan 9, 2017 Collaborator

Layout property -> Layout property

@ardalis
ardalis Jan 9, 2017 Collaborator

"This would also be a good place to evaluate if a different layout should be used for the properties associated with the request, namely a user claim or perhaps the host name."
Consider:
"This would also be a good place to customize the view's layout, perhaps based on properties of the request, such as a user claim or the host name."

+}
+```
+
+Our `_Layout.cshtml` file is much more opinionated. It essentially creates the HTML page structure that our views will use including the containers and styles with which they are decorated. The template has to take on some dependencies on JavaScript and CSS libraries in order for this to be of any use to someone creating a web site, and you will see evidence of Bootstrap and jQuery here. We will leave full exploration of the HTML, CSS and JavaScript incorporated in this page to the reader, but there are a few important lines to point out in `_Layout.cshtml`. First is how the page head information is being set.
@ardalis
ardalis Jan 9, 2017 Collaborator

Seem to switch back and forth between "you" and "we". Let's stick with "you" throughout to refer to the reader.

+
+## Using the Data Passed to Our Views
+
+Now that we're starting to see how
@ardalis
ardalis Jan 9, 2017 Collaborator

Unfinished bit...

+
+Now that we're starting to see how
+
+In the sample project we have a controller called `PersonController` with an action method on it called `Index`. Index accepts an integer called `id` as a parameter, retrieves the requested person from the service and returns with a call to the `View` helper method, passing in the person that was resolved from the service.
@ardalis
ardalis Jan 9, 2017 Collaborator

replace "we"
"passing in the Person" (or whatever type person is)

+}
+```
+
+We use the above code with the view we discussed at the start of this document, which we'll revisit now.
@ardalis
ardalis Jan 9, 2017 Collaborator

Replace "we"

+
+In the first line of our document we instruct the view engine to use the `Person` class from our project. The person is set in the `Model` property for us at runtime by virtue of us having passed an instance of a person to the `View` helper method in the controller. To access the properties of our `Person` object, we use the `@Model.FirstName` notation.
+
+There is much more to take advantage of in the Razor view engine and further reading is available at the official documentation, linked to in the "Next Steps" section at the end of the document.
@ardalis
ardalis Jan 9, 2017 Collaborator

Why not just link it here (and keep it in the Next Steps as well)?
"...and further reading is available at the official documentation."

+A partial view has no layout applied to it, so HTML elements in it should be crafted in a way that respect the design frameworks of the pages they will appear in.
@ardalis
ardalis Jan 9, 2017 Collaborator

respect -> respects
frameworks -> framework's
maybe change "design framework" to "UI framework"

+For more information on working with Razor views check out the official [ASP.NET documentation](https://docs.asp.net/en/latest/mvc/views/index.html), or these related resources in this tutorial:
@ardalis
ardalis Jan 9, 2017 Collaborator

Most lessons give the user some "homework". The additional reading/info, is good, too, but before that can you ask the user to use some of what they've just learned in an applied manner? Ask them create a new view or layout (or both) to see how they work together, for instance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment