diff --git a/README.md b/README.md index e0b9a6b..d1d0cd5 100644 --- a/README.md +++ b/README.md @@ -72,3 +72,8 @@ Once the projects are running, you can access them via the following URLs: - **FormBuilder.API**: The Web API project for managing form data and LOV (List of Values) data. - **FormBuilder.DesignerApp**: The Blazor WebAssembly project for designing and rendering forms. - **FormBuilder.Shared**: The shared project containing common models used across the `FormBuilder` and `FormBuilder.API` projects. + +## Documentation +- **[API Reference](docs/api-reference.md)**: Learn how to use the Form Builder API to create, update, delete, and retrieve forms and LOV data. +- **[Integration Guide](docs/integration-guide.md)**: Integrate the Blazor Form Builder with your existing Blazor application. +- **[Form Renderer Component Reference](docs/form-renderer.md)**: Render forms in your Blazor application using the `FormRenderer` component. diff --git a/docs/api-reference.md b/docs/api-reference.md index e925f63..c8eac95 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -3,12 +3,256 @@ The Form Builder REST API provides endpoints to manage forms and list of values (LOV). You can use the Form Builder API to create, update, delete, and retrieve forms and LOV data. -## Form API -- `GET /api/forms`: Get all forms in the form of paged response. - - Query Parameters: - - `page`: The non-zero-based page number. Default is 1. - - `pageSize`: The number of items per page. Default is 10. - - Response: - - `pageSize`: The number of items per page. - - `pagesCount`: The total number of available pages. - - `data`: An array of form data. +All endpoints have general response structure, with `success`, `data`, and `error` fields. +The `success` field indicates whether the request was successful. +If the request was successful, the `data` field contains the response data. +Otherwise, the `error` field contains the error message and the `data` field is not present. + +```json +{ + "success": true, + "error": "Error message", // Only if success is false + "data": { // Only if success is true + "id": 1, + "formName": "Form 1", + "formDesign": "{JSON Data}" + } +} +``` + +For pagination, the response contains `pageSize`, `pagesCount`, and `data` fields. +```json +{ + "success": true, + "pageSize": 10, // Number of items per page + "pagesCount": 1, // Total number of pages + "data": [ + { + "id": 1, + "formName": "Form 1", + "formDesign": "{JSON Data}" + } + ] +} +``` + +#### GET `/api/forms` +##### Summary: + +Gets a paged list of forms. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +|----------|------------|----------------------------------------------|----------|---------| +| OrderBy | query | The field to order by. | No | string | +| Page | query | Non-zero-based page number. Default is 1. | No | integer | +| PageSize | query | The number of items per page. Default is 10. | No | integer | + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | + +Response body example, +```json +{ + "success": true, + "pageSize": 10, + "pagesCount": 1, + "data": [ + { + "id": 1, + "formName": "Form 1", + "formDesign": "{JSON Data}", + } + ] +} +``` + +### POST `/api/forms` +##### Summary: + +Creates a new form. + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | +| 400 | Bad Request | + +Success response body example, +```json +{ + "success": true, + "data": { + "id": 1, + "formName": "Form 1", + "formDesign": "{JSON Data}" + } +} +``` + +Error response body example, +```json +{ + "success": false, + "error": "Error message" +} +``` + +### GET `/api/forms/{id}` +##### Summary: + +Gets a form by its id. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| id | path | Form ID | Yes | string | + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | +| 400 | Bad Request | + +### PUT `/api/forms/{id}` +##### Summary: + +Updates a form by its id. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +|------|------------|------------------|----------|--------| +| id | path | Existing form ID | Yes | string | + +Example request body, +```json +{ + "formName": "Form 1", + "formDesign": "{JSON Data}" +} +``` + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | +| 400 | Bad Request | + +### DELETE `/api/forms/{id}` +##### Summary: + +Deletes a form by its id. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +|------|------------|-------------|----------|--------| +| id | path | Form ID | Yes | string | + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | +| 400 | Bad Request | + + +### GET `/api/lov` +##### Summary: + +Gets a paged list of List IDs. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +|----------|------------|----------------------------------------------|----------|---------| +| OrderBy | query | The field to order by. | No | string | +| Page | query | Non-zero-based page number. Default is 1. | No | integer | +| PageSize | query | The number of items per page. Default is 10. | No | integer | + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | + +### POST `/api/lov` +##### Summary: + +Batch add list of values + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | + +Request body example, +```json +{ + "lovs": [ + { + "listId": 1, + "listValue": "Value 1" + } + ] +} +``` + +### GET `/api/lov/{listId}` +##### Summary: + +Gets list of values filtered by ListId + +##### Parameters + +| Name | Located in | Description | Required | Schema | +|--------|------------|-------------|----------|---------| +| listId | path | | Yes | integer | + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | + +Success response body example, +```json +{ + "success": true, + "data": [ + { + "id": 1, + "listId": 1, + "listValue": "Value 1" + } + ] +} +``` + +### POST `/api/lov/batch-delete` +##### Summary: + +Batch delete list of values + +##### Responses + +| Code | Description | +|------|-------------| +| 200 | Success | + +Request body example, +```json +{ + "listIds": [1, 2, 3] +} +``` diff --git a/docs/form-renderer.md b/docs/form-renderer.md index c5ba2ef..54bca4b 100644 --- a/docs/form-renderer.md +++ b/docs/form-renderer.md @@ -1,51 +1,66 @@ # Form Renderer Component Reference -The Form Renderer component is used to render forms in that designed by the `FormEditor` component. +The Form Renderer component is used to render forms designed by the `FormEditor` component. You can specify either the `FormId` or `FormJson` property to render a form. ## FormRenderer Properties -- `FormId`: The ID of the form to render. It fetches form data from the API based on the ID. -- `FormJson`: The JSON data of the form to render. You can pass the JSON data of the form directly to the component. -- `IsLoadingForm`: A boolean value that indicates whether the form is loading and rendering. + +- **`FormId`**: The ID of the form to render. This fetches form data from the API based on the ID. +- **`FormJson`**: The JSON data of the form to render. This allows you to pass the JSON data of the form directly to the component. +- **`IsLoadingForm`**: A boolean value indicating whether the form is currently loading and rendering. ## FormRenderer Events -- `IsLoadingFormChanged`: An event that is triggered when the `IsLoadingForm` property changes. You can use this event to perform additional actions when the form is loading. -- `FormLoaded`: An event that is triggered when the form is loaded and rendered. You can use this event to perform additional actions when the form is loaded. -## FormRenderer public methods -- `LoadFormFromIdAsync(string formId)`: A method that loads the form data from the API based on the form ID. -- `LoadFormFromJsonAsync(string formJson)`: A method that loads the form data from the JSON data. -- `GetFormAsJsonAsync()`: A method that returns the JSON data of the rendered form. +- **`IsLoadingFormChanged`**: An event triggered when the `IsLoadingForm` property changes. Use this event to perform additional actions when the form is loading. +- **`FormLoaded`**: An event triggered when the form is fully loaded and rendered. Use this event to perform additional actions when the form is loaded. + +## FormRenderer Public Methods + +- **`LoadFormFromIdAsync(string formId)`**: Loads the form data from the API based on the form ID. +- **`LoadFormFromJsonAsync(string formJson)`**: Loads the form data from the provided JSON data. +- **`GetFormAsJsonAsync()`**: Returns the JSON data of the rendered form. ## Examples -## Render a form using FormId or FormJson properties + +### Render a form using FormId or FormJson properties + +Render a form using the `FormId` property: + ```html ``` + +Render a form using the `FormJson` property: + ```html ``` -## Render a form dynamically using methods +### Render a form dynamically using methods + ```html ``` + ```csharp @code { private FormRenderer? formRendererRef; private string? _formId; - + private async Task LoadForm() { if (formRendererRef is null || string.IsNullOrEmpty(_formId)) { return; } - - await formRenderer.LoadFormFromIdAsync(_formId); + + await formRendererRef.LoadFormFromIdAsync(_formId); } } ``` + +In these examples, the `FormRenderer` component can be used to dynamically load forms based on either a form ID or JSON data. +The component also provides events and methods to manage the loading state and retrieve the rendered form data as JSON. diff --git a/docs/integration-guide.md b/docs/integration-guide.md index 6e66350..2e8e633 100644 --- a/docs/integration-guide.md +++ b/docs/integration-guide.md @@ -1,58 +1,99 @@ -# How to integrate FormBuilder with your Blazor application - -This guide explains how to integrate the Blazor Form Builder with your existing Blazor application. The integration process involves the following steps: - -1. **Add the FormBuilder Razor class library to your Blazor application**: - Add the `FormBuilder` Razor class library to your Blazor application as a project reference. - -2. **Register the FormBuilder services**: - Add `AddFormBuilder()` to the service collection in the `Program.cs` file. - Also, you need to pass `FormApiUrl` to the `AddFormBuilder()` method. The `FormApiUrl` is the URL of the Form Builder API. - For example: - ```csharp - builder.Services.AddFormBuilder(options => - { - options.FormApiUrl = "https://localhost:8000"; - }); - ``` - -3. **Add styles and scripts**: - Include the required styles and scripts in the `index.html` file. - Add the following styles to the `head` section: - ```html - - ``` - The `app.css` file includes styles for Radzen components and Bootstrap 5. - Alternatively, you can directly include Radzen styles and Bootstrap in your application. - For example: - ```html - - - ``` - Add the following scripts to the `body` section: - ```html - - ``` - The `app.js` file includes scripts for Radzen components. - Alternatively, you can directly include Radzen scripts in your application. - For example: - ```html - - ``` -4. **Use FormEditor component**: - Use the `FormEditor` component in your Blazor application to design forms. - For example: - ```html - - ``` - -5. **Use FormRenderer component**: - Use the `FormRenderer` component in your Blazor application to render forms. - For example: - ```html - - ``` - -You can view a sample Blazor application that integrates the Blazor Form Builder in the `src/FormBuilder.DesignerApp` project. -The sample application demonstrates how to design and render forms using the Blazor Form Builder components. +# How to Integrate FormBuilder with Your Blazor Application +This guide explains how to integrate the Blazor FormBuilder with your existing Blazor application. +The integration process involves the following steps: + +## Step 1: Add the FormBuilder Razor Class Library + +Add the `FormBuilder` Razor class library to your Blazor application as a project reference. + +## Step 2: Register the FormBuilder Services + +Add `AddFormBuilder()` to the service collection in the `Program.cs` file. +You also need to pass the `FormApiHost` to the `AddFormBuilder()` method. +The `FormApiHost` is the base URL of the Form Builder API. + +Example: + +```csharp +builder.Services.AddFormBuilder(options => +{ + options.FormApiHost = "https://localhost:8000"; +}); +``` + +## Step 3: Add Styles, Scripts, and Required Components + +Include the required styles and scripts in the `index.html` file. + +### Add Styles + +Add the following styles to the `head` section: + +```html + +``` + +The `app.css` file includes styles for Radzen components and Bootstrap 5. + +Alternatively, you can directly include Radzen styles and Bootstrap in your application: + +```html + + +``` + +### Add Scripts + +Add the following scripts to the `body` section: + +```html + +``` + +The `app.js` file includes scripts for Radzen components. + +Alternatively, you can directly include Radzen scripts in your application: + +```html + +``` +### Add Required Components +Add the `RadzenComponents` component to the layout file. +It is used to render Radzen notifications and dialog components. +For example, add the following code to the `MainLayout.razor` file: + +```html + +``` + +And don't forget to include namespace in the `_Imports.razor` file: + +```csharp +@using FormBuilder.Components +``` + +## Step 4: Use FormEditor Component + +Use the `FormEditor` component in your Blazor application to design forms. + +Example: + +```html + +``` + +## Step 5: Use FormRenderer Component + +Use the `FormRenderer` component in your Blazor application to render forms. + +Example: + +```html + +``` + +## Sample Application + +You can view a sample Blazor application that integrates the Blazor Form Builder components in the `src/FormBuilder.DesignerApp` project. +The sample application demonstrates how to design and render forms using the Blazor FormBuilder components. diff --git a/src/FormBuilder.API/Configurations/SwaggerConfiguration.cs b/src/FormBuilder.API/Configurations/SwaggerConfiguration.cs index 3db4070..806b19d 100644 --- a/src/FormBuilder.API/Configurations/SwaggerConfiguration.cs +++ b/src/FormBuilder.API/Configurations/SwaggerConfiguration.cs @@ -1,4 +1,5 @@ using System.Reflection; +using FormBuilder.Shared.Models; using Microsoft.OpenApi.Models; namespace FormBuilder.API.Configurations; @@ -21,8 +22,18 @@ public static void ConfigureSwagger(this WebApplicationBuilder builder) Version = "v1" }); - var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; - options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename)); + // Include XML comments from the current assembly + var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; + options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFile)); + + // Include XML comments from the shared assembly + var modelsXmlFile = $"{Assembly.GetAssembly(typeof(PagedQuery))?.GetName().Name}.xml"; + var modelsXmlPath = Path.Combine(AppContext.BaseDirectory, modelsXmlFile); + + if (File.Exists(modelsXmlPath)) + { + options.IncludeXmlComments(modelsXmlPath); + } }); } } diff --git a/src/FormBuilder.API/Controllers/LovController.cs b/src/FormBuilder.API/Controllers/LovController.cs index de9f42d..4125f34 100644 --- a/src/FormBuilder.API/Controllers/LovController.cs +++ b/src/FormBuilder.API/Controllers/LovController.cs @@ -56,8 +56,8 @@ public async Task> AddListOfValues(BatchAddLovCommand comma /// /// The command containing the list of ListIds to delete /// - [HttpDelete] - public async Task> DeleteListOfValues(BatchDeleteLovCommand command) + [HttpPost("batch-delete")] + public async Task> BatchDeleteListOfValues(BatchDeleteLovCommand command) { var result = await _lovService.DeleteListOfValuesAsync(command); return result.Success ? Ok(result) : BadRequest(result); diff --git a/src/FormBuilder.Shared/FormBuilder.Shared.csproj b/src/FormBuilder.Shared/FormBuilder.Shared.csproj index 3a63532..fa1a6d8 100644 --- a/src/FormBuilder.Shared/FormBuilder.Shared.csproj +++ b/src/FormBuilder.Shared/FormBuilder.Shared.csproj @@ -4,6 +4,8 @@ net8.0 enable enable + true + $(NoWarn);1591