Welcome to django-portlets’s documentation!

What is it?

Portlets are pieces of content which are managed in Slots. Slots can be freely defined and placed anywhere within a HTML page.

django-portlets provides just a generic engine to manage portlets. You can find a comprehensive implementation within LFS.


To install just do:

  1. python setup.py install or easy_install django-portlets
  2. Add portlets to INSTALLED_APPS.


In order to use django portlets you first have to implement a portlet. This is done by inheriting from the provided base class, for instance:

Create a portlet

Let’s create a simple text portlet:

# django imports
from django import forms
from django.db import models
from django.template.loader import render_to_string
from django.utils.translation import ugettext_lazy as _

from portlets.models import Portlet

class TextPortlet(Portlet):
    """A simple portlet to display some text.
    text = models.TextField(_(u"Text"), blank=True)

    def __unicode__(self):
        return "%s" % self.id

    def render(self, context):
        """Renders the portlet as html.
        return render_to_string("portlets/text_portlet.html", {
            "title" : self.title,
            "text" : self.text

    def form(self, **kwargs):
        return TextPortletForm(instance=self, **kwargs)

class TextPortletForm(forms.ModelForm):
    """Form for the TextPortlet.
    class Meta:
        model = TextPortlet

Register the portlet

In order to make it available for selection, the portlet has to be registered (make sure that this is called, when django starts up):

from portlets.utils import register_portlet
register_portlet(TextPortlet, "TextPortlet")

To display portlets within your templates, just use the provided portlet_slot tag, e.g.:

{% load portlets_tags %}

             {% portlet_slot 'Left' flatpage %}
             Content goes here.
             {% portlet_slot 'Right' flatpage %}

Assign the portlet to content

Now go to the admin interface and add a Slot, e.g. “Left” and a TextPortlet (assuming you have it registered for the django’s admin application). Now you can assign the portlet (via PortletAssignment) to any content object.


django-portlets provides a simple example. If you want to see a more sophisticated implementation please refer to LFS


  1. Install flatpages (flatpages serve as our example content)

  2. Add the portlets and portlets.example to INSTALLED_APPS

  3. Sync the database

  4. Go to django admin and:

    1. add a flatpage
    2. add a TextPortlet
    3. assign the TextPortlet to the flatpage (via PortletAssignment)
  5. Browse to the flatpage

Indices and tables

Table Of Contents

This Page