Getting started¶
Requirements¶
- Python 2.7, 3.3, 3.4 or 3.5
- Django 1.8.x or 1.9.x
- Pillow 2.2. or higher
- Django-model-utils 2.0. or higher
- Django-mptt 0.8. or higher
- Django-haystack 2.1. or higher
- Django-markdown 0.7. or higher
- Django-widget-tweaks 1.4. or higher
Note
Django-machina uses Markdown (django-markdown) by default as a syntax for forum messages, but you can change this in your settings.
Installation¶
Install django-machina using:
pip install django-machina
Note
Please remember that django-machina is currently in alpha. It is not yet suitable for production environments.
Project configuration¶
Django settings¶
First update your INSTALLED_APPS
in your project’s settings module. Modify it to be a list and append the django-machina‘s apps to this list:
from machina import get_apps as get_machina_apps
INSTALLED_APS = [
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.messages',
'django.contrib.staticfiles',
'django.contrib.admin',
# Machina related apps:
'mptt',
'haystack',
'widget_tweaks',
'django_markdown',
] + get_machina_apps()
Note
As previously stated, Markdown is the default syntax used for forum messages.
Django-machina uses django-mptt to handle the tree of forum instances. Search capabilities are provided by django-haystack.
Then update your TEMPLATE_CONTEXT_PROCESSORS
setting as follows:
TEMPLATE_CONTEXT_PROCESSORS = (
# ...
# Machina
'machina.core.context_processors.metadata',
)
Next add the machina.apps.forum_permission.middleware.ForumPermissionMiddleware
to your MIDDLEWARE_CLASSES
setting:
MIDDLEWARE_CLASSES = (
# ...
# Machina
'machina.apps.forum_permission.middleware.ForumPermissionMiddleware',
)
Then edit your TEMPLATE_DIRS
setting so that it includes the django-machina‘s template directory:
from machina import MACHINA_MAIN_TEMPLATE_DIR
TEMPLATE_DIRS = (
# ...
MACHINA_MAIN_TEMPLATE_DIR,
)
Then edit your STATICFILES_DIRS
setting so that it includes the django-machina‘s static directory:
from machina import MACHINA_MAIN_STATIC_DIR
STATICFILES_DIRS = (
# ...
MACHINA_MAIN_STATIC_DIR,
)
Finally you have to add a new cache to your settings. This cache will be used to store temporary post attachments. Note that this machina_attachments
cache must use the django.core.cache.backends.filebased.FileBasedCache
backend, as follows:
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
},
'machina_attachments': {
'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
'LOCATION': '/tmp',
}
}
Django-haystack settings¶
Django-machina uses django-haystack to provide search for forum conversations. Django-haystack allows you to plug in many search backends so you may want to choose the one that best suits your need.
You can start using the basic search provided by the django-haystack‘s simple backend:
HAYSTACK_CONNECTIONS = {
'default': {
'ENGINE': 'haystack.backends.simple_backend.SimpleEngine',
},
}
You can also decide to use a more powerfull backend such as Solr or Whoosh:
HAYSTACK_CONNECTIONS = {
'default': {
'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',
'PATH': os.path.join(PROJECT_PATH, 'whoosh_index'),
},
}
Database and migrations¶
Django-machina only provides new-style migrations. So if you are using Django 1.8 or higher, just use the syncdb
or migrate
commands:
python manage.py migrate
URLs configuration¶
Finally you have to update your main urls.py
module in order to include the forum’ URLs and the django-markdown‘ URLs:
from machina.app import board
urlpatterns = patterns(
# [...]
# Apps
url(r'^markdown/', include( 'django_markdown.urls')),
url(r'^forum/', include(board.urls)),
)
Creating your first forums¶
You can now navigate to http://127.0.0.1:8000/forum/ in order to visualize the index of your forum board. As you should see no forum have been created yet. Django-machina does not ship with pre-created forums, so you should navigate to your administration panel and create some forum instances.
Note
A common practice when creating forums is to embed them in categories in order to better organize the tree of forum instances. Please refer to Glossary if you do not know what a category is in a forum tree.
Congrats! You’re in.