README.md

OnTopic Library

The OnTopic assembly represents the core domain layer of the OnTopic library. It includes the primary entity (Topic), abstractions (e.g., ITopicRepository), and associated classes (e.g., KeyedTopicCollection<>).

Contents

• Entities
  • Editor
• Key Abstractions
• Implementation
• Extension Methods
• Collections
  • Specialty Collections
  • Editor
• View Models
  • Binding Models

Entities

• Topic: This is the core entity in OnTopic, and models all attributes, relationships, and references associated with a topic record.

Note: Any class that derives from Topic will automatically be loaded by TopicFactory.Create(), thus allowing content type specific business logic to be added to any Topic instance. This is especially useful for custom AttributeDescriptor types used to extend the OnTopic Editor.

Editor

Out of the box, the OnTopic library contains two specially derived topics for supporting core infrastructure requirements:

• ContentTypeDescriptor: A ContentTypeDescriptor is composed of multiple AttributeDescriptor instances which describe the schema of a content type. This is primarily used by the OnTopic Editor.
• AttributeDescriptor: An AttributeDescriptor describes a single attribute on a ContentTypeDescriptor. This includes the AttributeType, Description, DisplayGroup, and whether or not it's required (IsRequired).

Note: In addition, the OnTopic Editor can be extended through types derived from AttributeDescriptor, such as the BooleanAttributeDescriptor. Plugins may optionally implement these in order to overwrite the EditorType or ModelType of the attribute, and thus determine where and how their values will be stored.

Key Abstractions

• ITopicRepository: Defines an interface for data access, with Load(), Save(), Delete(), Move(), Refresh(), and Rollback() methods.
• ITopicMappingService: Defines an interface for a service that can convert a Topic into any arbitrary data transfer object based on predetermined conventions—or vice versa (via the IReverseTopicMappingService).
• IHierarchicalTopicMappingService<T>: Defines an interface for applying the ITopicMappingService to hierarchical data with constraints on depth. Used primarily for mapping data for navigation components, such as the NavigationTopicViewComponentBase<T>.
• ITypeLookupService: Defines an interface that can identify Type objects based on a Lookup(typeName) query. Used by e.g. ITopicMappingService to find corresponding TopicViewModel classes to map to.

Implementations

• TopicMappingService: A default implementation of the ITopicMappingService, with built-in conventions that should address the majority of mapping requirements. This also includes a number of attributes for annotating view models with hints that the TopicMappingService can use to fine-tune the mapping process.
  • CachedTopicMappingService: Provides an optional caching layer for decorating the TopicMappingService—or any ITopicMappingService implementation.
• ReverseTopicMappingService: A default implementation of the IReverseTopicMappingService, honoring similar conventions and attribute hints as the TopicMappingService. Useful for merging binding models with topics as part of form processing.
• HierarchicalTopicMappingService<T>: A default implementation of the IHierarchicalTopicMappingService<T>, which accepts an ITopicMappingService for mapping each individual node in the hierarchy.
  • CachedHierarchicalTopicMappingService<T>: Provides an optional caching layer for the HierarchicalTopicMappingService—or any IHierarchicalTopicMappingService implementation.
• StaticTypeLookupService: A basic implementation of the ITypeLookupService interface that allows types to be explicitly registered; useful when a small number of well-known types are expected.
  • DynamicTypeLookupService: A reflection-based implementation of the ITypeLookupService interface that looks up types from all loaded assemblies based on a Func<Type, bool> delegate passed to the constructor.
    • DynamicTopicLookupService: A version of DynamicTypeLookupService that returns all classes that derive from Topic; this is the default implementation for TopicFactory.
    • DynamicTopicViewModeLookupService: A version of DynamicTypeLookupService that returns all classes that end with ViewModel; this is useful for the TopicMappingService.
    • DynamicTopicBindingModelLookupService: A version of DynamicTypeLookupService that returns all classes that implement ITopicBindingModel; this is useful for the ReverseTopicMappingService.

Extension Methods

• Querying: The TopicExtensions class exposes optional extension methods for querying a topic (and its descendants) based on attribute values. This includes the useful Topic.FindAll(Func<Topic, bool>) method for querying an entire topic graph and returning topics validated by a predicate. There are also specialty extensions for querying IEnumerable<Topic>.
• Attributes: The AttributeCollectionExtensions class exposes optional extension methods for strongly typed access to the AttributeCollection. This includes e.g., GetBooleanValue() and SetBooleanValue(), which takes care of the conversion to and from the underlying string value type.

Collections

The OnTopic assembly contains a number of generic, keyed, and/or read-only collections for working with topics. These include:

	Read-Write	Read-Only
Unkeyed	TopicCollection	ReadOnlyTopicCollection
Keyed	KeyedTopicCollection	ReadOnlyKeyedTopicCollection
Keyed (Generic)	KeyedTopicCollection<T>	ReadOnlyKeyedTopicCollection

Specialty Collections

The OnTopic.Collections.Specialized namespace includes a number of collections that are used by the OnTopic library, but won't generally be used directly by implementors, except as exposed by the core library. These include:

• TrackedRecordCollection{TItem, TValue, TAttribute}: A KeyedCollection<TItem, TValue> of TrackedRecord<TValue> instances which tracks the IsDirty status and DeletedItems, while also enforcing business logic against corresponding properties on the associated Topic.
  • AttributeCollection: A TrackedRecordCollection of AttributeRecord instances keyed by AttributeRecord.Key; exposed by Topic.Attributes.
  • TopicReferenceCollection: A TrackedRecordCollection of TopicReferenceRecord instances keyed by TopicReference.Key; exposed by Topic.References.
• TopicMultiMap: Provides a multi-map (or collection-of-collections) for topics organized by a collection key.
  • ReadOnlyTopicMultiMap: A read-only interface to the TopicMultiMap, thus allowing simple enumeration of the collection withouthout exposing any write access.
    • TopicRelationshipMultiMap: A TopicMultiMap of KeyValuesPair instances keyed by KeyValuesPair.Key; exposed by Topic.Relationships.

Editor

The following are intended to provide support for the Editor domain objects, ContentTypeDescriptor and AttributeDescriptor.

• ContentTypeDescriptorCollection: A KeyedCollection of ContentTypeDescriptor objects keyed by Id and Key.
• AttributeDescriptorCollection: A KeyedCollection of AttributeDescriptor objects keyed by Id and Key.

View Models

The core Topic library has been designed to be view model agnostic; i.e., view models should be defined for the specific presentation framework (e.g., ASP.NET Core) and customer. That said, to facilitate reusability of features that work with view models, several interfaces are defined which can be applied as appropriate. These include:

• ICoreTopicViewModel: Includes core properties Key and ContentType necessary for every Topic.
  • ITopicViewModel: Includes universal properties such as UniqueKey, WebPath, Id, and Title.
• IHierarchicalTopicViewModel<T>: Includes a generic Children property necessary to model a hierarchical graph.
• INavigableTopicViewModel: Includes core properties Title, ShortTitle, and WebPath, necessary treating a topic as a navigable link.
  • INavigationTopicViewModel<T>: Includes IHierarchicalTopicViewModel<T> and the IsSelected() view logic method, for use with navigation menus.

Binding Models

• ITopicBindingModel: Includes the bare minimum properties—namely Key and ContentType—needed to support a binding model that will be consumed by the IReverseTopicMappingService.
• IAssociatedTopicBindingModel: Includes the bare minimum properties—namely UniqueKey—needed to associate another topic on a binding model that will be consumed by the IReverseTopicMappingService.

In addition to these interfaces, a set of concrete implementations of view models corresponding to the default schemas for the out-of-the-box content types can be found in the OnTopic.ViewModels package.