Customize Zinnia’s look and feel¶
The templates provided for Zinnia are simple but complete and as generic as possible. You can easily change them by specifying a template directory. If you are not familiar with Django, part two of the excellent Django tutorial explains in details how to customize the look and feel of the admin app: it’s actually the same thing in Zinnia.
A good starting point is to copy-paste the zinnia/base.html template, and edit the extends instruction in order to fit into your skin.
Note
- The main content is displayed in a block named content.
- Additional data is displayed in a block named sidebar.
You can also create your own app containing some Zinnia’s templates based on inheritance. For example you can find these two applications which aim to turn Zinnia’s templates HTML5 ready, which can be a good starting point to make your own at:
Warning
Changed in version 0.9.
Django Blog Quintet is no longer compatible with Zinnia, but is still a good example.
Now that we have seen the basic mechanisms to add and customize Zinnia’s templates we will see in details the different possibilities in the customization process.
CSS customizations¶
Most of the time the customization process of Zinnia is about editing the cascading style sheet of the differents pages delivered by the Weblog.
First of all you have to note that each page of the Weblog has several classes applied on the <body> markup. For examples if the document has paginated entries, the paginated and page-{id} classes will be added. Many classes are used within the default templates so should take a look on it, maybe it will be useful for you.
Secondly all the documents served by Zinnia have the zinnia class name on the <body>. If you remove this class, all the default CSS provided by Zinnia will not be applied. And if you add it on templates provided by third-party applications, the Zinnia’s style will be applied. Pretty useful, for enabling or disabling Zinnia’s default style.
Of course adding or removing classes can easily be done in your own templates by overriding the block named body-class.
You also have to note that a real effort has be done for providing clean and valid HTML documents, without redondant and useless classes or IDs overweighting the document respecting the presentation-free markup rule.
Now that you have all of these information in mind, you can add new cascading style sheets into your templates, containing your customization rules and of course remove the default CSS files provided by Zinnia if needed.
Compass and Sass¶
If you take a look at zinnia/static/zinnia/css/screen.css you will probably notice that the CSS is compressed. It has been generated by Compass and it is good pratice not to edit this file directly.
All the CSS documents are actually generated by the awesome Compass tool and you must take a look on this video tutorial if your are not familiar with it.
Compass is an open-source CSS authoring framework which uses the Sass stylesheet language to make writing stylesheets powerful and easy.
Aside of zinnia/static/zinnia/css directory, you can see another directory named sass which is organized like this:
sass/
|-- screen.scss
|-- config
|-- mixins
`-- partials
The partials folder contains all the partials used to build the CSS, the mixins folder contains reusable mixins like the tag-cloud and finally the config folder contains all the configurable variables. screen.scss will include all these files into a single CSS document.
This organization allow you to easily customize the default Zinnia’s CSS by doing a copy of these files or reuse some parts of the Zinnia’s CSS into third-party templates.
Special templates¶
Since the beginning of Zinnia, the development has been influenced by the idea of Power templates for easy rendering. Customizing all the templates of the Weblog must be possible, easy and fast. So Zinnia has a unique feature for returning custom templates depending on the view’s context.
Templates for filters¶
Zinnia as a complete Weblog application provides views for filtering the last entries by authors, categories and tags. In these views you have the possibility to use a dedicated template related to the filtering model. This feature is useful for highlighting a special category or for providing a template per author.
Each of these views will return a list of templates name to render the page but only the first template name matching to an existing template will be used to render.
Examples:
For the URL /blog/categories/events/ the CategoryDetail view will be called and return this list of template names:
['zinnia/category/event/entry_list.html', 'zinnia/category/event_entry_list.html', 'zinnia/category/entry_list.html', 'zinnia/entry_list.html']
For the URL /blog/tags/featured/ the TagDetail view will be called and return this list of template names:
['zinnia/tag/featured/entry_list.html', 'zinnia/tag/featured_entry_list.html', 'zinnia/tag/entry_list.html', 'zinnia/entry_list.html']
For the URL /blog/authors/keneda/ the AuthorDetail view will be called and return this list of template names:
['zinnia/auhtor/keneda/entry_list.html', 'zinnia/author/keneda_entry_list.html', 'zinnia/author/entry_list.html', 'zinnia/entry_list.html']
Templates for archives¶
Concerning the archive views the same feature is implemented, a list of template names will be returned depending of the date and the archive period. This feature take all his sense if want to use Halloween or Christmas templates for your Weblog. With this feature you can also program and re-use your themes on several periods.
Another side effect is if you write an Entry during the Halloween period with dedicated templates, even after the Halloween period the templates will still be used.
Examples:
For the URL /blog/2012/week/16/ the EntryWeek view will be called and return this list of template names:
['zinnia/archives/2012/week/16/entry_archive_week.html', 'zinnia/archives/week/16/entry_archive_week.html', 'zinnia/archives/2012/entry_archive_week.html', 'zinnia/archives/entry_archive_week.html', 'zinnia/entry_archive_week.html', 'entry_archive_week.html']
For the URL /blog/2012/04/21/my-entry/ the EntryDetail view will be called and return this list of template names:
['zinnia/archives/2012/04/21/entry_detail.html', 'zinnia/archives/month/04/day/21/entry_detail.html', 'zinnia/archives/2012/day/21/entry_detail.html', 'zinnia/archives/day/21/entry_detail.html', 'zinnia/archives/2012/month/04/entry_detail.html', 'zinnia/archives/month/04/entry_detail.html', 'zinnia/archives/2012/entry_detail.html', 'zinnia/archives/entry_detail.html', 'zinnia/entry_detail.html', 'entry_detail.html']
Templates for entry detail¶
Each entries of the Weblog has the possibility to have his own template to be rendered by using the ZINNIA_ENTRY_TEMPLATES settings, so with this option you can handle multiple presentation of your entries.
But if you have followed the latest example about the archives templates, you must have seen that even the EntryDetail view implement a custom list of templates, because this view is based on the archives.
So if I use the custom.html template to render the entry located at the URL /blog/2012/04/21/my-entry/ the list of template names will be:
['zinnia/archives/2012/04/21/custom.html',
'zinnia/archives/month/04/day/21/custom.html',
'zinnia/archives/2012/day/21/custom.html',
'zinnia/archives/day/21/custom.html',
'zinnia/archives/2012/month/04/custom.html',
'zinnia/archives/month/04/custom.html',
'zinnia/archives/2012/custom.html',
'zinnia/archives/custom.html',
'zinnia/custom.html',
'custom.html']
Changing templates¶
Maybe CSS customizations and adding markup to the templates is not enough because you need to change a more important part of the templates or you simply don’t want to use it.
Because all the front views bundled in Zinnia are customizable, changing the template used to render the view is pretty easy and can be a good solution for you if you are confortable with Django.
Example of changing the default template for the search view by another view:
from zinnia.views.search import EntrySearch
class CustomTemplateEntrySearch(EntrySearch):
template_name = 'custom/template.html'
or directly in the urls:
from django.conf.urls import url
from django.conf.urls import patterns
from zinnia.views.search import EntrySearch
urlpatterns = patterns(
'',
url(r'^$', EntrySearch.as_view(
template_name='custom/template.html'),
name='zinnia_entry_search'),
)
Going further¶
As you can see that you can customize the look and feel of Zinnia by CSS, SASS, HTML and Python and even by adding custom views. So why don’t you make a Python package containing a Django application of your complete theme ? The theme of your weblog will be sharable and easily installable. You can take a look at Zinnia-theme-html5 to have a good starting point of a packaged theme.
Project Versions
RTD Search
Full-text doc search.