Abstract navigation components from INavigationTopicViewModel

The `INavigationTopicViewModel` defines properties that are expected to be used by views. The `NavigationTopicViewComponentBase<T>`, and its derivatives, don't need to know about most of that information. Instead, they simply need to know about the `IHiearchicalTopicViewModel<T>`. As such, by relying on this interface instead, we offer more flexibility to navigation component implementations over what types of view they return.

That said, in practice, we anticipate that _most_ implementors _will_ want to implement the members associated with `INavigationTopicViewModel`, and so we continue to support that interface as a convenience for standardizing how navigation view models are implemented, and especially with regards to determining if the current node is currently selected (via the `IsSelected()` method).

Author: JeremyCaney

OnTopic.AspNetCore.Mvc/Components/MenuViewComponentBase{T}.cs

@@ -23,22 +23,29 @@ namespace OnTopic.AspNetCore.Mvc.Components {
   /// </summary>
   /// <remarks>
   ///   <para>
-  ///     As a best practice, global data required by the layout view are requested independent of the current page. This
-  ///     allows each layout element to be provided with its own layout data, in the form of <see
-  ///     cref="NavigationViewModel{T}"/>s, instead of needing to add this data to every view model returned by <see
-  ///     cref="TopicController"/>.
+  ///     As a best practice, global data required by the layout view are requested independent of the current page. This allows
+  ///     each layout element to be provided with its own layout data, in the form of a <see cref="NavigationViewModel{T}"/>s,
+  ///     instead of needing to add this data to every view model returned by e.g. a <see cref="TopicController"/>.
   ///   </para>
   ///   <para>
   ///     In order to remain view model agnostic, the <see cref="NavigationViewModel{T}"/> does not assume that a particular
   ///     view model will be used, and instead accepts a generic argument for any view model that implements the interface <see
-  ///     cref="INavigationTopicViewModel{T}"/>. Since generic view components cannot be effectively routed to, however, that
-  ///     means implementors must, at minimum, provide a local instance of <see cref="NavigationViewModel{T}"/> which sets the
+  ///     cref="IHierarchicalTopicViewModel{T}"/>. Since generic view components cannot be effectively routed to, however, that
+  ///     means implementors must, at minimum, provide a local instance of <see cref="NavigationViewModel{T}"/>, which sets the
   ///     generic value to the desired view model. To help enforce this, while avoiding ambiguity, this class is marked as
   ///     <c>abstract</c> and suffixed with <c>Base</c>.
   ///   </para>
+  ///   <para>
+  ///     While the <see cref="MenuViewComponentBase{T}"/> only requires that the <typeparamref name="T"/> implement <see cref="
+  ///     IHierarchicalTopicViewModel{T}"/>, views will require additional properties. These can be determined on a per-case
+  ///     basis, as required by the implementation. Implementaters, however, should consider implementing the <see cref="
+  ///     INavigationTopicViewModel{T}"/> interface, which provides the standard properties that most views will likely need, as
+  ///     well as a <see cref="INavigationTopicViewModel{T}.IsSelected(String)"/> method for determining if the navigation item
+  ///     is currently selected.
+  ///   </para>
   /// </remarks>
   public abstract class MenuViewComponentBase<T> :
-    NavigationTopicViewComponentBase<T> where T : class, INavigationTopicViewModel<T>, new()
+    NavigationTopicViewComponentBase<T> where T : class, IHierarchicalTopicViewModel<T>, new()
   {
 
     /*==========================================================================================================================

OnTopic.AspNetCore.Mvc/Components/NavigationTopicViewComponentBase{T}.cs

@@ -3,6 +3,7 @@
 | Client        Ignia, LLC
 | Project       Topics Library
 \=============================================================================================================================*/
+using System;
 using Microsoft.AspNetCore.Mvc;
 using OnTopic.Mapping.Hierarchical;
 using OnTopic.Models;
@@ -19,10 +20,20 @@ namespace OnTopic.AspNetCore.Mvc.Components {
   ///   model.
   /// </summary>
   /// <remarks>
+  ///   <para>
   ///   This class is intended to provide a foundation for concrete implementations. It is not a fully formed implementation
   ///   itself. As a result, it is marked as <c>abstract</c>.
+  ///   </para>
+  ///   <para>
+  ///     While the <see cref="NavigationTopicViewComponentBase{T}"/> only requires that the <typeparamref name="T"/> implement
+  ///     <see cref="IHierarchicalTopicViewModel{T}"/>, views will require additional properties. These can be determined on a
+  ///     per-case basis, as required by the implementation. Implementaters, however, should consider implementing the <see cref
+  ///     ="INavigationTopicViewModel{T}"/> interface, which provides the standard properties that most views will likely need,
+  ///     as well as a <see cref="INavigationTopicViewModel{T}.IsSelected(String)"/> method for determining if the navigation
+  ///     item is currently selected.
+  ///   </para>
   /// </remarks>
-  public abstract class NavigationTopicViewComponentBase<T> : ViewComponent where T : class, INavigationTopicViewModel<T>, new() {
+  public abstract class NavigationTopicViewComponentBase<T> : ViewComponent where T : class, IHierarchicalTopicViewModel<T>, new() {
 
     /*==========================================================================================================================
     | PRIVATE VARIABLES

OnTopic.AspNetCore.Mvc/Components/PageLevelNavigationViewComponentBase{T}.cs

@@ -3,6 +3,7 @@
 | Client        Ignia, LLC
 | Project       Topics Library
 \=============================================================================================================================*/
+using System;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Mvc;
 using OnTopic.AspNetCore.Mvc.Controllers;
@@ -30,14 +31,22 @@ namespace OnTopic.AspNetCore.Mvc.Components {
   ///   <para>
   ///     In order to remain view model agnostic, the <see cref="PageLevelNavigationViewComponentBase{T}"/> does not assume that
   ///     a particular view model will be used, and instead accepts a generic argument for any view model that implements the
-  ///     interface <see cref="INavigationTopicViewModel{T}"/>. Since generic view components cannot be effectively routed to,
+  ///     interface <see cref="IHierarchicalTopicViewModel{T}"/>. Since generic view components cannot be effectively routed to,
   ///     however, that means implementors must, at minimum, provide a local instance of <see
   ///     cref="PageLevelNavigationViewComponentBase{T}"/> which sets the generic value to the desired view model. To help
   ///     enforce this, while avoiding ambiguity, this class is marked as <c>abstract</c> and suffixed with <c>Base</c>.
   ///   </para>
+  ///   <para>
+  ///     While the <see cref="PageLevelNavigationViewComponentBase{T}"/> only requires that the <typeparamref name="T"/>
+  ///     implement <see cref="IHierarchicalTopicViewModel{T}"/>, views will require additional properties. These can be
+  ///     determined on a per-case basis, as required by the implementation. Implementaters, however, should consider
+  ///     implementing the <see cref="INavigationTopicViewModel{T}"/> interface, which provides the standard properties that
+  ///     most views will likely need, as well as a <see cref="INavigationTopicViewModel{T}.IsSelected(String)"/> method for
+  ///     determining if the navigation item is currently selected.
+  ///   </para>
   /// </remarks>
   public abstract class PageLevelNavigationViewComponentBase<T> :
-    NavigationTopicViewComponentBase<T> where T : class, INavigationTopicViewModel<T>, new()
+    NavigationTopicViewComponentBase<T> where T : class, IHierarchicalTopicViewModel<T>, new()
   {
 
     /*==========================================================================================================================

OnTopic.AspNetCore.Mvc/Models/NavigationViewModel{T}.cs

@@ -13,21 +13,24 @@ namespace OnTopic.AspNetCore.Mvc.Models {
   | VIEW MODEL: NAVIGATION TOPIC
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Provides a strongly-typed data transfer object for feeding views with information about a tier of navigation.
+  ///   Provides a strongly-typed view model for feeding views with information expected to be required for each node in of
+  ///   navigation.
   /// </summary>
   /// <remarks>
   ///   <para>
   ///     No topics are expected to have a <c>Navigation</c> content type. Instead, this view model is expected to be manually
   ///     constructed by the <see cref="NavigationTopicViewComponentBase{T}"/>.
   ///   </para>
   ///   <para>
-  ///     The <see cref="NavigationRoot"/> can be any view model that implements <see cref="INavigationTopicViewModel{T}"/>,
-  ///     which provides a base level of support for properties associated with the typical <c>Page</c> content type as well as
-  ///     a method for determining if a given <see cref="INavigationTopicViewModel{T}"/> instance is the currently-selected
-  ///     topic. Implementations may support additional properties, as appropriate.
+  ///     The <see cref="NavigationRoot"/> can be any view model that implements <see cref="IHierarchicalTopicViewModel{T}"/>,
+  ///     which ensures support for hierarchical coverage. In practice, we expect most implementers will choose to implement
+  ///     <see cref="INavigationTopicViewModel{T}"/> instead, which addresses not only <see cref="IHierarchicalTopicViewModel{T}
+  ///     "/>, but also provides a base level of support for properties that most navigation views will need, as well as a
+  ///     method for determining if a given <see cref="IHierarchicalTopicViewModel{T}"/> instance is the currently-selected
+  ///     topic. Derived implementations may introduce additional properties, as appropriate.
   ///   </para>
   /// </remarks>
-  public class NavigationViewModel<T> where T : class, INavigationTopicViewModel<T> {
+  public class NavigationViewModel<T> where T : class, IHierarchicalTopicViewModel<T> {
 
     /*==========================================================================================================================
     | NAVIGATION ROOT
@@ -37,9 +40,9 @@ public class NavigationViewModel<T> where T : class, INavigationTopicViewModel<T
     /// </summary>
     /// <remarks>
     ///   Since this implements <see cref="IHierarchicalTopicViewModel{T}"/>, it  may include multiple levels of children. By
-    ///   implementing it as a generic, each site or application can provide its own <see cref="INavigationTopicViewModel{T}"/>
-    ///   implementation, thus potentially extending the schema with properties relevant to that site's navigation. For example,
-    ///   a site may optionally add an <c>IconUrl</c> property if it wishes to assign unique icons to each link in the
+    ///   implementing it as a generic, each site or application can provide its own <see cref="IHierarchicalTopicViewModel{T}"
+    ///   /> implementation, thus potentially extending the schema with properties relevant to that site's navigation. For
+    ///   example, a site may optionally add an <c>IconUrl</c> property if it wishes to assign unique icons to each link in the
     ///   navigation.
     /// </remarks>
     public T? NavigationRoot { get; set; }
@@ -58,7 +61,7 @@ public class NavigationViewModel<T> where T : class, INavigationTopicViewModel<T
     ///     always have access to this information.
     ///   </para>
     ///   <para>
-    ///     It's worth noting that while this <i>could</i> be stored on the <see cref="INavigationTopicViewModel{T}"/> itself,
+    ///     It's worth noting that while this <i>could</i> be stored on the <see cref="IHierarchicalTopicViewModel{T}"/> itself,
     ///     that would prevent those values from being cached. As such, it's preferrable to keep the navigation nodes stateless,
     ///     and maintaining state exclusively in the <see cref="NavigationViewModel{T}"/> itself.
     ///   </para>

OnTopic.ViewModels/NavigationTopicViewModel.cs

@@ -18,13 +18,13 @@ namespace OnTopic.ViewModels {
   /// <remarks>
   ///   <para>
   ///     No topics are expected to have a <c>Navigation</c> content type. Instead, this view model is expected to be manually
-  ///     constructed by e.g. a <c>LayoutController</c>.
+  ///     constructed by e.g. a <c>MenuViewComponent</c>.
   ///   </para>
   ///   <para>
-  ///     Since C# doesn't support return-type covariance, this class can't be derived in a meaningful way (i.e., if it were to
-  ///     be, the <see cref="NavigationTopicViewModel.Children"/> property would still return a <see cref="Collection{T}"/> of
-  ///     <see cref="NavigationTopicViewModel"/> instances). Instead, the preferred way to extend the functionality is to create
-  ///     a new implementation of <see cref="INavigationTopicViewModel{T}"/>. To help communicate this, the <see
+  ///     Since .NET Standard doesn't support return-type covariance, this class can't be derived in a meaningful way (i.e., if
+  ///     it were to be, the <see cref="NavigationTopicViewModel.Children"/> property would still return a <see cref="Collection
+  ///     {T}"/> of <see cref="NavigationTopicViewModel"/> instances). Instead, the preferred way to extend the functionality is
+  ///     to create a new implementation of <see cref="INavigationTopicViewModel{T}"/>. To help communicate this, the <see
   ///     cref="NavigationTopicViewModel"/> class is marked as <c>sealed</c>.
   ///   </para>
   /// </remarks>

OnTopic/Models/INavigationTopicViewModel{T}.cs

@@ -10,7 +10,7 @@ namespace OnTopic.Models {
   | INTERFACE: NAVIGATION TOPIC VIEW MODEL
   \---------------------------------------------------------------------------------------------------------------------------*/
   /// <summary>
-  ///   Provides a generic data transfer topic for feeding views information about a navigation entry.
+  ///   Provides a generic model for feeding views information about a navigation entry.
   /// </summary>
   /// <remarks>
   ///   No topics are expected to have a <c>Navigation</c> content type. Instead, implementers of this view model are expected