.. include:: _replacement-directives.txt

==========================
Getting started with |dlm|
==========================

:Author: Vincent Fretin
:Contributors: Aroldo Souza-Leite
:Version: This tutorial has been tested with dolmenproject 1.0a3
          and Dolmen 0.5.4.

(last modified: |datetime|)

|dlm| is set of thin enhancement layers, that is, very modular, task
specific libraries, based on Grok_. Among other things, you can use
the |dlm| libraries to gradually create a |grok| based CMS.

|dlm| is strongly based on Grok_, but you don't need to have
experience with |grok| to start working with |dlm|. This tutorial can
also be seen as manual for creating your first |grok| site and start
playing with |grok| using a |dlm| site (or simply a |dlm|) as a
|grok| sample site.

Here you will learn how to create your first |dlm| render it in the
browser. You do it by first creating a |dlm| project on the file
system using the |dprj| script. For this, you have to install a Python
virtual environment, activate it and then install |dprj| in this
environment.

The examples in this tutorial are done on the operating system Linux
Ubuntu_, a Linux distribution based on Debian. But as Python and
|grok| run independently from the operating system, it should be easy
to take virtually the same steps on a MacOS or MSWindows machine.

.. _`Ubuntu`: http://www.ubuntu.com/


Preconditions
-------------

In order to install a |dlm| for the first time, you need:

- Python-2.6 (see Python_)
- the Python tool *virtualenv* installed in your system Python (see virtualenv_)
- a separate Python virtual environment
- the Python imaging tool *PIL* installed for your installeed Python.
- the tool *dolmenproject* installed in the Python virtual environment

.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv


Python, lxml and PIL
--------------------

We need to install some packages via the package manager:

.. code-block:: bash

    $ sudo apt-get install build-essential python2.6 python2.6-dev \
        python-imaging libxslt1-dev libxml2-dev

We use python-imaging to install PIL and
libxslt1-dev libxml2-dev to be able to build lxml.


The Python virtual environment
------------------------------

The main Python system must include a tool called *virtualenv* that
creates a separate Python environment. A separate Python virtual
environment can be used among other purposes for testing a Python
library without changing the main Python configuration on your
computer. For the installation of the *virtualenv* utility in your
main Python system see the virtualenv_ documentation on the Python_
site.

Here and in then next examples, `$` stands for your usual operating
system's usual command prompt, whereas `(dolmenenv)$` stands for the
prompt indicating that the virtual environment is active.

.. code-block:: bash

   $ virtualenv -p /usr/bin/python2.6 dolmenenv
   $ source dolmenenv/bin/activate
   (dolmenenv)$

A label `(dolmenenv)` will appear on the left of your usual command
prompt. This is a sign that you are working in the separate Python
environment you created. In order to deactivate it, type `deactivate`
and you will see your usual operating system prompt again.  Now change
the current directory to the location where you want to create |dlm|
projects:

.. code-block:: bash

   (dolmenenv)$ cd /path/to/my/projects


Installing the |dprj| script
----------------------------

You can easy_install dolmenproject:

.. code-block:: bash

    (dolmenenv)$ easy_install dolmenproject

.. topic:: Development version of dolmenproject
   
   If you want to work on |dprj|, you can install it from the *git* repository.

    .. code-block:: bash

        (dolmenenv)$ git clone git://devel.dolmen-project.org/dolmenproject.git
        (dolmenenv)$ cd dolmenproject
        (dolmenenv)$ python setup.py install

    To update |dprj| afterwards, issue ``git pull`` in the directory and
    run ``python setup.py install`` again.

    .. code-block:: bash

        (dolmenenv)$ git pull
        (dolmenenv)$ python setup.py install       # with the dolmenenv enabled.


Using |dprj| to create the |dlm| project
-----------------------------------------

Make sure you changed to the directory where you want to create your
|dlm| projects and that the Python virtual environment `(dolmenenv)`
is active.

Create a |dlm| project by calling ``dolmenproject`` with the project
name as a parameter. Here we call it *MyDolmen* but of course you can
give it a name of your choice.

.. code-block:: bash

    (dolmenenv)$ dolmenproject MyDolmen

You can use an older KGS like this:

.. code-block:: bash

    (dolmenenv)$ dolmenproject \
    --version-url="http://www.dolmen-project.org/kgs/dolmen-kgs-0.5.4.cfg" \
    MyDolmen

Or use development version like this:

.. code-block:: bash

    (dolmenenv)$ dolmenproject \
    --version-url="http://gitweb.dolmen-project.org/misc.git?a=blob_plain;f=dolmen-kgs-1.0dev.cfg;hb=HEAD" \
    MyDolmen

In the process of creating the |dlm| project, you are asked for a user
name and a password as a site adminstrator. You have to remember these
credentials later on.

Disable the virtual environment:

.. code-block:: bash

    (dolmenenv)$ deactivate

Then change to the MyDolmen project root to bootstrap your project
with distribute (-d option) and run buildout:

.. code-block:: bash

    $ cd MyDolmen
    $ python2.6 bootstrap.py -d
    $ bin/buildout

Run the |dlm| site like this:

.. code-block:: bash

    $ bin/paster serve parts/etc/deploy.ini

For development purpose, run it with the following command:

.. code-block:: bash

    $ bin/paster serve --reload parts/etc/debug.ini

This command causes the |dlm| process to be more verbose,
so that you are told about what is happening through messages in the
console.

Point your browser to http://localhost:8080 to see the page being
served. You are going to be asked for your credentials. Here you can
test your |dlm| server by creating a test |dlm| application (give it
some name like *mydolmen*).

Then click on 'mydolmen' to see your first |dlm| application.

There is almost no content in 'mydolmen', but it's already a fully
functional |dlm| application.


Use a skin
----------

To use a skin for your Dolmen project, you have to do some work on
``setup.py`` of the MyDolmen root and then change the working
directory to ``src/mydolmen`` to do some work there.

.. code-block:: bash

   $ cd src/mydolmen


Add to :file:`setup.py`:

.. code-block:: python

    menhir.skin.lightblue

Add to :file:`configure.zcml`:

.. code-block:: xml

    <include package="menhir.skin.lightblue" />

and replace:

.. code-block:: xml

    <!-- Skin  -->
    <includeOverrides
        package="dolmen.app.layout"
        file="skin.zcml"
        />

by:

.. code-block:: xml

    <!-- Skin  -->
    <includeOverrides
        package="menhir.skin.lightblue"
        file="skin.zcml"
        />

You can try the *menhir.skin.snappy* skin too, but it may not be up to date
with the latest Dolmen changes.

You can remove 'dummydolmen' by pointing your browser back to
http://localhost:8080 , checking the 'delete' box and submitting
it. You will implement your |dlm| application in the following parts
of this tutorial.