Article with APPhooks and CMS Plugins
=====================================

Build on the basic article model by adding CMS plugins and an app hook for frontend display.

This tutorial builds on the :doc:`basic_setup` tutorial.

Overview
--------

We'll extend the article model created earlier by:

- Creating CMS plugins to display articles
- Adding an app hook for article URLs
- Creating templates to render articles on the frontend

Step 1: Create CMS Plugins
---------------------------

Add ``my_content/cms_plugins.py``:

.. code-block:: python

    from cms.plugin_base import CMSPluginBase
    from cms.plugin_pool import plugin_pool
    from django.utils.translation import gettext_lazy as _
    from django.utils.translation import get_language
    from .models import ArticleContent

    @plugin_pool.register_plugin
    class ArticleTeaserPlugin(CMSPluginBase):
        name = _("Article Teaser")
        render_template = "my_content/article_teaser.html"

        def render(self, context, instance, placeholder):
            articles = ArticleContent.objects.filter(
                language=get_language()
            )[:3]
            return {
                **context,
                "articles": articles,
            }

    @plugin_pool.register_plugin
    class ArticleListPlugin(CMSPluginBase):
        name = _("Article List")
        render_template = "my_content/article_list.html"

        def render(self, context, instance, placeholder):
            articles = ArticleContent.objects.filter(
                language=get_language()
            ).order_by("-id")
            return {
                **context,
                "articles": articles,
            }

Step 2: Create Templates
------------------------

Create the template directory:

.. code-block:: bash

    mkdir -p my_content/templates/my_content

Create ``my_content/templates/my_content/article_teaser.html``:

.. code-block:: django

    <section class="article-teaser">
        <h2>Latest Articles</h2>
        <div class="articles-grid">
            {% for article in articles %}
                <article class="article-card">
                    <h3><a href="{{ article.get_absolute_url }}">{{ article.title }}</a></h3>
                    <p>{{ article.body|truncatewords:30 }}</p>
                    <a href="{{ article.get_absolute_url }}" class="btn">Read more</a>
                </article>
            {% empty %}
                <p>No articles yet.</p>
            {% endfor %}
        </div>
    </section>

Create ``my_content/templates/my_content/article_list.html``:

.. code-block:: django

    <section class="article-list">
        <h2>All Articles</h2>
        <ul class="articles">
            {% for article in articles %}
                <li>
                    <a href="{{ article.get_absolute_url }}">{{ article.title }}</a>
                </li>
            {% empty %}
                <p>No articles available.</p>
            {% endfor %}
        </ul>
    </section>

Create the detail template. By convention it is named
``<app_label>/<modelname>_detail.html``, and the content object is available
under its model name (``articlecontent``) in both the app-hook view and the
frontend editor — so create
``my_content/templates/my_content/articlecontent_detail.html``:

.. code-block:: django

    {% extends "base.html" %}
    {% load cms_tags %}

    {% block content %}
        {% cms_edit_on %}
        <article class="article">
            <h1>{{ articlecontent.title }}</h1>
            <p class="meta">Published on {{ articlecontent.id }}</p>
            <div class="content">
                {{ articlecontent.body|safe }}
            </div>
        </article>
        {% cms_edit_off %}
    {% endblock %}

See :doc:`../how-to/apphooks` for the full template contract (why
``articlecontent`` rather than ``object``).

Step 3: Enable App Hook
-----------------------

To enable URL routing for articles, add ``apphook = True`` to ``ArticleContent.CMSConfig``:

Update ``my_content/models.py``:

.. code-block:: python

    class ArticleContent(AbstractCustomContent):
        """The editable article content."""
        article = models.ForeignKey(Article, on_delete=models.CASCADE)
        title = models.CharField(max_length=200)
        slug = models.SlugField()
        body = models.TextField()

        class CMSConfig:
            # Make editable in the frontend and versionable
            enable_frontend_editing = True
            enable_versioning = True
            # Enable URL routing via app hook
            apphook = True

        def __str__(self):
            return self.title

That's all you need! The generic detail view will automatically handle URL routing.

Step 4: Add the App Hook to a CMS Page
---------------------------------------

In the Django CMS admin:

1. Create a new Django CMS page (or edit an existing one)
2. Go to the **Advanced** tab
3. Under **Application**, select your app hook ("My Content")
4. Save the page

The generic detail view automatically handles displaying articles by slug.

Done!
-----

Your article model now has:

✅ CMS plugins for teaser and list display
✅ An app hook for frontend URLs
✅ Proper templates
✅ Frontend display of articles

Next Steps:

- :doc:`model_with_m2m` - Add authors to articles using M2M relations
- :doc:`../how-to/m2m_relations` - Learn more about generic M2M relations
- :doc:`../explanation/architecture` - Understand the grouper/content pattern