0
# Django CMS Blog
1

2
A comprehensive blog application for django CMS providing multilingual blog functionality with advanced content management features. The package enables creation of complex blog websites with placeholder content editing, multilingual support, social media integration, and extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: djangocms-blog
7
- **Language**: Python
8
- **Installation**: `pip install djangocms-blog`
9

10
## Core Imports
11

12
```python
13
from djangocms_blog.models import Post, BlogCategory
14
from djangocms_blog.views import PostDetailView, PostListView
15
from djangocms_blog.admin import PostAdmin, BlogCategoryAdmin
16
from djangocms_blog.cms_apps import BlogApp
17
from djangocms_blog.cms_appconfig import BlogConfig
18
```
19

20
## Basic Usage
21

22
```python
23
# Basic post creation and retrieval
24
from djangocms_blog.models import Post, BlogCategory
25
from django.contrib.auth import get_user_model
26
from django.utils import timezone
27

28
User = get_user_model()
29

30
# Create a blog category
31
category = BlogCategory.objects.create()
32
category.set_current_language('en')
33
category.name = 'Technology'
34
category.slug = 'technology'
35
category.save()
36

37
# Create a blog post  
38
post = Post.objects.create(
39
    author=User.objects.get(pk=1),
40
    app_config=BlogConfig.objects.first(),
41
    date_published=timezone.now(),
42
    enable_comments=True
43
)
44
post.set_current_language('en')
45
post.title = 'My First Blog Post'
46
post.slug = 'my-first-blog-post'
47
post.abstract = 'This is the post abstract'
48
post.meta_description = 'SEO description for the post'
49
post.save()
50

51
# Add the post to category
52
post.categories.add(category)
53

54
# Query published posts
55
published_posts = Post.objects.published()
56
recent_posts = Post.objects.published()[:5]
57
```
58

59
## Architecture
60

61
Django CMS Blog integrates deeply with django CMS's architecture and extends it with blog-specific functionality:
62

63
- **Models**: Core data models (Post, BlogCategory) with multilingual support via django-parler
64
- **Views**: Class-based views for post display, lists, archives, and filtering
65
- **CMS Integration**: Full CMS app, plugins, menus, wizards, and toolbar integration
66
- **Admin Interface**: Advanced admin with placeholder editing and frontend editing support
67
- **Configuration**: Per-apphook configuration system for multi-site blog setups
68
- **Template System**: Flexible template organization with custom template tags
69
- **SEO Features**: Built-in meta tag support, sitemaps, and RSS feeds
70

71
The package follows django CMS patterns for extensibility and provides hooks for customization across all components.
72

73
## Capabilities
74

75
### Core Models and Data Management
76

77
Primary data models for blog posts and categories with full multilingual support, meta tag integration, and relationship management.
78

79
```python { .api }
80
class Post(KnockerModel, BlogMetaMixin, TranslatableModel):
81
    """Main blog post model with multilingual and meta support."""
82
    
83
    # Key properties
84
    is_published: bool
85
    guid: str
86
    date: datetime
87
    liveblog_group: str
88
    
89
    # Key methods
90
    def get_absolute_url(self, lang: Optional[str] = None) -> str: ...
91
    def get_title(self) -> str: ...
92
    def get_description(self) -> str: ...
93
    def get_keywords(self) -> List[str]: ...
94
    def get_tags(self) -> str: ...
95
    def get_author(self) -> Optional[AbstractUser]: ...
96
    
97
    # Manager methods
98
    objects: GenericDateTaggedManager
99
    # Post.objects.published(current_site=True)
100
    # Post.objects.archived(current_site=True)
101
    # Post.objects.tagged(other_model=None, queryset=None)
102
    
103
class BlogCategory(BlogMetaMixin, TranslatableModel):
104
    """Blog category model with multilingual support."""
105
    
106
    # Key properties
107
    linked_posts: QuerySet
108
    count: int
109
    count_all_sites: int
110
    
111
    # Key methods
112
    def get_absolute_url(self, lang: Optional[str] = None) -> str: ...
113
    def descendants(self) -> List['BlogCategory']: ...
114
    def get_title(self) -> str: ...
115
    def get_description(self) -> str: ...
116
```
117

118
[Models and Data Management](./models.md)
119

120
### View Classes and URL Handling
121

122
Complete set of class-based views for displaying blog content including detail views, list views, archive views, and filtered views.
123

124
```python { .api }
125
class PostDetailView(TranslatableSlugMixin, BaseBlogView, DetailView): ...
126
class PostListView(BaseBlogListView, ListView): ...
127
class PostArchiveView(BaseBlogListView, ListView): ...
128
class TaggedListView(BaseBlogListView, ListView): ...
129
class AuthorEntriesView(BaseBlogListView, ListView): ...
130
class CategoryEntriesView(BaseBlogListView, ListView): ...
131
```
132

133
[Views and URL Handling](./views.md)
134

135
### CMS Integration and Plugins
136

137
Full django CMS integration including CMS app configuration, plugins for embedding blog content, wizards for content creation, and toolbar integration.
138

139
```python { .api }
140
class BlogApp(AutoCMSAppMixin, CMSConfigApp): ...
141
class BlogLatestEntriesPlugin(BlogPlugin): ...
142
class BlogFeaturedPostsPlugin(BlogPlugin): ...
143
class BlogAuthorPostsPlugin(BlogPlugin): ...
144
class PostWizard(Wizard): ...
145
```
146

147
[CMS Integration](./cms-integration.md)
148

149
### Admin Interface and Forms
150

151
Advanced admin interface with placeholder editing, frontend editing, and comprehensive form handling for posts, categories, and configuration.
152

153
```python { .api }
154
class PostAdmin(PlaceholderAdminMixin, FrontendEditableAdminMixin, ModelAppHookConfig, TranslatableAdmin): ...
155
class BlogCategoryAdmin(ModelAppHookConfig, TranslatableAdmin): ...
156
class PostAdminForm(PostAdminFormBase): ...
157
```
158

159
[Admin and Forms](./admin-forms.md)
160

161
### Configuration and Settings
162

163
Per-apphook configuration system enabling multiple blog instances with different settings, plus global settings management.
164

165
```python { .api }
166
class BlogConfig(TranslatableModel, AppHookConfig): ...
167
class BlogConfigForm(AppDataForm): ...
168
def get_setting(name: str): ...
169
```
170

171
[Configuration](./configuration.md)
172

173
### Template Tags and Utilities
174

175
Template tags for extracting media content from posts, utility functions, and helper classes for template integration.
176

177
```python { .api }
178
@register.simple_tag(name="media_plugins", takes_context=True)
179
def media_plugins(context: Dict[str, Any], post: Post) -> List[CMSPlugin]: ...
180

181
@register.simple_tag(name="media_images", takes_context=True)  
182
def media_images(context: Dict[str, Any], post: Post, main: bool = True) -> List[str]: ...
183

184
def slugify(base: str) -> str: ...
185

186
# Manager utilities
187
class GenericDateTaggedManager(TaggedFilterItem, AppHookConfigTranslatableManager):
188
    def published(self, current_site: bool = True) -> QuerySet: ...
189
    def archived(self, current_site: bool = True) -> QuerySet: ...
190
    def tagged(self, other_model: Optional[models.Model] = None, queryset: Optional[QuerySet] = None) -> QuerySet: ...
191
```
192

193
[Template Tags and Utilities](./templates-utilities.md)
194

195
### RSS Feeds and Sitemaps
196

197
Automated RSS feed generation and sitemap integration for SEO optimization.
198

199
```python { .api }
200
class LatestEntriesFeed(Feed):
201
    """RSS feed for latest blog entries."""
202
    def items(self, obj: BlogConfig) -> QuerySet: ...
203
    def item_title(self, item: Post) -> str: ...
204
    def item_description(self, item: Post) -> str: ...
205
    def item_link(self, item: Post) -> str: ...
206

207
class TagFeed(LatestEntriesFeed):
208
    """RSS feed for posts filtered by specific tag."""
209
    def get_object(self, request: HttpRequest, tag: str) -> Dict[str, Any]: ...
210
    def items(self, obj: Dict[str, Any]) -> QuerySet: ...
211

212
class FBInstantArticles(LatestEntriesFeed):
213
    """Facebook Instant Articles feed with custom XML format."""
214
    content_type: str = 'application/rss+xml; charset=utf-8'
215

216
class BlogSitemap(Sitemap):
217
    """Sitemap generator for blog posts."""
218
    def items(self) -> List[Post]: ...
219
    def location(self, obj: Post) -> str: ...
220
    def lastmod(self, obj: Post) -> datetime: ...
221
```
222

223
[Feeds and Sitemaps](./feeds-sitemaps.md)
224

225
## Types
226

227
```python { .api }
228
# Common type aliases and imports
229
from typing import Optional, List, Dict, Any, Union
230
from datetime import datetime
231
from django.db import models
232
from django.db.models import QuerySet
233
from django.contrib.auth.models import AbstractUser
234
from django.contrib.syndication.views import Feed
235
from django.contrib.sitemaps import Sitemap
236
from django.http import HttpRequest, HttpResponse
237
from django.forms import ModelForm
238
from django.template import Library, register
239
from cms.models import PlaceholderField, CMSPlugin
240
from cms.toolbar_base import CMSToolbar
241
from cms.wizards.wizard_base import Wizard
242
from parler.models import TranslatableModel
243
from djangocms_blog.models import Post, BlogCategory
244
from djangocms_blog.cms_appconfig import BlogConfig
245
from djangocms_blog.managers import GenericDateTaggedManager, TaggedFilterItem
246
```