Serene Doc ‐ Book Repo - FadiZahhar/umbraco8showandtell GitHub Wiki

BookRepository - Overview & Implementation Guide

BookRepository provides CRUD and search operations for managing Book entities stored in the database. It uses NPoco ORM within Umbraco’s scoped database context for data access.

Implementation Steps

1. Create the POCO Model (Book)

  • Define the Book POCO class with NPoco attributes for table mapping.
  • Apply data validation attributes ([Required], [StringLength], [Range], etc.).

2. Create the Migration Class for Table Creation

  • Create a Migration class using Umbraco’s migration API to define the database schema.

3. Register and Run the Migration

  • Implement a Migration Component that runs the migration during application startup.

4. Register Component via Composer

  • Create a Composer class to register the migration component into Umbraco's composition pipeline.

5. Service Layer

  • Implement a service layer for business logic, wrapping the repository.

6. Implement the Repository for CRUD and Search

  • Create the BookRepository with methods:
    • GetAll()
    • GetById(int id)
    • Insert(Book book)
    • Update(Book book)
    • Delete(int id)
    • Search(string term, int page, int pageSize) — supports paginated filtered searches.

File Structure

Feature File Path Description
Book Model /Models/Book.cs POCO model with NPoco and validation attributes
Migration /Migrations/CreateBookTableMigration.cs Migration class to create Books table
Repository /Repositories/BookRepository.cs Data access methods using Umbraco scoped database
Migration Component /Migrations/BookTableMigrationComponent.cs Runs migration at startup
Composer (Migration) /Composers/BookTableMigrationComposer.cs Registers migration component
Composer (Repository) /Composers/BookManagerComposer.cs Registers repository/component
API Controller /Controllers/BookApiController.cs Handles CRUD API endpoints
App_Plugin /App_Plugins/BookManager/ Frontend UI: package.manifest, dashboard.html, controller.js
Language Files /App_Plugins/BookManager/lang/en-US.xml Localization resources

Notes

  • AngularJS CDN is required: Without including the AngularJS library via CDN or local script, Angular directives (e.g., ng-controller, ng-model) will not work. Umbraco does not bundle AngularJS by default in all contexts, so explicitly adding the CDN is necessary for Angular features to work properly in custom views or dashboards.

  • Attribute binding between HTML and Controller:

    • Make sure that the attributes in the HTML (e.g., ng-model="bookManager.currentBook.Title", ng-click="bookManager.saveBook()") correctly match the controller's exposed properties and methods.

  • Form Validation

    • To enable AngularJS form validation with your Save button, you must pass the form object to the save function as shown below.

Steps

Create Model

  • Book.cs model is created in the Models folder in HighlyDeveloped.Core.
  • It contains our data model attributes and validation.

Create Migration Class

  • CreateBookTableMigration.cs is created in the Migrations folder in HighlyDeveloped.Core.
  • The class inherits from MigrationBase to create the table using Create.Table.

Create the Component and Composer for our Migration Table

  • BookTableMigrationComposer.cs is created in the Composers folder in HighlyDeveloped.Core to register our BookTableMigrationComponent.cs component.
  • BookTableMigrationComponent.cs is created in the Migrations folder in HighlyDeveloped.Core.
    • It implements IComponent.
    • After composition, when the application starts, it runs our component.
    • Used to run migrations, set up routes, and start logic.

Use PetaPoco for CRUD

  • Create the file BookRepository.cs in the Repositories folder in HighlyDeveloped.Core.
  • To use CRUD, we inject IScopeProvider into BookRepository.cs.
  • The repository handles the data (better for separation of concerns).
  • BookRepository.cs is our database layer.

Create Service: Business Logic Layer

  • Create the file BookService.cs in the Services folder in HighlyDeveloped.Core.
  • This class is directly linked to our BookRepository.cs.

Inject Service with Composer

  • Create the file BookServiceComposer.cs in the Composers folder in HighlyDeveloped.Core.

Create an API Controller

  • Create the file BookApiController.cs in the Controllers folder in HighlyDeveloped.Core.
  • Endpoint that connects our backend with the frontend.

Our BookManagerComposer.cs registers repository, services, and ensures our migrations.

App_Plugins

  • Create the file package.manifest in /App_Plugins/BookManager folder in HighlyDeveloped.Web.
  • Create /dashboard/dashboard.html.
  • Create /dashboard/dashboard.controller.js.

Create a Public API Route

  • Create the file BooksPublicController.cs in the /Controllers/ folder in HighlyDeveloped.Core.
  • This controller connects our BookService to our dashboard.