Page models reference

This document provides a detailed technical reference for the Razor Page Models used in the TheExampleApp application. Page Models are C# classes that encapsulate the logic and data for their corresponding Razor Pages. They are responsible for handling HTTP requests, fetching data from the Contentful CMS, and preparing data for rendering in the view.

This application follows the standard ASP.NET Core Razor Pages architecture. For a general overview of this pattern, please refer to the Core Features: Razor Pages documentation. All page models inherit from a common BasePageModel, which likely provides shared functionality, such as the injected IContentfulClient.

Page model classes

The following sections detail each specific Page Model, its purpose, dependencies, and implementation logic.

IndexModel

File: TheExampleApp/Pages/Index.cshtml.cs
Route: /
Purpose: Serves as the backend logic for the application's home page.

The IndexModel is responsible for fetching the main layout structure for the home page from Contentful.

Logic

The OnGet handler is an asynchronous method that executes a query against the Contentful API to retrieve a single entry of the content type layout where the slug field is "home". It uses the contentful.aspnetcore SDK's QueryBuilder for a type-safe query.

Key implementation details:

Localization: The query respects the current language setting by using LocaleIs(), retrieving the locale from the user's session (HttpContext.Session), with a fallback to CultureInfo.CurrentCulture if no session locale is set.
Include Depth: It uses .Include(4) to resolve linked entries up to 4 levels deep, ensuring that all necessary content modules are fetched in a single API call.
Data for Rendering: It exposes the fetched Layout object and a collection of SystemProperties to the view. The SystemProperties collection includes the layout's system properties and those of all its content modules. These properties are used by view components to enable editorial features, such as the "Edit in Contentful" links.

Properties

public Layout IndexPage { get; set; }: Holds the fetched Layout entry from Contentful. See the API Models Reference for the structure of the Layout class.
public IEnumerable<SystemProperties> SystemProperties { get; set; }: A collection of system properties for the main layout and its nested content modules.

CoursesModel

File: TheExampleApp/Pages/Courses.cshtml.cs
Route: /courses and /courses?category={slug}
Purpose: Displays a list of all available courses, with an option to filter by category.

This model manages the course catalog page. It fetches all courses and categories and performs filtering based on a URL query parameter.

Dependencies

IContentfulClient: For fetching data from Contentful.
IBreadcrumbsManager: A custom service to dynamically update the page's breadcrumb navigation.
IViewLocalizer: For accessing localized string resources, used for error messages.

Logic

The OnGet(string category) handler contains the core logic:

It fetches all category entries to populate the filtering UI.
It fetches all course entries, ordered by creation date.
If the optional category parameter is present, it filters the Courses list to include only those matching the category slug.
Error Handling: If a category slug is provided but does not correspond to an existing category, the model sets a TempData["NotFound"] message and returns a NotFoundResult (HTTP 404). This is a crucial pattern for handling invalid slugs gracefully.
Breadcrumbs: It interacts with the IBreadcrumbsManager to replace the generic slug in the breadcrumb trail with the more user-friendly category Title.

csharp

// TheExampleApp/Pages/Courses.cshtml.cs

public async Task<IActionResult> OnGet(string category)
{
    // ... fetch categories and courses ...

    if (!string.IsNullOrEmpty(category))
    {
        // Filter the courses by the selected category.
        Courses = courses.Where(c => c.Categories != null && c.Categories.Any(x => x.Slug == category.ToLower())).ToList();
        var cat = Categories.FirstOrDefault(c => c.Slug == category.ToLower());

        if(cat == null)
        {
            // If the category doesn't exist, return a 404.
            TempData["NotFound"] = _localizer["errorMessage404Category"].Value;
            return NotFound();
        }
        // Update the breadcrumb with the category's title.
        _breadcrumbsManager.ReplaceCrumbForSlug(category.ToLower().Replace('-', ' '), cat.Title);
    }
    else
    {
        // If we don't have a category, just display all courses.
        Courses = courses.ToList();
    }
    return Page();
}

Properties

public Category SelectedCategory { get; set; }: The Category object that matches the current filter, if any.
public List<Course> Courses { get; set; }: The list of courses to be displayed on the page.
public List<Category> Categories { get; set; }: The complete list of all categories, used to render the filter navigation.
public bool EditorialFeaturesEnabled => HttpContext.Session.GetString("EditorialFeatures") == "Enabled": A computed property that checks the session to determine if editorial features should be enabled.

Courses/IndexModel

File: TheExampleApp/Pages/Courses/Index.cshtml.cs
Route: /courses/{slug}
Purpose: Displays the details for a single course.

This model is responsible for fetching and displaying an individual course page, which typically lists the lessons within that course.

Dependencies

IVisitedLessonsManager: A custom service to track which courses and lessons a user has viewed.
IBreadcrumbsManager: To update the breadcrumb trail.
IViewLocalizer: For localized error messages.

Logic

The OnGet(string slug) handler fetches a single course from Contentful using its slug.

Key implementation details:

Localization: The query respects the current language setting by using LocaleIs(), retrieving the locale from the user's session (HttpContext.Session), with a fallback to CultureInfo.CurrentCulture if no session locale is set.
Include Depth: It uses .Include(5) to resolve linked entries up to 5 levels deep, ensuring that nested course content (such as lessons and their modules) is fetched in a single API call.
Error Handling: If no course matches the provided slug, it sets a TempData["NotFound"] message with a localized error string and returns a NotFoundResult (HTTP 404).
User Tracking: It calls _visitedLessonsManager.AddVisitedLesson(Course.Sys.Id) to register that the user has viewed this course. The manager's state is then passed to the view via ViewData["VisitedLessons"] to visually indicate progress (e.g., checkmarks next to visited lessons).
Breadcrumbs: It updates the breadcrumb trail with the course's actual title using _breadcrumbsManager.ReplaceCrumbForSlug(), transforming the slug into a user-friendly label.

Properties

public Course Course { get; set; }: The fetched Course object to be displayed. See the API Models Reference for the structure of the Course class.

Courses/LessonsModel

File: TheExampleApp/Pages/Courses/Lessons.cshtml.cs
Route: /courses/{slug}/lessons/{lessonSlug}
Purpose: Displays the content of a single lesson within a course.

This is the model for the lesson viewer page. It fetches the parent course and then identifies the specific lesson to display.

Dependencies

IContentfulClient: For fetching data from Contentful.
IVisitedLessonsManager: A custom service to track which courses and lessons a user has viewed.
IBreadcrumbsManager: To update the breadcrumb trail.
IViewLocalizer: For localized error messages.

Logic

The OnGet(string slug, string lessonSlug) handler uses two route parameters to locate the correct content.

Key implementation details:

Course Fetching: It first fetches the parent Course using the slug, with .Include(5) to resolve linked entries up to 5 levels deep.
Localization: The query respects the current language setting by using LocaleIs(), retrieving the locale from the user's session (HttpContext.Session), with a fallback to CultureInfo.CurrentCulture if no session locale is set.
Lesson Selection: It then searches within the Course.Lessons collection for a Lesson that matches the lessonSlug.
Error Handling: It includes robust checks and returns a NotFoundResult with localized error messages if either the course or the lesson cannot be found.
Breadcrumbs: It updates the breadcrumb trail for both the course and the lesson using _breadcrumbsManager.ReplaceCrumbForSlug(), transforming the slugs into user-friendly titles.
User Tracking: It calls _visitedLessonsManager.AddVisitedLesson(SelectedLesson.Sys.Id) to register that the user has viewed this specific lesson. The manager's state is then passed to the view via ViewData["VisitedLessons"] to visually indicate progress.
System Properties: It builds a collection of SystemProperties that includes the lesson's system properties and those of all its modules, used for editorial features.

csharp

// TheExampleApp/Pages/Courses/Lessons.cshtml.cs

// ... inside OnGet ...

SelectedLesson = Course.Lessons.FirstOrDefault(c => c.Slug == lessonSlug?.ToLower());

if (SelectedLesson == null)
{
    // If the lesson is not found, also return a 404.
    TempData["NotFound"] = _localizer["errorMessage404Lesson"].Value;
    return NotFound();
}

// ...

// Add the current lesson as visited.
_visitedLessonsManager.AddVisitedLesson(SelectedLesson.Sys.Id);

// Add the visited lessons and courses to viewdata.
ViewData["VisitedLessons"] = _visitedLessonsManager.VisitedLessons;

Properties

public Course Course { get; set; }: The parent course of the lesson.
public Lesson SelectedLesson { get; set; }: The specific Lesson object to be displayed.
public IEnumerable<SystemProperties> SystemProperties { get; set; }: System properties for the lesson and its modules, used for editorial features.
public string NextLessonSlug { get => ... }: A computed property that finds the slug of the next lesson in the course sequence, returning null if the current lesson is the last one.

SettingsModel

File: TheExampleApp/Pages/Settings.cshtml.cs
Route: /settings
Purpose: Allows developers to configure the Contentful Space ID and API tokens used by the application at runtime.

This is a more complex model with multiple handlers for GET and POST requests, managing application configuration stored in the user's session.

Dependencies

IContentfulOptionsManager: A custom service that manages the Contentful configuration for the application.
IContentfulClient: For fetching data from Contentful.

Logic & Handlers

OnGet(): Prepares the settings page asynchronously. It retrieves any validation errors from a previous failed POST attempt (stored in the session) and populates the form with those errors and options if present. It also fetches the current space name from Contentful using _client.GetSpace(), populates the AppOptions with current configuration values, and determines if custom credentials are being used via _manager.IsUsingCustomCredentials.
OnGetInvalidCredentials(): A named GET handler that simply redirects back to the settings page.
OnPost(SelectedOptions appOptions): Handles the main form submission. It validates the submitted options using the SelectedOptions class validation. If invalid, it redisplays the page with validation errors. If valid, it updates the editorial features setting in the session and serializes the new Contentful options into the session, then redirects back to the settings page with a success message.
OnPostResetCredentials(): A named handler that clears any custom credentials from the session by setting an empty string for the ContentfulOptions key, reverting the application to its default configuration (likely from appsettings.json).
OnPostSwitchApi(string api, string prevPage): A named handler used by the API switcher dropdown. It updates the UsePreviewApi flag in the session while retaining all other options, and redirects the user back to the page they were on with an api query parameter.

`SelectedOptions` Validation

A key feature of the SettingsModel is its nested SelectedOptions class, which implements IValidatableObject for advanced, server-side validation.

The Validate method performs the following checks:

Ensures required fields (SpaceId, AccessToken, PreviewToken) are not empty.
Live API Verification: If all fields are present, it creates a temporary ContentfulClient and attempts to make a GetSpace() call against both the Delivery API and the Preview API.
It catches ContentfulException and checks the StatusCode to provide specific error messages for invalid tokens (401) or an incorrect space ID (404).

This proactive validation prevents the application from entering a broken state due to misconfigured credentials.

csharp

// TheExampleApp/Pages/Settings.cshtml.cs - Inside SelectedOptions.Validate

// ...
try
{
    // Attempts to connect to the Delivery API
    var space = contentfulClient.GetSpace().Result;
}
catch (AggregateException ae)
{
    ae.Handle((ce) => {
        if (ce is ContentfulException)
        {
            if ((ce as ContentfulException).StatusCode == 401)
            {
                validationResult = new ValidationResult(localizer["deliveryKeyInvalidLabel"].Value, new[] { nameof(AccessToken) });
            }
            // ... other status code handling ...
            return true;
        }
        return false;
    });
}
// ... similar logic for the Preview API ...

Properties

public ContentfulOptions Options { get; set; }: The current Contentful configuration options being used by the application, injected via IContentfulOptionsManager.
public SelectedOptions AppOptions { get; set; }: The options displayed in the settings form, editable by the user.
public string SpaceName { get; set; }: The name of the currently connected Contentful space, fetched during OnGet().
public bool IsUsingCustomCredentials { get; set; }: Indicates whether the application is using custom credentials (from session) or default credentials (from configuration).

Other Models

ErrorModel: Handles the display of error pages.
ImprintModel: Handles the display of the site's imprint/legal notice page.

These models are standard and contain minimal logic, primarily serving to render their respective static or semi-static pages.

Methods

The Page Models in this application consistently use the following patterns and conventions defined by the ASP.NET Core Razor Pages framework.

OnGet/OnGetAsync handlers

These methods are the entry point for handling HTTP GET requests. Their primary responsibilities are:

Accepting parameters from the route or query string (e.g., OnGet(string slug)).
Querying services (like IContentfulClient) to fetch the necessary data.
Populating the public properties of the model class with this data.
Performing business logic, such as filtering or user tracking.
Returning an IActionResult, typically Page() to render the view or NotFound() in case of an error.

OnPost/OnPostAsync handlers

These methods handle HTTP POST requests, typically from form submissions.

Model Binding: They accept a model class as a parameter (e.g., OnPost(SelectedOptions appOptions)), which ASP.NET Core automatically populates with the form data.
Validation: They check ModelState.IsValid to ensure the submitted data meets the defined validation rules.
PRG Pattern: They implement the Post-Redirect-Get (PRG) pattern by returning a RedirectToPageResult after successfully processing data. This prevents form re-submission on page refresh.
State Transfer: They use TempData to pass short-lived messages (e.g., "Settings saved successfully!") to the target page after a redirect.
Named Handlers: The application uses named handlers (e.g., OnPostResetCredentials) to manage multiple distinct POST actions on a single page. These are linked from a form using the asp-page-handler tag helper.

Properties and data binding

Public properties on the Page Model serve as the bridge to the Razor view (.cshtml file).

Data Exposure: Any data fetched in an OnGet handler is assigned to a public property, making it accessible for rendering in the view.
Computed Properties: The codebase makes effective use of C# expression-bodied properties for simple, derived data, as seen in LessonsModel.NextLessonSlug. This keeps logic encapsulated within the model rather than cluttering the view.

csharp

// TheExampleApp/Pages/Courses/Lessons.cshtml.cs

/// <summary>
/// The slug of the next lesson of the course.
/// </summary>
public string NextLessonSlug { get => Course.Lessons.SkipWhile(x => x != SelectedLesson).Skip(1).FirstOrDefault()?.Slug; }

This pattern provides a clean and efficient way to calculate values that depend on other model properties.

Page models reference ​

Page model classes ​

IndexModel ​

Logic ​

Properties ​

CoursesModel ​

Dependencies ​

Logic ​

Properties ​

Courses/IndexModel ​

Dependencies ​

Logic ​

Properties ​

Courses/LessonsModel ​

Dependencies ​

Logic ​

Properties ​

SettingsModel ​

Dependencies ​

Logic & Handlers ​

SelectedOptions Validation ​

Properties ​

Other Models ​

Methods ​

OnGet/OnGetAsync handlers ​

OnPost/OnPostAsync handlers ​

Properties and data binding ​

Page models reference

Page model classes

IndexModel

Logic

Properties

CoursesModel

Dependencies

Logic

Properties

Courses/IndexModel

Dependencies

Logic

Properties

Courses/LessonsModel

Dependencies

Logic

Properties

SettingsModel

Dependencies

Logic & Handlers

`SelectedOptions` Validation

Properties

Other Models

Methods

OnGet/OnGetAsync handlers

OnPost/OnPostAsync handlers

Properties and data binding