V3

Events

This module includes functions related to the event API endpoint.

integreat_cms.api.v3.events.events(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

List all events of the region and transform result into JSON

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The slug of the requested region

  • language_slug (str) – The slug of the requested language

Returns:

JSON object according to APIv3 events endpoint definition

Return type:

JsonResponse

integreat_cms.api.v3.events.transform_available_languages(event_translation: EventTranslation, recurrence_date: date) → dict[str, dict[str, str | None]][source]

Function to create a JSON object of all available translations of an event translation. This is similar to event_translation.available_languages_dict embeds the recurrence date in the translation slug.

Parameters:

  • event_translation (EventTranslation) – The event translation object which should be converted

  • recurrence_date (date) – The date of this event translation

Returns:

data necessary for API

Return type:

dict[str, dict[str, str | None]]

integreat_cms.api.v3.events.transform_event(event: Event, custom_date: date | None = None) → dict[str, Any][source]

Function to create a JSON from a single event object.

Parameters:

  • event (Event) – The event which should be converted

  • custom_date (date | None) – The date overwrite of the event

Returns:

data necessary for API

Return type:

dict[str, Any]

integreat_cms.api.v3.events.transform_event_recurrences(event_translation: EventTranslation, poi_translation: POITranslation | None, today: date) → Iterator[dict[str, Any]][source]

Yield all future recurrences of the event.

Parameters:

  • event_translation (EventTranslation) – The event translation object which should be converted

  • poi_translation (POITranslation | None) – The poi translation object which is associated to this event

  • today (date) – The first date at which event may be yielded

Returns:

An iterator over all future recurrences up to settings.API_EVENTS_MAX_TIME_SPAN_DAYS

Return type:

Iterator[dict[str, Any]]

integreat_cms.api.v3.events.transform_event_translation(event_translation: EventTranslation, poi_translation: POITranslation | None, recurrence_date: date | None = None) → dict[str, Any][source]

Function to create a JSON from a single event_translation object.

Parameters:

  • event_translation (EventTranslation) – The event translation object which should be converted

  • poi_translation (POITranslation | None) – The poi translation object which is associated to this event

  • recurrence_date (date | None) – The recurrence date for the event

Returns:

data necessary for API

Return type:

dict[str, Any]

Imprint

This module includes functions related to the imprint API endpoint.

integreat_cms.api.v3.imprint.imprint(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

Get imprint for language and return JSON object to client. If no imprint translation is available in the selected language, try to return the translation in the region default language.

Parameters:

  • request (HttpRequest) – Django request

  • region_slug (str) – slug of a region

  • language_slug (str) – language slug

Returns:

JSON object according to APIv3 imprint endpoint definition

Return type:

JsonResponse

integreat_cms.api.v3.imprint.transform_imprint(imprint_translation: ImprintPageTranslation) → dict[str, Any][source]

Function to create a JSON from a single imprint_translation object.

Parameters:

imprint_translation (ImprintPageTranslation) – single page translation object

Returns:

data necessary for API

Return type:

dict[str, Any]

Languages

This module includes functions related to the languages API endpoint.

integreat_cms.api.v3.languages.languages(request: HttpRequest, region_slug: str) → JsonResponse[source]

Function to add all languages related to a region to a JSON.

Parameters:

  • request (HttpRequest) – Django request

  • region_slug (str) – slug of a region

Returns:

JSON object according to APIv3 languages endpoint definition

Return type:

JsonResponse

integreat_cms.api.v3.languages.transform_language(language: Language) → dict[str, Any][source]

Function to create a JSON from a single language object.

Parameters:

language (Language) – The language object which should be converted

Returns:

data necessary for API

Return type:

dict[str, Any]

Location Categories

This module includes the POI category API endpoint.

integreat_cms.api.v3.location_categories.location_categories(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

Function to return all POI categories as JSON.

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The slug of the requested region

  • language_slug (str) – The slug of the requested language

Returns:

JSON object of all POI categories

Return type:

JsonResponse

integreat_cms.api.v3.location_categories.transform_location_category(location_category: POICategory, language_slug: str) → dict[str, Any] | None[source]

Function to create a JSON from a single location category object.

Parameters:

  • location_category (POICategory) – The location category object which should be converted

  • language_slug (str) – The slug of the requested language

Returns:

Data necessary for API

Return type:

dict[str, Any] | None

Locations

This module includes functions related to the locations/POIs API endpoint.

integreat_cms.api.v3.locations.locations(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

List all POIs of the region and transform result into JSON

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The slug of the requested region

  • language_slug (str) – The slug of the requested language

Returns:

JSON object according to APIv3 locations endpoint definition

Return type:

JsonResponse

integreat_cms.api.v3.locations.transform_poi(poi: POI | None) → dict[str, Any][source]

Function to create a JSON from a single poi object.

Parameters:

poi (POI | None) – The poi object which should be converted

Returns:

data necessary for API

Return type:

dict[str, Any]

integreat_cms.api.v3.locations.transform_poi_translation(poi_translation: POITranslation) → dict[str, Any][source]

Function to create a JSON from a single poi_translation object.

Parameters:

poi_translation (POITranslation) – The poi translation object which should be converted

Returns:

data necessary for API

Return type:

dict[str, Any]

Offers

This module includes functions related to the offers API endpoint.

integreat_cms.api.v3.offers.get_post_data(offer: OfferTemplate, region: Region) → dict[str, str] | None[source]

In case the url expects additional post data, it is stored inside the post_data-dict. Some offers depend on the location which is realized by adding the postal code of the current region to the request. If the offer template indicates that the postal code should be used as GET-parameter, the class attribute use_postal_code has to be set to postal_code.POST (see postal_code) and then the key search-plz is automatically added to the post data. In case a third party service needs a different format, it has to be hard-coded here or we need other changes to the offer model.

Parameters:

  • offer (OfferTemplate) – one offer (formerly extra)

  • region (Region) – current region object

Returns:

The post data of the offer’s url

Return type:

dict[str, str] | None

integreat_cms.api.v3.offers.get_url(offer: OfferTemplate, region: Region) → str[source]

The offer should inherit the slug property from its template. This is the url to an API endpoint in most cases. Some offers depend on the location which is realized by adding the postal code of the current region to the request. If the offer template indicates that the postal code should be used as GET-parameter, the class attribute use_postal_code has to be set to postal_code.GET (see postal_code) and the url has to end with the name of the required parameter-name, e.g. https://example.com/api?location=.

Parameters:

  • offer (OfferTemplate) – one offer (formerly extra)

  • region (Region) – current region object

Returns:

The url of an offer

Return type:

str

integreat_cms.api.v3.offers.offers(request: HttpRequest, region_slug: str, language_slug: str | None = None) → JsonResponse[source]

Function to iterate through all offers related to a region and adds them to a JSON.

Parameters:

  • request (HttpRequest) – Django request

  • region_slug (str) – slug of a region

  • language_slug (str | None) – language slug

Returns:

JSON object according to APIv3 offers endpoint definition

Return type:

JsonResponse

integreat_cms.api.v3.offers.transform_offer(offer: OfferTemplate, region: Region) → dict[str, Any][source]

Function to create a JSON from a single offer Object.

Parameters:

  • offer (OfferTemplate) – one offer (formerly extra)

  • region (Region) – current region object

Returns:

data necessary for API

Return type:

dict[str, Any]

Pages

This module includes functions related to the pages API endpoint.

integreat_cms.api.v3.pages.children(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

Retrieves all children for a single page

Parameters:

  • request (HttpRequest) – The request that has been sent to the Django server

  • region_slug (str) – Slug defining the region

  • language_slug (str) – Code to identify the desired language

Raises:

Http404 – HTTP status 404 if the request is malformed or no page with the given id or url exists.

Returns:

JSON with the requested page descendants

Return type:

JsonResponse

integreat_cms.api.v3.pages.get_public_ancestor_translations(current_page: Page, language_slug: str) → list[dict[str, Any]][source]

Retrieves all ancestors (parent and all nodes up to the root node) of a page. If any ancestor is archived or has a missing translation, a 404 is raised.

Parameters:

  • current_page (Page) – the page that needs a list of its ancestor translations

  • language_slug (str) – Code to identify the desired language

Raises:

Http404 – HTTP status 404 if the request is malformed or no page with the given id or url exists.

Returns:

JSON with the requested page ancestors

Return type:

list[dict[str, Any]]

integreat_cms.api.v3.pages.get_single_page(request: HttpRequest, language_slug: str) → Page[source]

Helper function returning the desired page or a 404 if the requested page does not exist or is archived.

Parameters:

  • request (HttpRequest) – The request that has been sent to the Django server

  • language_slug (str) – Code to identify the desired language

Raises:

  • MultipleObjectsReturned – If the given url cannot be resolved unambiguously

  • Http404 – HTTP status 404 if the request is malformed or no page with the given id or url exists.

  • RuntimeError – If neither the id nor the url parameter is given

Returns:

the requested page

Return type:

Page

integreat_cms.api.v3.pages.pages(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

Function to iterate through all non-archived pages of a region and return them as JSON.

Parameters:

  • request (HttpRequest) – Django request

  • region_slug (str) – slug of a region

  • language_slug (str) – language slug

Returns:

JSON object according to APIv3 pages endpoint definition

Return type:

JsonResponse

integreat_cms.api.v3.pages.parents(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

Retrieves all ancestors (parent and all nodes up to the root node) of a page. If any ancestor is archived, an 404 is raised.

Parameters:

  • request (HttpRequest) – The request that has been sent to the Django server

  • region_slug (str) – Slug defining the region

  • language_slug (str) – Code to identify the desired language

Raises:

Http404 – HTTP status 404 if the request is malformed or no page with the given id or url exists.

Returns:

JSON with the requested page ancestors

Return type:

JsonResponse

integreat_cms.api.v3.pages.push_page_translation_content(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

Retrieves all ancestors (parent and all nodes up to the root node) of a page

Parameters:

  • request (HttpRequest) – The request that has been sent to the Django server

  • region_slug (str) – Slug defining the region

  • language_slug (str) – Code to identify the desired language

Raises:

Http404 – HTTP status 404 if the request is malformed or no page with the given id or url exists.

Returns:

JSON with the requested page ancestors

Return type:

JsonResponse

integreat_cms.api.v3.pages.single_page(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

View function returning the desired page as a JSON or a 404 if the requested page does not exist.

Parameters:

  • request (HttpRequest) – The request that has been sent to the Django server

  • region_slug (str) – Slug defining the region

  • language_slug (str) – Code to identify the desired language

Raises:

Http404 – HTTP status 404 if the request is malformed or no page with the given id or url exists.

Returns:

JSON with the requested page and a HTTP status 200.

Return type:

JsonResponse

integreat_cms.api.v3.pages.transform_page(page_translation: PageTranslation) → dict[str, Any][source]

Function to create a dict from a single page_translation Object.

Parameters:

page_translation (PageTranslation) – single page translation object

Raises:

Http404 – HTTP status 404 if a parent is archived

Returns:

data necessary for API

Return type:

dict[str, Any]

PDF Export

View to return PDF document containing the requested pages. Single pages may be requested by url parameter, if no parameter is included all pages related to the current region and language will be returned.

integreat_cms.api.v3.pdf_export.pdf_export(request: HttpRequest, region_slug: str, language_slug: str) → HttpResponseRedirect[source]

View function that either returns the requested page specified by the url parameter or returns all pages of current region and language as PDF document by forwarding the request to generate_pdf()

Parameters:

  • request (HttpRequest) – request that was sent to the server

  • region_slug (str) – Slug defining the region

  • language_slug (str) – current language slug

Raises:

Http404 – HTTP status 404 if the requested page translation cannot be found.

Returns:

The redirect to the generated PDF document

Return type:

HttpResponseRedirect

Push Notifications

This module includes functions related to the push notification that are sent via firebase.

integreat_cms.api.v3.push_notifications.sent_push_notifications(request: HttpRequest, region_slug: str, language_slug: str) → JsonResponse[source]

Function to iterate through all sent push notifications related to a region and adds them to a JSON.

Parameters:

  • request (HttpRequest) – Django request

  • region_slug (str) – slug of a region

  • language_slug (str) – language slug

Returns:

JSON object according to APIv3 push notifications definition

Return type:

JsonResponse

integreat_cms.api.v3.push_notifications.transform_notification(pnt: PushNotificationTranslation) → dict[str, Any][source]

Function to create a JSON from a single push notification translation Object.

Parameters:

pnt (PushNotificationTranslation) – A push notification translation

Returns:

data necessary for API

Return type:

dict[str, Any]

Regions

This module includes functions related to the regions API endpoint.

integreat_cms.api.v3.regions.region_by_slug(request: HttpRequest, region_slug: str) → JsonResponse[source]

Retrieve a single region and transform result into JSON

Returns:

JSON object according to APIv3 live regions endpoint definition

Parameters:

  • request (HttpRequest)

  • region_slug (str)

Return type:

JsonResponse

integreat_cms.api.v3.regions.regions(_: HttpRequest) → JsonResponse[source]

List all regions that are not archived and transform result into JSON

Returns:

JSON object according to APIv3 regions endpoint definition

Parameters:

_ (HttpRequest)

Return type:

JsonResponse

integreat_cms.api.v3.regions.transform_region(region: Region) → dict[str, Any][source]

Function to create a JSON from a single region object, including information if region is live/active.

Parameters:

region (Region) – The region object which should be converted

Returns:

data necessary for API

Return type:

dict[str, Any]

Social Media Headers

This module contains views of the social media headers API endpoint.

integreat_cms.api.v3.social_media_headers.event_social_media_headers(request: HttpRequest, region_slug: str, language_slug: str, slug: str) → HttpResponse[source]

Tries rendering the social_media headers for an event page in a specified region and language.

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The region slug for the region, which the event belongs to

  • language_slug (str) – The language slug of the language, which the event belongs to

  • slug (str) – The event slug

Returns:

HTML social meta headers required by social media platforms if the event page exists

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.get_excerpt(content: str) → str[source]

Correctly escapes, truncates and normalizes the content of the page to display in a search result

Parameters:

content (str) – The content of the page

Returns:

A page excerpt containing the first 100 characters of “raw” content

Return type:

str

integreat_cms.api.v3.social_media_headers.get_region_title(region: Region, page_title: str) → str[source]

Constructs in a unified format the page title of a page in a region.

Parameters:

  • region (Region) – The region where the page resides in

  • page_title (str) – The title of the page

Returns:

The constructed page title

Return type:

str

integreat_cms.api.v3.social_media_headers.location_social_media_headers(request: HttpRequest, region_slug: str, language_slug: str, slug: str) → HttpResponse[source]

Tries rendering the social media headers for a location page in a specified region and language.

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The region slug for the region, which the location belongs to

  • language_slug (str) – The language slug of the language, which the location belongs to

  • slug (str) – The location slug

Returns:

HTML social meta headers required by social media platforms if the location page exists

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.news_social_media_headers(request: HttpRequest, region_slug: str, language_slug: str, slug: str) → HttpResponse[source]

Tries rendering the social media headers for a news page in a specified region and language.

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The region slug for the region, which the push notification belongs to

  • language_slug (str) – The language slug of the language, which the push notification belongs to

  • slug (str) – The news specific slug of the news route e.g. /local/<slug>

Returns:

HTML social meta headers required by social media platforms if the news page exists

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.page_social_media_headers(request: HttpRequest, region_slug: str, language_slug: str, path: str) → HttpResponse[source]

Tries rendering the social media headers for a page in a specified region and language.

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The region slug for the region, which the page belongs to

  • language_slug (str) – The language slug of the language, which the page belongs to

  • path (str) – The page path (url_infix + slug)

Returns:

HTML social meta headers required by social media platforms if the page exists

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.partial_html_response(function: Callable) → Callable[source]

This decorator can be used to catch Http404 exceptions and convert them to a partial HTML responses needed for the webapp’s server side includes.

Parameters:

function (Callable) – The view function which should always return a partial HTML response

Returns:

The decorated function

Return type:

Callable

integreat_cms.api.v3.social_media_headers.region_social_media_headers(request: HttpRequest, region_slug: str, language_slug: str | None = None) → HttpResponse[source]

Generally renders the social media headers for a root region page. This is also used as a fallback for any routes in a region, where no content can be found.

Parameters:

  • request (HttpRequest) – The current request

  • region_slug (str) – The region the request refers to

  • language_slug (str | None) – The current language

Returns:

HTML social meta headers required by social media platforms

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.render_error_headers(request: HttpRequest, error: str) → HttpResponse[source]

Renders the partial HTML response for the webapp’s server side include

Parameters:

  • request (HttpRequest) – The current request

  • error (str) – The error message

Returns:

Partial HTML response for the webapp’s server side include

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.render_social_media_headers(request: HttpRequest, title: str, language_code: str, excerpt: str | None, url: str) → HttpResponse[source]

Renders the social media headers with the specified arguments

Parameters:

  • request (HttpRequest) – The current request

  • title (str) – The title of the page in the social media headers

  • language_code (str) – The language of the requested resource

  • excerpt (str | None) – An optional excerpt describing the content of the page. If omitted google, will automatically crawl an excerpt

  • url (str) – The url the headers belong to

Returns:

HTML social meta headers required by social media platforms

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.root_social_media_headers(request: HttpRequest, language_slug: str = 'de') → HttpResponse[source]

Renders the social media headers for a root page

Parameters:

  • request (HttpRequest) – The current request

  • language_slug (str) – The language slug of the page or the default language

Returns:

HTML social meta headers required by social media platforms

Return type:

HttpResponse

integreat_cms.api.v3.social_media_headers.site_url(request: HttpRequest) → str[source]

Extracts the path from the request and constructs the original url.

Parameters:

request (HttpRequest) – The current request

Returns:

The url for the page which the social media headers have been requested for

Return type:

str