An Angular filtering widget is a user interface component built using the Angular library that facilitates the process of filtering and refining data or content displayed on a web page. This widget is particularly useful when dealing with sunbird data or lists of items and allows users to interactively narrow down the displayed information based on their preferences or criteria.
-
Prerequisites: Ensure that you have Node.js and npm (Node Package Manager) installed on your system. You can download them from the official website: Node.js Downloads: here.
-
Create an Angular App: If you haven't already, create an Angular application using the Angular CLI. This tool sets up a basic Angular project structure for you.
ng new my-app
- Navigate to Your Project Directory: Open your terminal or command prompt and navigate to the root directory of your Angular project.
Install the Filtering Widget Package: Use npm or yarn to install the filtering widget package. For example:
npm install filtering-package
# or
yarn add filtering-package
- Import the Widget: In your Angular component where you want to use the filtering widget, import it at the top of your file:
- you need to import the filtering.module module. For example:
import { NgModule } from "@angular/core";
import { BrowserModule } from "@angular/platform-browser";
import { AppComponent } from "./app.component";
import { FilteringModule } from "angular-sunbird-filtering";
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, FilteringModule],
providers: [],
bootstrap: [AppComponent],
})
export class AppModule {}
The project is set up in a modular fashion, with each folder containing code for a specific component or functionality.
project
├── lib
│ ├── components
│ ├── cards
│ │ ├── cards.component.css
│ │ ├── cards.component.html
│ │ ├── cards.component.spec.ts
│ │ └── cards.component.ts
│ ├── filters
│ | ├── filters.component.css
│ | ├── filters.component.html
│ | ├── filters.component.spec.ts
│ | └── filters.component.ts
│ └── wrapper
│ ├── wrapper.component.css
│ ├── wrapper.component.html
│ ├── wrapper.component.spec.ts
│ └── wrapper.component.ts
├── services
│ ├── api.service.ts
│ └── filters.service.ts
│ └── wrapper.service.ts
└── models
├── interfaces.ts
└── serviceFunctionInterfaces.ts
The following are some of the key files in the project setup:
The services
folder contains the code for fetching data from a remote server and filtering functions and other important functions for optimal working.
- api.service.ts : This file defines the API endpoints. It contains the functions that are used to fetch data from the remote server.
- filters.service.ts : This file contains the functions used in the
filters
component that are used to process the process the data of the side filters optimally. - wrapper.service.ts : This file contains the functions used in the
wrapper
component that are used filter the data as per the formConfig of the side and providing the addtional filtering and card field management.
- The cards folder contains the source code for the
CardsComponent
component. This component is used to render a list of cards. - The filters folder contains the source code for the
FiltersComponent
component. This component is used to create a filter input. - The wrapper folder contains the source code for the
WrapperComponent
component. This component is used to wrap the CardsComponent and FiltersComponent components together.
The interfaces folder contains the interface definitions. The interface.ts
file defines the interface for the filter component. The Service Function_Interfaces.ts
file defines the interface for the service functions.
-
Filtering Criteria: Users can specify criteria or parameters by which they want to filter the data. This might include text-based searches, date ranges, categories, or any other relevant attributes.
-
Filter Inputs: Input fields, dropdown menus, sliders, or checkboxes are provided for users to input their filtering criteria. For instance, on an e-commerce website, users might filter products by price range, brand, or product category.
-
Card Fields Management: Card Fields Management refers to the process of configuring and controlling the fields or attributes displayed on a digital card or card-based interface within a Sunbird application.
-
Multiple Filters (Additional Filters): The widget should support multiple filters simultaneously, allowing users to refine their search with a combination of criteria.
-
Customization: The widget should be customizable to fit the visual style and functionality of the specific application or website.
Description: The Form configuration which configures the Field: formUrl
[
{
id: "api.form.read",
name: "Categories",
responseCode: "OK",
data: {
defaultLanguage: "en",
PrimaryFields: {
Board: {
field: "",
isEnabled: true,
depends: ["framework"],
editable: true,
displayProperty: "Editable",
dataType: "text",
renderingHints: {
semanticColumnWidth: "six",
},
description: "board",
index: 1,
label: "board",
required: true,
name: "board",
inputType: "select",
placeholder: "Select",
},
Medium: {
field: "",
isEnabled: true,
depends: ["framework", "board"],
editable: true,
displayProperty: "Editable",
dataType: "list",
renderingHints: {
semanticColumnWidth: "six",
},
description: "medium",
index: 2,
label: "medium",
required: true,
name: "medium",
inputType: "multiSelect",
placeholder: "Select",
},
Class: {
field: "",
isEnabled: true,
visible: true,
depends: ["framework", "board", "medium"],
editable: true,
displayProperty: "Editable",
dataType: "list",
renderingHints: {
semanticColumnWidth: "six",
},
description: "grade",
index: 3,
label: "Class",
required: true,
name: "Class",
inputType: "multiSelect",
placeholder: "Select",
},
Subject: {
field: "",
isEnabled: true,
depends: ["framework", "board", "medium", "grade"],
editable: true,
displayProperty: "Editable",
dataType: "list",
renderingHints: {
semanticColumnWidth: "six",
},
description: "Learning Outcome",
index: 4,
label: "subject",
required: true,
name: "subject",
inputType: "multiSelect",
placeholder: "Select",
},
},
additionalFields: {
Identifier: {
name: "Identifier",
field: "identifier",
isEnabled: false,
depends: [],
editable: true,
displayProperty: "Editable",
dataType: "text",
renderingHints: {
semanticColumnWidth: "six",
},
description: "identifier",
index: 1,
label: "identifier",
required: false,
inputType: "multiselect",
placeholder: "select",
},
},
},
created_on: "2022-08-18T15:00:46.375Z",
last_modified_on: "2022-08-23T08:08:46.600Z",
rootOrgId: "*",
ts: "2023-08-09T07:13:17.674Z",
ver: "1.0",
},
];
Description: This section configures default settings related to channel communication. Channels are typically used for data retrieval or messaging.
Fields Accepted:
- Method: The HTTP request method (e.g., GET, POST) is used for default channel communication.
- Headers (Optional): HTTP headers are included in the default channel request.
- Cache: The caching strategy applied to default channel requests (e.g., "default").
Description: This configuration section is related to the Search API, which is commonly used for querying and retrieving data.
Fields Accepted:
- Method: The HTTP request method (e.g., GET, POST) for Search API requests.
- Headers (Optional): HTTP headers included in Search API requests.
- Body (Optional): The content of the request body for Search API requests.
Description: Similar to the Default Channel Configuration, this section pertains to the configuration of a specific channel used for data retrieval.
Fields Accepted:
- Method: The HTTP request method for Get Channel requests.
- Headers: HTTP headers are included in Get Channel requests.
- Cache: The caching strategy applied to Get Channel requests.
- Field: getChannel
Description: This section configures how terms are read or retrieved, potentially for use in the application.
Fields Accepted:
- Method: The HTTP request method for reading terms.
- Headers: HTTP headers are included in terms of reading requests.
- Body: The content of the request body for terms reading requests (typically empty).
- Field: termsRead
- Description: The Hostname specifies the base URL (https://dev.sunbirdsaas.com) where API requests are directed.
- Field: hostname
Description: This section defines properties related to the display of cards or items. Cards are often used to represent data visually. We have to put Fields in cardFieldsProps
which we have to show on the card.
Fields Accepted:
- name: The field name for card display.
- type: The type of field for card display.
- tags: An array of tags associated with the card.
- image: The field used for displaying card images.
- Publisher: The field used for displaying the card's publisher information.
- Subject: The field used for displaying the card's subject.
- Field: cardFieldsProps
cardFieldsProps={{
name: {
field: 'name',
},
type: {
field: "se_subjects"
},
tags: {
tagsFieldArray: [
"medium",
"se_boards",
"se_subjects",
]
},
image: {
field: "appIcon"
},
publisher: { field: "organisation" },
subject: { field: "se_subjects" }
}}
Description: This setting determines the caching behavior of the component, potentially influencing how data is retrieved and displayed. Field: cache
Description: This section defines various filters that can be applied to the data. Filters allow users to narrow down or customize data views.
Fields Accepted:
- name: The display name of the filter.
- Field: The corresponding API field associated with the filter.
Here, are the master categories
Supported Filters (examples):
Board
Medium
Subject
Grade Level
- Field: filterConfig
- Description: Additional filter configuration options that can be applied to enhance data filtering capabilities.
Fields Accepted:
- name: The display name of the filter.
- Field: The corresponding API field associated with the filter.
- Is Enabled: Indicates whether the filter is enabled (true or false).
This detailed documentation explains the purpose and potential usage of each configuration option within the Wrapper component. It also outlines the types of fields accepted by each configuration element, helping users understand how to customize and adapt the component to their specific needs.
We welcome contributions from the community to improve this project. By participating, you agree to follow these guidelines to maintain a positive and collaborative environment.
- Fork the repository on GitHub.
- Clone your forked repository to your local machine.
- Create a new branch for your work:
git checkout -b feature/your-feature-name
.
- Ensure that your code adheres to the project's coding standards.
- Make meaningful and focused commits. Use descriptive commit messages.
- Keep pull requests (PRs) small and focused on a single feature or bug fix.
- Update documentation as necessary.
- Test your changes thoroughly.
- Push your changes to your forked repository.
- Create a PR from your fork to the main project repository.
- Provide a clear title and description for your PR.
- Mention any related issues using keywords like "Fixes #123" in the description.
- Your PR will be reviewed by project maintainers. Be prepared to make changes if requested.
Please follow our Code of Conduct to ensure a welcoming and inclusive community.
If you encounter bugs or have feature requests, please open an issue on GitHub.
Contributions will be reviewed by maintainers. Constructive feedback may be provided, and changes may be requested. Be patient and open to feedback.
By contributing to this project, you agree that your contributions will be licensed under the project's LICENSE .
Thank you for your contributions! 🎉
Here are some additional resources that may be helpful as you contribute to this project: