How to customize Quokka CMS home page template

Bruno Rocha Uncategorized

How to customize quokka CMS templates

So you want to create a website using Quokka CMS but this website will not use the default ‘blogging like’ template that is the default CMS theme.

You can use Quokka to create any kind of website that handle dynamix content, the only thing you need is to create the desired channels and customize some jinja2 templates.

Take a look at this example of fundraising campaign website done with quokka: http://www.natalanimal.com.br this an e-commerce like app using quokka-fundraising and quokka-cart modules, this website customized the templates for ‘home’ channel as it looks like a web portal.
(the source code for this template is available in: https://bitbucket.org/rochacbruno/natal-theme/)

Now lets create a sample website to our fake company that looks more like an institutional home-page than a blog.

Environment

If you do not have a quokka environment yet, lets start creating one, you will need a running instance of MongoDB as you can find more instructions here

And you will need git plus python 2.7 and virtualenvwrapper

git clone https://github.com/quokkaproject/quokka
cd quokka
mkvirtualenv quokka
pip install -r requirements.txt

NOTE: if your MongoDB is running externally you may need to change the MONGODB_HOST = xxx.xxx.x.x in a file called local_settings.py or you can export as an environment variable export QUOKKA_MONGODB_HOST=xxx.xxx.x.x

Populate sample data and run the local server

python manage.py populate
python manage.py runserver --reloader --debug

Now you should be able to see your running site in http://localhost:5000, as you can see your Quokka site looks like a blog because it uses the default theme, now we are going to customize this theme.

Hit CTRL+C to stop the running server and lets make a copy of current theme.

cp -r quokka/themes/pure quokka/themes/custom
export QUOKKA_DEFAULT_THEME="custom"

you can also put DEFAULT_THEME = ‘custom’ in your local_settings.py if you created one.

lets create a new channel

Now run the website again

python manage.py runserver --reloader --debug

Now access the website admin panel http://localhost:5000/admin using the default populated credentials ‘admin@example.com’ with passwd ‘admin’

Go to the menu Content -> Channel

And create a new channel by clicking in create tab:

Put a name My Home Page and a description in html editor and then click in submit/save at the end of the form.

Your new channel is identified by the slug my-home-page this is the important detail to start customizing the theme.

Back to the channels page select your new channel:

And then click in actions selector with selected -> publish

Select it again and now use with selected -> set as homepage to set the new channel as the site homepage

lets create an about-us page

Access the admin and create a new channel called About Us (which will be identified by the slug about-us) add some text to description and check ‘publish’ and ‘show in menu’ and save it.

Now lets customize the home page template template

Home page:

Create a new template for my-home-page channel.

Quokka themes will try to find specific templates under a folder with the same name as the channel under content folder

mkdir quokka/themes/custom/templates/content/my-home-page

Now copy the default listing template to this folder and customize it

cp quokka/themes/custom/templates/content/default_list.html quokka/themes/custom/templates/content/my-home-page/

Edit the file quokka/themes/custom/templates/content/my-home-page/default_list.html with the following jinja2 code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="icon" href="/favicon.ico">
    <title>{{channel.long_slug.split('/')|join(' | ')}} | {{Config.get('site', 'site_name', 'Quokka site')}}</title>
    <link href="http://getbootstrap.com/dist/css/bootstrap.min.css" rel="stylesheet">
    <link href="http://getbootstrap.com/examples/justified-nav/justified-nav.css" rel="stylesheet">
    <script src="http://getbootstrap.com/assets/js/ie-emulation-modes-warning.js"></script>
  </head>
  <body>
    <div class="container">
      <div class="masthead">
        <h3 class="text-muted">{{Config.get('site', 'site_name', 'Quokka site')}}</h3>
        <nav>
          <ul class="nav nav-justified">
            <li class="active"><a href="/">Home</a></li>
            {% for channel in channels.filter(show_in_menu=True)%}
            <li><a href="{{channel.get_absolute_url()}}">{{channel.title}}</a></li>
            {% endfor %}
          </ul>
        </nav>
      </div>
      <div class="jumbotron">
        <h1>{{channel.title}}</h1>
        <p class="lead">{{channel.get_text()|safe}}</p>
        <p><a class="btn btn-lg btn-success" href="#" role="button">Welcome!</a></p>
      </div>
      <div class="row">
        {% for content in contents.items[0:3] %}
        <div class="col-lg-4">
          <h2>{{content.title}}</h2>
          <p class="text-danger"></p>
          <p>{{content.get_summary()|safe}}}} </p>
          <p><a class="btn btn-primary" href="{{content.get_absolute_url()}}" role="button">View details &raquo;</a></p>
        </div>
        {% endfor %}
      <footer class="footer">
        <p>&copy; Powered by Quokka CMS</p>
      </footer>
    </div> <!-- /container -->
    <script src="http://getbootstrap.com/assets/js/ie10-viewport-bug-workaround.js"></script>
  </body>
</html>

Now restart the server and go to the http://localhost:5000 to see yout new homepage template in action.

You can do the same as above for the about-us if needed, but note that empty channels will render its html description, so you don´t need to customize it if html description is enough

Now if you wish, you can customize the other templates located in content folder to follow the same pattern and you will have a completely modified Quokka CMS theme.

As you can see it is very easy to deal with templates in Quokka CMS because it uses Quokka-Themes extension and just pure Jinja2 templates.