invenio-banners 5.2.1__py2.py3-none-any.whl

invenio_banners/resources/errors.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2023 CERN.
+# Copyright (C) 2024-2025 Graz University of Technology.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Errors."""
+
+import marshmallow as ma
+from flask_resources import HTTPJSONException, create_error_handler
+from invenio_records_resources.errors import validation_error_to_list_errors
+
+
+class BannerNotExistsError(Exception):
+    """Banner not found exception."""
+
+    def __init__(self, banner_id):
+        """Constructor."""
+        self.banner_id = banner_id
+
+    @property
+    def description(self):
+        """Exception's description."""
+        return f"Banner with id {self.banner_id} is not found."
+
+
+class HTTPJSONValidationException(HTTPJSONException):
+    """HTTP exception serializing to JSON and reflecting Marshmallow errors."""
+
+    description = "A validation error occurred."
+
+    def __init__(self, exception):
+        """Constructor."""
+        super().__init__(code=400, errors=validation_error_to_list_errors(exception))
+
+
+class ErrorHandlersMixin:
+    """Mixin to define error handlers."""
+
+    error_handlers = {
+        BannerNotExistsError: create_error_handler(
+            lambda e: HTTPJSONException(
+                code=404,
+                description=e.description,
+            )
+        ),
+        ma.ValidationError: create_error_handler(
+            lambda e: HTTPJSONValidationException(e)
+        ),
+    }

invenio_banners/resources/resource.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022-2023 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Invenio Banners module to create REST APIs."""
+
+from flask import g
+from flask_resources import Resource, resource_requestctx, response_handler, route
+from invenio_records_resources.resources.records.resource import (
+    request_data,
+    request_headers,
+    request_search_args,
+    request_view_args,
+)
+
+from .errors import ErrorHandlersMixin
+
+
+#
+# Resource
+#
+class BannerResource(ErrorHandlersMixin, Resource):
+    """Banner resource."""
+
+    def __init__(self, config, service):
+        """Constructor."""
+        super(BannerResource, self).__init__(config)
+        self.service = service
+
+    def create_url_rules(self):
+        """Create the URL rules for the record resource."""
+        routes = self.config.routes
+        return [
+            route("POST", routes["list"], self.create),
+            route("GET", routes["item"], self.read),
+            route("GET", routes["list"], self.search),
+            route("DELETE", routes["item"], self.delete),
+            route("PUT", routes["item"], self.update),
+        ]
+
+    @request_view_args
+    @request_data
+    @response_handler()
+    def update(self):
+        """Update a banner."""
+        banner = self.service.update(
+            id=resource_requestctx.view_args["banner_id"],
+            identity=g.identity,
+            data=resource_requestctx.data,
+        )
+
+        # disable expired banners
+        self.service.disable_expired(identity=g.identity)
+
+        return banner.to_dict(), 200
+
+    @request_view_args
+    @response_handler()
+    def read(self):
+        """Read a banner."""
+        banner_id = resource_requestctx.view_args["banner_id"]
+        banner = self.service.read(
+            id=banner_id,
+            identity=g.identity,
+        )
+
+        return banner.to_dict(), 200
+
+    @request_search_args
+    @response_handler(many=True)
+    def search(self):
+        """Perform a search over the banners."""
+        banners = self.service.search(
+            identity=g.identity,
+            params=resource_requestctx.args,
+        )
+
+        return banners.to_dict(), 200
+
+    @request_data
+    @response_handler()
+    def create(self):
+        """Create a banner."""
+        banner = self.service.create(
+            g.identity,
+            resource_requestctx.data or {},
+        )
+
+        # disable expired banners
+        self.service.disable_expired(identity=g.identity)
+
+        return banner.to_dict(), 201
+
+    @request_headers
+    @request_view_args
+    def delete(self):
+        """Delete a banner."""
+        banner_id = resource_requestctx.view_args["banner_id"]
+        banner = self.service.delete(
+            id=banner_id,
+            identity=g.identity,
+        )
+
+        return banner.to_dict(), 204

invenio_banners/services/__init__.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Banners Service API."""
+
+from .config import BannerServiceConfig, BannersLink
+from .results import BannerItem, BannerList
+from .service import BannerService
+
+__all__ = (
+    "BannerService",
+    "BannerServiceConfig",
+    "BannerList",
+    "BannerItem",
+    "BannersLink",
+)

invenio_banners/services/config.py

@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022-2023 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Banners Service configuration."""
+
+from invenio_i18n import gettext as _
+from invenio_records_resources.services import Link, RecordServiceConfig
+from invenio_records_resources.services.records.links import pagination_links
+from sqlalchemy import asc, desc
+
+from ..records.models import BannerModel
+from .permissions import BannersPermissionPolicy
+from .results import BannerItem, BannerList
+from .schemas import BannerSchema
+
+
+class BannersLink(Link):
+    """Link variables setter for Banner links."""
+
+    @staticmethod
+    def vars(banner, vars):
+        """Variables for the URI template."""
+        vars.update({"id": banner.id})
+
+
+class SearchOptions:
+    """Search options."""
+
+    sort_direction_default = "asc"
+    sort_direction_options = {
+        "asc": dict(
+            title=_("Ascending"),
+            fn=asc,
+        ),
+        "desc": dict(
+            title=_("Descending"),
+            fn=desc,
+        ),
+    }
+
+    sort_default = "start_datetime"
+    sort_options = {
+        "url_path": dict(
+            title=_("Url path"),
+            fields=["url_path"],
+        ),
+        "start_datetime": dict(
+            title=_("Start time"),
+            fields=["start_datetime"],
+        ),
+        "end_datetime": dict(
+            title=_("End time"),
+            fields=["end_datetime"],
+        ),
+        "active": dict(
+            title=_("Active"),
+            fields=["active"],
+        ),
+    }
+    pagination_options = {
+        "default_results_per_page": 25,
+    }
+
+
+class BannerServiceConfig(RecordServiceConfig):
+    """Service factory configuration."""
+
+    result_item_cls = BannerItem
+    result_list_cls = BannerList
+    permission_policy_cls = BannersPermissionPolicy
+    schema = BannerSchema
+
+    # Search configuration
+    search = SearchOptions
+
+    # links configuration
+    links_item = {
+        "self": BannersLink("{+api}/banners/{id}"),
+    }
+    links_search = pagination_links("{+api}/banners{?args*}")
+    record_cls = BannerModel

invenio_banners/services/permissions.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Banners permissions."""
+
+from invenio_administration.generators import Administration
+from invenio_records_permissions import BasePermissionPolicy
+from invenio_records_permissions.generators import AnyUser, SystemProcess
+
+
+class BannersPermissionPolicy(BasePermissionPolicy):
+    """Permission policy for banners."""
+
+    can_create = [Administration(), SystemProcess()]
+    can_read = [AnyUser(), SystemProcess()]
+    can_search = [AnyUser(), SystemProcess()]
+    can_update = [Administration(), SystemProcess()]
+    can_delete = [Administration(), SystemProcess()]
+    can_disable = [Administration(), SystemProcess()]

invenio_banners/services/results.py

@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022-2023 CERN.
+# Copyright (C) 2024 Graz University of Technology.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Service results."""
+
+from invenio_records_resources.services.records.results import RecordItem, RecordList
+
+try:
+    # flask_sqlalchemy<3.0.0
+    from flask_sqlalchemy import Pagination
+except ImportError:
+    # flask_sqlalchemy>=3.0.0
+    from flask_sqlalchemy.pagination import Pagination
+
+
+class BannerItem(RecordItem):
+    """Single banner result."""
+
+    def __init__(
+        self,
+        service,
+        identity,
+        banner,
+        links_tpl=None,
+        errors=None,
+        schema=None,
+    ):
+        """Constructor."""
+        super().__init__(service, identity, banner, errors, links_tpl, schema)
+
+    @property
+    def data(self):
+        """Property to get the banner."""
+        if self._data:
+            return self._data
+
+        self._data = self._schema.dump(
+            self._obj,
+            context={
+                "identity": self._identity,
+                "record": self._record,
+            },
+        )
+
+        if self._links_tpl:
+            self._data["links"] = self.links
+
+        return self._data
+
+
+class BannerList(RecordList):
+    """List of banner results."""
+
+    def __init__(
+        self,
+        service,
+        identity,
+        banners,
+        params=None,
+        links_tpl=None,
+        links_item_tpl=None,
+        schema=None,
+    ):
+        """Constructor."""
+        super().__init__(
+            service, identity, banners, params, links_tpl, links_item_tpl, schema
+        )
+
+    @property
+    def hits(self):
+        """Iterator over the hits."""
+        for record in self.banners_result():
+            # Project the record
+            projection = self._schema.dump(
+                record,
+                context=dict(
+                    identity=self._identity,
+                    record=record,
+                ),
+            )
+
+            if self._links_item_tpl:
+                projection["links"] = self._links_item_tpl.expand(
+                    self._identity, record
+                )
+
+            yield projection
+
+    def to_dict(self):
+        """Return result as a dictionary."""
+        res = {
+            "hits": {
+                "hits": list(self.hits),
+                "total": self.total,
+            }
+        }
+
+        if self._params:
+            if self._links_tpl:
+                res["links"] = self._links_tpl.expand(self._identity, self.pagination)
+
+        return res
+
+    @property
+    def total(self):
+        """Get total number of banners."""
+        return (
+            self._results.total
+            if isinstance(self._results, Pagination)
+            else len(self._results)
+        )
+
+    def banners_result(self):
+        """Get iterable banners list."""
+        return (
+            self._results.items
+            if isinstance(self._results, Pagination)
+            else self._results
+        )

invenio_banners/services/schemas.py

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022-2023 CERN.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Banners schema."""
+
+from datetime import datetime, timezone
+
+from invenio_records_resources.services.records.schema import BaseRecordSchema
+from marshmallow import fields, pre_load
+from marshmallow_utils.fields import SanitizedHTML, TZDateTime
+
+
+class BannerSchema(BaseRecordSchema):
+    """Schema for banners."""
+
+    message = SanitizedHTML(required=True)
+    url_path = fields.String(allow_none=True)
+    category = fields.String(required=True, metadata={"default": "info"})
+    start_datetime = fields.DateTime(
+        required=True,
+        metadata={"default": datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")},
+    )
+    end_datetime = fields.DateTime(allow_none=True)
+    active = fields.Boolean(required=True, metadata={"default": True})
+    created = TZDateTime(timezone=timezone.utc, format="iso", dump_only=True)
+    updated = TZDateTime(timezone=timezone.utc, format="iso", dump_only=True)
+
+    @pre_load
+    def change_none_to_string(self, data, **kwargs):
+        """Fix for empty strings not in line with allow_none=True."""
+        for field in data:
+            if field == "end_datetime" or field == "category":
+                if data[field] == "":
+                    data[field] = None
+        return data

invenio_banners/services/service.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2022-2025 CERN.
+# Copyright (C) 2024-2025 Graz University of Technology.
+#
+# Invenio-Banners is free software; you can redistribute it and/or modify it
+# under the terms of the MIT License; see LICENSE file for more details.
+
+"""Banner Service API."""
+
+
+import arrow
+from invenio_db.uow import unit_of_work
+from invenio_records_resources.services import RecordService
+from invenio_records_resources.services.base import LinksTemplate
+from invenio_records_resources.services.base.utils import map_search_params
+from sqlalchemy import and_, func, literal, or_
+
+from ..records.models import BannerModel
+from ..utils import strtobool
+
+
+class BannerService(RecordService):
+    """Banner Service."""
+
+    def read(self, identity, id):
+        """Retrieve a banner."""
+        self.require_permission(identity, "read")
+
+        banner = self.record_cls.get(id)
+
+        return self.result_item(
+            self,
+            identity,
+            banner,
+            links_tpl=self.links_item_tpl,
+        )
+
+    def search(self, identity, params):
+        """Search for banners with multiple filter options.
+
+        Supports filtering by:
+        - active: boolean filter
+        - url_path: prefix matching (empty paths match all, specific paths match as prefixes)
+        - q: text or date search across multiple fields
+
+        active and url_path filters are combined with AND logic, while OR is used while combining them with the q filters.
+        """
+        self.require_permission(identity, "search")
+
+        active_filter_param = params.pop("active", None)
+        url_path_filter_param = params.pop("url_path", None)
+        search_params = map_search_params(self.config.search, params)
+
+        and_filters = []
+        if active_filter_param is not None:
+            and_filters.append(BannerModel.active.is_(active_filter_param))
+
+        if url_path_filter_param is not None:
+            and_filters.append(
+                or_(
+                    BannerModel.url_path == "",
+                    literal(url_path_filter_param).like(BannerModel.url_path + "%"),
+                )
+            )
+
+        filters = [and_(*and_filters)] if and_filters else []
+        query_param = search_params["q"]
+        if query_param:
+            filters.extend(
+                [
+                    BannerModel.url_path.ilike(f"%{query_param}%"),
+                    BannerModel.message.ilike(f"%{query_param}%"),
+                    BannerModel.category.ilike(f"%{query_param}%"),
+                ]
+            )
+
+            datetime_value = self._validate_datetime(query_param)
+            if datetime_value is not None:
+                filters.extend(
+                    [
+                        func.date(BannerModel.start_datetime) == datetime_value,
+                        func.date(BannerModel.end_datetime) == datetime_value,
+                        func.date(BannerModel.created) == datetime_value,
+                        func.date(BannerModel.updated) == datetime_value,
+                    ]
+                )
+
+        banners = self.record_cls.search(search_params, filters)
+
+        return self.result_list(
+            self,
+            identity,
+            banners,
+            params=search_params,
+            links_tpl=LinksTemplate(self.config.links_search, context={"args": params}),
+            links_item_tpl=self.links_item_tpl,
+        )
+
+    @unit_of_work()
+    def create(self, identity, data, raise_errors=True, uow=None):
+        """Create a banner."""
+        self.require_permission(identity, "create")
+
+        # validate data
+        valid_data, errors = self.schema.load(
+            data,
+            context={"identity": identity},
+            raise_errors=raise_errors,
+        )
+
+        # create the banner with the specified data
+        banner = self.record_cls.create(valid_data)
+
+        return self.result_item(
+            self, identity, banner, links_tpl=self.links_item_tpl, errors=errors
+        )
+
+    @unit_of_work()
+    def delete(self, identity, id, uow=None):
+        """Delete a banner from database."""
+        self.require_permission(identity, "delete")
+
+        banner = self.record_cls.get(id)
+        self.record_cls.delete(banner)
+
+        return self.result_item(self, identity, banner, links_tpl=self.links_item_tpl)
+
+    @unit_of_work()
+    def update(self, identity, id, data, uow=None):
+        """Update a banner."""
+        self.require_permission(identity, "update")
+
+        banner = self.record_cls.get(id)
+
+        # validate data
+        valid_data, errors = self.schema.load(
+            data,
+            context={"identity": identity},
+            raise_errors=True,
+        )
+
+        self.record_cls.update(valid_data, id)
+
+        return self.result_item(
+            self,
+            identity,
+            banner,
+            links_tpl=self.links_item_tpl,
+        )
+
+    @unit_of_work()
+    def disable_expired(self, identity, uow=None):
+        """Disable expired banners."""
+        self.require_permission(identity, "disable")
+        self.record_cls.disable_expired()
+
+    def _validate_bool(self, value):
+        try:
+            bool_value = strtobool(value)
+        except ValueError:
+            return None
+        return bool(bool_value)
+
+    def _validate_datetime(self, value):
+        try:
+            date_value = arrow.get(value).date()
+        except ValueError:
+            return None
+        return date_value

invenio_banners/templates/semantic-ui/invenio_banners/banner.html

@@ -0,0 +1,26 @@
+{# -*- coding: utf-8 -*-
+
+  This file is part of Invenio.
+  Copyright (C) 2020-2023 CERN.
+
+  Invenio-Banners is free software; you can redistribute it and/or modify it
+  under the terms of the MIT License; see LICENSE file for more details.
+#}
+
+{%- macro banner(ui_classes) -%}
+  {%- block banner %}
+    {%- set banners = get_active_banners() %}
+    {% if not ui_classes %}
+      {% set ui_classes = "top attached m-0" %}
+    {% endif %}
+    {% if banners %}
+      {% for banner in banners %}
+        <div class="ui {{ banner.category|style_banner_category }} message {{ ui_classes }} inv-banner" id="banner-{{ banner.id }}">
+          <div class="ui container">
+              {{ banner.message|safe }}
+          </div>
+        </div>
+      {% endfor %}
+    {% endif %}
+  {%- endblock banner %}
+{%- endmacro %}