README.md

Topic View Models

The OnTopic.ViewModels assembly includes default implementations of basic view models which map to the stock content types that ship with OnTopic. These can optionally be used or extended by client implementations.

Note: It is not necessary to use or derive from these view models. They are provided exclusively for convenience so implementers don't need to recreate basic data models.

Contents

• Installation
• Inventory
• Usage
  • DynamicTopicViewModelLookupService
• Design Considerations
  • Parameterless Constructor
  • Inheritance

Installation

Installation can be performed by providing a <PackageReference /> to the OnTopic.ViewModels NuGet package.

<Project Sdk="Microsoft.NET.Sdk.Web">
  …
  <ItemGroup>
    <PackageReference Include="OnTopic.ViewModels" Version="5.0.0" />
  </ItemGroup>
</Project>

Inventory

• TopicViewModel
  • PageTopicViewModel
    • ContentListTopicViewModel (ContentItemTopicViewModel)
    • IndexTopicViewModel
    • SlideshowTopicViewModel (SlideTopicViewModel)
    • VideoTopicViewModel
  • SectionTopicViewModel
    • PageGroupTopicViewModel
  • NavigationTopicViewModel
  • ItemTopicViewModel
    • ContentItemTopicViewModel
    • LookupListItemTopicViewModel
    • SlideTopicViewModel
• AssociatedTopicBindingModel
• TopicViewModelLookupService
• TopicViewModelCollection<>

Usage

By default, the OnTopic.AspNetCore.Mvc's TopicController uses the out-of-the-box TopicMappingService to map topics to view models. For applications primarily relying on the out-of-the-box view models, it is recommended that the TopicViewModelLookupService be used; this includes all of the out-of-the-box view models, and can be derived to add application-specific view models.

DynamicTopicViewModelLookupService

For applications with a large number of view models, it may be preferable to use the DynamicTopicViewModelLookupService, which will attempt to map topics to view models from any assembly or namespace based on the naming convention, {ContentType}TopicViewModel or {ContentType}ViewModel. If a reference to the OnTopic.ViewModels package is included in a project's csproj, then these view models will be available to the lookup service and, thus, the mapping service. If any classes with the same name are available in any other assembly or namespace then they will override the ViewModels from this assembly. That allows these classes to be treated as default fallbacks.

Note: If a base class is overwritten, topics that derive from the original version will continue to do so unless they are also overwritten. For example, if a Theme property is added to a customer-specific PageTopicViewModel, the Theme property won't be available on e.g. SlideShowTopicViewModel unless it is also overwritten by the customer to inherit from their custom PageTopicViewModel.

Design Considerations

As view models, not all attributes and associations are exposed. The properties chosen are optimized around values that are expected to be of common interest to most views.

Parameterless Constructor

All of the view models assume a parameterless constructor (e.g., new TopicViewModel()), which can optionally be the default constructor if no other constructors are required. This is necessary to provide compatibility with the TopicMappingService, which will attempt to create new instances of view models based on the the topic's ContentType, using the view models parameterless constructor.

Inheritance

The view models map to the hierarchy of the content types in OnTopic, with each view model only including properties that are specific to that content type. So, for example, PageTopicViewModel includes a Body property, which is introduced by the Page content type, but doesn't include e.g. Key, ContentType, or Title; these are all inherited from the base TopicViewModel.

This is advantageous not only because it effectively models the familiar content type hierarchy, but also because it allows for polymorphism in the mapping library. So, for example, if a property accepts a Collection<PageTopicViewModel>, then this can also contain any view models that derive from the PageTopicViewModel (e.g., SlideshowTopicViewModel, VideoTopicViewModel, &c.).