To install Wagtail completely from scratch, create a new Django project and an app within that project. For instructions on these tasks, see `Writing your first Django app <https://docs.djangoproject.com/en/dev/intro/tutorial01/>`_. Your project directory will look like the following::
From your app directory, you can safely remove ``admin.py`` and ``views.py``, since Wagtail will provide this functionality for your models. Configuring Django to load Wagtail involves adding modules and variables to ``settings.py`` and urlconfs to ``urls.py``. For a more complete view of what's defined in these files, see `Django Settings <https://docs.djangoproject.com/en/dev/topics/settings/>`__ and `Django URL Dispatcher <https://docs.djangoproject.com/en/dev/topics/http/urls/>`_.
What follows is a settings reference which skips many boilerplate Django settings. If you just want to get your Wagtail install up quickly without fussing with settings at the moment, see :ref:`complete_example_config`.
Wagtail requires several common Django middleware modules to work and cover basic security. Wagtail provides its own middleware to cover these tasks:
``SiteMiddleware``
Wagtail routes pre-defined hosts to pages within the Wagtail tree using this middleware. For configuring sites, see :ref:`wagtail_site_admin`.
``RedirectMiddleware``
Wagtail provides a simple interface for adding arbitrary redirects to your site and this module makes it happen.
Apps (settings.py)
~~~~~~~~~~~~~~~~~~
..code-block:: python
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'south',
'compressor',
'taggit',
'modelcluster',
'django.contrib.admin',
'wagtail.wagtailcore',
'wagtail.wagtailadmin',
'wagtail.wagtaildocs',
'wagtail.wagtailsnippets',
'wagtail.wagtailusers',
'wagtail.wagtailimages',
'wagtail.wagtailembeds',
'wagtail.wagtailsearch',
'wagtail.wagtailredirects',
'wagtail.wagtailforms',
'myapp', # your own app
)
Wagtail requires several Django app modules, third-party apps, and defines several apps of its own. Wagtail was built to be modular, so many Wagtail apps can be omitted to suit your needs. Your own app (here ``myapp``) is where you define your models, templates, static assets, template tags, and other custom functionality for your site.
Third-Party Apps
----------------
``south``
Used for database migrations. See `South Documentation`_.
Tagging framework for Django. This is used internally within Wagtail for image and document tagging and is available for your own models as well. See :ref:`tagging` for a Wagtail model recipe or the `Taggit Documentation`_.
Extension of Django ForeignKey relation functionality, which is used in Wagtail pages for on-the-fly related object creation. For more information, see :ref:`inline_panels` or `the django-modelcluster github project page`_.
The Django admin module. While Wagtail will eventually provide a sites-editing interface, the Django admin is included for now to provide that functionality.
Wagtail Apps
------------
``wagtailcore``
The core functionality of Wagtail, such as the ``Page`` class, the Wagtail tree, and model fields.
``wagtailadmin``
The administration interface for Wagtail, including page edit handlers.
``wagtaildocs``
The Wagtail document content type.
``wagtailsnippets``
Editing interface for non-Page models and objects. See :ref:`Snippets`.
``wagtailusers``
User editing interface.
``wagtailimages``
The Wagtail image content type.
``wagtailembeds``
Module governing oEmbed and Embedly content in Wagtail rich text fields. See :ref:`inserting_videos`.
``wagtailsearch``
Search framework for Page content. See :ref:`search`.
``wagtailredirects``
Admin interface for creating arbitrary redirects on your site. See :ref:`redirects`.
``wagtailforms``
Models for creating forms on your pages and viewing submissions. See :ref:`form_builder`.
These settings variables set the Django authentication system to redirect to the Wagtail admin login. If you plan to use the Django authentication module to log in non-privileged users, you should set these variables to your own login views. See `Django User Authentication`_.
.._Django User Authentication: https://docs.djangoproject.com/en/dev/topics/auth/
Site Name
---------
..code-block:: python
WAGTAIL_SITE_NAME = 'Stark Industries Skunkworks'
This is the human-readable name of your Wagtail install which welcomes users upon login to the Wagtail admin.
Search
------
..code-block:: python
# Override the search results template for wagtailsearch
The search settings customize the search results templates as well as choosing a custom backend for search. For a full explanation, see :ref:`search`.
Embeds
------
Wagtail uses the oEmbed standard with a large but not comprehensive number of "providers" (youtube, vimeo, etc.). You can also use a different embed backend by providing an Embedly key or replacing the embed backend by writing your own embed finder function.
Use a custom embed finder function, which takes a URL and returns a dict with metadata and embeddable HTML. Refer to the ``wagtail.wagtailemebds.embeds`` module source for more information and examples.
..code-block:: python
# not a working key, get your own!
EMBEDLY_KEY = '253e433d59dc4d2xa266e9e0de0cb830'
Providing an API key for the Embedly service will use that as a embed backend, with a more extensive list of providers, as well as analytics and other features. For more information, see `Embedly`_.
.._Embedly: http://embed.ly/
To use Embedly, you must also install their python module:
..code-block:: bash
$ pip install embedly
Images
------
..code-block:: python
WAGTAILIMAGES_IMAGE_MODEL = 'myapp.MyImage'
This setting lets you provide your own image model for use in Wagtail, which might extend the built-in ``AbstractImage`` class or replace it entirely.
Wagtail sends email notifications when content is submitted for moderation, and when the content is accepted or rejected. This setting lets you pick which email address these automatic notifications will come from. If omitted, Django will fall back to using the ``DEFAULT_FROM_EMAIL`` variable if set, and ``webmaster@localhost`` if not.
This is the path to the Django template which will be used to display the "password required" form when a user accesses a private page. For more details, see the :ref:`private_pages` documentation.
This loads Wagtail's search signal handlers, which need to be loaded very early in the Django life cycle. While not technically a urlconf, this is a convenient place to load them. Calling this function registers signal handlers to watch for when indexed models get saved or deleted. This allows wagtailsearch to update ElasticSearch automatically.
# Optional urlconf for including your own vanilla Django urls/views
url(r'', include('myapp.urls')),
# For anything not caught by a more specific rule above, hand over to
# Wagtail's serving mechanism
url(r'', include(wagtail_urls)),
)
This block of code for your project's ``urls.py`` does a few things:
* Load the vanilla Django admin interface to ``/django-admin/``
* Load the Wagtail admin and its various apps
* Dispatch any vanilla Django apps you're using other than Wagtail which require their own urlconfs (this is optional, since Wagtail might be all you need)
* Lets Wagtail handle any further URL dispatching.
That's not everything you might want to include in your project's urlconf, but it's what's necessary for Wagtail to flourish.
.._complete_example_config:
Ready to Use Example Config Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These two files should reside in your project directory (``myproject/myproject/``).
