Ella CMS¶

Dependencies¶

We assume that python, setuptools and python-imaging (PIL) are installed on your system directly since they can be non-trivial to install the python way. We will be working with pip and virtualenv which are great tools for any Python project.

First we need to install virtualenv (under root):

easy_install virtualenv

Now we can create and activate a virtualenv where our project and all related code will reside:

virtualenv ella_sandbox
source ella_sandbox/bin/activate

Next, install Ella into your fresh virtualenv. Ella has all it’s dependencies covered in it’s setup, so it’s fairly sufficent to run following command using pip:

pip install ella

After these steps, everything required is ready and we can create a new Django project using Ella in standard Django way:

mkdir ellablog
cd ellablog
django-admin.py startproject ellablog

settings.py¶

Our first step in actual code will be adding Ella to your project’s INSTALLED_APPS along with some required settings, the resulting values (unchanged values are omitted) should look similar to this:

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

    'ella.core',
    'ella.photos',
    'ella.articles',
)
...

In order to create our new blog, we are gonna need some HTML templates showing post listings, post details, hompage etc. Therefore, we have to tell Django, where to look for those templates. This settings are kept in settings.py contained in root of our project. Second, we need to specify a directory + URL used to serve media files from:

from os.path import join, dirname

PROJECT_ROOT = dirname(__file__)

# set the templates directory
TEMPLATE_DIRS = (
    join(PROJECT_ROOT, 'templates'),
)

# give Django media settings
MEDIA_ROOT = join(PROJECT_ROOT, 'media')
MEDIA_URL = '/media/'

This will tell Django, that it should look for the templates in directory templates which is located in the root of the project directory. And store the media in PROJECT_ROOT/media/ directory.

urls.py¶

Last thing to configure is the URL mappings. We want to include ella.core.urls which handle all the Ella magic but also create some mappings that will serve our static files (and static files for admin) in the development server. Note that these patterns for static files will work only when DEBUG mode is turned on since it would be rather inefficent in production (for more on this topic, see Managing static files section in Django docs). In similar fashion, serve also media files discussed in previous paragraph:

from django.conf.urls.defaults import *
from django.conf import settings
from django.contrib import admin
from django.contrib.staticfiles.urls import staticfiles_urlpatterns

# make sure to import ella error handlers
from ella.core.urls import handler404, handler500

# register apps for Django admin and let the apps do any initialization they need
from ella.utils.installedapps import call_modules
call_modules(('admin', 'register', ))

urlpatterns = patterns('',)

# actual URL mappings
urlpatterns += patterns('',
    # serve media files
    (r'^%s/(?P<path>.*)$' % settings.MEDIA_URL, 'django.views.static.serve', { 'document_root': settings.MEDIA_ROOT, 'show_indexes': True }),

    # run Django admin
    (r'^admin/', include(admin.site.urls)),

    # enable Ella
    (r'^', include('ella.core.urls')),
) + staticfiles_urlpatterns()

Database¶

Last configuration step is the database settings. Ella supports all Django DB backends. Example configuration for MySQL can look like this:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'ellablog',
        'USER': 'user',
        'PASSWORD': '',
        'HOST': '',
        'PORT': '',
    }
}

To make this work, you should make appropriate database by your custom DB-related tool (such as command-line tool mysql in Linux-like operating systems). After creating the database, you can proceed with creating all the required tables by Django for you (and admin user during this process):

python manage.py syncdb

Congratulations, you should have a working Ella project. If you start the development server by typing:

python manage.py runserver

try to load the site’s root. If everything worked out, you should get a welcome screen looking similar to this:

Now when we have a working project, we need to actually create the site in the admin interface. To use it, go to /admin/ and log in using credentials you entered when creating your superuser account during the syncdb command. While being there we will also create an article - our very first blog post so that we can actually have something to work with in our templates in the next step of the tutorial.

First we need some theory on how Ella handles sites, categories and published objects though.

Ella sites and categories¶

Ella was designed to serve several sites from a single database. It does so by using Django’s built-in sites framework. The sites app creates a default Site called example.com during the syncdb command. Just rename the domain name to relevant value and you will have an Ella site, just empty.

Within sites, Ella organizes content into categories. Categories (instances of ella.core.models.Category) are organized in a tree for each site. Every site needs to have exactly one what we call root category - a category without a parent. This category then represents the root of the website (/).

Categories are represented by their tree_path - a path of slugs from root category, for example with categories layout:

Ella Blog
    About
    Technology
        Concepts
        Django
            Django applications
        Typical deployment env

the tree_path values would be:

Category‘s URL is it’s tree_path (which is what makes the root category the root of the site) and every post in Ella belongs to one or more categories, nothing shall exist outside of the category tree.

Publishable object¶

The main objective of Ella is publishing content. Ella together with it’s plugins provides several types of content (Article, Gallery, Quiz, ...) and can be easily extended to add more (just define the model) or used with existing models.

For ease of manipulation and efficiency, all content models inherit from ella.core.models.Publishable. This base class has all the fields needed to display a listing of the content object (title, description, slug, photo), basic metadata (category, authors, source). When using Ella API you will always receive an instance of the actual class (Article) and not the base class (Publishable). If you have access to only a Publishable instance the target property will return instance of the correct class (it holds a reference to it’s ContentType).

Information about publication are also kept on the Publishable model (attributes published, publish_from, publish_to and static). All these information together are used to create an URL for the object which will point to it’s detail (e.g. article content). There are two types of publication with slightly different use cases:

• time-based has URL containing the date of publishing and should be used for objects that have some relevance to date (most of the content presumably since Ella was designed to power magazines and news sites). The URL of an object published in time-based way will look like:

  /category/tree/path/[YEAR]/[MONTH]/[DAY]/[CONTENT_TYPE_NAME]/slug/
  

  so for example:

  /about/2007/08/11/ella-first-in-production/
  

• static has no date in it’s URL and should be used for objects with universal validity. URL of statically published objects contains a primary key reference to avoid namespace clashes:

  /category/tree/path/[PK]-slug/
  

  for example:

  /about/1-ella-first-in-production/
  

Just setting up publish information for a Publishable object makes it visible (starting from publish_from) but doesn’t make it appear in any listing in any Category. For that you need to specify in which categories you want it listed.

Listing object¶

ella.core.models.Listing instances carry the information in which Category and when should be a publishable object listed - it enables users to list the object in as many categories as they wish at arbitrary times (but not sooner that the Publishable.publish_from).

By default, listings in the root category only contain Listings specifically targeted there whereas listings for any subcategory also contains all the listings of it’s subcategories. This is a model we found most useful when working with large sites where the site’s homepage needs to be controlled closely by editors and the interim categories only serve as aggregators of all the content published in them either directly or via a subcategory.

Creating a site¶

Now you should have enough information to be able to start exploring the admin (found on /admin/) and create your own site and it’s first post. You will know that you were succesfull if you manage to create and publish an article whose URL gives you a TemplateDoesNotExist exception upon accessing - that means we are ready to create some templates.

page/category.html¶

First we will create a template rendering a category: page/category.html. This is a default template that will be used for all categories if their specific template (one with their path) isn’t found. The two most important variables in the context we want to use is {{ category }} containing the Category model itself and {{ listings }} containing a list of Listing objects for that category ordered by publish_from and/or priority.

The basic template will look like:

<h1>Welcome to category {{ category.title }}</h1>
<p>{{ category.description }}</p>

{% for listing in listings %}
    <p>
        <a href="{{ listing.get_absolute_url }}">{{ listing.publishable.title }}</a>
        {{ listing.publishable.description|safe }}
    </p>
{% endfor %}

That will render the category title, description and a list of objects published in that category. Upon accessing / you should then see the name of the category and the article you created in administration.

page/listing.html¶

This template represents the archive, it gets the same context as page/category.html and the same code can be used. We will use the same code:

{% extends "page/category.html" %}

page/object.html¶

As with page/category.html, page/object.html is a fallback template that will be used for rendering any object if more suitable template isn’t found. In real life we will probably have different templates for different content types, but to verify the concept and get us started a simple template should be enough:

<h1>{{ object.title }}</h1>
<p>Published on {{ placement.publish_from|date }} in category: <a href="{{ category.get_absolute_url }}">{{ category }}</a></p>
{% render object.description %}

This template will have access to the actual Publishable subclass instance (Article in our case), as opposed to page/category.html and page/listing.html which only gets instance of Publishable by default.

Note the use of {% render %} templatetag that is used to render rich-text fields (which object.description is) thorought Ella.

Error pages¶

By importing handler404 and handler500 in our urls.py, we turned over the control of error pages to Ella. This means that we need to create two additional templates: page/404.html:

<h1>Oops, nothing here</h1>

and page/500.html:

<h1>If you see this, let us please know how you did it, thanks!</h1>

Now that we have a set of rudimentary templates, we can try doing something useful with them.

Boxes¶

First change we will make is abstract the rendering of the object listing on category homepage and archive. To do this, Ella provides a Box for individual objects. It’s primary use is as a templatetag. Boxes can be rendered for objects accessible through a variable or through a database lookup:

{% box <box_name> for <object> %}{% endbox %}
    or
{% box <box_name> for <app.model> with <field> <value> %}{% endbox %}

What {% box %} does is a little more then fancy include - it retrieves the object, find the appropriate template and renders that with object-specific context. The context can be quite different for an Article or Photo gallery. Boxes are usually used throughout an Ella site to provide maximum flexibility in rendering objects and also for embedding objects into rich text fields stored in the database (in text of an article for example). Some applications ( Defining positions on the page for example) also use boxes to represent objects.

To create our first box, we just need to create a template called box/listing.html containing:

<p>
    <a href="{{ object.get_absolute_url }}">{{ object.title }}</a>
    {% render object.description %}
</p>

And change page/category.html to use the box instead of manually specifying the output:

<h1>Welcome to category {{ category.title }}</h1>
<p>{{ category.description }}</p>

{% for listing in listings %}
    {% box listing for listing %}{% endbox %}
{% endfor %}

If you still struggle, why the bloody Box is used instead of standard {% include SOMETHING %}, keep in mind following advantages:

• They know which template to use with proper fallback engine.

• The provide class-specific context so that an Article can have

  different context than Photo.

Template fallback mechanisms¶

In last step we created a few templates that should suffice for an entire site based on Ella. In real life you probably wouldn’t want every category and every object to share the same template. Ella provides a simple mechanism to target your templates more directly.

Let’s say that we want to create a specific template for rendering articles, just create a template called page/content_type/articles.article/object.html and you are done - next time you visit some article’s URL, this template will get rendered instead of your page/object.html. This template would be a good place to render the text of an article for example:

{% extends "page/object.html" %}
{% block content %}
    {% render object.content %}
{% endblock %}

Now if you just define the appropriate block in your page/object.html:

<h1>{{ object.title }}</h1>
<p>Published on {{ object.publish_from|date }} in category: <a href="{{ category.get_absolute_url }}">{{ category }}</a></p>
{% render object.description %}

{% block content %}{% endblock %}

You should be able to see your article’s text on the web.

Another way you can override your templates is based on Category. For example if you want to create a custom template for your root category (and your root category’s slug is ella-blog), just create one called page/category/ella-blog/category.html:

<h1>Welcome to site {{ category.site }}</h1>
<p>{{ category.description }}</p>

{% for listing in listings %}
    {% box listing for listing %}{% endbox %}
{% endfor %}

You will be greeted into the site and not your root category next time you visit the root of your blog. Just create any subcategory to check it will remain unaffected.

You can use the same simple mechanism (creating new templates) to change the look of your boxes for individual objects as well.

Selecting template for a category¶

When selecting templates for a rendering of category, Ella uses this set of rules:

1. Look at the tree_path. Try to find a template in page/category/[TREE_PATH]/category.html.

   Example:

   http://www.example.com/category/subcategory/

   Ella would first try to find page/category/category/subcategory/category.html.

2. If template was not found in previous step, try to find the template of an direct ancestor providing we have one and it’s not the root category.

   Examples:

   http://www.example.com/category/subcategory/subsubcategory/

   First, try page/category/category/subcategory/category.html, next try page/category/category/category.html and stop because the category "category" is the main one.

   http://www.example.com/category/subcategory/

   Try page/category/category/category.html and stop.

   http://www.example.com/category/

   Would not try anything, we are already in main category.

   http://www.example.com/

   Would not try anything, we are in root.

3. If template wasn’t found yet, use default template (which is page/category.html in most cases).

Selecting template for an object¶

Selecting template for an object adds even more possibilities for the developer. It also uses content_type in form of app_label.model_label (both lowercased). Example would be: articles.article, videos.video and so on.

1. Try to find a template in page/category/[TREE_PATH]/content_type/[CONTENT_TYPE]/object.html.
2. Try to find a template in page/content_type/[CONTENT_TYPE]/object.html.
3. Continue in the same way as when selecting a category template except for using object.html instead of category.html.

Selecting template for a box¶

Lookup for boxes is done in "box" subdirectory. It then works exactly the same as for objects, except that the template name is the name of the box being rendered and last resort is template box/box.html.

Working with category templates¶

When creating category templates, here are some basic rules you can count on:

The template used is by default category.html using the template fallback mechanism (for details on that, see Template fallback mechanisms). You can set the different template for your category using administration. For details and explanation of the whole concept, have a look at Defining custom template for category.

Context will always contain at least:

The basic scenario when building up site’s category templates is following:

1. Create the base template page/category.html. Make this template as generic as possible to enable nice inheritance. Most often, this category will be created as generic, paginated, content listing as seen on most sites using articles.
2. Create customized template for homepage since it has different layout in most cases. Use proper fallback to tell Ella that it should use a different template for HP. It’s as simple as putting the template to page/category/[YOUR_HP_SLUG]/category.html. Also, practice inheritance, make this template using {% extend "page/category.html" %}.
3. Create other category templates that need customization. You will most likely end up building some static pages.

Homepages¶

In Ella, a homepage is recognized as the category, that has no parent. Therefore, it is also the root category. Only one such page is allowed for each site that is contained in database.

The URL of homepage is always “/”, so for a domain example.com, full URL of root category would be of course the root of the whole site:

http://www.example.com/

When working with category templates, homepage will set the variable is_homepage in the template’s context to True. Thanks to it, something like this is possible:

<!-- in page/category.html -->
{% if is_homepage %}
   This is homepage category.
{% else %}
   This is not a homepage.
{% endif %}

This makes it very easy to have only one template which covers most of the category pages including homepage. However, you should always consider splitting the HP-specific code to it’s own template when the HP layout is completely different from other categories. This would make your templates much more readable which is always a good thing.

Other categories¶

In most Ella sites, categories other than HP usually serve for content listings or static pages. We’ll demonstrate the basic code for content listing for the sake of completness.

{% extends "page/base.html" %}

{% block content %}
    {% block object_listing %}
        {% listing 10 for category as category_listing %}
        {% for l in category_listing %}
            {% box listing for l.publishable %}{% endbox %}
        {% endfor %}
    {% endblock %}
    {% block pagination %}
       {% if is_paginated %}{% paginator 5 %}{% endif %}
    {% endblock %}
{% endblock %}

Defining custom template for category¶

By default, template used for rendering category is category.html. You can override this behavior to use your custom template. This can be useful when you need to implement several different layouts for your categories. Suppose we have following layouts:

• Top 4 articles, then listing of 6 more
• Listing of 10 articles without top ones
• Listing of 10 articles without perexes, only big images

If it wasn’t possible to select a template for category, you would need to override the template for each category diferrent from the base one (let it be the first one). Using different templates, you can avoid doing so. First, define the templates in your settings.py:

# in settings.py
CATEGORY_TEMPLATES = (
    ('category.html', 'default (top 4 + listing 6)'),
    ('category_10.html', 'top 10'),
    ('category_10_no_perex.html', 'top 10 w/o perexes'),
)

Next, create the base template. That would be category.html. It would be used, when not set otherwise in your Ella administration:

<!-- in page/category.html -->
{% extends "page/base.html" %}

{% block object_listing %}
    <!-- show 4 boxes with big images -->
    {% listing 4 for category as category_listing %}
    {% for l in category_listing %}
        {% box listing_big_image for l.publishable %}{% endbox %}
    {% endfor %}

    <!-- show 6 more regular boxes -->
    {% listing 6 from 4 for category as category_listing %}
    {% for l in category_listing %}
        {% box listing for l.publishable %}{% endbox %}
    {% endfor %}
{% endblock %}

Then, you would create category_10.html template to show only ten same boxes for listing:

<!-- in page/category_10.html -->
{% extends "page/category.html" %}

{% block object_listing %}
    <!-- show 10 same boxes -->
    {% listing 10 for category as category_listing %}
    {% for l in category_listing %}
        {% box listing for l.publishable %}{% endbox %}
    {% endfor %}
{% endblock %}

Finally, create the last category_10_no_perex.html template, that would define the last layout:

<!-- in page/category_10_no_perex.html -->
{% extends "page/category.html" %}

{% block object_listing %}
    <!-- show 10 boxes without perexes -->
    {% listing 10 for category as category_listing %}
    {% for l in category_listing %}
        {% box listing_no_perex for l.publishable %}{% endbox %}
    {% endfor %}
{% endblock %}

This way, you don’t need to override template for each of different categories, you just set the layout in your administration. Also, this is widely used when it comes to creating Static pages that don’t ever change.

Object detail URL¶

The URL of Publishable object detail depends on publication type. As we already mentioned in Quickstart, there are two:

• time-based publication is limited by publish_from - publish_to period. Outside of these time boundaries, object won’t be reachable on the website. Most websites only use publish_from so that the object won’t disappear.
• static publication is not limited by time and thus it is unlimited and permanent. Such object will be always reachable on the website.

With time-based publications, objects are given a date stamp in the URL so the namespaces clashes doesn’t happen very often. URL structure goes like:

/category/tree/path/[YEAR]/[MONTH]/[DAY]/[CONTENT_TYPE_NAME]/slug/

So for an example, /about/2007/08/11/articles/ella-first-in-production/ could be proper result of time-based publication.

With static publication, no date stamp is used. Instead, object’s primary key is prepended before slug to avoid name conflicts. URL structure looks like this:

/category/tree/path/[CONTENT_TYPE_NAME]/[PK]-slug/

And a valid result could be /about/articles/1-ella-first-in-production/.

Using positions in your pages¶

Position is defined in the admin interface and used from the templates via two templatetags.

{% position POSITION_NAME for CATEGORY [using BOX_TYPE] [nofallback] %}
  ...
{% endposition %}

{% ifposition POSITION_NAME ... for CATEGORY [nofallback] %}
    POSITION EXISTS!
{% else %}
    NO POSITION DEFINED!
{% endifposition %}

<!-- in page/category.html -->
{% load positions %}
...

{% block right_column %}
    {% position rightcol_poll for category %}{% endposition %}
{% endblock %}

...

Generating thumbnails in the tempalates¶

The {% img %} template tag is used to get a thumbnail for original Photo object. It is smart enough to use all the meta info defined on Photo, so the important box is taken into account.

Syntax:

{% img <FORMAT> for <VAR> as <VAR_NAME> %}
{% img <FORMAT> with <FIELD_VALUE> as <VAR_NAME> %}

Templatetag supports two approaches. First is very simple, you just give it a Photo instance and it will generate thumbnail for it. The second one tries to find a Photo you describe by FIELD_VALUE. See the examples:

{% img category_listing for object.photo as thumb %}
{% img category_listing with pk 1150 as thumb %}

The result (stored as thumb in the example above) then contains a FormatedPhoto instance. This means you can access it’s attributes, particularly url method and width and height.

Workflow¶

The basic workflow when using photos goes like this:

1. Define formats. This step is usually already done when you enter the stage as the designer is reponsible for it in most cases. We only need to enter the data to the Ella database.

2. Store the formats in fixtures is quite important step, because it makes development much easier when a more than one developer is involved. It makes sense to add the fixture as initial data because it shouldn’t be altered in database without an intent.

3. Use image boxes in your templates. For the thumbnails, use boxes. The snippet below shows how you can embed photos using boxes in an object box we used in Category detail page section.

   <!-- in box/listing.html -->
   <div class="article">
       <h2><a href="{{ object.get_absolute_url }}">{{ object }}</a></h2>
       {% if object.photo %}
           <a href="{{ object.get_absolute_url }}" title="{{ object.title }}">
               {% box category_listing for object.photo %}{% endbox %}
           </a>
       {% endif %}
   </div>
   

4. Use image templatetag to generate thumbnails. When the photo is embedded, the last remaining step is to generate thumbnails so the photo will fit on the page nicely. To do this, use {% image %} template tag.

   <!-- in box/content_type/photos.photo/category_listing.html -->
   {% load photos %}
   
   {% block image_tag %}
       {% image object in "200x100" as image %}
       <img src="{{ image.url }}" alt="{% firstof title object.title %}" width="{{ image.width }}" height="{{ image.height }}" />
   {% endblock %}
   

Using placeholder images during development¶

It is quite common that during development of the Ella application, one doesn’t always have all the photos stated in database on his HDD. This can happen when you share one database dump with co-workers and someone adds new articles etc.

In order to show at least something, Ella provides debugging setting which will replace the missing image files by placeholder images. You can enable this by setting PHOTOS_DEBUG = True in your project settings. By default, Ella will use web service http://placehold.it to generate the images. Optionally, you can use your custom placeholder service by changing the PHOTOS_DEBUG_PLACEHOLDER_PROVIDER_TEMPLATE to your own. Use something like this:

DEBUG_PLACEHOLDER_PROVIDER_TEMPLATE = 'http://placehold.it/%(width)sx%(height)s'

What are related objects?¶

By related objects, we understand publishable objects which have some relation between them. They can be related in various ways, for example:

• belong to the same category
• have a same topic
• have similar tags attached to them
• have same author
• have same source

Showing such related content is very common on news sites because it helps to link the content and also, it is very SEO friendly.

Ella has simple but powerful interface for querying such relations and the core module also implements some basic ones.

{% related %} template tag¶

Related template tag is ment for simple access to the related queries from within your templates. It fills up a given variable with list of publishable objects that were collected by the finder functions defined for the project(see Related finders for more details). When no query_type is given, default will be used.

Usage:

{% related <limit>[ query_type] [app.model, ...] for <object> as <result> %}

Parameters:

Examples:

{% related 10 for object as related_list %}
{% related 10 directly articles.article, galleries.gallery for object as related_list %}

Conventions¶

AppDataField recognizes namespaces for different applications. The access is not limited though so that any application can access any namespace. The namespace is a simple first-level dict key (e.g. ‘emailing’ or ‘my_articles’ in the following examples).

To avoid name clashes, we encourage you to follow this convention so that all your custom data is stored by using a key which coresponds to the app label of aplication storing the data, such as:

# in app "emailing"
p = Publishable()
p.app_data['emailing'] = {'sent': False}

# in app "my_articles"
p = Publishable()
p.app_data['my_articles'] = {'custom_title': 'Foobar'}

Custom container classes¶

By default, Ella returns an AppDataContainer class when you access a namespace. This is simply a dict subclass with no additional data except for the information about the model class it is bound to. However, you can provide your own classess for the namespaces. This allows you to create methods working with the your custom data. For example, you can have CommentsDataContainer for your comments application which can provide methods like comment_count.

Registering your custom container class is very simple. The formula is:

from app_data import app_registry
app_registry.register('comments', CommentsDataContainer, Publishable)

Unregistration works the same way:

app_registry.unregister('comments', Publishable)
app_registry.register('comments', SomeOtherDataContainer, Publishable)

Double rendering¶