diff --git a/docs/README.md b/docs/README.md index 3d1b031..f51bf76 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,6 @@ - [x] Repositories usage - [x] AuthService usage - [x] AuthMiddleware usage -- [ ] AdminPages usage +- [x] AdminPages usage - [x] Endpoints usage -- [ ] Blazor pages usage +- [x] Blazor pages usage diff --git a/docs/api/endpoints.md b/docs/api/endpoints.md index f082a1d..8ed7fb0 100644 --- a/docs/api/endpoints.md +++ b/docs/api/endpoints.md @@ -8,14 +8,14 @@ HopFrame currently only supports endpoints for authentication out of the box. > **Hint:** you can use the build-in [swagger](https://swagger.io/) ui to explore and test all endpoints of your application __including__ HopFrame endpoints. ### SecurityController -Base endpoint: `api/v1/authentication`\ +Base endpoint: `/api/v1/authentication`\ **Important:** All primitive data types (including `string`) are return as a [`SingleValueResult`](./models.md#SingleValueResult) -| Method | Endpoint | Payload | Returns | -| ------ | -------- | ------- | ------- | -| PUT | login | [UserLogin](./models.md#UserLogin) | access token (string) | -| POST | register | [UserRegister](./models#UserRegister) | access token (string) | -| GET | authenticate | | access token (string) | -| DELETE | logout | | | -| DELETE | delete | [UserPasswordValidation](./models.md#UserPasswordValidation) | | +| Method | Endpoint | Payload | Returns | +|--------|---------------|--------------------------------------------------------------|-----------------------| +| PUT | /login | [UserLogin](./models.md#UserLogin) | access token (string) | +| POST | /register | [UserRegister](./models#UserRegister) | access token (string) | +| GET | /authenticate | | access token (string) | +| DELETE | /logout | | | +| DELETE | /delete | [UserPasswordValidation](./models.md#UserPasswordValidation) | | diff --git a/docs/blazor/admin.md b/docs/blazor/admin.md index 4b90907..feec095 100644 --- a/docs/blazor/admin.md +++ b/docs/blazor/admin.md @@ -1,2 +1,133 @@ # HopFrame Admin Pages +Admin pages can be defined through a `AdminContext` similar to how a `DbContext` is defined. They generate administration pages like [`/administration/users`](./pages.md) +simply by reading the structure of the provided model and optionally some additional configuration. +> **Fun fact:** The already existing pages `/administration/users` and `/administration/groups` are also generated using an internal `AdminContext`. + +## Usage +1. Create a class that inherits the `AdminPagesContext` base class + + ```csharp + public class AdminContext : AdminPagesContext { + + } + ``` + +2. Add your admin pages as properties to the class + + ```csharp + public class AdminContext : AdminPagesContext { + + public AdminPage
Addresses { get; set; } + + public AdminPage Employees { get; set; } + + } + ``` + +3. **Optionally** you can further configure your pages in the `OnModelCreating` method + + ```csharp + public class AdminContext : AdminPagesContext { + + public AdminPage
Addresses { get; set; } + public AdminPage Employees { get; set; } + + public override void OnModelCreating(IAdminContextGenerator generator) { + base.OnModelCreating(generator); + + generator.Page() + .Property(e => e.Address) + .IsSelector(); + + generator.Page
() + .Property(a => a.Employee) + .Ignore(); + + generator.Page
() + .Property(a => a.AddressId) + .IsSelector() + .Parser((model, e) => model.AddressId = e.EmployeeId); + + generator.Page() + .ConfigureRepository() + .ListingProperty(e => e.Name); + + generator.Page
() + .ConfigureRepository() + .ListingProperty(a => a.City); + } + } + ``` +4. **Optionally** you can also add some of the following attributes to your classes / properties to further configure the admin pages:\ + \ + Attributes for classes: + + ```csharp + [AttributeUsage(AttributeTargets.Class)] + public sealed class AdminButtonConfigAttribute(bool showCreateButton = true, bool showDeleteButton = true, bool showUpdateButton = true) : Attribute { + public bool ShowCreateButton { get; set; } = showCreateButton; + public bool ShowDeleteButton { get; set; } = showDeleteButton; + public bool ShowUpdateButton { get; set; } = showUpdateButton; + } + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Class)] + public sealed class AdminPermissionsAttribute(string view = null, string create = null, string update = null, string delete = null) : Attribute { + public AdminPagePermissions Permissions { get; set; } = new() { + Create = create, + Update = update, + Delete = delete, + View = view + }; + } + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Class)] + public class AdminUrlAttribute(string url) : Attribute { + public string Url { get; set; } = url; + } + ``` + + Attributes for properties: + + ```csharp + [AttributeUsage(AttributeTargets.Property)] + public sealed class AdminHideValueAttribute : Attribute; + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Property)] + public sealed class AdminIgnoreAttribute(bool onlyForListing = false) : Attribute { + public bool OnlyForListing { get; set; } = onlyForListing; + } + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Property)] + public sealed class AdminPrefixAttribute(string prefix) : Attribute { + public string Prefix { get; set; } = prefix; + } + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Property)] + public sealed class AdminUneditableAttribute : Attribute; + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Property)] + public class AdminUniqueAttribute : Attribute; + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Property)] + public sealed class AdminUnsortableAttribute : Attribute; + ``` + + ```csharp + [AttributeUsage(AttributeTargets.Property)] + public sealed class ListingPropertyAttribute : Attribute; + ``` diff --git a/docs/blazor/auth.md b/docs/blazor/auth.md index 0b15e1c..a759486 100644 --- a/docs/blazor/auth.md +++ b/docs/blazor/auth.md @@ -15,6 +15,6 @@ public interface IAuthService { } ``` ## Automatically refresh user sessions -1. Make sure you have implementented the `AuthMiddleware` how it's described in step 5 of the [installation](./installation.md). +1. Make sure you have implemented the `AuthMiddleware` how it's described in step 5 of the [installation](./installation.md). 2. After that, the access token of the user gets automatically refreshed as long as the refresh token is valid. diff --git a/docs/blazor/pages.md b/docs/blazor/pages.md index e69de29..214b771 100644 --- a/docs/blazor/pages.md +++ b/docs/blazor/pages.md @@ -0,0 +1,14 @@ +# HopFrame Pages +By default, the HopFrame provides some blazor pages for managing user accounts and permissions + +## All currently supported blazor pages + +| Page | Endpoint | Permission | Usage | +|-----------------|------------------------|----------------------------|--------------------------------------------------------------------------------------------------------| +| Admin Dashboard | /administration | hopframe.admin | This page provides an overview to all admin pages built-in and created by [AdminContexts](./admin.md). | +| Admin Login | /administration/login | | This page is a simple login screen so no login screen needs to be created to access the admin pages. | +| User Dashboard | /administration/users | hopframe.admin.users.view | This page serves as a management site for all users and their permissions. | +| Group Dashboard | /administration/groups | hopframe.admin.groups.view | This page serves as a management site for all groups and their permissions. | + +> **Hint:** All pages created by [AdminContexts](./admin.md) are also under the `/administration/` location. This can unfortunately __not__ be changed at the moment. +