This will include non *.py files in our distribution for setup.py, easy_install,...
[philo.git] / docs / tutorials / getting-started.rst
1 Getting started with philo
2 ==========================
3
4 .. note:: This guide assumes that you have worked with Django's built-in administrative interface.
5
6 Once you've installed `philo`_ and `mptt`_ to your python path, there are only a few things that you need to do to get :mod:`philo` working.
7
8 1. Add :mod:`philo` and :mod:`mptt` to :setting:`settings.INSTALLED_APPS`::
9                 
10         INSTALLED_APPS = (
11                 ...
12                 'philo',
13                 'mptt',
14                 ...
15         )
16
17 2. Syncdb or run migrations to set up your database.
18         
19 3. Add :class:`philo.middleware.RequestNodeMiddleware` to :setting:`settings.MIDDLEWARE_CLASSES`::
20         
21         MIDDLEWARE_CLASSES = (
22                 ...
23                 'philo.middleware.RequestNodeMiddleware',
24                 ...
25         )
26         
27 4. Include :mod:`philo.urls` somewhere in your urls.py file. For example::
28         
29         from django.conf.urls.defaults import patterns, include, url
30         urlpatterns = patterns('',
31                 url(r'^', include('philo.urls')),
32         )
33
34 Philo should be ready to go! (Almost.)
35
36 .. _philo: http://philocms.org/
37 .. _mptt: http://github.com/django-mptt/django-mptt
38
39 Hello world
40 +++++++++++
41
42 Now that you've got everything configured, it's time to set up your first page! Easy peasy. Open up the admin and add a new :class:`.Template`. Call it "Hello World Template". The code can be something like this::
43         
44         <html>
45                 <head>
46                         <title>Hello world!</title>
47                 </head>
48                 <body>
49                         <p>Hello world!</p>
50                         <p>The time is {% now %}.</p>
51                 </body>
52         </html>
53
54 Next, add a philo :class:`.Page` - let's call it "Hello World Page" and use the template you just made.
55
56 Now make a philo :class:`.Node`. Give it the slug ``hello-world``. Set the ``view_content_type`` to "Page" and the ``view_object_id`` to the id of the page that you just made - probably 1. If you navigate to ``/hello-world``, you will see the results of rendering the page!
57
58 Setting the root node
59 +++++++++++++++++++++
60
61 So what's at ``/``? If you try to load it, you'll get a 404 error. This is because there's no :class:`.Node` located there - and since :attr:`.Node.slug` is a required field, getting a node there is not as simple as leaving the :attr:`.~Node.slug` blank.
62
63 In :mod:`philo`, the node that is displayed at ``/`` is called the "root node" of the current :class:`Site`. To represent this idea cleanly in the database, :mod:`philo` adds a :class:`ForeignKey` to :class:`.Node` to the :class:`django.contrib.sites.models.Site` model.
64
65 Since there's only one :class:`.Node` in your :class:`Site`, we probably want ``hello-world`` to be the root node. All you have to do is edit the current :class:`Site` and set its root node to ``hello-world``. Now you can see the page rendered at ``/``!
66
67 Editing page contents
68 +++++++++++++++++++++
69
70 Great! We've got a page that says "Hello World". But what if we want it to say something else? Should we really have to edit the :class:`.Template` to change the content of the :class:`.Page`? And what if we want to share the :class:`.Template` but have different content? Adjust the :class:`.Template` to look like this::
71         
72         <html>
73             <head>
74                 <title>{% container page_title %}</title>
75             </head>
76             <body>
77                 {% container page_body as content %}
78                 {% if content %}
79                     <p>{{ content }}</p>
80                 {% endif %}
81                 <p>The time is {% now "jS F Y H:i" %}.</p>
82             </body>
83         </html>
84
85 Now go edit your :class:`.Page`. Two new fields called "Page title" and "Page body" have shown up! You can put anything you like in here and have it show up in the appropriate places when the page is rendered.
86
87 .. seealso:: :ttag:`philo.templatetags.containers.container`
88
89 Congrats! You've done it!