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 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!
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_DETAIL_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 !
Templates for entries’ content¶
Imagine that you have different kind of entries, some with photos, some with videos or even with tweets. You might not want to share the same presentation between these different entries.
An elegent solution to better highlight the content is to use different templates for each kind of content or presentation you want.
You can easily do this by using the ZINNIA_ENTRY_CONTENT_TEMPLATES
.
It allows you to specify a content template for each entries of your blog
using the administration interface.
Templates within loops¶
When displaying a list of entries the templates are chosen according to
ZINNIA_ENTRY_CONTENT_TEMPLATES
.
But how can we specify a template for a given index position the list ? For example if we want to highlight the first entry.
Then we simply create a new template suffixed by a dash followed by the position.
Example: zinnia/_entry_detail-1.html
If we use an underscore instead of a dash the position will reset at every new page. Replacing the dash by an underscore in the previous example would highlight the first entry of every page.
You can bypass this behavior altogether and have more control over your
templates by using the ZINNIA_ENTRY_LOOP_TEMPLATES
setting.
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='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-bootstrap for having a good starting point of a packaged theme.