Low-level API’s

This package provides internal API’s, so projects can use those to query the tree or even prefill it.


When using the Python shell, make sure the activate a language first.

from django.conf import settings
from django.utils.translations import activate


Query pages

When you query the general Page or UrlNode model, the pages are returned in their specific type.

>>> from fluent_pages.models import Page
>>> Page.objects.published()
<Queryset [<FluentPage: Homepage>, <BlogPage: Blog>, <FluentPage: Contact>]>

To filter the results, use one of these methods:

  • parent_site() - select a different site.
  • get_for_path() - find the node for a path.
  • best_match_for_path() - find the node starting with


Finding pages by ID

When FLUENT_PAGES_KEY_CHOICES is set, specific pages can be fetched using Page.objects.get_for_key().

Creating pages

The tree can hold different page types. Always create the specific type needed, for example:

from django.contrib.auth import get_user_model
from fluent_pages.pagetypes.flatpage.models import FlatPage

User = get_user_model()
admin = User.objects.get(active=True, username='admin')

page = FlatPage.objects.create(
    # Standard fields
    title="Flat test",

    # Type specific fields:
    content="This page is created via the API!"

Now the page will appear too:

>>> from fluent_pages.models import Page
>>> Page.objects.published()
<Queryset [<FluentPage: Homepage>, <BlogPage: Blog>, <FluentPage: Contact>, <FlatPage: Flat test>]>

The same approach can be used for other page types. Review the model API to see which fields can be used:

  • FlatPage (provide content and optionally, template_name).
  • RedirectNode (provide new_url and optionally, redirect_type).
  • TextFile (provide content and optionally, content_type).

Pages with visible HTML content also inherit from HtmlPage, which makes the meta_keywords, meta_description and optional meta_title available too.

Fluent content pages

A similar way can be used for pages with block content. This uses the django-fluent-contents and django-parler API’s too:

from django.contrib.auth import get_user_model
from fluent_pages.pagetypes.fluentpage.models import FluentPage
from fluent_contents.plugins.textitem.models import TextItem
from fluent_contents.plugins.oembeditem.models import OEmbedItem

User = get_user_model()
admin = User.objects.get(active=True, username='admin')

page = FluentPage.objects.language('en').create(
    # Standard fields
    title="Fluent test",

# Create the placeholder
placeholder = page.create_placeholder('main')

# Create the content items
TextItem.objects.create_for_placeholder(placeholder, text="Hello, World!")
OEmbedItem.objects.create_for_placeholder(placeholder, embed_url="https://vimeo.com/channels/952478/135740366")

# Adding another language:
TextItem.objects.create_for_placeholder(placeholder, language_code="nl", text="Hello, World NL!")
OEmbedItem.objects.create_for_placeholder(placeholder, language_code="nl", embed_url="https://vimeo.com/channels/952478/135740366")

The .language('en') is not required, as the current language is selected. However, it’s good to be explicit in case your project is multilingual. When no language code is given to create_for_placeholder(), it uses the current language that the parent object (i.e. the page) has.