Simple Forums¶

Requirements¶

• Python 2.7, 3.3 [*], 3.4, or 3.5
• Django 1.8+
• bleach, bleach-whitelist, markdown, and pymdown-extensions [†]

Features¶

• Threads are separated into different topics to allow for easy organization
• Easily swappable rendering solutions for markup

Django¶

$ pip install django-simple-forums

INSTALLED_APPS = [
    ...
    # default django apps
    'adminsortable',
    'simple_forums',

    # If you want email notification functionality, add the following:
    'simple_forums.notifications',
    ...
]

TEMPLATES = [
    {
        'OPTIONS': {
            'context_processors': [
                # other context processors
                'simple_forums.context_processors.installed_apps',
            ],
        },
    },
]

urlpatterns = [
    ...
    url(r'^forums/', include('simple_forums.urls')),
    ...
]

# In a template file

{% url 'simple-forums:index' %}


# In a .py file

reverse('simple-forums:index')

Post-Installation¶

Apply the migrations for simple forums:

$ ./manage.py migrate

On your server, visit the admin page and start creating topics for users to post under.

Available Settings¶

markdown_extensions (=[‘pymdownx.github’])

A list of extensions to process markdown with. Only has an effect if MarkdownRenderer is used. The default list of extensions is defined in simple_forums.markup_renderers.MarkdownRenderer.DEFAULT_EXTENSIONS.

markup_renderer (=’simple_forums.backends.renderers.TextRenderer’)

This class specifies which form of markup should be used to render posts. Currently there is a choice between plain text and Markdown.

Choices:

• 'simple_forums.backends.renderers.MarkdownRenderer'
• 'simple_forums.backends.renderers.TextRenderer'

search_backend

A dictionary containing the settings for the search engine to use. See the Searching section for more details.

Simple Search¶

Class: simple_forums.backends.search.SimpleSearch

This backend performs searches by separating the search query into individual words, and then filtering the threads down to the ones that include all the keywords in their title. It does not rank results in any way. This can be useful if you don’t need a complicated search engine.

Configuration Options:

None

Elasticsearch¶

Class: simple_forums.backends.search.ElasticSearch

Requires Installation of the elasticsearch-py package.

This backend connects to an elasticsearch server using the given credentials and uses it to perform searches. It is much more powerful than the Simple Search backend because it has the ability to search through replies to threads rather than just the thread titles.

Configuration Options:

host (Required): The hostname of the elasticsearch server

port (Required): The port to connect to the elasticsearch server on

index: The name of the elasticsearch index to use

Configuration¶

To use email notifications, you must add 'simple_forums.notifications' to INSTALLED_APPS. Don’t forget to run your database migrations after doing that.

The other requirement for notifications is to have your email settings correctly configured. The crucial settings are EMAIL_HOST and EMAIL_PORT. For more information, refer to the django documentation.

Templates¶

To include notifications-specific items in your templates, you can use the variables provided by simple forums’ context processor (if installed). Example:

# my_app/my_template.html

{% if notifications_installed %}
    {{ notification_form }}
{% endif %}