Town6: Adds a topics API endpoint

Also includes a small extension to the existing news/events endpoint

TYPE: Feature
LINK: OGC-2058

Author: Daverball

Diff for: docs/api/org/README.md

@@ -4,6 +4,7 @@ The headless Org API offers the following views:
 
 - [Events](#events-view)
 - [News](#news-view)
+- [Topics](#topics-view)
 
 We implement the called Collection+JSON standard established by Mike
 Amundsen. For details please refer to [media types - collection & json](http://amundsen.com/media-types/collection/format/)
@@ -122,13 +123,17 @@ A collection+JSON of items including paging
 
 ## News View
 
-The news view provides information about all people in relation with agencies
-within the organisation. Each person offers several data fields like
-first and last name, academic title, function within the organisation,
-contact information and more. Additionally, the people api provides links to
-a picture, website and memberships to agencies memberships if given.
+The news view provides information about all the news.
 
-`curl https://[base_url]/people`
+`curl https://[base_url]/news`
+
+## Topics View
+
+The topics view provides information about all the topics, including
+their hierarchical relationship via a `parent` link. Links to children
+are implicit through their `parent` link.
+
+`curl https://[base_url]/topics`
 
 
 ## Authorization

Diff for: src/onegov/org/models/page.py

@@ -351,6 +351,46 @@ def all_tags(self) -> list[str]:
         return sorted(all_hashtags)
 
 
+class TopicCollection(Pagination[Topic], AdjacencyListCollection[Topic]):
+    """
+    Use it like this:
+
+        from onegov.page import TopicCollection
+        topics = TopicCollection(session)
+    """
+
+    __listclass__ = Topic
+
+    def __init__(
+        self,
+        session: Session,
+        page: int = 0,
+    ):
+        self.session = session
+        self.page = page
+
+    def subset(self) -> Query[Topic]:
+        topics = self.session.query(Topic)
+        topics = topics.filter(
+            News.publication_started == True,
+            News.publication_ended == False
+        )
+        topics = topics.order_by(desc(Topic.published_or_created))
+        topics = topics.options(undefer('created'))
+        topics = topics.options(undefer('content'))
+        return topics
+
+    @property
+    def page_index(self) -> int:
+        return self.page
+
+    def page_by_index(self, index: int) -> Self:
+        return self.__class__(
+            self.session,
+            page=index
+        )
+
+
 class NewsCollection(Pagination[News], AdjacencyListCollection[News]):
     """
     Use it like this:

Diff for: src/onegov/town6/api.py

@@ -1,17 +1,16 @@
 from __future__ import annotations
 
 from onegov.event.collections import OccurrenceCollection
-from onegov.api import ApiEndpoint
+from onegov.api.models import ApiEndpoint, ApiEndpointItem
 from onegov.gis import Coordinates
 
 
 from typing import Any
 from typing import TYPE_CHECKING
 
-from onegov.org.models.page import NewsCollection
+from onegov.org.models.page import News, NewsCollection, Topic, TopicCollection
 
 if TYPE_CHECKING:
-    from onegov.org.models.page import News
     from onegov.town6.app import TownApp
     from onegov.event.models import Occurrence
     from onegov.core.orm.mixins import ContentMixin
@@ -36,9 +35,7 @@ def get_modified_iso_format(item: TimestampMixin) -> str:
     return item.last_change.isoformat()
 
 
-class EventApiEndpoint(
-    ApiEndpoint['Occurrence'],
-):
+class EventApiEndpoint(ApiEndpoint['Occurrence']):
     app: TownApp
     endpoint = 'events'
 
@@ -73,14 +70,13 @@ def item_data(self, item: Occurrence) -> dict[str, Any]:
 
     def item_links(self, item: Occurrence) -> dict[str, Any]:
         return {
+            'html': item,
             'image': item.event.image,
             'pfd': item.event.pdf
         }
 
 
-class NewsApiEndpoint(
-    ApiEndpoint['News'],
-):
+class NewsApiEndpoint(ApiEndpoint[News]):
     app: TownApp
     endpoint = 'news'
     filters = set()
@@ -109,6 +105,7 @@ def item_data(self, item: News) -> dict[str, Any]:
             'title': item.title,
             'lead': item.lead,
             'text': item.text,
+            'hashtags': item.hashtags,
             'publication_start': publication_start,
             'publication_end': publication_end,
             'created': item.created.isoformat(),
@@ -117,5 +114,51 @@ def item_data(self, item: News) -> dict[str, Any]:
 
     def item_links(self, item: News) -> dict[str, Any]:
         return {
-            'image': item.page_image,
+            'html': item,
+            'image': item.page_image or None,
+        }
+
+
+class TopicApiEndpoint(ApiEndpoint[Topic]):
+    app: TownApp
+    endpoint = 'topics'
+    filters = set()
+
+    @property
+    def collection(self) -> Any:
+        result = TopicCollection(
+            self.session,
+            page=self.page or 0
+        )
+        result.batch_size = 25
+        return result
+
+    def item_data(self, item: Topic) -> dict[str, Any]:
+        if item.publication_start:
+            publication_start = item.publication_start.isoformat()
+        else:
+            publication_start = None
+
+        if item.publication_end:
+            publication_end = item.publication_end.isoformat()
+        else:
+            publication_end = None
+
+        return {
+            'title': item.title,
+            'lead': item.lead,
+            'text': item.text,
+            'publication_start': publication_start,
+            'publication_end': publication_end,
+            'created': item.created.isoformat(),
+            'modified': get_modified_iso_format(item),
+        }
+
+    def item_links(self, item: Topic) -> dict[str, Any]:
+        return {
+            'html': item,
+            'image': item.page_image or None,
+            'parent': ApiEndpointItem(
+                self.app, self.endpoint, str(item.parent_id)
+            ) if item.parent_id is not None else None,
         }

Diff for: src/onegov/town6/app.py

@@ -12,7 +12,8 @@
 from onegov.foundation6.integration import FoundationApp
 from onegov.org.app import OrgApp
 from onegov.org.app import get_i18n_localedirs as get_org_i18n_localedirs
-from onegov.town6.api import EventApiEndpoint, NewsApiEndpoint
+from onegov.town6.api import (
+    EventApiEndpoint, NewsApiEndpoint, TopicApiEndpoint)
 from onegov.town6.custom import get_global_tools
 from onegov.town6.initial_content import create_new_organisation
 from onegov.town6.theme import TownTheme
@@ -197,7 +198,8 @@ def get_public_ticket_messages() -> tuple[str, ...]:
 def get_api_endpoints() -> list[type[ApiEndpoint[Any]]]:
     return [
         EventApiEndpoint,
-        NewsApiEndpoint
+        NewsApiEndpoint,
+        TopicApiEndpoint,
     ]