Rioki’s Corner

Fist you need to install Django. I will not repeat the documentation on Django. So you should read the Django’s Installation Guide.

There is to note that I am using the bleeding edge version from their subversion repository. This is done in anticipation of their 1.0 release, which is scheduled for beginning of September. You can use the 0.95 version, but It lacks some juicy bits.

All Django project (website) starts the same way:

django-admin.py startproject rioki

This will create a template, but usable website.

On of the nifty features is that Django comes with a embedded web server that can (and only should) be used for development. This feature really cuts down development time.

To use it launch the server (in the project directory):

./manage.py runserver

You will now find your website under http://127.0.0.1:8000/.

Well it actually is only a page that tells you have not “configured any urls”. We will get to that soon.

Well the first step is to configure your site. This is a simple process, open settings.py in your favorite text editor and edit the file as appropriate.

Mine looks about so:

from os.path import join, dirname

DEBUG = True
TEMPLATE_DEBUG = DEBUG

ADMINS = (
    ('Sean "Rioki" Farrell', 'i.dont.think@so.com'),
)

MANAGERS = ADMINS

DATABASE_ENGINE = 'sqlite3'
DATABASE_NAME = join(dirname(__file__), 'database')

TIME_ZONE = 'Europe/Berlin'

LANGUAGE_CODE = 'en-us'

SITE_ID = 1

USE_I18N = False

MEDIA_ROOT = join(dirname(__file__), 'media')

MEDIA_URL = '/media/'

ADMIN_MEDIA_PREFIX = '/admin_media/'

SECRET_KEY = 'Mine, not yours...'

TEMPLATE_LOADERS = (
    'django.template.loaders.filesystem.load_template_source',
    'django.template.loaders.app_directories.load_template_source',
)

MIDDLEWARE_CLASSES = (
    'django.middleware.common.CommonMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.middleware.doc.XViewMiddleware',
)

ROOT_URLCONF = 'rioki.urls'

TEMPLATE_DIRS = (
    join(dirname(__file__), 'templates')
)

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
)

I used a nifty trick for the different paths. For security and stability reasons, you are to give absolute paths for the values such as MEDIA_ROOT. Well I use join(dirname(file), ‘media’), which makes it relative to the settings.py file. As a result I can move the entire package around and always be right and an absolute path.

Now is a good time to create the initial database:

./manage.py syncdb

Well this will load the initial tables and ask you if you want to create a super user.

One of the most powerful features is the admin backend. You might not see that in this post.

To use the admin you need to add 'django.contrib.admin‘ to the INSTALLED_APPS. You need to rerun syncdb, wich you must almost always do after you add something to INSTALLED_APPS.

./manage.py syncdb

In addition uncomment lines for the admin in urls.py. You urls.py should about look like that:

from django.conf.urls.defaults import *

urlpatterns = patterns('',
    (r'^admin/', include('django.contrib.admin.urls')),
)

You can see the admin interface under http://127.0.0.1:8000/admin/

Here you can see one of the nice features of Django: Instant pretty URLs. This comes from the fact that all incoming requests are matched against a table of regular expressions.

You might want to change the Sites entry from example.com to your website, but that’s all for now.

Django comes with a module for static content, that is django.contrib.flatpages.

To use it add 'django.contrib.flatpages‘ to INSTALLED_APPS and 'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware‘ to MIDDLEWARE_CLASSES.

Rerun syncdb:

./manage.py syncdb

Now you can add some pages via the admin. I added ”/” for the portal page and ”/imprint/” for the imprint. You can find the pages you created at http://127.0.0.1:8000/ and http://127.0.0.1:8000/imprint/.

Well actually, you can’t. It is still complaining about a missing template. Let’s create that.

Create the file templates/flatpages/default.html:

<html>
    <head>
        <title>{{ flatpage.title }}</title>
    </head>
    <body>
        <h1>{{ flatpage.title }}</h1>
        {{ flatpage.content }}
    </body>
</html>

As you can see the content is copied verbatim. You got two solutions you either write the content HTML or use one of the built-in markup languages.

Django comes bundled with 3 markup languages, that is Textile, Markdown and ReST. To enable those you need to add 'django.contrib.markup‘ to your INSTALLED_APPS. And change the template to look like this:

{% load markup %}
<html>
    <head>
        <title>{{ flatpage.title }}</title>
    </head>
    <body>
        <h1>{{ flatpage.title }}</h1>
        {{ flatpage.content|textile }}
    </body>
</html>

As you can see we are using textile.

During debug we are using the builtin server. That has the consequence that media files are not explicitly served. To fix this we we extend urls.py file:

from django.conf.urls.defaults import *
from django.conf import settings

urlpatterns = patterns('',
    (r'^admin/', include('django.contrib.admin.urls')),
)

if settings.DEBUG:
    urlpatterns += patterns('',
        (r'^media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': settings.MEDIA_ROOT})
    )

As you can see, the media files are only server through Django when in debug mode. In production mode, on the production website media is server through apache. This is a obvious performance issue.

Well so far we are “done”, except that the site looks really crappy. I took the design from this site, as it will replace it and just adapted it to Django.

I created the site rump templates/default.html:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
    <head>
        <title>{% block title %}Rioki{% endblock %}</title>
        <link rel="stylesheet" type="text/css" href="/media/design/default.css" />
    </head>
    <body>
        <div class="page">
            <div class="header">
                {% block header %}
                    <a href="/">Start</a> |
                    <a href="/blog/">Blog</a> |
                    <a href="/about/">About</a> |
                    <a href="/proejcts/">Projects</a>
                {% endblock %}
            </div>
            <div class="sidebar">
                {% block sidebar %}
                    <h3>Sidebar:</h3>
                    <ul>
                        <li><a href="http://www.libqgl.org">libQGL</a></li>
                        <li><a href="http://www.sf.net/projects/lunar-exodus">Lunar Exodus</a></li>
                        <li><a href="/stl_algorithm_shortcuts">STL Algorithm Shortcuts</a></li>
                        <li><a href="/tstring">std::tstring</a></li>
                        <li><a href="/blog:itx_rock_my_web_app">ITX Rock my Web App</a></li>
                        <li><a href="http://www.motivator-generator.com">Motivator Generator</a></li>
                    </ul>
                {% endblock %}
            </div>
            <div class="content">
                {% block content %}No content here.{% endblock %}
            </div>
            <div class="footer">
                {% block footer %}
                    © 2006-2008 Sean Farrell<br/>
                    <a href="/about/">Imprint</a> |
                    <a href="/contact/">Contact</a>
                {% endblock %}
            </div>
        </div>
    </body>
</html>

I also put CSS style sheet and the images into /media/design.

This is nice, but the flatpages need the design. To do this I altered the template for the flatpages to be the following:

{% extends 'default.html' %}
{% load markup %}

{% block title %}{{ flatpage.title }}{% endblock %}

{% block content %}
    <h1>{{ flatpage.title }}</h1>
    {{ flatpage.content|textile }}
{%endblock %}

And viola, the beauty of reuse.

As far as it comes to static content, we are done. To be honest for many sites this is enough; but not for mine.

Firs of all we need the blog. This site is 90% blog, so it will really miss. I could realize it via flatpages, but that is slightly awkward.

An other issue is that media files need to be uploaded to the server via some file transfer process, I want to be able to do that via the admin, since I may not have access to the server directly.

As you can see the menus are hardwired to the template, this is Ok if they don’t change often. (Which might be the case here…) But I want to be able to change them at any time via the admin.

Finally textile is okish, but I don’t like it too much. The other markup languages are worse. I have once tried to implement the dokuwiki syntax in python, let’s see if that works out as template tag.

What needs to be done:

• blog
• handling of media files via admin
• handling of menu via admin
• integrate dokuml

When working on web applications, it is obvious to separate the design of a website from its core logic. Not only can different people edit the bits, it also ensures a certain design consistency is created. There are many ways to use template but one of the most prominent is PEAR’s IT/ITX. But even those have a huge potential for reuse that is not obvious.

If you check out the PEAR module HTML_Template_IT you will see that using it is straight forward.

Let’s write a friendly greeting program. It will get a title and message via GET or POST and display it. The simple implementation is something like:

<?php
    if (isset($_REQUEST["title"]))
    {
        $title = $_REQUEST["title"];
    }
    else
    {
        $title = "Greeting";
    }
    if (isset($_REQUEST["message"]))
    {
        $title = $_REQUEST["message"];
    }
    else
    {
        $title = "No message specified.";
    }
?>
<html>
    <head>
        <title><?php echo $title ?></title>
    </head>
    <body>
        <div align="center">
            <?php echo $message ?>
        </div>
    </body>
</html>

Now the problem is that the HTML is entangled with the code. If you have a similar page with totally different logic you end up duplicating your design. If you ever have to change something you have to do it everywhere, not to mention site wide design changes.

We will now rewrite the program to use IT template. For this we will first write the template.

<html>
    <head>
        <title>{title}</title>
    </head>
    <body>
        <div align="center">
            {message}
        </div>
    </body>
</html>

This is quite simple the {title} and {message} are place holders that are substituted. To do this we change the application as follows.

<?php

require_once "HTML/Template/IT.php";

if (isset($_REQUEST["title"]))
{
    $title = $_REQUEST["title"];
}
else
{
    $title = "Greeting";
}
if (isset($_REQUEST["message"]))
{
    $title = $_REQUEST["message"];
}
else
{
    $title = "No message specified.";
}

$template = new HTML_Template_IT("./tpl");

$template->loadTemplateFile("message.tpl", true, true);

$template->setVariable("title", $title);
$template->setVariable("message", $message);

$template->show();

The code is quite self explanatory. You create a HTML_Template_IT object and then load the template with loadTemplateFile. The variable substitution is done with setVariable and the compiled template is printed with show.

Now we can consistently show different messages from different applications. The problem now comes when you consider site wide design changes. In this case you have to go to the next level and use ITX.

Now let’s consider you have a finished design and you convert it to a template.

<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
    <head>
        <title>{title} - MySite</title>
        <meta name="author" content="{author}">
        <meta name="description" content="{description}">
        <meta name="keywords" content="{keywords}">
        <link rel="stylesheet" type="text/css" href="{url}/tpl/style.css" />
    </head>
    <body>
        <div class="page">
            <div class="header"></div>
            <div class="main">
                {main}
            </div>
            <div class="footer">
                &copy; 2008 Jon Doe |
                <a href="{url}/contact.php">Contact</a>
            </div>
        </div>
    </body>
</html>

This the basic outline every page gets and is the basic design of the site. Please note that placeholders for menus and such where omitted in the example.

This design is nice, only how do I get the different content there. Well there is the simple solution, put it all into main place holder. Since we want to reuse it we encapsulate all the template handling into a Page object.

The Page object is fairly simple:

<?php
require_once 'HTML/Template/ITX.php';
require_once 'inc/config.php';

class Page
{
    var $template;

    function Page($title)
    {
        $this->template = new HTML_Template_ITX(get_template_path());
        $this->template->loadTemplatefile('main.tpl', true, true);

        $this->template->setVariable('url', get_config('site', 'url'));
        $this->template->setVariable('title', $title);

        $this->template->setVariable('author', get_config('site', 'author'));
        $this->template->setVariable('description', get_config('site', 'description'));
        $this->template->setVariable('keywords', get_config('site', 'keywords'));
    }

    function set_main($value)
    {
        $this->template->setVariable('main', $value);
    }

    function show()
    {
        $this->template->show();
    }
}

The Page class basically loads the template and sets the common values. These values are pulled via get_config but you can do it in any way you like.

The class is used as follows:

<?php
require_once "inc/Page.php";

if (isset($_REQUEST["title"]))
{
    $title = $_REQUEST["title"];
}
else
{
    $title = "Greeting";
}
if (isset($_REQUEST["message"]))
{
    $title = $_REQUEST["message"];
}
else
{
    $title = "No message specified.";
}

$page = new Page($title);
$page->set_main("<div align=\"center\">{$message}</div>");
$page->show();

This is quite ok. But you can see the issue coming, you need to assemble tons of HTML bits to make a large page.

Since we want the most explicit solution, we will create a Message_Page. To do this we start with a template.

<!-- BEGIN message -->
<div align="center">{message}</div>
<!-- END message -->

Well this is the missing bit. Its not much, but messages look this way.

The Message_Page is a s follows:

<?php

#include "Page.php"

class Message_Page extends Page
{
    function Message_Page($title)
    {
        $this->Page($title);

        $this->template->addBlockFile('main', 'main', 'message.tpl');
        $this->template->setCurrentBlock('message');
    }

    function set_message($text)
    {
        $this->template->setVariable('message',   $message);
    }

    function show()
    {
        $this->template->parseCurrentBlock('message');
        Page::show();
    }
}

Well this is where it gets interesting, we insert one template into an other by calling addBlockFile. The template message.tpl is inserted into the main placeholder and converted to a block. We add a setCurrentBlock, parseCurrentBlock pair, so that the variable scoping works properly.

This seems slightly overkill, but consider the following example.

You want also to have forms on your page. The simple way is to build one template with the entire form and substitute that. But there is a nifty solution, built the form from template bits.

Here is the template:

<!-- BEGIN form -->
<h1>{title}</h1>
<!-- BEGIN instructions -->
<p>{instructions}</p>
<!-- END instructions -->
<form method="{method}" action="{action}">
    <table>
        <!-- BEGIN input -->
        <tr>
            <td valign="top">{name}</td>
            <td><input type="text" name="{variable}" value="{value}" size="{size}" /></td>
        </tr>
        <!-- END input -->
        <!-- BEGIN text -->
        <tr>
            <td valign="top">{name}</td>
            <td><textarea name="{variable}" cols="{cols}" rows="{rows}">{value}</textarea></td>
        </tr>
        <!-- END text -->
    </table>
    <input type="submit" value="{submit}">
</form>
<!-- END form -->

How this template works, we will see with the Form_Page class:

<?php

require_once 'Page.php';

class Form_Page extends Page
{
    function Form_Page($title, $method, $action)
    {
        $this->Page($title);

        $this->template->addBlockFile('main', 'main', 'form.tpl');

        $this->template->setCurrentBlock('form');
        $this->template->setVariable('title',    $title);
        $this->template->setVariable('method',   $method);
        $this->template->setVariable('action',   $action);
    }

    function set_instructions($text)
    {
        $this->template->setVariable('instructions', $text);
    }    

    function add_input($name, $variable, $value = '', $size = 50)
    {
        $this->template->setCurrentBlock('input');    

        $this->template->setVariable('name',     $name);
        $this->template->setVariable('variable', $variable);
        $this->template->setVariable('value',    $value);
        $this->template->setVariable('size',     $size);

        $this->template->parseCurrentBlock('input');
    }

    function add_text($name, $variable, $value = '', $cols = 50, $rows = 10)
    {
        $this->template->setCurrentBlock('text');    

        $this->template->setVariable('name',     $name);
        $this->template->setVariable('variable', $variable);
        $this->template->setVariable('value',    $value);
        $this->template->setVariable('cols',     $cols);
        $this->template->setVariable('rows',     $rows);

        $this->template->parseCurrentBlock('text');
    }

    function set_submit_text($text)
    {
        $this->template->setVariable('submit', $text);
    }

    function show()
    {
        $this->template->parseCurrentBlock('form');
        Page::show();
    }
}

Well basically it is the same as with Message_Page, the template is substituted into the main placeholder and common values are used. The difference comes with add_text and add_input.

Since blocks can be reused, multiple calls to add_input, will add multiple fields. The following application shows the Form_Page in action by using a contact form.

<?php
require_once 'inc/Form_Page.php';

$page = new Form_Page('Contact', 'POST', 'contact.php');

$instructions = 'If you whish to contact us, please us the following form.' .
                'We will reply via e-mail in the comming days.';
$page->set_instructions($instructions);

$page->add_input('Name', 'name');
$page->add_input('E-Mail', 'email');
$page->add_text('Text', 'text');
$page->set_submit_text('Send');

$page->show();

Every web application has static content, to simplify access to this, I created a Static_Page class. This page will load the content from a text file and add it verbatim into to main placeholder.

<?php

require_once 'Page.php';
require_once 'inc/config.php';

class Text_Page extends Page
{
    function Text_Page($title, $text_file)
    {
        $this->Page($title);    

        $text = $this->read_text($text_file);
        $this->template->setVariable('main', $text);
    }

    function read_text($text_file)
    {
        $content_file = get_data_path() . $text_file;
        $fh = fopen($content_file, "r") or die("Could not open $content_file.");
        $content = fread($fh, filesize($content_file));
        fclose($fh);
        return $content;
    }
}

A static page would use it as follows:

<?php 

require_once 'inc/Static_Page.php';

$template = new Static_Page('Example', 'example.txt');
$template->show();

PHP and MySQL

PHP and MySQL

Well I must addmit that I did not come to the idea fully on my own. The concept with recycling templates and building forms from blocks in templates was taken from the very good book PHP and MySQL from O’Reilly.

But I cleaned up the concept and code, since I think the author is a crappy programmer, although the concepts are nice. To state a example he reuses the templates by inheriting from the HTML_Template_ITX class. Well sorry, inheritance is not for code reuse and a page definitely is not a template.

Links

If you read about this in the Microsoft Developer Network (MSDN) you get a plain solution: Use the preprocessor.

#ifdef _UNICODE
#define tstring wstring
#else
#define tstring string
#endif

This solution follows the same as many proposed by Microsoft. But if you give me a Euro for every #undef I needed to write in my code, bacause a macro from the WinAPI tainted my code, I would be rich.

Since we are programming C++, it is wise to solve the problem with the means of the language instead of the using a preprocessor hack. The definition of tstring follows the definition of string and wstring. tstring is a variant of the template basic_string with TCHAR. To add a little type safety and portability I defined tchar_t following the idea of wchar_t.

namespace std
{
    typedef TCHAR tchar_t;
    typedef basic_string<tchar_t> tstring;
}

tchar_t and tstring where defined in the namespace std, to show that it actually just is a special form of basic_string and fully compatible to other standard code.

Well now that you have your string class dependent on TCHAR, there is the problem of streams. Streams are also parameterized for char or wchar_t. But here the solution is straight forward. Define your own types based on ”basic_streamtype”

namespace std
{
    typedef basic_ios<tchar_t>              tios;
    typedef basic_streambuf<tchar_t>        tstreambuf;
    typedef basic_istream<tchar_t>          tistream;
    typedef basic_ostream<tchar_t>          tostream;
    typedef basic_iostream<tchar_t>         tiostream;
    typedef basic_stringbuf<tchar_t>        tstringbuf;
    typedef basic_istringstream<tchar_t>    tistringstream;
    typedef basic_ostringstream<tchar_t>    tostringstream;
    typedef basic_stringstream<tchar_t>     tstringstream;
    typedef basic_filebuf<tchar_t>          tfilebuf;
    typedef basic_ifstream<tchar_t>         tifstream;
    typedef basic_ofstream<tchar_t>         tofstream;
    typedef basic_fstream<tchar_t>          tfstream;
}

Conversion to and from CString, LPTCSTR or LPTSTR is plain simple. The most important aspect is that no character conversion is necessary.

Conversion from CString to std::tstring:

CString     cstr(_T("test"));
std::string std_str(cstr);

Conversion from std::tstring to CString:

std::string std_str(_T("test"));
CString     cstr(std_str.c_str());