Added in version 3.2.

Content creation wizards¶

See the How-to section on wizards for an introduction to creating wizards.

Wizard classes are sub-classes of cms.wizards.wizard_base.Wizard.

Before making a wizard available to the CMS it needs to be instantiated, for example:

my_app_wizard = MyAppWizard(
    title="New MyApp",
    weight=200,
    form=MyAppWizardForm,
    description="Create a new MyApp instance",
)

When instantiating a Wizard object, use the keywords:

class cms.wizards.wizard_base.WizardBase(title, weight, form, model=None, template_name=None, description=None, edit_mode_on_success=True)¶

title:: The title of the wizard. This will appear in a large font size on the wizard “menu”
weight:: The “weight” of the wizard when determining the sort-order.
form:: The form to use for this wizard. This is mandatory, but can be sub-classed from django.forms.form or django.forms.ModelForm.
model:: If a Form is used above, this keyword argument must be supplied and should contain the model class. This is used to determine the unique wizard “signature” amongst other things.
template_name:: An optional template can be supplied.
description:: The description is optional, but if it is not supplied, the CMS will create one from the pattern: “Create a new «model.verbose_name» instance.”
edit_mode_on_success:: Whether the user will get redirected to object edit url after a successful creation or not. This only works if the object is registered for toolbar enabled models.

Important

As of version 4 of django CMS wizards are no longer registered with the wizard_pool. Instead you need to create a app config in cms_config.py to register wizards.

Added in version 4.0.

Wizards are made available to the CMS by adding a cms.app_base.CMSAppConfig subclass to your apps’s cms_config.py. As an example, here’s how the CMS itself registers its wizards:

class CMSCoreConfig(CMSAppConfig):
    cms_enabled = True  # Use cms core's functionality
    cms_wizards = [cms_page_wizard, cms_subpage_wizard]   # Namely, those wizards

For the above example the configuration might look like this:

from .cms_wizards import my_app_wizard

class MyAppConfig(CMSAppConfig):
    cms_enabled = True
    cms_wizards = [my_app_wizard]

Wizard class¶

class cms.wizards.wizard_base.Wizard(title, weight, form, model=None, template_name=None, description=None, edit_mode_on_success=True)¶

All wizard classes should inherit from cms.wizards.wizard_base.Wizard. This class implements a number of methods that may be overridden as required.

get_description(**kwargs)¶: Simply returns the description property assigned during instantiation or one derived from the model if description is not provided during instantiation. Override this method if this needs to be determined programmatically.

get_success_url(obj, **kwargs)¶

Once the wizard has completed, the user will be redirected to the URL of the new object that was created. By default, this is done by return the result of calling the get_absolute_url method on the object. If the object is registered for toolbar enabled models, the object edit url will be returned. This may be modified to return the preview url instead by setting the wizard property edit_mode_on_success to False.

In some cases, the created content will not implement get_absolute_url or that redirecting the user is undesirable. In these cases, simply override this method. If get_success_url returns None, the CMS will just redirect to the current page after the object is created.

Parameters:

obj (object) – The created object
kwargs (dict) – Arbitrary keyword arguments

get_title(**kwargs)¶: Simply returns the title property assigned during instantiation. Override this method if this needs to be determined programmatically.

get_weight(**kwargs)¶: Simply returns the weight property assigned during instantiation. Override this method if this needs to be determined programmatically.

user_has_add_permission(user, **kwargs)¶

Returns boolean reflecting whether the given «user» has permission to add instances of this wizard’s associated model. Can be overridden as required for more complex situations.

Parameters:: user – The current user using the wizard.
Returns:: True if the user should be able to use this wizard.

property id¶: To construct a unique ID for each wizard, we start with the module and class name for uniqueness, we hash it because a wizard’s ID is displayed in the form’s markup, and we’d rather not expose code paths there.

Helpers¶

cms.wizards.helpers.get_entry(entry_key)¶: Returns a wizard object based on its id.

cms.wizards.helpers.get_entries()¶

Returns a list of (wizard.id, wizard) tuples (for all registered wizards) ordered by weight

get_entries() is useful if it is required to have a list of all registered wizards. Typically, this is used to iterate over them all. Note that they will be returned in the order of their weight: smallest numbers for weight are returned first.:

for wizard_id, wizard in get_entries():
    # do something with a wizard...

wizard_pool¶

Warning

The wizard pool is deprecated since version 4.0 and will be removed in a future version.

cms.wizards.wizard_pool.wizard_pool¶: Warning

Deprecated since version 4.0.

Using wizard_pool is deprecated. Use cms.wizards.helper functions instead. Since django CMS version 4 wizards are registered with the cms using cms.app_base.CMSAppConfig in cms_config.py.

class cms.wizards.wizard_pool.WizardPool¶

Deprecated since version 4.0.

get_entry(entry)¶: Deprecated since version 4.0: use cms.wizards.helpers.get_entry() instead

Returns the wizard from the pool identified by «entry», which may be a Wizard instance or its “id” (which is the PK of its underlying content-type).

is_registered(entry, **kwargs)¶: Deprecated since version 4.0.

Returns True if the provided entry is registered.

register(entry)¶

Deprecated since version 4.0.

You may notice from the example above that the last line in the sample code is:

wizard_pool.register(my_app_wizard)

This sort of thing should look very familiar, as a similar approach is used for cms_apps, template tags and even Django’s admin.

Calling the wizard pool’s register method will register the provided wizard into the pool, unless there is already a wizard of the same module and class name. In this case, the register method will raise a cms.wizards.wizard_pool.AlreadyRegisteredException.

unregister(entry)¶

Deprecated since version 4.0.

If «entry» is registered into the pool, remove it.

Returns True if the entry was successfully registered, else False.