Install Plugie

Plugie is a Django app and installing it is as easy as any other. In this tutorial, we will cover the steps you need to take to get started.

What you need to get started

First, you should have a Django application installed and running, with Django CMS. Make sure to check the required versions in the Django/Django CMS Compatibility table.

We will be using pip to install Plugie, so make sure you have it installed. If you don't, you can install it by following the instructions here.

It is unnecessary, but creating a virtual environment for your Django project is a good practice. Check the following instructions for installing and creating a virtual environment if you still don't have it.

Step 1: Installing Plugie from pip

After activating your virtual environment, run the following command to install Plugie:

pip install djangocms_plugie

This will install Plugie and all its dependencies. Alternatively, you can check out previous releases here.

ATTENTION: Make sure to read the README file of the respective release for specific instructions on how to install it and set it up.

Step 2: Add Plugie to your list of Installed Apps

Now you can add Plugie to your Django project by adding it to the INSTALLED_APPS list in your django project's settings.py file:

INSTALLED_APPS = [
    ...
    'djangocms_plugie',
    ...
]

Step 3: Manually add the urls

You will also need to manually add the urls to your project's urls.py file. Add the following line before the catch-all url pattern from Django CMS (usually url(r'^', include('cms.urls'))):

urlpatterns = [
    ...
    path('admin/', include('djangocms_plugie.urls')),
    ...
]

Step 4: Set up Plugie with Plugie CLI

Plugie needs some quick setup to work properly. It expects a plugie_config.json file in your project's root directory. This file will contain the configuration for Plugie, such as the custom methods path, the dummy source/target plugins and a list of fields to skip when serializing/deserializing.

{
    "dummy_plugins": {
        "source": [
            "PluginToBeConverted"
        ],
        "target": "DummyPluginThatWillBeConvertedTo"
    },
    "skip_fields": [
        "unimportant_field",
        "some_translation_field"
    ],
    "custom_methods_path": "plugie/custom_methods"
}

Plugie also requires serializer/deserializer methods for each type of field in your models. We provide a set of default serializers/deserializers for the most common field types, but you can easily create your own or overrides the ones we provide. Refer to the Add a Custom Serializer-Deserializer Method section for more information.

For creating the configuration file and the custom methods, you can use the Plugie CLI. Run the following command:

plugie <project_dir>

where <project_dir> is the path to your Django project directory. If you are already in your project directory, you can run the following command:

plugie .

This will create the plugie_config.json file and the plugie/custom_methods directory in your project's root directory. You can now start using Plugie in your project.