.. -*- ispell-local-dictionary: "british" -*-

.. _chapter_tutorial:

********
Tutorial
********

The ``dja_skel`` application provides an stand alone script named
``dja_skel`` and a django management command named ``skel``. The
former is useful when you want to instantiate an skeleton that does
not operate on an existing project, the so called non-project
skeletons (an skeleton that bootstraps a django project btw), while
the latter requires at least a working project to operate (a project
in which ``dja_skel`` appears in ``INSTALLED_APPS`` so that
``manage.py`` knows about the ``skel`` command).


Creating a sample application
=============================

The ``skel`` management command works on django applications, so first
at all we need a project and an application. ``skel`` does some
assumptions on the source layout and content. For now we will
bootstrap a project using the ``dja_skel`` script and an application
with the ``skel`` management command. The section :ref:`adapting_code`
explains how to prepare existing code in order to play nicely with
``skel``.

.. code-block:: bash

   $ source ~/virtualenvs/dja_skel/bin/activate
   (dja_skel)$ cd ~/projects
   (dja_skel)$ mkdir testing_dja_skel
   (dja_skel)$ cd testing_dja_skel
   # replace project14 with project13 if you're using django < 1.4
   (dja_skel)$ dja_skel -i -t project14 prjname=myproject
   # if running django < 1 .4
   (dja_skel)$ cd project
   # end if
   (dja_skel)$ ./manage.py skel -i -t app appname=myapp

That's all. This will create a django project (using the template
``project14``) and an application called ``myapp`` . The project is
configured with sensible defaults so that we can start working with it
right now. The section :ref:`default_skeletons` contains a detailed
descriptions of the application and project skeletons.

Next we need a model to play with. We'll use the ``skel`` management
command to bootstrap a simple model:

.. code-block:: python

   (dja_skel)$ ./manage.py skel -i -t model applabel= myapp ModelName=MyModel

This command will create an almost empty ``MyModel`` model in the
``myapp`` application. The model definition is located in the
``myapp/models/my_model.py`` module:

.. code-block:: python

   class MyModel(models.Model):
      """MyModel
      """

      # put here your field definitions

      class Meta:
          app_label = "myapp"
          db_table = "myapp_my_model"
          permissions = (("read_mymodel", "Can read MyModel"), )
          verbose_name = "My model"
          verbose_name_plural = "My models"

This command performs other operation:

* adds permission definitions for the CRUD operations into the
  ``permissions.py`` module.

* creates and empty ``MyModelAdmin`` model admin class and registers
  it with the ``admin``.

Add a couple of fields so that it looks like:

.. code-block:: python

   class MyModel(models.Model):
      name = models.CharField(max_length=100)
      age = models.IntegerField()
      class Meta:
          app_label = "myapp"
          db_table = "myapp_my_model"
          permissions = (("read_mymodel", "Can read MyModel"), )
          verbose_name = "My model"
          verbose_name_plural = "My models"

And execute ``syncdb`` as usual.

.. code-block:: python

   (dja_skel)$ ./manage.py syncdb

As a final step we will create a (class based) view to list the
``MyModel`` models.

.. code-block:: python

   (dja_skel)$ ./manage.py skel myapp -i -t list_view ModelName=MyModel

This command performs a lot of work under the hood:

* creates a view in the ``views`` package, in the module
  ``my_model_list_view.py``

* creates the template ``templates/myapp/my_model_list_views.html``

* adds an ``from views.my_model_list_view import my_model_list_view``
  to ``views/__init__.py``.

* adds the url ``my_model/list`` to the ``urls.py``.

Add a couple of ``MyModel`` in the admin and visit
``http://localhost:8000/myapp/my_model/list``.