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 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 redundant 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.
Variations on the default theme¶
New in version 0.12.
Beside the zinnia
class name in the <body>
tag of the
zinnia/skeleton.html
template, three other class names are available:
<body class="zinnia default blue right-sidebar {% block body-class %}{% endblock %}">
The default
class name represents the original default theme of
Zinnia. You can remove this class, or replace with the classes light
or
dark
to activate the variations with high readability and contrast,
thanks to the Solarized project.
The blue
class represents the main color used within the
theme. Available color are: yellow
, orange
, red
, magenta
,
violet
, blue
, cyan
, green
.
The right-sidebar
class sets the sidebar at right and left-sidebar
at left, by default if none of these classes are present, the sidebar is
set at right. You can hide the sidebar by using the no-sidebar
class.
With these 3 sets of classes available in the CSS, you now have 4*9*3=108 variations of the default theme available. Try them and choose your favorite!
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/
|-- config/
|-- mixins/
|-- partials/
`-- screen.scss
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. For example the screen.scss
file will include at the
end all the files who belong in these directories into a single compiled
CSS document, named screen.css
.
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.
Because Compass and his librairies evolve, here the actual versions of the gems (Ruby powered !) used to build the CSS documents:
$ gem list
*** LOCAL GEMS ***
chunky_png (1.2.6)
compass (0.12.2)
fssm (0.2.9)
sass (3.2.1)
susy (1.0.1)
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/
theCategoryDetail
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/
theTagDetail
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/
theAuthorDetail
view will be called and return this list of template names:['zinnia/author/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/
theEntryYear
view will be called and return this list of template names:['zinnia/archives/2012/entry_archive_year.html', 'zinnia/archives/entry_archive_year.html', 'zinnia/entry_archive_year.html', 'entry_archive_year.html']
For the URL
/blog/2012/week/16/
theEntryWeek
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/
theEntryDay
view will be called and return this list of template names:['zinnia/archives/2012/04/21/entry_archive_day.html', 'zinnia/archives/month/04/day/21/entry_archive_day.html', 'zinnia/archives/2012/day/21/entry_archive_day.html', 'zinnia/archives/day/21/entry_archive_day.html', 'zinnia/archives/2012/month/04/entry_archive_day.html', 'zinnia/archives/month/04/entry_archive_day.html', 'zinnia/archives/2012/entry_archive_day.html', 'zinnia/archives/entry_archive_day.html', 'zinnia/entry_archive_day.html', 'entry_archive_day.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 for your entries. And
because EntryDetail
is based on an archive
view a custom list of templates is built uppon the publication date.
The entry’s slug is also used to build the template list for having
maximal customization capabilities with ease.
For example 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/my-entry_custom.html',
'zinnia/archives/month/04/day/21/my-entry_custom.html',
'zinnia/archives/2012/day/21/my-entry_custom.html',
'zinnia/archives/day/21/my-entry_custom.html',
'zinnia/archives/2012/04/21/my-entry.html',
'zinnia/archives/month/04/day/21/my-entry.html',
'zinnia/archives/2012/day/21/my-entry.html',
'zinnia/archives/day/21/my-entry.html',
'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/my-entry_custom.html',
'zinnia/archives/month/04/my-entry_custom.html',
'zinnia/archives/2012/month/04/my-entry.html',
'zinnia/archives/month/04/my-entry.html',
'zinnia/archives/2012/month/04/custom.html',
'zinnia/archives/month/04/custom.html',
'zinnia/archives/2012/my-entry_custom.html',
'zinnia/archives/2012/my-entry.html',
'zinnia/archives/2012/custom.html',
'zinnia/archives/my-entry_custom.html',
'zinnia/my-entry_custom.html',
'my-entry_custom.html',
'zinnia/archives/my-entry.html',
'zinnia/my-entry.html',
'my-entry.html',
'zinnia/archives/custom.html',
'zinnia/custom.html',
'custom.html']
Now you have the choice !
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. Remember to take a look at Zinnia-theme-html5 for having a good starting point of a packaged theme.