Django Sidebar’s Documentation¶

Django sidebar is a dynamic sidebar creation for Django.

Easily create and manage sidebar from Django Admin with drag and drop interface and sidebar widget ordering.

Requirement¶

Django 1.3+

Installation¶

From pypi:

$ pip install django-sidebar

or:

$ easy_install django-sidebar

or clone from github:

$ git clone git://github.com/ekaputra07/django-sidebar.git

or:

$ cd django-sidebar
$ sudo python setup.py install

Add ‘sidebar’ into project INSTALLED_APPS settings:

#file: settings.py

INSTALLED_APPS = (
    ...
    ...
    'sidebar',
)

Add sidebar urls into project urls:

#file urls.py
urlpatterns = patterns('',
...
...
url(r'sidebar/', include('sidebar.urls')),
)

Synchronize project database:
```
$ python manage.py syncdb
```
Create a directory called ‘sidebar_widgets’ inside the project directory

It is in the same directory as manage.py file, and remember to put an __init__.py in it so python can access its content.:
```
.
..
manage.py
sidebar_widgets/
```

Add a sidebar settings into ‘settings.py’

This settings value will determine what sidebar location and sidebar widget are available.

Each sidebar location must have unique ID, this id could be the position of itself on the page.

And each widget is determined by its filename without the extension.

# Specify the available sidebar location, example:
# 'left' and 'right' is the location ID.

AVAILABLE_SIDEBARS = (
    ('left', 'Left Sidebar'),
    ('right', 'Right Sidebar'),
)

# Specify the available sidebar widget, example:
# 'promotional_image' is the ID of the widget, taken from its file name without the file extension.
# the filename of 'promotional_image' widget is 'promotional_image.py'

AVAILABLE_SIDEBAR_WIDGETS = (
    'promotional_image',
)

Create the widget

To create the widget, you must register the widget in the AVAILABLE_SIDEBAR_WIDGETS settings (described in the step #5 above). Example :

If your sidebar widget named promotional_image, create a file inside the sidebar_widgets directory and name it promotional_image.py.

sidebar_widgets/
__init__.py
promotional_image.py

The widget promotional_image.py would look like this:

from sidebar.base import SidebarWidget, sidebar_widget
from django import forms

TEMPLATE = """
{{widget_title}}
<div class="side_block">
<img src="{{image}}"/>
{{text|safe}}
 </div>
"""

class TextForm(forms.Form):
    text = forms.CharField(widget=forms.Textarea)
    image = forms.CharField()

class PromotionalImage(SidebarWidget):
    admin_form = TextForm
    template_text = TEMPLATE

# register the Widget
sidebar_widget = PromotionalImage('Promotional Image','Display a promotional image with text')

Add a place for our sidebar in template

Open your template file where the sidebar will be rendered, and make a simple call to the sidebar tag:

<!-- this is your template file. eg. index.html -->

<div class="sidebar">

{% load sidebar_tags %}
{% get_sidebar 'left' %} or {% get_sidebar 'right' %}

</div>

Now, start the server, go to Django administration page. On the Sidebars page, open (or create the sidebar if no yet created) the available sidebar and our widget will be available on the widgets list.

More on creating sidebar widget¶

Here are our simple sidebar widget,

# === STEP 1 ===
from sidebar.base import SidebarWidget, sidebar_widget
from django import forms

# === STEP 2 ===
TEMPLATE = """
{{widget_title}}
<div class="side_block">
<img src="{{image}}"/>
{{text|safe}}
</div>
"""

# === STEP 3 ===
class PromotionalForm(forms.Form):
    image = forms.CharField()
    text = forms.CharField(widget=forms.Textarea)

# === STEP 4 ===
class PromotionalImage(SidebarWidget):
    admin_form = PromotionalForm
    template_text = TEMPLATE

# === STEP 5 ===
sidebar_widget = PromotionalImage('Promotional Image','Display a promotional image with text')

I will break down the above code into 5 parts so we could understand more closely on how it works.

STEP 1

We imported SidebarWidget base class since every widget created must be based on this class.

Also imported sidebar_widget, this is just an empty variable but will be used to hold an instance of our widget object.

And we also need to import django form, since widget mostly need inputs in the admin area, which will be based on django form.

STEP 2

Widget template is a template that will be rendered to web page and filled with context/data specified in admin area.

Sidebar widget have two kinds of template that can be used:

The First is text template, this template mostly will be declared in the same file as the widget code itself.

The Second is file template, this template is a normal django template file, we can put it in our project template directory.

STEP 3

Create a data form, this form will be displayed in admin area which you can enter data.

Whatever field that you create, will be available as a context data in the template. The name of the context is same as the field name.

Beside all available contexts based on form fields, sidebar template also have one additional context called widget_title, this context will hold the widget title you set in the admin area.

STEP 4

This is our widget class which must extends the SidebarWidget class, available class attributes:

admin_form, (Optional) accept form class that you created in STEP 3.

template_text or template_file, if you use template file, please provide it with the correct template file name.

STEP 5

The last step is to initialize our widget class, and assign it to sidebar_widget variable.

When initializing our widget class, it accept two parameters, the first one is the name of the widget. And the second one is the description of the widget.

These two information will be displayed in widget admin of Django-sidebar.

Django Sidebar’s Documentation¶

Requirement¶

Installation¶

Usage example¶

More on creating sidebar widget¶