0
# Utilities and Helpers
1
2
Django CMS provides extensive utility functions for internationalization, configuration management, URL handling, and CMS-specific operations that support the framework's core functionality.
3
4
## Capabilities
5
6
### Language and Internationalization
7
8
Comprehensive utilities for managing multi-language sites with fallback support and site-aware configuration.
9
10
```python { .api }
11
def get_current_language():
12
"""
13
Get the currently active language code.
14
15
Returns:
16
str: Current language code (e.g., 'en', 'de', 'fr')
17
"""
18
19
def get_default_language(site_id=None):
20
"""
21
Get the default language for a site.
22
23
Args:
24
site_id (int, optional): Site ID, uses current site if None
25
26
Returns:
27
str: Default language code
28
"""
29
30
def get_language_list(site_id=None):
31
"""
32
Get list of available language codes for site.
33
34
Args:
35
site_id (int, optional): Site ID, uses current site if None
36
37
Returns:
38
list: Available language codes
39
"""
40
41
def get_language_from_request(request, current_page=None):
42
"""
43
Determine language from request context.
44
45
Args:
46
request (HttpRequest): Current request
47
current_page (Page, optional): Current CMS page
48
49
Returns:
50
str: Resolved language code
51
"""
52
53
def force_language(new_lang):
54
"""
55
Context manager to temporarily change active language.
56
57
Args:
58
new_lang (str): Language code to activate
59
60
Returns:
61
ContextManager: Language context manager
62
"""
63
64
def get_fallback_languages(language, site_id=None):
65
"""
66
Get language fallback chain for given language.
67
68
Args:
69
language (str): Primary language code
70
site_id (int, optional): Site ID
71
72
Returns:
73
list: Ordered list of fallback language codes
74
"""
75
76
def get_languages(site_id=None):
77
"""
78
Get complete language configuration for site.
79
80
Args:
81
site_id (int, optional): Site ID
82
83
Returns:
84
dict: Language configuration with names and settings
85
"""
86
87
def get_public_languages(site_id=None):
88
"""
89
Get only publicly visible languages.
90
91
Args:
92
site_id (int, optional): Site ID
93
94
Returns:
95
list: Public language codes
96
"""
97
98
def hide_untranslated(language, site_id=None):
99
"""
100
Check if untranslated content should be hidden.
101
102
Args:
103
language (str): Language code
104
site_id (int, optional): Site ID
105
106
Returns:
107
bool: Whether to hide untranslated content
108
"""
109
```
110
111
### Page and Request Utilities
112
113
Functions for resolving pages from requests and managing page-related operations.
114
115
```python { .api }
116
def get_page_from_request(request, use_path=None, clean_path=None):
117
"""
118
Resolve CMS page from current request.
119
120
Args:
121
request (HttpRequest): Current request
122
use_path (str, optional): Specific path to resolve
123
clean_path (bool, optional): Whether to clean URL path
124
125
Returns:
126
Page: Resolved page or None
127
"""
128
129
def get_available_slug(site, path, language, suffix=None):
130
"""
131
Generate unique page slug for given parameters.
132
133
Args:
134
site (Site): Target site
135
path (str): Desired URL path
136
language (str): Language code
137
suffix (str, optional): Slug suffix
138
139
Returns:
140
str: Available unique slug
141
"""
142
143
def get_clean_username(user):
144
"""
145
Get safely formatted username for storage.
146
147
Args:
148
user (User): User instance
149
150
Returns:
151
str: Clean username string
152
"""
153
154
def get_page_queryset(site=None, draft=True, published=True):
155
"""
156
Get filtered page queryset.
157
158
Args:
159
site (Site, optional): Site filter
160
draft (bool): Include draft pages
161
published (bool): Include published pages
162
163
Returns:
164
QuerySet: Filtered page queryset
165
"""
166
```
167
168
### Configuration Management
169
170
Utilities for accessing CMS settings and configuration with sensible defaults.
171
172
```python { .api }
173
def get_cms_setting(name):
174
"""
175
Get CMS setting value with framework defaults.
176
177
Args:
178
name (str): Setting name (without CMS_ prefix)
179
180
Returns:
181
Any: Setting value or default
182
"""
183
184
def get_templates():
185
"""
186
Get available CMS template configurations.
187
188
Returns:
189
list: Template configuration tuples (identifier, name)
190
"""
191
192
def get_cache_durations():
193
"""
194
Get cache duration settings for CMS components.
195
196
Returns:
197
dict: Cache duration configuration
198
"""
199
200
def get_site_id(site):
201
"""
202
Normalize site ID from various input types.
203
204
Args:
205
site (Site|int|str): Site object, ID, or identifier
206
207
Returns:
208
int: Site ID
209
"""
210
```
211
212
### URL and Request Processing
213
214
Functions for URL manipulation, request analysis, and admin URL generation.
215
216
```python { .api }
217
def admin_reverse(viewname, args=None, kwargs=None, current_app=None):
218
"""
219
Generate admin URLs with proper namespace handling.
220
221
Args:
222
viewname (str): Admin view name
223
args (tuple, optional): URL arguments
224
kwargs (dict, optional): URL keyword arguments
225
current_app (str, optional): Current app namespace
226
227
Returns:
228
str: Generated admin URL
229
"""
230
231
def add_url_parameters(url, *args, **params):
232
"""
233
Add query parameters to existing URL.
234
235
Args:
236
url (str): Base URL
237
*args: Positional parameters
238
**params: Query parameters as key-value pairs
239
240
Returns:
241
str: URL with added parameters
242
"""
243
244
def levelize_path(path):
245
"""
246
Split URL path into hierarchical components.
247
248
Args:
249
path (str): URL path to process
250
251
Returns:
252
list: Path components as hierarchy levels
253
"""
254
255
def urljoin(*segments):
256
"""
257
Join URL segments with proper slash handling.
258
259
Args:
260
*segments: URL segments to join
261
262
Returns:
263
str: Joined URL with correct slashes
264
"""
265
266
def is_media_request(request):
267
"""
268
Check if request is for media files.
269
270
Args:
271
request (HttpRequest): Request to check
272
273
Returns:
274
bool: Whether request targets media
275
"""
276
277
def static_with_version(path):
278
"""
279
Add CMS version parameter to static file paths.
280
281
Args:
282
path (str): Static file path
283
284
Returns:
285
str: Versioned static file URL
286
"""
287
```
288
289
### Plugin and Placeholder Utilities
290
291
Functions for managing plugins, placeholders, and content rendering.
292
293
```python { .api }
294
def copy_plugins_to_placeholder(plugins, placeholder, language, root_plugin=None):
295
"""
296
Copy plugin tree to target placeholder.
297
298
Args:
299
plugins (QuerySet): Source plugins to copy
300
placeholder (Placeholder): Target placeholder
301
language (str): Language code
302
root_plugin (CMSPlugin, optional): Root plugin for nesting
303
304
Returns:
305
list: Created plugin instances
306
"""
307
308
def get_bound_plugins(plugins):
309
"""
310
Get plugin instances with their implementation classes.
311
312
Args:
313
plugins (QuerySet): Plugin queryset
314
315
Returns:
316
list: Plugin instances with bound classes
317
"""
318
319
def has_reached_plugin_limit(placeholder, plugin_type, language, template=None):
320
"""
321
Check if plugin limit reached for placeholder.
322
323
Args:
324
placeholder (Placeholder): Target placeholder
325
plugin_type (str): Plugin type identifier
326
language (str): Language code
327
template (str, optional): Template identifier
328
329
Returns:
330
bool: Whether limit is reached
331
"""
332
333
def get_placeholder_conf(setting, placeholder, template=None, default=None):
334
"""
335
Get placeholder configuration setting.
336
337
Args:
338
setting (str): Configuration setting name
339
placeholder (str): Placeholder slot name
340
template (str, optional): Template identifier
341
default (Any, optional): Default value
342
343
Returns:
344
Any: Configuration value or default
345
"""
346
347
def get_placeholders(template):
348
"""
349
Extract placeholder names from template.
350
351
Args:
352
template (str): Template path or content
353
354
Returns:
355
list: Placeholder slot names found in template
356
"""
357
```
358
359
### Validation and Setup
360
361
Utilities for validating CMS configuration and setting up the environment.
362
363
```python { .api }
364
def validate_dependencies():
365
"""
366
Check for required package dependencies.
367
368
Raises:
369
ImportError: If required packages are missing
370
"""
371
372
def validate_settings():
373
"""
374
Validate Django and CMS configuration.
375
376
Raises:
377
ImproperlyConfigured: If settings are invalid
378
"""
379
380
def setup():
381
"""
382
Run all CMS validation and setup checks.
383
384
Performs dependency checking, settings validation,
385
and environment preparation.
386
"""
387
388
def setup_cms_apps():
389
"""
390
Configure CMS-enabled applications.
391
392
Initializes app hooks and CMS integration
393
for registered applications.
394
"""
395
```
396
397
## Usage Examples
398
399
### Language Management
400
401
```python
402
from cms.utils import get_current_language, get_fallback_languages, force_language
403
from cms.utils.i18n import get_language_from_request
404
405
# Get current language context
406
current_lang = get_current_language()
407
print(f"Current language: {current_lang}")
408
409
# Get language from request
410
def my_view(request):
411
page_language = get_language_from_request(request)
412
fallbacks = get_fallback_languages(page_language)
413
414
# Try to get content in preferred language, fall back if needed
415
content = get_content_in_language(page_language)
416
if not content:
417
for fallback_lang in fallbacks:
418
content = get_content_in_language(fallback_lang)
419
if content:
420
break
421
422
return render(request, 'page.html', {'content': content})
423
424
# Temporary language switching
425
with force_language('de'):
426
# Operations here run in German context
427
german_title = get_localized_title()
428
german_url = reverse('page_detail', args=[page.id])
429
```
430
431
### Page Resolution and URLs
432
433
```python
434
from cms.utils.page import get_page_from_request, get_available_slug
435
from cms.utils.urlutils import admin_reverse, add_url_parameters
436
437
def custom_middleware(get_response):
438
def middleware(request):
439
# Resolve current CMS page
440
current_page = get_page_from_request(request)
441
request.current_page = current_page
442
443
response = get_response(request)
444
return response
445
return middleware
446
447
# Generate unique slugs
448
from django.contrib.sites.models import Site
449
450
site = Site.objects.get_current()
451
base_slug = "my-new-page"
452
unique_slug = get_available_slug(site, base_slug, "en")
453
454
# Admin URL generation
455
edit_url = admin_reverse('cms_page_change', args=[page.id])
456
add_url = admin_reverse('cms_page_add')
457
458
# Add parameters to URLs
459
search_url = add_url_parameters(
460
'/search/',
461
q='django cms',
462
category='documentation'
463
)
464
```
465
466
### Configuration and Settings
467
468
```python
469
from cms.utils.conf import get_cms_setting, get_templates
470
471
# Get CMS settings
472
templates = get_cms_setting('TEMPLATES')
473
languages = get_cms_setting('LANGUAGES')
474
cache_duration = get_cms_setting('CACHE_DURATIONS')
475
476
# Template configuration
477
available_templates = get_templates()
478
for template_id, template_name in available_templates:
479
print(f"Template: {template_name} ({template_id})")
480
481
# Custom settings with defaults
482
def get_my_cms_setting(name, default=None):
483
"""Get custom CMS setting with fallback."""
484
try:
485
return get_cms_setting(name)
486
except KeyError:
487
return default
488
489
# Site-specific configuration
490
from cms.utils import get_current_site
491
492
current_site = get_current_site()
493
site_languages = get_cms_setting('LANGUAGES').get(current_site.id, {})
494
```
495
496
### Plugin and Content Management
497
498
```python
499
from cms.utils.plugins import (
500
copy_plugins_to_placeholder,
501
get_bound_plugins,
502
has_reached_plugin_limit
503
)
504
505
# Copy content between pages
506
source_page = Page.objects.get(reverse_id='template-page')
507
target_page = Page.objects.get(reverse_id='new-page')
508
509
source_placeholder = source_page.get_placeholders('en').get(slot='content')
510
target_placeholder = target_page.get_placeholders('en').get(slot='content')
511
512
# Copy all plugins
513
source_plugins = source_placeholder.get_plugins('en')
514
copied_plugins = copy_plugins_to_placeholder(
515
plugins=source_plugins,
516
placeholder=target_placeholder,
517
language='en'
518
)
519
520
# Check plugin limits before adding
521
def add_plugin_with_limit_check(placeholder, plugin_type, language, **data):
522
if has_reached_plugin_limit(placeholder, plugin_type, language):
523
raise ValueError(f"Plugin limit reached for {plugin_type}")
524
525
return add_plugin(placeholder, plugin_type, language, **data)
526
527
# Work with bound plugins
528
plugins = placeholder.get_plugins('en')
529
bound_plugins = get_bound_plugins(plugins)
530
531
for bound_plugin in bound_plugins:
532
plugin_instance, plugin_class = bound_plugin
533
print(f"Plugin: {plugin_class.name} - {plugin_instance}")
534
```
535
536
### Validation and Setup
537
538
```python
539
from cms.utils.setup import validate_dependencies, validate_settings, setup
540
541
# In Django app configuration
542
class MyAppConfig(AppConfig):
543
name = 'myapp'
544
545
def ready(self):
546
# Validate CMS setup during app initialization
547
try:
548
validate_dependencies()
549
validate_settings()
550
except Exception as e:
551
logger.error(f"CMS setup validation failed: {e}")
552
553
# Manual setup validation
554
def health_check():
555
"""Check CMS health and configuration."""
556
try:
557
setup() # Run all validations
558
return {'status': 'healthy', 'cms': 'configured'}
559
except Exception as e:
560
return {'status': 'error', 'message': str(e)}
561
```
562
563
## Types
564
565
```python { .api }
566
class CMSSite:
567
"""
568
CMS site configuration wrapper.
569
570
Provides access to site-specific settings
571
and language configuration.
572
"""
573
574
class LanguageConfig:
575
"""
576
Language configuration object.
577
578
Attributes:
579
code: Language code (e.g., 'en')
580
name: Display name (e.g., 'English')
581
public: Whether language is publicly visible
582
fallbacks: List of fallback language codes
583
redirect_on_fallback: Whether to redirect to fallback
584
"""
585
586
class PlaceholderConfig:
587
"""
588
Placeholder configuration object.
589
590
Contains placeholder-specific settings like
591
plugin limits, inheritance rules, and rendering options.
592
"""
593
```