Added documentation for the core module

This commit is contained in:
2025-02-12 11:19:34 +01:00
parent 47f30bf33f
commit 08d4ddb2c6
6 changed files with 723 additions and 37 deletions

View File

@@ -1,3 +1,31 @@
# Callbacks
Start typing here...
Callbacks are a way of executing actions on curtain events in the web ui.
## Registering a callback handler
You can register a callback handler using the method provided in the [](TableConfig.md):
```c#
table.AddCallbackHandler(CallbackType.DeleteEntry, (user, services) => {
var logger = services.GetRequiredService<ILogger<Program>>();
logger.LogInformation("User {user} deleted!", user.Username);
});
```
The callback handler takes the entity that's modified and a `IServiceProvider` as arguments
and can either be synchronous or asynchronous.
## Callback types
```C#
public enum CallbackType {
CreateEntry = 0,
UpdateEntry = 1,
DeleteEntry = 2
}
```
- `CallbackType.CreateEntry`: The handler gets executed, when an entity is created.
- `CallbackType.UpdateEntry`: The handler gets executed, when an entity is updated.
- `CallbackType.DeleteEntry`: The handler gets executed, when an entity is deleted.

View File

@@ -1,3 +1,38 @@
# DbContextConfig
Start typing here...
This config contains all configurations for the given DbContext type.
## Configuration methods
### Table (With configurator)
Configures the table of the `DbContext` using the provided configurator.
```c#
DbContextConfigurator<TDbContext> Table<TModel>(Action<TableConfigurator<TModel>> configurator) where TModel : class
```
- **Type Parameters:**
- `TModel`: The model of the table for identifying the correct one.
- **Parameters:**
- `configurator`: Used for configuring the table.
- **Returns:** `DbContextConfigurator<TDbContext>`
- **See Also:** [](TableConfig.md)
### Table (Without configurator)
Configures the table of the `DbContext`.
```c#
TableConfigurator<TModel> Table<TModel>() where TModel : class
```
- **Type Parameters:**
- `TModel`: The model of the table for identifying the correct one.
- **Returns:** `TableConfigurator<TModel>`
- **See Also:** [](TableConfig.md)

View File

@@ -1,2 +1,159 @@
# HopFrameConfig
The HopFrame config is the global object containing all configurations made for the HopFrame.
It is registered as a singleton and can be injected by any service.
But it should be treated as a read only dependency because changing the configuration during runtime is not tested and may cause bugs.
## Changing the configuration
As already mentioned in the [](Installation.md), you configure the HopFrame using the extension method of the `IServiceCollection` named `AddHopFrame`.
This extension method eiter takes a `HopFrameConfig` or a configurator action with a `HopFrameConfigurator` as an argument.
You can optionally also provide a `LibraryConfiguration` for the Fluent UI library and a toggle named `addRazorComponents` which disables the calls for adding
Razor pages with interactive server components if you want to do this yourself.
### Mapping the HopFrame pages
In order for the HopFrame pages to be served you need to add them to your application.
You can do that in two ways:
1. Just use the HopFrame as the razor host (Useful for APIs)
Just map the HopFrame before you run your application:
```c#
app.MapHopFrame();
```
2. Add the HopFrame to your Razor container (Useful for Blazor web apps)
Add the HopFrame to the `MapRazorComponents` call:
```C#
app.MapRazorComponents<App>()
.AddInteractiveServerRenderMode()
.AddHopFramePages();
```
### Example
```C#
builder.Services.AddHopFrame(options => {
options.DisplayUserInfo(false);
options.AddDbContext<DatabaseContext>(context => {
context.Table<User>(table => {
table.Property(u => u.Password)
.DisplayValue(false);
table.Property(u => u.Id)
.IsSortable(false)
.SetOrderIndex(3);
table.SetViewPolicy("policy");
table.Property(u => u.Posts)
.FormatEach<Post>((post, _) => post.Caption);
});
});
options.AddCustomView("Counter", "/counter")
.SetDescription("A custom view")
.SetPolicy("counter.view");
});
```
## Configuration methods
### AddDbContext (With configurator)
Adds all tables defined in the `DbContext` to the HopFrame UI and configures it using the provided configurator.
```c#
HopFrameConfigurator AddDbContext<TDbContext>(Action<DbContextConfigurator<TDbContext>> configurator) where TDbContext : DbContext
```
- **Type Parameters:**
- `TDbContext`: The `DbContext` from which all tables should be added.
- **Parameters:**
- `configurator`: Used for configuring the `DbContext`.
- **Returns:** `HopFrameConfigurator`
- **See Also:** [](DbContextConfig.md)
### AddDbContext (without configurator)
Adds all tables defined in the `DbContext` to the HopFrame UI and configures it.
```c#
DbContextConfigurator<TDbContext> AddDbContext<TDbContext>() where TDbContext : DbContext
```
- **Type Parameters:**
- `TDbContext`: The `DbContext` from which all tables should be added.
- **Returns:** `DbContextConfigurator<TDbContext>`
- **See Also:** [](DbContextConfig.md)
### HasDbContext
Checks if a context is already registered in the HopFrame.
```c#
bool HasDbContext<TDbContext>() where TDbContext : DbContext
```
- **Type Parameters:**
- `TDbContext`: The context that should be checked.
- **Returns:** `true` if the context is already registered, `false` if not.
### GetDbContext
Returns a configurator for the context if it was already defined.
```c#
DbContextConfigurator<TDbContext>? GetDbContext<TDbContext>() where TDbContext : DbContext
```
- **Type Parameters:**
- `TDbContext`
- **Returns:** The configurator of the context if it already was defined, `null` if not.
### DisplayUserInfo
Determines if the name of the currently logged-in user should be displayed in the top right corner of the admin UI.
```c#
HopFrameConfigurator DisplayUserInfo(bool display)
```
- **Parameters:**
- `display`: A boolean value to set if the user info should be displayed.
- **Returns:** `HopFrameConfigurator`
### SetBasePolicy
Sets a default policy that every user needs to have in order to access the admin UI.
```c#
HopFrameConfigurator SetBasePolicy(string basePolicy)
```
- **Parameters:**
- `basePolicy`: The default policy string.
- **Returns:** `HopFrameConfigurator`
### SetLoginPage
Sets a custom login page to redirect to if the request to the admin UI was unauthorized.
```c#
HopFrameConfigurator SetLoginPage(string url)
```
- **Parameters:**
- `url`: The URL of the custom login page.
- **Returns:** `HopFrameConfigurator`

View File

@@ -1,3 +1,286 @@
# PropertyConfig
Start typing here...
This configuration contains all configurations for the given property type on the table.
## Configuration methods
### SetDisplayName
Sets the title displayed in the table header and edit dialog.
```c#
PropertyConfigurator<TProp> SetDisplayName(string displayName)
```
- **Parameters:**
- `displayName`: The display name for the property.
- **Returns:** `PropertyConfigurator<TProp>`
### List
Determines if the property should appear in the table, if not the property is also set to be not searchable.
```c#
PropertyConfigurator<TProp> List(bool list)
```
- **Parameters:**
- `list`: A boolean value to set if the property should appear in the table.
- **Returns:** `PropertyConfigurator<TProp>`
### IsSortable
Determines if the table can be sorted by the property.
```c#
PropertyConfigurator<TProp> IsSortable(bool sortable)
```
- **Parameters:**
- `sortable`: A boolean value to set if the property is sortable.
- **Returns:** `PropertyConfigurator<TProp>`
### IsSearchable
Determines if the property get taken into account for search results.
```c#
PropertyConfigurator<TProp> IsSearchable(bool searchable)
```
- **Parameters:**
- `searchable`: A boolean value to set if the property is searchable.
- **Returns:** `PropertyConfigurator<TProp>`
### SetDisplayedProperty
Determines if the value that should be displayed instead of the string representation of the type.
```c#
PropertyConfigurator<TProp> SetDisplayedProperty<TInnerProp>(Expression<Func<TProp, TInnerProp>> propertyExpression)
```
- **Type Parameters:**
- `TInnerProp`: The inner property type to display.
- **Parameters:**
- `propertyExpression`: The expression to determine the property.
- **Returns:** `PropertyConfigurator<TProp>`
### Format (Synchronous)
Determines the value that's displayed in the admin UI.
```c#
PropertyConfigurator<TProp> Format(Func<TProp, IServiceProvider, string> formatter)
```
- **Parameters:**
- `formatter`: The function to format the value.
- **Returns:** `PropertyConfigurator<TProp>`
- **See Also:** [](#setdisplayedproperty)
### Format (Asynchronous)
Determines the value that's displayed in the admin UI.
```c#
PropertyConfigurator<TProp> Format(Func<TProp, IServiceProvider, Task<string>> formatter)
```
- **Parameters:**
- `formatter`: The function to format the value.
- **Returns:** `PropertyConfigurator<TProp>`
### FormatEach (Synchronous)
Determines the value that's displayed for each entry in the list.
```c#
PropertyConfigurator<TProp> FormatEach<TInnerProp>(Func<TInnerProp, IServiceProvider, string> formatter)
```
- **Parameters:**
- `formatter`: The function to format the value for each entry.
- **Returns:** `PropertyConfigurator<TProp>`
### FormatEach (Asynchronous)
Determines the value that's displayed for each entry in the list.
```c#
PropertyConfigurator<TProp> FormatEach<TInnerProp>(Func<TInnerProp, IServiceProvider, Task<string>> formatter)
```
- **Parameters:**
- `formatter`: The function to format the value for each entry.
- **Returns:** `PropertyConfigurator<TProp>`
### SetParser (Synchronous)
Determines the function used for parsing the value provided in the editor dialog to the actual property value.
```c#
PropertyConfigurator<TProp> SetParser(Func<string, IServiceProvider, TProp> parser)
```
- **Parameters:**
- `parser`: The function to parse the value.
- **Returns:** `PropertyConfigurator<TProp>`
### SetParser (Asynchronous)
Determines the function used for parsing the value provided in the editor dialog to the actual property value.
```c#
PropertyConfigurator<TProp> SetParser(Func<string, IServiceProvider, Task<TProp>> parser)
```
- **Parameters:**
- `parser`: The function to parse the value.
- **Returns:** `PropertyConfigurator<TProp>`
### SetEditable
Determines if the value can be edited in the admin UI. If true, the value can still be initially set, but not modified.
```c#
PropertyConfigurator<TProp> SetEditable(bool editable)
```
- **Parameters:**
- `editable`: A boolean value to set if the property is editable.
- **Returns:** `PropertyConfigurator<TProp>`
### SetCreatable
Determines if the initial value can be edited in the admin UI. If true the value will not be visible in the create dialog.
```c#
PropertyConfigurator<TProp> SetCreatable(bool creatable)
```
- **Parameters:**
- `creatable`: A boolean value to set if the property is creatable.
- **Returns:** `PropertyConfigurator<TProp>`
### DisplayValue
Determines if the value should be displayed in the admin UI (useful for secrets like passwords etc.).
```c#
PropertyConfigurator<TProp> DisplayValue(bool display)
```
- **Parameters:**
- `display`: A boolean value to set if the property value is displayed.
- **Returns:** `PropertyConfigurator<TProp>`
### IsTextArea
Determines if the admin UI should use a text area for modifying the value.
```c#
PropertyConfigurator<TProp> IsTextArea(bool textField)
```
- **Parameters:**
- `textField`: A boolean value to set if the property is a text area.
- **Returns:** `PropertyConfigurator<TProp>`
### SetTextAreaRows
Determines the initial size of the text area field.
```c#
PropertyConfigurator<TProp> SetTextAreaRows(int rows)
```
- **Parameters:**
- `rows`: The number of rows for the text area.
- **Returns:** `PropertyConfigurator<TProp>`
### SetValidator (Synchronous)
Determines the validator used for the property value before saving.
```c#
PropertyConfigurator<TProp> SetValidator(Func<TProp?, IServiceProvider, IEnumerable<string>> validator)
```
- **Parameters:**
- `validator`: The function to validate the property value.
- **Returns:** `PropertyConfigurator<TProp>`
### SetValidator (Asynchronous)
Determines the validator used for the property value before saving.
```c#
PropertyConfigurator<TProp> SetValidator(Func<TProp?, IServiceProvider, Task<IEnumerable<string>>> validator)
```
- **Parameters:**
- `validator`: The function to validate the property value.
- **Returns:** `PropertyConfigurator<TProp>`
### SetOrderIndex
Determines the order index for the property in the admin UI.
```c#
PropertyConfigurator<TProp> SetOrderIndex(int index)
```
- **Parameters:**
- `index`: The order index for the property.
- **Returns:** `PropertyConfigurator<TProp>`
- **See Also:** [](TableConfig.md#setorderindex)
### SetDisplayLength
Sets the maximum character length displayed in the admin UI (not in the editor dialog).
```c#
PropertyConfigurator<TProp> SetDisplayLength(int maxLength)
```
- **Parameters:**
- `maxLength`: The maximum length of characters to be displayed.
- **Returns:** `PropertyConfigurator<TProp>`
### ForceRelation
Forces a property to be treated as a relation.
```c#
PropertyConfigurator<TProp> ForceRelation(bool isEnumerable = false, bool isRequired = true)
```
- **Parameters:**
- `isEnumerable`: Determines if it is possible to assign multiple objects to the property.
- `isRequired`: Determines if the property is nullable.
- **Returns:** `PropertyConfigurator<TProp>`

View File

@@ -1,3 +1,191 @@
# TableConfig
Start typing here...
This configuration contains all configurations for the given table type.
## Configuration methods
### Ignore
Determines if the table should be ignored in the admin UI.
```c#
TableConfigurator<TModel> Ignore(bool ignore)
```
- **Parameters:**
- `ignore`: A boolean value to set if the table should be ignored.
- **Returns:** `TableConfigurator<TModel>`
### Property (With configurator)
Configures the property of the table using the provided configurator.
```c#
TableConfigurator<TModel> Property<TProp>(Expression<Func<TModel, TProp>> propertyExpression, Action<PropertyConfigurator<TProp>> configurator)
```
- **Parameters:**
- `propertyExpression`: Used for determining the property.
- `configurator`: Used for configuring the property.
- **Returns:** `TableConfigurator<TModel>`
- **See Also:** [](PropertyConfig.md)
### Property (Without configurator)
Configures the property of the table.
```c#
PropertyConfigurator<TProp> Property<TProp>(Expression<Func<TModel, TProp>> propertyExpression)
```
- **Parameters:**
- `propertyExpression`: Used for determining the property.
- **Returns:** `PropertyConfigurator<TProp>`
- **See Also:** [](PropertyConfig.md)
### AddVirtualProperty (With configurator)
Adds a virtual property to the table view and configures it using the provided configurator (this property will not appear in the editor).
```c#
TableConfigurator<TModel> AddVirtualProperty(string name, Func<TModel, IServiceProvider, string> template, Action<PropertyConfigurator<string>> configurator)
```
- **Parameters:**
- `name`: The name of the virtual property.
- `template`: The template used for generating the property value.
- `configurator`: Used for configuring the virtual property.
- **Returns:** `TableConfigurator<TModel>`
- **See Also:** [](PropertyConfig.md)
### AddVirtualProperty (Synchronous)
Adds a virtual property to the table view (this property will not appear in the editor).
```c#
PropertyConfigurator<string> AddVirtualProperty(string name, Func<TModel, IServiceProvider, string> template)
```
- **Parameters:**
- `name`: The name of the virtual property.
- `template`: The template used for generating the property value.
- **Returns:** `PropertyConfigurator<string>`
- **See Also:** [](PropertyConfig.md)
### AddVirtualProperty (Asynchronous)
Adds a virtual property to the table view (this property will not appear in the editor).
```c#
PropertyConfigurator<string> AddVirtualProperty(string name, Func<TModel, IServiceProvider, Task<string>> template)
```
- **Parameters:**
- `name`: The name of the virtual property.
- `template`: The template used for generating the property value.
- **Returns:** `PropertyConfigurator<string>`
- **See Also:** [](PropertyConfig.md)
### SetDisplayName
Determines the name for the table used in the admin UI and URL for the table page.
```c#
TableConfigurator<TModel> SetDisplayName(string name)
```
- **Parameters:**
- `name`: The display name for the table.
- **Returns:** `TableConfigurator<TModel>`
### SetDescription
Determines the description displayed in the admin UI.
```c#
TableConfigurator<TModel> SetDescription(string description)
```
- **Parameters:**
- `description`: The description for the table.
- **Returns:** `TableConfigurator<TModel>`
### SetOrderIndex
Determines the order index for the table in the admin UI.
```c#
TableConfigurator<TModel> SetOrderIndex(int index)
```
- **Parameters:**
- `index`: The order index for the table.
- **Returns:** `TableConfigurator<TModel>`
- **See Also:** [](PropertyConfig.md#setorderindex)
### SetViewPolicy
Determines the policy needed by a user in order to view the table.
```c#
TableConfigurator<TModel> SetViewPolicy(string policy)
```
- **Parameters:**
- `policy`: The view policy string.
- **Returns:** `TableConfigurator<TModel>`
### SetUpdatePolicy
Determines the policy needed by a user in order to edit the entries.
```c#
TableConfigurator<TModel> SetUpdatePolicy(string policy)
```
- **Parameters:**
- `policy`: The update policy string.
- **Returns:** `TableConfigurator<TModel>`
### SetCreatePolicy
Determines the policy needed by a user in order to create entries.
```c#
TableConfigurator<TModel> SetCreatePolicy(string policy)
```
- **Parameters:**
- `policy`: The create policy string.
- **Returns:** `TableConfigurator<TModel>`
### SetDeletePolicy
Determines the policy needed by a user in order to delete entries.
```c#
TableConfigurator<TModel> SetDeletePolicy(string policy)
```
- **Parameters:**
- `policy`: The delete policy string.
- **Returns:** `TableConfigurator<TModel>`