diff --git a/search/README.md b/search/README.md new file mode 100644 index 00000000..2a92de60 --- /dev/null +++ b/search/README.md @@ -0,0 +1,106 @@ +# Search & Filter System + +A flexible, reusable search and filtering system that can be used across any Django model in the project. + +## Features + +- Modular filter system with composable mixins +- HTMX integration for dynamic updates +- Responsive, accessible filter UI components +- Automatic filter generation based on model fields +- Location-based filtering support +- Flexible template system + +## Usage + +### Basic Implementation + +Add filtering to any ListView by using the `HTMXFilterableMixin`: + +```python +from django.views.generic import ListView +from search.mixins import HTMXFilterableMixin + +class MyModelListView(HTMXFilterableMixin, ListView): + model = MyModel + template_name = "myapp/mymodel_list.html" + search_fields = ['name', 'description'] # Fields to include in text search +``` + +### Custom Filters + +Add custom filters for specific model needs: + +```python +additional_filters = { + 'category': ChoiceFilter(choices=MyModel.CATEGORY_CHOICES), + 'rating': RangeFilter(field_name='average_rating'), +} +``` + +### Template Integration + +Extend the base filtered list template: + +```html +{% extends "search/layouts/filtered_list.html" %} + +{% block list_actions %} + + Add New + +{% endblock %} +``` + +### Custom Result Display + +Create a custom results template in `templates/search/partials/mymodel_results.html`: + +```html +
+ {{ object.description|truncatewords:30 }} +
+ {% endif %} + + {% block object_metadata %} +No {{ view.model|model_name_plural }} found matching your criteria.
+ {% if applied_filters %} + + {% endif %} ++ Showing {{ page_obj.start_index }} + to {{ page_obj.end_index }} + of {{ page_obj.paginator.count }} + results +
+{{ park.formatted_location }}
+ {% endif %} ++ {{ park.description }} +
+ {% endif %} +