1##############
2API References
3##############
4
5*******
6cms.api
7*******
8
9Python APIs for creating CMS content. This is done in :mod:`cms.api` and not
10on the models and managers, because the direct API via models and managers is
11slightly counterintuitive for developers. Also the functions defined in this
12module do sanity checks on arguments.
13
14.. warning:: None of the functions in this module does any security or permission
15             checks. They verify their input values to be sane wherever
16             possible, however permission checks should be implemented manually
17             before calling any of these functions.
18
19.. warning:: Due to potential circular dependency issues, it's recommended
20             to import the api in the functions that uses its function.
21
22             e.g. use:
23
24             ::
25
26                 def my_function():
27                     from cms.api import api_function
28
29                     api_function(...)
30
31             instead of:
32
33             ::
34
35                 from cms.api import api_function
36
37                 def my_function():
38                     api_function(...)
39
40
41Functions and constants
42=======================
43
44.. module:: cms.api
45
46.. data:: VISIBILITY_ALL
47
48    Used for the ``limit_visibility_in_menu`` keyword argument to
49    :func:`create_page`. Does not limit menu visibility.
50
51
52.. data:: VISIBILITY_USERS
53
54    Used for the ``limit_visibility_in_menu`` keyword argument to
55    :func:`create_page`. Limits menu visibility to authenticated users.
56
57.. data:: VISIBILITY_ANONYMOUS
58
59    Used for the ``limit_visibility_in_menu`` keyword argument to
60    :func:`create_page`. Limits menu visibility to anonymous (not authenticated) users.
61
62
63.. function:: create_page(title, template, language, menu_title=None, slug=None, apphook=None, apphook_namespace=None, redirect=None, meta_description=None, created_by='python-api', parent=None, publication_date=None, publication_end_date=None, in_navigation=False, soft_root=False, reverse_id=None, navigation_extenders=None, published=False, site=None, login_required=False, limit_visibility_in_menu=VISIBILITY_ALL, position="last-child", overwrite_url=None, xframe_options=Page.X_FRAME_OPTIONS_INHERIT)
64
65    Creates a :class:`cms.models.Page` instance and returns it. Also
66    creates a :class:`cms.models.Title` instance for the specified
67    language.
68
69    :param str title: Title of the page
70    :param str template: Template to use for this page. Must be in :setting:`CMS_TEMPLATES`
71    :param str language: Language code for this page. Must be in :setting:`django:LANGUAGES`
72    :param str menu_title: Menu title for this page
73    :param str slug: Slug for the page, by default uses a slugified version of *title*
74    :param apphook: Application to hook on this page, must be a valid apphook
75    :type apphook: str or :class:`cms.app_base.CMSApp` sub-class
76    :param str apphook_namespace: Name of the apphook namespace
77    :param str redirect: URL redirect
78    :param str meta_description: Description of this page for SEO
79    :param created_by: User that is creating this page
80    :type created_by: str of :class:`django.contrib.auth.models.User` instance
81    :param parent: Parent page of this page
82    :type parent: :class:`cms.models.Page` instance
83    :param datetime.datetime publication_date: Date to publish this page
84    :param datetime.datetime publication_end_date: Date to unpublish this page
85    :param bool in_navigation: Whether this page should be in the navigation or not
86    :param bool soft_root: Whether this page is a soft root or not
87    :param str reverse_id: Reverse ID of this page (for template tags)
88    :param str navigation_extenders: Menu to attach to this page. Must be a valid menu
89    :param bool published: Whether this page should be published or not
90    :param site: Site to put this page on
91    :type site: :class:`django.contrib.sites.models.Site` instance
92    :param bool login_required: Whether users must be logged in or not to view this page
93    :param limit_visibility_in_menu: Limits visibility of this page in the menu
94    :type limit_visibility_in_menu: :data:`VISIBILITY_ALL` or :data:`VISIBILITY_USERS` or :data:`VISIBILITY_ANONYMOUS`
95    :param str position: Where to insert this node if *parent* is given, must be ``'first-child'`` or ``'last-child'``
96    :param str   overwrite_url: Overwritten path for this page
97    :param int xframe_options: X Frame Option value for Clickjacking protection
98    :param str page_title: Overridden page title for HTML title tag
99
100
101.. function:: create_title(language, title, page, menu_title=None, slug=None, redirect=None, meta_description=None, parent=None, overwrite_url=None)
102
103    Creates a :class:`cms.models.Title` instance and returns it.
104
105    :param str language: Language code for this page. Must be in :setting:`django:LANGUAGES`
106    :param str title: Title of the page
107    :param page: The page for which to create this title
108    :type page: :class:`cms.models.Page` instance
109    :param str menu_title: Menu title for this page
110    :param str slug: Slug for the page, by default uses a slugified version of *title*
111    :param str redirect: URL redirect
112    :param str meta_description: Description of this page for SEO
113    :param parent: Used for automated slug generation
114    :type parent: :class:`cms.models.Page` instance
115    :param str overwrite_url: Overwritten path for this page
116    :param str page_title: Overridden page title for HTML title tag
117
118
119.. function:: add_plugin(placeholder, plugin_type, language, position='last-child', target=None,  **data)
120
121    Adds a plugin to a placeholder and returns it.
122
123    :param placeholder: Placeholder to add the plugin to
124    :type placeholder: :class:`cms.models.placeholdermodel.Placeholder` instance
125    :param plugin_type: What type of plugin to add
126    :type plugin_type: str or :class:`cms.plugin_base.CMSPluginBase` sub-class, must be a valid plugin
127    :param str language: Language code for this plugin, must be in :setting:`django:LANGUAGES`
128    :param str position: Position to add this plugin to the placeholder, must be a valid django-treebeard ``pos``
129        value for :meth:`treebeard:treebeard.models.Node.add_sibling`
130    :param target: Parent plugin. Must be plugin instance
131    :param data: Data for the plugin type instance
132
133
134.. function:: create_page_user(created_by, user, can_add_page=True, can_change_page=True, can_delete_page=True, can_recover_page=True, can_add_pageuser=True, can_change_pageuser=True, can_delete_pageuser=True, can_add_pagepermission=True, can_change_pagepermission=True, can_delete_pagepermission=True, grant_all=False)
135
136    Creates a page user for the user provided and returns that page user.
137
138    :param created_by: The user that creates the page user
139    :type created_by: :class:`django.contrib.auth.models.User` instance
140    :param user: The user to create the page user from
141    :type user: :class:`django.contrib.auth.models.User` instance
142    :param bool can_*: Permissions to give the user
143    :param bool grant_all: Grant all permissions to the user
144
145
146.. function:: assign_user_to_page(page, user, grant_on=ACCESS_PAGE_AND_DESCENDANTS, can_add=False, can_change=False, can_delete=False, can_change_advanced_settings=False, can_publish=False, can_change_permissions=False, can_move_page=False, grant_all=False)
147
148    Assigns a user to a page and gives them some permissions. Returns the
149    :class:`cms.models.PagePermission` object that gets
150    created.
151
152    :param page: The page to assign the user to
153    :type page: :class:`cms.models.Page` instance
154    :param user: The user to assign to the page
155    :type user: :class:`django.contrib.auth.models.User` instance
156    :param grant_on: Controls which pages are affected
157    :type grant_on: :data:`cms.models.ACCESS_PAGE`, :data:`cms.models.ACCESS_CHILDREN`, :data:`cms.models.ACCESS_DESCENDANTS` or :data:`cms.models.ACCESS_PAGE_AND_DESCENDANTS`
158    :param can_*: Permissions to grant
159    :param bool grant_all: Grant all permissions to the user
160
161
162.. function:: publish_page(page, user, language)
163
164    Publishes a page.
165
166    :param page: The page to publish
167    :type page: :class:`cms.models.Page` instance
168    :param user: The user that performs this action
169    :type user: :class:`django.contrib.auth.models.User` instance
170    :param str language: The target language to publish to
171
172.. function:: publish_pages(include_unpublished=False, language=None, site=None)
173
174    Publishes multiple pages defined by parameters.
175
176    :param bool include_unpublished: Set to ``True`` to publish all drafts, including unpublished ones; otherwise, only already published pages will be republished
177    :param str language: If given, only pages in this language will be published; otherwise, all languages will be published
178    :param site: Specify a site to publish pages for specified site only; if not specified pages from all sites are published
179    :type site: :class:`django.contrib.sites.models.Site` instance
180
181.. function:: get_page_draft(page):
182
183    Returns the draft version of a page, regardless if the passed in
184    page is a published version or a draft version.
185
186    :param page: The page to get the draft version
187    :type page: :class:`cms.models.Page` instance
188    :return page: draft version of the page
189
190.. function:: copy_plugins_to_language(page, source_language, target_language, only_empty=True):
191
192    Copy the plugins to another language in the same page for all the page
193    placeholders.
194
195    By default plugins are copied only if placeholder has no plugin for the target language; use ``only_empty=False`` to change this.
196
197    .. warning:: This function skips permissions checks
198
199    :param page: the page to copy
200    :type page: :class:`cms.models.Page` instance
201    :param str source_language: The source language code, must be in :setting:`django:LANGUAGES`
202    :param str target_language: The source language code, must be in :setting:`django:LANGUAGES`
203    :param bool only_empty: if False, plugin are copied even if plugins exists in the
204     target language (on a placeholder basis).
205    :return int: number of copied plugins
206
207Example workflows
208=================
209
210Create a page called ``'My Page`` using the template ``'my_template.html'`` and
211add a text plugin with the content ``'hello world'``. This is done in English::
212
213    from cms.api import create_page, add_plugin
214
215    page = create_page('My Page', 'my_template.html', 'en')
216    placeholder = page.placeholders.get(slot='body')
217    add_plugin(placeholder, 'TextPlugin', 'en', body='hello world')
218
219
220*************
221cms.constants
222*************
223
224..  module:: cms.constants
225
226..  data:: TEMPLATE_INHERITANCE_MAGIC
227
228    The token used to identify when a user selects "inherit" as template for a
229    page.
230
231..  data:: LEFT
232
233    Used as a position indicator in the toolbar.
234
235..  data:: RIGHT
236
237    Used as a position indicator in the toolbar.
238
239..  data:: REFRESH
240
241    Constant used by the toolbar.
242
243..  data:: EXPIRE_NOW
244
245    Constant of 0 (zero) used for cache control headers
246
247..  data:: MAX_EXPIRATION_TTL
248
249    Constant of 31536000 or 365 days in seconds used for cache control headers
250
251
252************
253cms.app_base
254************
255
256..  module:: cms.app_base
257
258..  class:: CMSApp
259
260    .. attribute:: _urls
261
262        list of urlconfs: example: ``_urls = ["myapp.urls"]``
263
264    .. attribute:: _menus
265
266        list of menu classes: example: ``_menus = [MyAppMenu]``
267
268    .. attribute:: name = None
269
270        name of the apphook (required)
271
272    .. attribute:: app_name = None
273
274        name of the app, this enables Django namespaces support (optional)
275
276    .. attribute:: app_config = None
277
278        configuration model (optional)
279
280    .. attribute:: permissions = True
281
282        if set to true, apphook inherits permissions from the current page
283
284    .. attribute:: exclude_permissions = []
285
286        list of application names to exclude from inheriting CMS permissions
287
288
289    .. method:: get_configs()
290
291        Returns all the apphook configuration instances.
292
293    .. method:: get_config(namespace)
294
295        Returns the apphook configuration instance linked to the given namespace
296
297    .. method:: get_config_add_url()
298
299        Returns the url to add a new apphook configuration instance
300        (usually the model admin add view)
301
302    .. method:: get_menus(page, language, **kwargs)
303
304        .. versionadded:: 3.3
305            ``CMSApp.get_menus`` accepts page, language and generic keyword arguments:
306            you can customize this function to return different list of menu classes
307            according to the given arguments.
308
309            Returns the menus for the apphook instance, selected according
310            to the given arguments.
311
312            By default it returns the menus assigned to :attr:`_menus`
313
314            If no page and language are provided, this method **must** return all the
315            menus used by this apphook. Example::
316
317                if page and page.reverse_id == 'page1':
318                    return [Menu1]
319                elif page and page.reverse_id == 'page2':
320                    return [Menu2]
321                else:
322                    return [Menu1, Menu2]
323
324            :param page: page the apphook is attached to
325            :param language: current site language
326            :return: list of menu classes
327
328    .. method:: get_urls(page, language, **kwargs)
329
330            .. versionadded:: 3.3
331
332            Returns the URL configurations for the apphook instance, selected
333            according to the given arguments.
334
335            By default it returns the urls assigned to :attr:`_urls`
336
337            This method **must** return a non empty list of URL configurations,
338            even if no arguments are passed.
339
340            :param page: page the apphook is attached to
341            :param language: current site language
342            :return: list of strings representing URL configurations
343