simplesitesearch 0.0.1.dev1__tar.gz → 0.0.3__tar.gz

{simplesitesearch-0.0.1.dev1/simplesitesearch.egg-info → simplesitesearch-0.0.3}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: simplesitesearch
-Version: 0.0.1.dev1
+Version: 0.0.3
 Summary: Reptile Simple Site Search django app
-Home-page: https://github.com/reptiletech/simplesitesearch
+Home-page: https://github.com/FlavienLouis/simplesitesearch
 Author: Reptile Tech
 Author-email: Reptile Tech <flouis@reptile.tech>
 Maintainer-email: Reptile Tech <flouis@reptile.tech>
 License: MIT
-Project-URL: Homepage, https://github.com/reptiletech/simplesitesearch
-Project-URL: Documentation, https://github.com/reptiletech/simplesitesearch#readme
-Project-URL: Repository, https://github.com/reptiletech/simplesitesearch.git
-Project-URL: Bug Tracker, https://github.com/reptiletech/simplesitesearch/issues
+Project-URL: Homepage, https://github.com/FlavienLouis/simplesitesearch
+Project-URL: Documentation, https://github.com/FlavienLouis/simplesitesearch#readme
+Project-URL: Repository, https://github.com/FlavienLouis/simplesitesearch.git
+Project-URL: Bug Tracker, https://github.com/FlavienLouis/simplesitesearch/issues
 Keywords: django,search,cms,django-cms
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
@@ -48,7 +48,6 @@ Dynamic: requires-python
 
 A simple Django app for site search functionality with Django CMS integration. This package provides a clean, easy-to-use search interface that can be integrated into Django CMS projects.
 
-> **Note**: This is a development version (0.0.1.dev1). The package is still under active development and may have breaking changes in future releases.
 
 ## Features
 
@@ -119,8 +118,8 @@ urlpatterns = [
 ### 2. Configure the Page
 
 1. Go to **Advanced settings** of the search page
-2. Set the **ID** to `'search'`
-3. Set **APPLICATION** to "Site Search"
+2. Set **APPLICATION** to "Site Search"
+3. Set the **Application ID** to `'site_search'` (this is the default value)
 4. Save the page
 5. Remove the page from the menu (uncheck "menu" in the table)
 6. Publish the page in all languages
@@ -147,10 +146,53 @@ The search results support pagination with a `page` parameter:
 /search/?q=your+search+term&page=2
 ```
 
+### Tags filter
+
+You can send a comma-separated list of tags to filter results. The `tag` (or `tags`) query parameter is forwarded to the API as `tags`:
+
+```
+/search/?q=your+search+term&tag=news,blog,tutorial
+```
+
+Pagination links preserve the tag filter.
+
 ### Honeypot Protection
 
 The search includes basic honeypot protection. If a `message` parameter is present, the search will not execute.
 
+## Utility functions (QOL)
+
+The app provides helpers in `simplesitesearch.utils` for use in views, management commands, or other code.
+
+| Function | Description |
+|----------|-------------|
+| **`get_search_results(term, current_page, tags=None)`** | Fetches search results from the API. Returns a dict with `total_hits` and `hits`. On error returns `{"total_hits": 0, "hits": []}`. |
+| **`get_search_api_url(term, current_page, tags=None)`** | Builds the full search API URL (uses Django settings and current language). |
+| **`build_search_query_string(term, page=1, tags=None)`** | Builds the query string for search URLs (e.g. pagination links), e.g. `?q=foo&page=2&tag=a,b`. |
+| **`parse_comma_separated_tags(value)`** | Parses a comma-separated string into a list of stripped tags; returns `[]` if value is falsy. |
+| **`normalize_search_term(term, max_words=10)`** | Trims and limits the search term to a maximum number of words. |
+| **`safe_int(value, default=None)`** | Safely converts a value to `int`; returns `default` on failure. |
+
+**Example — fetch results in code:**
+
+```python
+from simplesitesearch.utils import get_search_results
+
+data = get_search_results("django", current_page=1, tags=["cms", "tutorial"])
+total = data["total_hits"]
+results = data["hits"]
+```
+
+**Example — build search/pagination URLs:**
+
+```python
+from simplesitesearch.utils import build_search_query_string
+
+# Pagination link for page 2 with tag filter
+qs = build_search_query_string("my query", page=2, tags=["blog"])
+# => "?q=my+query&page=2&tag=blog"
+```
+
 ## Customization
 
 ### Templates
@@ -239,18 +281,29 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Support
 
-For support and questions, please open an issue on the [GitHub repository](https://github.com/yourusername/simplesitesearch/issues).
+For support and questions, please open an issue on the [GitHub repository](https://github.com/FlavienLouis/simplesitesearch/issues).
 
 ## Changelog
 
-### 0.0.1.dev1
-- Initial development release
-- Django CMS integration
-- Pagination support
-- Multi-language support
-- Basic search functionality
+### 0.0.3
+- Added `simplesitesearch.utils` QOL helpers: `get_search_results`, `get_search_api_url`, `build_search_query_string`, `parse_comma_separated_tags`, `normalize_search_term`, `safe_int`
+- Tag filter: `tag` (or `tags`) query parameter forwarded to API as comma-separated `tags`; pagination links preserve tags
+- README: Utility functions section and tags filter documentation
+
+### 0.0.2
+- Fixed template include path in search_results.html
+- Updated pagination template include to use full namespace: `simplesitesearch/pagination.html`
+- Improved template isolation and namespace consistency
+
+### 0.0.1
+- **First stable release**
+- Django CMS integration with apphook support
+- Pagination support for search results
+- Multi-language support with Django i18n
+- Basic search functionality with API integration
 - Template customization support
 - Support for Python 3.6+ and Django 2.2+
-- Updated API endpoint to use Reptile Search API
+- Reptile Search API integration
+- Comprehensive documentation and setup instructions
 
 

{simplesitesearch-0.0.1.dev1 → simplesitesearch-0.0.3}/README.md

@@ -2,7 +2,6 @@
 
 A simple Django app for site search functionality with Django CMS integration. This package provides a clean, easy-to-use search interface that can be integrated into Django CMS projects.
 
-> **Note**: This is a development version (0.0.1.dev1). The package is still under active development and may have breaking changes in future releases.
 
 ## Features
 
@@ -73,8 +72,8 @@ urlpatterns = [
 ### 2. Configure the Page
 
 1. Go to **Advanced settings** of the search page
-2. Set the **ID** to `'search'`
-3. Set **APPLICATION** to "Site Search"
+2. Set **APPLICATION** to "Site Search"
+3. Set the **Application ID** to `'site_search'` (this is the default value)
 4. Save the page
 5. Remove the page from the menu (uncheck "menu" in the table)
 6. Publish the page in all languages
@@ -101,10 +100,53 @@ The search results support pagination with a `page` parameter:
 /search/?q=your+search+term&page=2
 ```
 
+### Tags filter
+
+You can send a comma-separated list of tags to filter results. The `tag` (or `tags`) query parameter is forwarded to the API as `tags`:
+
+```
+/search/?q=your+search+term&tag=news,blog,tutorial
+```
+
+Pagination links preserve the tag filter.
+
 ### Honeypot Protection
 
 The search includes basic honeypot protection. If a `message` parameter is present, the search will not execute.
 
+## Utility functions (QOL)
+
+The app provides helpers in `simplesitesearch.utils` for use in views, management commands, or other code.
+
+| Function | Description |
+|----------|-------------|
+| **`get_search_results(term, current_page, tags=None)`** | Fetches search results from the API. Returns a dict with `total_hits` and `hits`. On error returns `{"total_hits": 0, "hits": []}`. |
+| **`get_search_api_url(term, current_page, tags=None)`** | Builds the full search API URL (uses Django settings and current language). |
+| **`build_search_query_string(term, page=1, tags=None)`** | Builds the query string for search URLs (e.g. pagination links), e.g. `?q=foo&page=2&tag=a,b`. |
+| **`parse_comma_separated_tags(value)`** | Parses a comma-separated string into a list of stripped tags; returns `[]` if value is falsy. |
+| **`normalize_search_term(term, max_words=10)`** | Trims and limits the search term to a maximum number of words. |
+| **`safe_int(value, default=None)`** | Safely converts a value to `int`; returns `default` on failure. |
+
+**Example — fetch results in code:**
+
+```python
+from simplesitesearch.utils import get_search_results
+
+data = get_search_results("django", current_page=1, tags=["cms", "tutorial"])
+total = data["total_hits"]
+results = data["hits"]
+```
+
+**Example — build search/pagination URLs:**
+
+```python
+from simplesitesearch.utils import build_search_query_string
+
+# Pagination link for page 2 with tag filter
+qs = build_search_query_string("my query", page=2, tags=["blog"])
+# => "?q=my+query&page=2&tag=blog"
+```
+
 ## Customization
 
 ### Templates
@@ -193,18 +235,29 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Support
 
-For support and questions, please open an issue on the [GitHub repository](https://github.com/yourusername/simplesitesearch/issues).
+For support and questions, please open an issue on the [GitHub repository](https://github.com/FlavienLouis/simplesitesearch/issues).
 
 ## Changelog
 
-### 0.0.1.dev1
-- Initial development release
-- Django CMS integration
-- Pagination support
-- Multi-language support
-- Basic search functionality
+### 0.0.3
+- Added `simplesitesearch.utils` QOL helpers: `get_search_results`, `get_search_api_url`, `build_search_query_string`, `parse_comma_separated_tags`, `normalize_search_term`, `safe_int`
+- Tag filter: `tag` (or `tags`) query parameter forwarded to API as comma-separated `tags`; pagination links preserve tags
+- README: Utility functions section and tags filter documentation
+
+### 0.0.2
+- Fixed template include path in search_results.html
+- Updated pagination template include to use full namespace: `simplesitesearch/pagination.html`
+- Improved template isolation and namespace consistency
+
+### 0.0.1
+- **First stable release**
+- Django CMS integration with apphook support
+- Pagination support for search results
+- Multi-language support with Django i18n
+- Basic search functionality with API integration
 - Template customization support
 - Support for Python 3.6+ and Django 2.2+
-- Updated API endpoint to use Reptile Search API
+- Reptile Search API integration
+- Comprehensive documentation and setup instructions
 
 

{simplesitesearch-0.0.1.dev1 → simplesitesearch-0.0.3}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
+requires = ["setuptools>=45", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplesitesearch"
-dynamic = ["version"]
+version = "0.0.3"
 description = "Reptile Simple Site Search django app"
 readme = "README.md"
 license = {text = "MIT"}
@@ -46,10 +46,10 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/reptiletech/simplesitesearch"
-Documentation = "https://github.com/reptiletech/simplesitesearch#readme"
-Repository = "https://github.com/reptiletech/simplesitesearch.git"
-"Bug Tracker" = "https://github.com/reptiletech/simplesitesearch/issues"
+Homepage = "https://github.com/FlavienLouis/simplesitesearch"
+Documentation = "https://github.com/FlavienLouis/simplesitesearch#readme"
+Repository = "https://github.com/FlavienLouis/simplesitesearch.git"
+"Bug Tracker" = "https://github.com/FlavienLouis/simplesitesearch/issues"
 
 [tool.setuptools]
 packages = ["simplesitesearch"]

{simplesitesearch-0.0.1.dev1 → simplesitesearch-0.0.3}/setup.cfg

@@ -1,12 +1,12 @@
 [metadata]
 name = simplesitesearch
-version = 0.0.1.dev1
+version = 0.0.2
 author = Reptile Tech
 author_email = flouis@reptile.tech
 description = Reptile Simple Site Search django app
 long_description = file: README.md
 long_description_content_type = text/markdown
-url = https://github.com/reptiletech/simplesitesearch
+url = https://github.com/FlavienLouis/simplesitesearch
 license = MIT
 license_files = LICENSE
 classifiers = 
@@ -33,10 +33,10 @@ classifiers =
 	Topic :: Software Development :: Libraries :: Python Modules
 keywords = django search cms django-cms
 project_urls = 
-	Homepage = https://github.com/yourusername/simplesitesearch
-	Documentation = https://github.com/yourusername/simplesitesearch#readme
-	Repository = https://github.com/yourusername/simplesitesearch.git
-	Bug Tracker = https://github.com/yourusername/simplesitesearch/issues
+	Homepage = https://github.com/FlavienLouis/simplesitesearch
+	Documentation = https://github.com/FlavienLouis/simplesitesearch#readme
+	Repository = https://github.com/FlavienLouis/simplesitesearch.git
+	Bug Tracker = https://github.com/FlavienLouis/simplesitesearch/issues
 
 [options]
 packages = find:

{simplesitesearch-0.0.1.dev1 → simplesitesearch-0.0.3}/setup.py

@@ -8,13 +8,13 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="simplesitesearch",
-    version="0.0.1.dev1",
+    version="0.0.3",
     author="Reptile Tech",
     author_email="flouis@reptile.tech",
     description="Reptile Simple Site Search django app",
     long_description=long_description,
     long_description_content_type="text/markdown",
-    url="https://github.com/reptiletech/simplesitesearch",
+    url="https://github.com/FlavienLouis/simplesitesearch",
     packages=find_packages(),
     classifiers=[
         "Development Status :: 5 - Production/Stable",

simplesitesearch-0.0.3/simplesitesearch/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.3"

{simplesitesearch-0.0.1.dev1 → simplesitesearch-0.0.3}/simplesitesearch/templates/simplesitesearch/search_results.html

@@ -48,7 +48,7 @@
     </section>
     {% if page_links|length > 1 %}
     <section class="section section--nopadding section--nomargin">
-        {% include "pagination.html" %}
+        {% include "simplesitesearch/pagination.html" %}
     </section>
     {% endif %}
 

simplesitesearch-0.0.3/simplesitesearch/utils.py

@@ -0,0 +1,153 @@
+"""
+Quality-of-life utilities for simplesitesearch.
+"""
+from urllib.parse import quote_plus, urlencode
+
+import requests
+
+from django.conf import settings
+from django.utils.translation import get_language
+
+
+def parse_comma_separated_tags(value):
+    """
+    Parse a comma-separated string of tags into a list of stripped tags.
+
+    Args:
+        value: String (e.g. from request.GET) or None.
+
+    Returns:
+        List of non-empty tag strings. Empty list if value is falsy.
+
+    Example:
+        >>> parse_comma_separated_tags("news, blog, tutorial")
+        ['news', 'blog', 'tutorial']
+        >>> parse_comma_separated_tags(None)
+        []
+    """
+    if not value or not value.strip():
+        return []
+    return [t.strip() for t in value.split(",") if t.strip()]
+
+
+def tags_to_query_value(tags):
+    """
+    Convert a list of tags to a comma-separated string for query params or API.
+
+    Args:
+        tags: Iterable of tag strings.
+
+    Returns:
+        Comma-separated string, or None if tags is empty.
+    """
+    if not tags:
+        return None
+    return ",".join(str(t).strip() for t in tags if str(t).strip())
+
+
+def build_search_query_string(term, page=1, tags=None):
+    """
+    Build the query string for search URLs (pagination, prev/next).
+
+    Args:
+        term: Search term.
+        page: Page number (optional).
+        tags: Optional list of tags or comma-separated string; as `tag` param.
+
+    Returns:
+        Query string with leading "?", e.g. "?q=foo&page=2&tag=a,b".
+    """
+    params = []
+    if term:
+        params.append(("q", term))
+    if page and page != 1:
+        params.append(("page", page))
+    parsed = (
+        parse_comma_separated_tags(tags) if isinstance(tags, str) else (tags or [])
+    )
+    tag_value = tags_to_query_value(parsed)
+    if tag_value:
+        params.append(("tag", tag_value))
+    if not params:
+        return ""
+    return "?" + urlencode(params)
+
+
+def normalize_search_term(term, max_words=10):
+    """
+    Limit search term to a maximum number of words (collapse whitespace).
+
+    Args:
+        term: Raw search string.
+        max_words: Maximum number of words to keep.
+
+    Returns:
+        Normalized string with at most max_words.
+    """
+    if not term or not term.strip():
+        return ""
+    return " ".join(term.split()[:max_words])
+
+
+def safe_int(value, default=None):
+    """
+    Safely convert a value to int.
+
+    Args:
+        value: Value to convert (e.g. from request.GET).
+        default: Value to return on failure (default None).
+
+    Returns:
+        int, or default on failure.
+    """
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def get_search_api_url(term, current_page, tags=None):
+    """
+    Build the full search API URL for the given term, page and optional tags.
+
+    Args:
+        term: Search term.
+        current_page: Page number (1-based).
+        tags: Optional list of tag strings; sent as comma-separated `tags` param.
+
+    Returns:
+        Full URL string for the search API.
+    """
+    base_url = settings.SITE_SEARCH_API_BASE_URL
+    site_key = settings.SITE_SEARCH_SITE_KEY
+    lang = get_language()
+    url = "%s%s?term=%s&lang=%s&page=%s" % (
+        base_url, site_key, quote_plus(term), lang, current_page
+    )
+    tag_value = tags_to_query_value(tags)
+    if tag_value:
+        url += "&tags=%s" % quote_plus(tag_value)
+    return url
+
+
+def get_search_results(term, current_page, tags=None):
+    """
+    Fetch search results from the API for the given term, page and optional tags.
+
+    Args:
+        term: Search term.
+        current_page: Page number (1-based).
+        tags: Optional list of tag strings (comma-separated in API).
+
+    Returns:
+        Dict with "total_hits" and "hits" (list). On request or JSON error,
+        returns {"total_hits": 0, "hits": []}.
+    """
+    api_url = get_search_api_url(term, current_page, tags=tags)
+    try:
+        response = requests.get(api_url, verify=False)
+        return response.json()
+    except Exception:
+        return {"total_hits": 0, "hits": []}

simplesitesearch-0.0.3/simplesitesearch/views.py

@@ -0,0 +1,111 @@
+from math import floor
+
+from django.views.generic import TemplateView
+
+from .utils import (
+    build_search_query_string,
+    get_search_results,
+    get_search_api_url,
+    normalize_search_term,
+    parse_comma_separated_tags,
+    safe_int,
+)
+
+
+def get_page_links(pages_count, current_page, term, tags=None):
+    page_links = []
+
+    if pages_count > 1:
+        if current_page == 1:
+            from_page = 1
+            to_page = from_page + 7
+        elif current_page == pages_count + 1:
+            from_page = to_page = current_page
+        else:
+            from_page = current_page - 4
+            to_page = current_page + 5
+
+        if from_page < 1:
+            from_page = 1
+        if to_page > pages_count:
+            to_page = pages_count
+
+        for page in range(from_page, to_page + 1):
+            page_link = build_search_query_string(term, page=page, tags=tags)
+            page_links.append({"page": page, "url": page_link})
+
+    return page_links
+
+
+def get_prev_next_links(next_page_number, prev_page_number, term, tags=None):
+    next_link = build_search_query_string(term, page=next_page_number, tags=tags) if next_page_number else None
+    prev_link = build_search_query_string(term, page=prev_page_number, tags=tags) if prev_page_number else None
+    return [prev_link, next_link]
+
+
+def get_prev_next_page_number(pages_count, current_page):
+    current_page = safe_int(current_page, 1)
+    pages_count = safe_int(pages_count, 0)
+
+    prev_page_number = current_page - 1 if current_page > 1 else None
+    next_page_number = current_page + 1 if current_page < pages_count else None
+    return [prev_page_number, next_page_number]
+
+
+def get_total_pages(total_hits):
+    pages_count = floor(total_hits / 10)
+    if total_hits % 10 > 0:
+        pages_count += 1
+    return pages_count
+
+
+def get_api_re_path(term, current_page, tags=None):
+    """Build the search API URL (delegates to utils for consistency)."""
+    return get_search_api_url(term, current_page, tags=tags)
+
+
+class SearchResult(TemplateView):
+
+    template_name = "simplesitesearch/search_results.html"
+
+    def get(self, request, *args, **kwargs):
+        context = self.get_context_data(**kwargs)
+
+        # get term and optional tag(s) from url params (tag can be comma-separated)
+        term = request.GET.get("q")
+        tag_param = request.GET.get("tag") or request.GET.get("tags")
+        tags_list = parse_comma_separated_tags(tag_param)
+        honeypot_message = request.GET.get("message")
+
+        current_page = safe_int(request.GET.get("page"), 1)
+
+        if term and not honeypot_message:
+            term = normalize_search_term(term)
+            response_data = get_search_results(
+                term, current_page, tags=tags_list or None
+            )
+            pages_count = get_total_pages(response_data["total_hits"])
+            prev_page_number, next_page_number = get_prev_next_page_number(pages_count, current_page)
+            prev_link, next_link = get_prev_next_links(
+                next_page_number, prev_page_number, term, tags=tags_list or None
+            )
+            page_links = get_page_links(pages_count, current_page, term, tags=tags_list or None)
+
+            context.update({
+                "pages_count": pages_count,
+                "current_page": current_page,
+                "results_count": response_data["total_hits"],
+                "prev_link": prev_link,
+                "next_link": next_link,
+                "page_links": page_links,
+                "results": response_data["hits"],
+            })
+        else:
+            context.update({"results": None})
+
+        context.update({
+            "query": term,
+            "tag": tag_param or "",
+        })
+
+        return self.render_to_response(context)

{simplesitesearch-0.0.1.dev1 → simplesitesearch-0.0.3/simplesitesearch.egg-info}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: simplesitesearch
-Version: 0.0.1.dev1
+Version: 0.0.3
 Summary: Reptile Simple Site Search django app
-Home-page: https://github.com/reptiletech/simplesitesearch
+Home-page: https://github.com/FlavienLouis/simplesitesearch
 Author: Reptile Tech
 Author-email: Reptile Tech <flouis@reptile.tech>
 Maintainer-email: Reptile Tech <flouis@reptile.tech>
 License: MIT
-Project-URL: Homepage, https://github.com/reptiletech/simplesitesearch
-Project-URL: Documentation, https://github.com/reptiletech/simplesitesearch#readme
-Project-URL: Repository, https://github.com/reptiletech/simplesitesearch.git
-Project-URL: Bug Tracker, https://github.com/reptiletech/simplesitesearch/issues
+Project-URL: Homepage, https://github.com/FlavienLouis/simplesitesearch
+Project-URL: Documentation, https://github.com/FlavienLouis/simplesitesearch#readme
+Project-URL: Repository, https://github.com/FlavienLouis/simplesitesearch.git
+Project-URL: Bug Tracker, https://github.com/FlavienLouis/simplesitesearch/issues
 Keywords: django,search,cms,django-cms
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
@@ -48,7 +48,6 @@ Dynamic: requires-python
 
 A simple Django app for site search functionality with Django CMS integration. This package provides a clean, easy-to-use search interface that can be integrated into Django CMS projects.
 
-> **Note**: This is a development version (0.0.1.dev1). The package is still under active development and may have breaking changes in future releases.
 
 ## Features
 
@@ -119,8 +118,8 @@ urlpatterns = [
 ### 2. Configure the Page
 
 1. Go to **Advanced settings** of the search page
-2. Set the **ID** to `'search'`
-3. Set **APPLICATION** to "Site Search"
+2. Set **APPLICATION** to "Site Search"
+3. Set the **Application ID** to `'site_search'` (this is the default value)
 4. Save the page
 5. Remove the page from the menu (uncheck "menu" in the table)
 6. Publish the page in all languages
@@ -147,10 +146,53 @@ The search results support pagination with a `page` parameter:
 /search/?q=your+search+term&page=2
 ```
 
+### Tags filter
+
+You can send a comma-separated list of tags to filter results. The `tag` (or `tags`) query parameter is forwarded to the API as `tags`:
+
+```
+/search/?q=your+search+term&tag=news,blog,tutorial
+```
+
+Pagination links preserve the tag filter.
+
 ### Honeypot Protection
 
 The search includes basic honeypot protection. If a `message` parameter is present, the search will not execute.
 
+## Utility functions (QOL)
+
+The app provides helpers in `simplesitesearch.utils` for use in views, management commands, or other code.
+
+| Function | Description |
+|----------|-------------|
+| **`get_search_results(term, current_page, tags=None)`** | Fetches search results from the API. Returns a dict with `total_hits` and `hits`. On error returns `{"total_hits": 0, "hits": []}`. |
+| **`get_search_api_url(term, current_page, tags=None)`** | Builds the full search API URL (uses Django settings and current language). |
+| **`build_search_query_string(term, page=1, tags=None)`** | Builds the query string for search URLs (e.g. pagination links), e.g. `?q=foo&page=2&tag=a,b`. |
+| **`parse_comma_separated_tags(value)`** | Parses a comma-separated string into a list of stripped tags; returns `[]` if value is falsy. |
+| **`normalize_search_term(term, max_words=10)`** | Trims and limits the search term to a maximum number of words. |
+| **`safe_int(value, default=None)`** | Safely converts a value to `int`; returns `default` on failure. |
+
+**Example — fetch results in code:**
+
+```python
+from simplesitesearch.utils import get_search_results
+
+data = get_search_results("django", current_page=1, tags=["cms", "tutorial"])
+total = data["total_hits"]
+results = data["hits"]
+```
+
+**Example — build search/pagination URLs:**
+
+```python
+from simplesitesearch.utils import build_search_query_string
+
+# Pagination link for page 2 with tag filter
+qs = build_search_query_string("my query", page=2, tags=["blog"])
+# => "?q=my+query&page=2&tag=blog"
+```
+
 ## Customization
 
 ### Templates
@@ -239,18 +281,29 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Support
 
-For support and questions, please open an issue on the [GitHub repository](https://github.com/yourusername/simplesitesearch/issues).
+For support and questions, please open an issue on the [GitHub repository](https://github.com/FlavienLouis/simplesitesearch/issues).
 
 ## Changelog
 
-### 0.0.1.dev1
-- Initial development release
-- Django CMS integration
-- Pagination support
-- Multi-language support
-- Basic search functionality
+### 0.0.3
+- Added `simplesitesearch.utils` QOL helpers: `get_search_results`, `get_search_api_url`, `build_search_query_string`, `parse_comma_separated_tags`, `normalize_search_term`, `safe_int`
+- Tag filter: `tag` (or `tags`) query parameter forwarded to API as comma-separated `tags`; pagination links preserve tags
+- README: Utility functions section and tags filter documentation
+
+### 0.0.2
+- Fixed template include path in search_results.html
+- Updated pagination template include to use full namespace: `simplesitesearch/pagination.html`
+- Improved template isolation and namespace consistency
+
+### 0.0.1
+- **First stable release**
+- Django CMS integration with apphook support
+- Pagination support for search results
+- Multi-language support with Django i18n
+- Basic search functionality with API integration
 - Template customization support
 - Support for Python 3.6+ and Django 2.2+
-- Updated API endpoint to use Reptile Search API
+- Reptile Search API integration
+- Comprehensive documentation and setup instructions
 
 

{simplesitesearch-0.0.1.dev1 → simplesitesearch-0.0.3}/simplesitesearch.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ setup.py
 simplesitesearch/__init__.py
 simplesitesearch/cms_apps.py
 simplesitesearch/urls.py
+simplesitesearch/utils.py
 simplesitesearch/views.py
 simplesitesearch.egg-info/PKG-INFO
 simplesitesearch.egg-info/SOURCES.txt

simplesitesearch-0.0.1.dev1/simplesitesearch/__init__.py

@@ -1,3 +0,0 @@
-__version__ = '0.0.1.dev1'
-
-

simplesitesearch-0.0.1.dev1/simplesitesearch/views.py

@@ -1,151 +0,0 @@
-from math import floor
-
-import requests
-from django.conf import settings
-from django.utils.translation import get_language
-from django.views.generic import TemplateView
-
-
-def get_page_links(pages_count, current_page, term):
-
-    page_links = []
-
-    if pages_count > 1:
-
-        if current_page == 1:
-            from_page = 1
-            to_page = from_page + 7
-        if current_page == pages_count + 1:
-            pass
-        else:
-            from_page = current_page - 4
-            to_page = current_page + 5
-
-        if from_page < 1:
-            from_page = 1
-
-        if to_page > pages_count:
-            to_page = pages_count
-
-        for page in range(from_page, to_page + 1):
-            page_link = "?q=%s&page=%s" % (term, page)
-
-            page_links.append({
-                'page': page,
-                'url': page_link
-            })
-
-    return page_links
-
-
-def get_prev_next_links(next_page_number, prev_page_number, term):
-    next_link = None
-    if next_page_number:
-        next_link = "?q=%s&page=%s" % (term, next_page_number)
-
-    prev_link = None
-    if prev_page_number:
-        prev_link = "?q=%s&page=%s" % (term, prev_page_number)
-
-    return [prev_link, next_link]
-
-
-def get_prev_next_page_number(pages_count, current_page):
-
-    current_page = int(current_page)
-    pages_count - int(pages_count)
-
-    if current_page > 1:
-        prev_page_number = current_page - 1
-    else:
-        prev_page_number = None
-
-    if current_page < pages_count:
-        next_page_number = current_page + 1
-    else:
-        next_page_number = None
-
-    return [prev_page_number, next_page_number]
-
-
-def get_total_pages(total_hits):
-    pages_count = floor(total_hits / 10)
-
-    modulo = total_hits % 10
-    if modulo > 0:
-        pages_count = pages_count + 1
-
-    return pages_count
-
-
-def get_api_re_path(term, current_page):
-    base_url = settings.SITE_SEARCH_API_BASE_URL
-    site_key = settings.SITE_SEARCH_SITE_KEY
-    lang = get_language()
-
-    return "%s%s?term=%s&lang=%s&page=%s" % (base_url, site_key, term, lang, current_page)
-
-
-class SearchResult(TemplateView):
-
-    template_name = "simplesitesearch/search_results.html"
-
-    def get(self, request, *args, **kwargs):
-        context = self.get_context_data(**kwargs)
-
-        # get Term from url params
-        term = request.GET.get('q', None)
-        honeypot_message = request.GET.get('message', None)
-
-        # get current page from url params
-        current_page = int(request.GET.get('page', 1))
-
-        if term and not honeypot_message:
-
-            term = ' '.join(term.split()[:10])
-
-            # get api URl depending on current page
-            api_url = get_api_re_path(term, current_page)
-
-            # get results from api
-            response = requests.get(api_url, verify=False)
-            # convert results to usable json
-            try:
-                response_data = response.json()
-            except:
-                response_data = {
-                    'total_hits': 0,
-                    'hits': []
-                }
-
-            # get pages count
-            pages_count = get_total_pages(response_data['total_hits'])
-
-            # get prev and next page numbers
-            prev_page_number, next_page_number = get_prev_next_page_number(pages_count, current_page)
-
-            # get prev and next btn links
-            prev_link, next_link = get_prev_next_links(next_page_number, prev_page_number, term)
-
-            # get pages links
-            page_links = get_page_links(pages_count, current_page, term)
-
-            context.update({
-                'pages_count': pages_count,
-                'current_page': current_page,
-                'results_count': response_data['total_hits'],
-                'prev_link': prev_link,
-                'next_link': next_link,
-                'page_links': page_links,
-                'results': response_data['hits']
-            })
-        else:
-            context.update({
-                'results': None
-            })
-
-        context.update({
-            'query': term
-        })
-
-        return self.render_to_response(context)