1####### 2Plugins 3####### 4 5********************************************** 6CMSPluginBase Attributes and Methods Reference 7********************************************** 8 9.. class:: cms.plugin_base.CMSPluginBase 10 11 Inherits :class:`django:django.contrib.admin.ModelAdmin` and in most respects behaves like a 12 normal sub-class. Note however that some attributes of ``ModelAdmin`` simply won't make sense in the 13 context of a Plugin. 14 15 16 **Attributes** 17 18 .. attribute:: admin_preview 19 20 Default: ``False`` 21 22 If ``True``, displays a preview in the admin. 23 24 25 .. attribute:: allow_children 26 27 Default: ``False`` 28 29 Allows this plugin to have child plugins - other plugins placed inside it? 30 31 If ``True`` you need to ensure that your plugin can render its children in the plugin template. For example: 32 33 .. code-block:: html+django 34 35 {% load cms_tags %} 36 <div class="myplugin"> 37 {{ instance.my_content }} 38 {% for plugin in instance.child_plugin_instances %} 39 {% render_plugin plugin %} 40 {% endfor %} 41 </div> 42 43 ``instance.child_plugin_instances`` provides access to all the plugin's children. 44 They are pre-filled and ready to use. The child plugins should be rendered using 45 the ``{% render_plugin %}`` template tag. 46 47 See also: :attr:`child_classes`, :attr:`parent_classes`, :attr:`require_parent`. 48 49 50 .. attribute:: cache 51 52 Default: :setting:`CMS_PLUGIN_CACHE` 53 54 Is this plugin cacheable? If your plugin displays content based on the user or 55 request or other dynamic properties set this to ``False``. 56 57 If present and set to ``False``, the plugin will prevent the caching of 58 the resulting page. 59 60 .. important:: Setting this to ``False`` will effectively disable the 61 CMS page cache and all upstream caches for pages where 62 the plugin appears. This may be useful in certain cases 63 but for general cache management, consider using the much 64 more capable :meth:`get_cache_expiration`. 65 66 .. warning:: 67 68 If you disable a plugin cache be sure to restart the server and clear the cache afterwards. 69 70 71 .. attribute:: change_form_template 72 73 Default: ``admin/cms/page/plugin_change_form.html`` 74 75 The template used to render the form when you edit the plugin. 76 77 Example:: 78 79 class MyPlugin(CMSPluginBase): 80 model = MyModel 81 name = _("My Plugin") 82 render_template = "cms/plugins/my_plugin.html" 83 change_form_template = "admin/cms/page/plugin_change_form.html" 84 85 See also: :attr:`frontend_edit_template`. 86 87 88 .. attribute:: child_classes 89 90 Default: ``None`` 91 92 A list of Plugin Class Names. If this is set, only plugins listed here can be 93 added to this plugin. 94 95 See also: :attr:`parent_classes`. 96 97 98 .. attribute:: disable_child_plugins 99 100 Default: ``False`` 101 102 Disables dragging of child plugins in structure mode. 103 104 105 .. attribute:: form 106 107 Custom form class to be used to edit this plugin. 108 109 110 .. attribute:: frontend_edit_template 111 112 *This attribute is deprecated and will be removed in 3.5.* 113 114 Default: ``cms/toolbar/plugin.html`` 115 116 The template used for wrapping the plugin in frontend editing. 117 118 See also: :attr:`change_form_template`. 119 120 121 .. attribute:: model 122 123 Default: ``CMSPlugin`` 124 125 If the plugin requires per-instance settings, then this setting must be set to 126 a model that inherits from :class:`~cms.models.pluginmodel.CMSPlugin`. 127 128 See also: :ref:`storing configuration`. 129 130 131 .. attribute:: module 132 133 Will group the plugin in the plugin picker. If the module 134 attribute is not provided plugin is listed in the "Generic" 135 group. 136 137 138 .. attribute:: name 139 140 Will be displayed in the plugin picker. 141 142 143 .. attribute:: page_only 144 145 Default: ``False`` 146 147 Set to ``True`` if this plugin should only be used in a placeholder that is attached to a django CMS page, 148 and not other models with ``PlaceholderFields``. 149 150 See also: :attr:`child_classes`, :attr:`parent_classes`, :attr:`require_parent`. 151 152 153 .. attribute:: parent_classes 154 155 Default: ``None`` 156 157 A list of the names of permissible parent classes for this plugin. 158 159 See also: :attr:`child_classes`, :attr:`require_parent`. 160 161 162 .. attribute:: render_plugin 163 164 If set to ``False``, this plugin will not be rendered at all. 165 Default: ``True`` 166 167 If ``True``, :meth:`render_template` must also be defined. 168 169 See also: :attr:`render_template`, :meth:`get_render_template`. 170 171 172 .. attribute:: render_template 173 174 Default: ``None`` 175 176 The path to the template used to render the template. If ``render_plugin`` 177 is ``True`` either this or ``get_render_template`` **must** be defined; 178 179 See also: :attr:`render_plugin` , :meth:`get_render_template`. 180 181 182 .. attribute:: require_parent 183 184 Default: ``False`` 185 186 Is it required that this plugin is a child of another plugin? Or can it be 187 added to any placeholder, even one attached to a page. 188 189 See also: :attr:`child_classes`, :attr:`parent_classes`. 190 191 192 .. attribute:: text_enabled 193 194 Default: ``False`` 195 196 This attribute controls whether your plugin will be usable (and rendered) 197 in a text plugin. When you edit a text plugin on a page, the plugin will show up in 198 the *CMS Plugins* dropdown and can be configured and inserted. The output will even 199 be previewed in the text editor. 200 201 Of course, not all plugins are usable in text plugins. Therefore the default of this 202 attribute is ``False``. If your plugin *is* usable in a text plugin: 203 204 * set this to ``True`` 205 * make sure your plugin provides its own :meth:`icon_alt`, this will be used as a tooltip in 206 the text-editor and comes in handy when you use multiple plugins in your text. 207 208 See also: :meth:`icon_alt`, :meth:`icon_src`. 209 210 211 **Methods** 212 213 .. method:: get_plugin_urls(instance) 214 215 Returns the URL patterns the plugin wants to register views for. 216 They are included under django CMS's page admin URLS in the plugin path 217 (e.g.: ``/admin/cms/page/plugin/<plugin-name>/`` in the default case). 218 219 220 ``get_plugin_urls()`` is useful if your plugin needs to talk asynchronously to the admin. 221 222 223 .. method:: get_render_template() 224 225 If you need to determine the plugin render model at render time 226 you can implement the :meth:`get_render_template` method on the plugin 227 class; this method takes the same arguments as ``render``. 228 229 The method **must** return a valid template file path. 230 231 Example:: 232 233 def get_render_template(self, context, instance, placeholder): 234 if instance.attr = 'one': 235 return 'template1.html' 236 else: 237 return 'template2.html' 238 239 See also: :meth:`render_plugin` , :meth:`render_template` 240 241 242 .. method:: get_extra_placeholder_menu_items(self, request, placeholder) 243 244 Extends the context menu for all placeholders. 245 246 To add one or more custom context menu items that are displayed in the context menu for all placeholders when 247 in structure mode, override this method in a related plugin to return a list of 248 :class:`cms.plugin_base.PluginMenuItem` instances. 249 250 251 .. method:: get_extra_global_plugin_menu_items(self, request, plugin) 252 253 Extends the context menu for all plugins. 254 255 To add one or more custom context menu items that are displayed in the context menu for all plugins when in 256 structure mode, override this method in a related plugin to return a list of 257 :class:`cms.plugin_base.PluginMenuItem` instances. 258 259 260 .. method:: get_extra_local_plugin_menu_items() 261 262 Extends the context menu for a specific plugin. To add one or more custom 263 context menu items that are displayed in the context menu for a given plugin 264 when in structure mode, override this method in the plugin to return a list of 265 :class:`cms.plugin_base.PluginMenuItem` instances. 266 267 .. _get_cache_expiration: 268 269 .. method:: get_cache_expiration(self, request, instance, placeholder) 270 271 Provides expiration value to the placeholder, and in turn to the page 272 for determining the appropriate Cache-Control headers to add to the 273 HTTPResponse object. 274 275 Must return one of: 276 277 :``None``: 278 This means the placeholder and the page will not even consider 279 this plugin when calculating the page expiration. 280 281 :``datetime``: 282 A specific date and time (timezone-aware) in the future when 283 this plugin's content expires. 284 285 .. important:: The returned ``datetime`` must be timezone-aware 286 or the plugin will be ignored (with a warning) 287 during expiration calculations. 288 289 :``int``: 290 An number of seconds that this plugin's content can be cached. 291 292 There are constants are defined in ``cms.constants`` that may be 293 useful: :const:`~cms.constants.EXPIRE_NOW` and :data:`~cms.constants.MAX_EXPIRATION_TTL`. 294 295 An integer value of ``0`` (zero) or :const:`~cms.constants.EXPIRE_NOW` effectively means 296 "do not cache". Negative values will be treated as :const:`~cms.constants.EXPIRE_NOW`. 297 Values exceeding the value :data:`~cms.constants.MAX_EXPIRATION_TTL` will be set to 298 that value. 299 300 Negative ``timedelta`` values or those greater than :data:`~cms.constants.MAX_EXPIRATION_TTL` 301 will also be ranged in the same manner. 302 303 Similarly, ``datetime`` values earlier than now will be treated as :const:`~cms.constants.EXPIRE_NOW`. Values 304 greater than :const:`~cms.constants.MAX_EXPIRATION_TTL` seconds in the future will be treated as 305 :data:`~cms.constants.MAX_EXPIRATION_TTL` seconds in the future. 306 307 :param request: Relevant ``HTTPRequest`` instance. 308 :param instance: The ``CMSPlugin`` instance that is being rendered. 309 :rtype: ``None`` or ``datetime`` or ``int`` 310 311 312 .. _get_vary_cache_on: 313 314 .. method:: get_vary_cache_on(self, request, instance, placeholder) 315 316 Returns an HTTP VARY header string or a list of them to be considered by the placeholder 317 and in turn by the page to caching behaviour. 318 319 Overriding this method is optional. 320 321 Must return one of: 322 323 :``None``: 324 This means that this plugin declares no headers for the cache 325 to be varied upon. (default) 326 327 :string: 328 The name of a header to vary caching upon. 329 330 :list of strings: 331 A list of strings, each corresponding to a header to vary the 332 cache upon. 333 334 335 .. method:: icon_alt() 336 337 By default :meth:`icon_alt` will return a string of the form: "[plugin type] - 338 [instance]", but can be modified to return anything you like. 339 340 This function accepts the ``instance`` as a parameter and returns a string to be 341 used as the ``alt`` text for the plugin's preview or icon. 342 343 Authors of text-enabled plugins should consider overriding this function as 344 it will be rendered as a tooltip in most browser. This is useful, because if 345 the same plugin is used multiple times, this tooltip can provide information about 346 its configuration. 347 348 :meth:`icon_alt` takes 1 argument: 349 350 * ``instance``: The instance of the plugin model 351 352 The default implementation is as follows:: 353 354 def icon_alt(self, instance): 355 return "%s - %s" % (force_text(self.name), force_text(instance)) 356 357 See also: :attr:`text_enabled`, :meth:`icon_src`. 358 359 360 .. method:: icon_src(instance) 361 362 By default, this returns an empty string, which, if left unoverridden would 363 result in no icon rendered at all, which, in turn, would render the plugin 364 uneditable by the operator inside a parent text plugin. 365 366 Therefore, this should be overridden when the plugin has ``text_enabled`` set to 367 ``True`` to return the path to an icon to display in the text of the text 368 plugin. 369 370 Since djangocms-text-ckeditor introduced inline previews of plugins, the icon 371 will not be rendered anymore. 372 373 icon_src takes 1 argument: 374 375 * ``instance``: The instance of the plugin model 376 377 Example:: 378 379 def icon_src(self, instance): 380 return settings.STATIC_URL + "cms/img/icons/plugins/link.png" 381 382 See also: :attr:`text_enabled`, :meth:`icon_alt` 383 384 385 .. method:: render(context, instance, placeholder) 386 387 This method returns the context to be used to render the template 388 specified in :attr:`render_template`. 389 390 The :meth:`render` method takes three arguments: 391 392 * ``context``: The context with which the page is rendered. 393 * ``instance``: The instance of your plugin that is rendered. 394 * ``placeholder``: The name of the placeholder that is rendered. 395 396 This method must return a dictionary or an instance of 397 :class:`django.template.Context`, which will be used as context to render the 398 plugin template. 399 400 By default this method will add ``instance`` and ``placeholder`` to the 401 context, which means for simple plugins, there is no need to overwrite this 402 method. 403 404 If you overwrite this method it's recommended to always populate the context 405 with default values by calling the render method of the super class:: 406 407 def render(self, context, instance, placeholder): 408 context = super(MyPlugin, self).render(context, instance, placeholder) 409 ... 410 return context 411 412 :param context: Current template context. 413 :param instance: Plugin instance that is being rendered. 414 :param placeholder: Name of the placeholder the plugin is in. 415 :rtype: ``dict`` 416 417 418 .. method:: text_editor_button_icon() 419 420 When :attr:`text_enabled` is ``True``, this plugin can be added in a text editor and 421 there might be an icon button for that purpose. This method allows to override 422 this icon. 423 424 By default, it returns ``None`` and each text editor plugin may have its own 425 fallback icon. 426 427 :meth:`text_editor_button_icon` takes 2 arguments: 428 429 * ``editor_name``: The plugin name of the text editor 430 * ``icon_context``: A dictionary containing information about the needed icon 431 like `width`, `height`, `theme`, etc 432 433 Usually this method should return the icon URL. But, it may depends on the text 434 editor because what is needed may differ. Please consult the documentation of 435 your text editor plugin. 436 437 This requires support from the text plugin; support for this is currently planned 438 for `djangocms-text-ckeditor <https://github.com/divio/djangocms-text-ckeditor/>`_ 2.5.0. 439 440 See also: :attr:`text_enabled`. 441 442 443.. class:: cms.plugin_base.PluginMenuItem 444 445 .. method:: __init___(name, url, data, question=None, action='ajax', attributes=None) 446 447 Creates an item in the plugin / placeholder menu 448 449 :param name: Item name (label) 450 :param url: URL the item points to. This URL will be called using POST 451 :param data: Data to be POSTed to the above URL 452 :param question: Confirmation text to be shown to the user prior to call the given URL (optional) 453 :param action: Custom action to be called on click; currently supported: 'ajax', 'ajax_add' 454 :param attributes: Dictionary whose content will be added as data-attributes to the menu item 455 456 457****************************************** 458CMSPlugin Attributes and Methods Reference 459****************************************** 460 461.. class:: cms.models.pluginmodel.CMSPlugin 462 463 See also: :ref:`storing configuration` 464 465 **Attributes** 466 467 .. attribute:: translatable_content_excluded_fields 468 469 Default: ``[ ]`` 470 471 A list of plugin fields which will not be exported while using :meth:`get_translatable_content`. 472 473 See also: :meth:`get_translatable_content`, :meth:`set_translatable_content`. 474 475 **Methods** 476 477 .. method:: copy_relations() 478 479 Handle copying of any relations attached to this plugin. Custom plugins have 480 to do this themselves. 481 482 ``copy_relations`` takes 1 argument: 483 484 * ``old_instance``: The source plugin instance 485 486 See also: :ref:`Handling-Relations`, :meth:`post_copy`. 487 488 .. method:: get_translatable_content() 489 490 Get a dictionary of all content fields (field name / field value pairs) from 491 the plugin. 492 493 Example:: 494 495 from djangocms_text_ckeditor.models import Text 496 497 plugin = Text.objects.get(pk=1).get_bound_plugin()[0] 498 plugin.get_translatable_content() 499 # returns {'body': u'<p>I am text!</p>\n'} 500 501 See also: :attr:`translatable_content_excluded_fields`, :attr:`set_translatable_content`. 502 503 504 .. method:: post_copy() 505 506 Can (should) be overridden to handle the copying of plugins which contain 507 children plugins after the original parent has been copied. 508 509 ``post_copy`` takes 2 arguments: 510 511 * ``old_instance``: The old plugin instance instance 512 * ``new_old_ziplist``: A list of tuples containing new copies and the old existing child plugins. 513 514 See also: :ref:`Handling-Relations`, :meth:`copy_relations`. 515 516 517 .. method:: set_translatable_content() 518 519 Takes a dictionary of plugin fields (field name / field value pairs) and 520 overwrites the plugin's fields. Returns ``True`` if all fields have been 521 written successfully, and ``False`` otherwise. 522 523 ``set_translatable_content`` takes 1 argument: 524 525 * ``fields``: A dictionary containing the field names and translated content for each. 526 527 * :meth:`get_translatable_content()` 528 529 Example:: 530 531 from djangocms_text_ckeditor.models import Text 532 533 plugin = Text.objects.get(pk=1).get_bound_plugin()[0] 534 plugin.set_translatable_content({'body': u'<p>This is a different text!</p>\n'}) 535 # returns True 536 537 See also: :attr:`translatable_content_excluded_fields`, :meth:`get_translatable_content`. 538 539 540 .. method:: get_add_url() 541 542 Returns the URL to call to add a plugin instance; useful to implement plugin-specific 543 logic in a custom view. 544 545 546 .. method:: get_edit_url() 547 548 Returns the URL to call to edit a plugin instance; useful to implement plugin-specific 549 logic in a custom view. 550 551 552 .. method:: get_move_url() 553 554 Returns the URL to call to move a plugin instance; useful to implement plugin-specific 555 logic in a custom view. 556 557 558 .. method:: get_delete_url() 559 560 Returns the URL to call to delete a plugin instance; useful to implement plugin-specific 561 logic in a custom view. 562 563 564 .. method:: get_copy_url() 565 566 Returns the URL to call to copy a plugin instance; useful to implement plugin-specific 567 logic in a custom view. 568 569 570.. class:: cms.plugin_pool.PluginPool 571
