leon.hoppe/HopFrame
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Added documentation for custom repos and exporter plugin

Browse Source
This commit is contained in:
Leon Hoppe
2025-03-15 12:34:16 +01:00
parent 222d4276d2
commit 5c6fafcd6f
8 changed files with 323 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/Writerside/hopframe.tree
View File

@@ -17,6 +17,7 @@
<toc-element topic="PropertyConfig.md"/>
</toc-element>
<toc-element topic="Callbacks.md"/>
<toc-element topic="Custom-Repositories.md"/>
</toc-element>
<toc-element toc-title="Web Module">
<toc-element toc-title="Interface">
@@ -27,6 +28,10 @@
<toc-element topic="Plugins.md">
<toc-element topic="Events.md">
</toc-element>
<toc-element topic="Exporter-Plugin.md"/>
</toc-element>
</toc-element>
<toc-element toc-title="Services">
<toc-element topic="IFileService.md"/>
</toc-element>
</instance-profile>

132
docs/Writerside/topics/Custom-Repositories.md Normal file
View File

@@ -0,0 +1,132 @@
# Custom Repositories
Custom repositories in HopFrame allow you to define and integrate custom logic for managing database entities. By implementing the `IHopFrameRepository<TModel, TKey>` interface, you can gain full control over how data is retrieved, modified, and managed. This feature is ideal for scenarios where the default behavior does not meet specific business requirements.
## IHopFrameRepository<TModel, TKey> Interface
The `IHopFrameRepository<TModel, TKey>` interface defines a contract for a repository that works with a specific model (`TModel`) and its primary key (`TKey`). The interface provides the following methods:
- **LoadPage**
Loads a paginated set of items.
```c#
Task<IEnumerable<TModel>> LoadPage(int page, int perPage);
```
- **Parameters:**
- `page`: The page number to load.
- `perPage`: The number of items per page.
- **Returns:** A collection of items for the specified page.
- **Search**
Performs a search query on the repository.
```c#
Task<SearchResult<TModel>> Search(string searchTerm, int page, int perPage);
```
- **Parameters:**
- `searchTerm`: The term to search for.
- `page`: The page number to load.
- `perPage`: The number of items per page.
- **Returns:** A `SearchResult` containing matching items and the total number of pages.
- **GetTotalPageCount**
Retrieves the total number of pages based on the items per page.
```c#
Task<int> GetTotalPageCount(int perPage);
```
- **Parameters:**
- `perPage`: The number of items per page.
- **Returns:** The total number of pages.
- **CreateItem**
Adds a new item to the repository.
```c#
Task CreateItem(TModel item);
```
- **Parameters:**
- `item`: The item to create.
- **EditItem**
Updates an existing item in the repository.
```c#
Task EditItem(TModel item);
```
- **Parameters:**
- `item`: The item to update.
- **DeleteItem**
Removes an item from the repository.
```c#
Task DeleteItem(TModel item);
```
- **Parameters:**
- `item`: The item to delete.
- **GetOne**
Retrieves a single item based on its primary key.
```c#
Task<TModel?> GetOne(TKey key);
```
- **Parameters:**
- `key`: The primary key of the item to retrieve.
- **Returns:** The item if found, or `null` if not.
## `SearchResult<TModel>` Struct
The `SearchResult<TModel>` struct is used to encapsulate the results of a search query.
- **Properties:**
- `Items`: The items retrieved from the search query.
- `PageCount`: The total number of pages based on the search results.
```c#
public readonly struct SearchResult<TModel>(IEnumerable<TModel> items, int pageCount) {
public IEnumerable<TModel> Items { get; init; }
public int PageCount { get; init; }
}
```
## Adding Custom Repositories
To add and configure a custom repository in HopFrame, use the `AddCustomRepository` methods. These methods allow you to specify a repository class (`TRepository`) implementing `IHopFrameRepository<TModel, TKey>` and define configurations for the associated table.
- **With Configurator**
```c#
HopFrameConfigurator AddCustomRepository<TRepository, TModel, TKey>(
Expression<Func<TModel, TKey>> keyExpression,
Action<TableConfigurator<TModel>> configurator
)
where TRepository : IHopFrameRepository<TModel, TKey>;
```
- **Parameters:**
- `keyExpression`: The key of the model.
- `configurator`: Configures the table page.
- **Without Configurator**
```c#
TableConfigurator<TModel> AddCustomRepository<TRepository, TModel, TKey>(
Expression<Func<TModel, TKey>> keyExpression
)
where TRepository : IHopFrameRepository<TModel, TKey>;
```
- **Parameters:**
- `keyExpression`: The key of the model.
- **Returns:** A `TableConfigurator` to configure the table.
By implementing custom repositories and using these methods, you can fully leverage the flexibility of HopFrame for your data management needs. Let me know if you'd like further elaboration!

51
docs/Writerside/topics/Exporter-Plugin.md Normal file
View File

@@ -0,0 +1,51 @@
# Exporter Plugin
The Exporter Plugin is a tool for managing the import and export of data from the HopFrame UI. It provides functionality for exporting table data into a CSV file and importing data back into the system, making data manipulation and backups more seamless.
## What the Exporter Plugin Does
1. **Export Table Data to CSV**
- The plugin allows users to export all data from a table as a CSV file.
- The exported file includes all non-virtual properties as table headers.
- The export process dynamically constructs rows for each entry in the table.
2. **Import Data from CSV**
- Users can import a CSV file to populate or update a table.
- The import process reads the file, validates the headers, and creates new entries or updates existing ones.
- Relationships and enumerable properties are also resolved using the appropriate managers.
3. **User Interface Integration**
- Adds two buttons, "Export" and "Import," to the page header of each table.
- **Export Button:** Initiates the export functionality.
- **Import Button:** Allows users to upload a CSV file for import.
4. **Error Handling**
- Ensures errors during import or export (e.g., invalid file format, missing data, or system issues) are shown to the user as toast messages.
## Adding the Exporter Plugin
To include the Exporter Plugin in your HopFrame setup, use the `AddExporters` method provided by the `HopFrameConfiguratorExtensions`.
Here’s how to register the Exporter Plugin in your application configuration:
```c#
builder.Services.AddHopFrame(options => {
options.AddExporters();
});
```
The `AddExporters` method internally registers the `ExporterPlugin` and attaches its functionality to the HopFrame.
## Key Features of the Export Process
- **Dynamic Header Creation:** Automatically generates headers based on the table's non-virtual properties.
- **Data Transformation:** Transforms property values into CSV-compatible formats.
- **File Download:** Saves the generated CSV file with the table’s display name.
## Key Features of the Import Process
- **Header Validation:** Validates that the CSV file headers match the table's properties.
- **Type Conversion:** Converts values in the CSV file to their respective data types.
- **Relationship Management:** Resolves relationships and enumerable properties during import.
This plugin streamlines data operations, reducing manual effort and enabling quick data migration or updates. Let me know if you’d like to dive deeper into any specific aspect!

44
docs/Writerside/topics/HopFrameConfig.md
View File

@@ -118,6 +118,50 @@ DbContextConfigurator<TDbContext>? GetDbContext<TDbContext>() where TDbContext :
- **Returns:** The configurator of the context if it already was defined, `null` if not.
### AddCustomRepository (With configurator)
Adds a table of the desired type and configures it to use a custom repository.
```c#
HopFrameConfigurator AddCustomRepository<TRepository, TModel, TKey>(
Expression<Func<TModel, TKey>> keyExpression,
Action<TableConfigurator<TModel>> configurator
)
where TRepository : IHopFrameRepository<TModel, TKey>
```
- **Type Parameters:**
- `TRepository`: The repository class that inherits from `IHopFrameRepository<TModel, TKey>` (needs to be registered as a service).
- `TModel`: The model of the table.
- `TKey`: The type of the primary key.
- **Parameters:**
- `keyExpression`: The key of the model.
- `configurator`: The configurator used for configuring the table page.
- **Returns:** `HopFrameConfigurator`
### AddCustomRepository (Without configurator)
Adds a table of the desired type and configures it to use a custom repository.
```c#
TableConfigurator<TModel> AddCustomRepository<TRepository, TModel, TKey>(
Expression<Func<TModel, TKey>> keyExpression
)
where TRepository : IHopFrameRepository<TModel, TKey>
```
- **Type Parameters:**
- `TRepository`: The repository class that inherits from `IHopFrameRepository<TModel, TKey>` (needs to be registered as a service).
- `TModel`: The model of the table.
- `TKey`: The type of the primary key.
- **Parameters:**
- `keyExpression`: The key of the model.
- **Returns:** The configurator used for configuring the table page: `TableConfigurator<TModel>`.
### DisplayUserInfo
Determines if the name of the currently logged-in user should be displayed in the top right corner of the admin UI.

41
docs/Writerside/topics/IFileService.md Normal file
View File

@@ -0,0 +1,41 @@
# IFileService
The `IFileService` interface provides methods for handling file operations, such as downloading and uploading files within the HopFrame web application. It abstracts file-related operations to ensure a smooth and consistent user experience.
## Methods
1. **DownloadFile**
- Initiates the download of a file with the given name and data.
- Suitable for dynamically generating and offering files to the user, such as CSV exports or reports.
```c#
Task DownloadFile(string name, byte[] data);
```
- **Parameters:**
- `name`: The name of the file to be downloaded (including the extension, e.g., "example.csv").
- `data`: The byte array representing the content of the file.
- **Usage Example:** Exporting table data as a CSV file for download.
2. **UploadFile**
- Allows the user to upload a file through the web interface and returns the uploaded file for further processing.
- This method provides integration with Blazor's `IBrowserFile` for easy file handling.
```c#
Task<IBrowserFile> UploadFile();
```
- **Returns:** An `IBrowserFile` instance representing the uploaded file.
- **Usage Example:** Importing data from a CSV file to populate or update a table.
## Integration
The `IFileService` is commonly used in conjunction with plugins or components that require file operations, such as the Exporter Plugin, which leverages this service to enable data export and import functionality.
## Key Features
- Streamlines file handling for web applications.
- Simplifies both download and upload processes with minimal code.
- Ensures compatibility with Blazor's file-handling capabilities.
By implementing or extending the `IFileService`, developers can customize the file-handling behavior to suit specific application needs. Let me know if you'd like more examples or details!