Oakrey.Applications.Help 3.0.3

Oakrey.Applications.Help

A WPF/.NET 10 library that provides a structured, interactive help system for desktop applications. It scans a directory of Markdown files, builds a hierarchical navigation tree, and exposes a ready-to-bind HelpViewModel with forward/back navigation history.

Main features

• Recursive directory scan that builds a tree of Folder and MarkdownFile items (HelpLoader)
• HelpService resolves the help root from IApplicationInfo.HelpPath and exposes the file tree
• HelpViewModel implements INotifyPropertyChanged with Next / Prev commands and a full browsing history (ObservableCollection<Uri>)
• BindableTreeView - a WPF TreeView subclass that exposes SelectedItem and PreviewSelectedItem as two-way bindable dependency properties
• DI registration via a single IServiceCollection extension method
• Integrated Oakrey.Log tracing on service start and dispose

Architecture

classDiagram
    IHelpService <|.. HelpService
    HelpService --> HelpLoader : uses
    HelpLoader --> FileSystemItem : produces
    FileSystemItem <|-- Folder
    FileSystemItem <|-- MarkdownFile
    HelpViewModel --> IHelpService : consumes
    HelpViewModel --> HelpLoader : fallback (default ctor)
    BindableTreeView --> HelpViewModel : binds SelectedItem

Requirements

• .NET 10 (Windows)
• WPF host application
• Oakrey.ViewModels >= 2.1.0
• Oakrey.Applications (provides IApplicationInfo)

Installation

NuGet Package Manager

1. Open your project in Visual Studio.
2. Navigate to Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
3. Search for Oakrey.Applications.Help and click Install.

.NET CLI

dotnet add package Oakrey.Applications.Help

Package Manager Console

Install-Package Oakrey.Applications.Help

Configuration

Register the help services during application startup:

services.ConfigureHelpServices();

This registers:

• IHelpService as HelpService (transient)
• HelpViewModel (transient)

HelpService expects IApplicationInfo to be registered separately. It reads IApplicationInfo.HelpPath as the root directory for Markdown files.

Example usage

ViewModel binding

// Inject or resolve HelpViewModel
public class ShellViewModel
{
    public HelpViewModel Help { get; }

    public ShellViewModel(HelpViewModel help)
    {
        Help = help;
    }
}

XAML

<help:BindableTreeView
    ItemsSource="{Binding Help.Files}"
    SelectedItem="{Binding Help.File}" />

<WebBrowser Source="{Binding Help.MdSource}" />

<Button Command="{Binding Help.Prev}" Content="Back" />
<Button Command="{Binding Help.Next}" Content="Forward" />

Help directory layout

The help root directory should contain .md files and optional subdirectories. Subdirectories named attachments are automatically excluded from the tree.

Assets/
  Help.md              <- default landing file (matched by name "Help")
  GettingStarted.md
  Advanced/
    Configuration.md
    attachments/       <- excluded from tree
      diagram.png

Development notes

• HelpViewModel has two constructors: a default constructor that reads from {BaseDirectory}/Assets/, and a DI constructor that accepts IHelpService. The DI constructor is used when the service is registered via ConfigureHelpServices().
• Navigation history is maintained as an ObservableCollection<Uri>. Next and Prev commands are enabled/disabled automatically via RelayCommand predicates.
• BindableTreeView works around the WPF TreeView limitation that SelectedItem is read-only by exposing a new bindable SelectedItem dependency property.
• All HelpService lifecycle events are traced through Oakrey.Log.

Project information

• Author: Oakrey
• License: MIT
• Repository: ApplicationServices
• Project URL: oakrey.cz

Contributions are welcome! Feel free to open issues or submit pull requests to improve the package.

License

This project is licensed under the MIT License. See the LICENSE file for details.