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


.. _adapting_code:

**********************
Adapting existing code
**********************

The skeletons bundled with ``dja_skel`` require that the source code
(application and project) follows a few simple rules. In this chapter
we will see how to adapt exiting code to play well with ``dja_skel``.

At this point of ``dja_skel`` development the customisation must be
made by hand. Future ``dja_skel`` releases may provide some means to
automate the process.

.. warning:: make sure you have a backup of your code before
             proceeding.


Packages, packages, packages
============================

By default the applications generated with ``manage.py startapp``
provide modules for the views, models etc. This is simple but as your
application grows so does the modules and they quickly become
unmanageable.

On the other hand, from ``dja_skel``'s the point of view, fiddling
with a big monolithic module is very complex: for example, we
bootstrap a view that requires objects from the ``django.forms``
package, an import must be added if no such import exists, but the
import statement can take different forms (``from django import
forms``, ``from django.forms import *`` etc.), guessing if it's
already present may be challenging.

For these reasons it was decided that the skeletons bundled with
``dja_skel`` will operate only on packages rather than modules,
putting each element they create in its own modules within the
package.

.. note:: Third party skeletons may behave differently.

Converting a module, say ``my_module.py``, into a package is
relatively easy:

.. code-block:: bash

   $ mkdir my_module
   $ rm -f my_module.pyc
   $ mv my_module.py my_module/old_module.py
   $ touch my_module/__init__.py

Edit ``my_module/__init__.py`` so that i looks like:

.. code-block:: python

   from my_module.old_module import *

That way the *external* code will still be able to import *objects*
from the package ``my_module`` as they did before.

There are two points that we must take care of when converting a
module into a package:

* if the module does relative imports they must be corrected, either
  using absolute imports or adjusting the *relativity*:

  .. code-block:: python

     from mylib import something

  may be converted into:

  .. code-block:: python

     from myapp.mylib import something

* models defined in the ``models`` package must include an
  ``app_label`` in the ``Meta`` class:

  .. code-block:: python

     class MyModel(models.Model):
         ...
         class Meta:
             app_label = "myapp"


Markers
=======

In order to know where to insert *things* ``dja_skel`` requires that
some *markers* are present in the application sources. What markers
and in which archives will depend on the skeletons being used. Read
the documentation provided by the skeletons.

A marker is a text like ``-*- I'M A MARKER -*-``. Text preceding and
following the marker in the same line is ignored. That way it's
possible to insert a marker in a file as a comment.

In a python module:

.. code-block:: python

   urlpatterns = patterns(
       "myapp.views",
       # -*- VIEW URLS -*-
   )

In a django template:

.. code-block:: html

   {% comment %}-*- MENU ENTRIES -*-{% endcomment %}