Logo
en nl

HTML in Paspartout - 1. introduction

last updated: 17/01/2012
difficulty: medium
licenses: Shop, Pro, Biz
Note that you need to have a basic understanding of HTML and probably CSS before you start using this feature.

Introduction

The ability to write your own HTML in Paspartout gives you a lot of freedom. It enables you to create a completely customised layout with a minimum amount of code. You don't need to  hassle with databases or know any server related languages like PHP or Ruby. Paspartout does all the hard work for you so you can focus on the important stuff: creating a beautiful layout.

Liquid

To make all this possible we chose to use Liquid, a simple and easy to understand markup language to create dynamic HTML templates. It might look daunting at first but if you know how to write HTML you will grasp the idea very quickly. Read all about liquid for designers before proceeding.

Graceful fallback

You don't have to be afraid about wrecking your site by modifying the HTML templates. We created a graceful fallback system, which means you can always go back to how it was by deleting the template you created yourself. Paspartout will first look if you have created a template. If it doesn't find one the default template will be used. So if you make an error you can always go back with just one click.

Template types

As you know there are various page types in Paspartout: Portfolio, Blog, About, Post and Project. The Biz and Shop licenses also have a "Regular" page. You can create a template for each page type. With Biz and Shop you can even create a template for a specific page, so you can make every page look different from the others if you want.

Creating a template

Let's jump right into it and start by creating a modified portfolio template. We will dissect the code to give you a better understanding of how this all works. 

To create a new HTML file head over to your theme editor and click on the "html" tab. Click on the "new .html file" button.

Medium-new-html-file
Enter a name in the following dialog, select "portfolio" from the dropdown menu and click on create.

Medium-new-html-file-settings

The new template will now appear in the file column on the left.
Medium-new-html-file-created

Click on the edit button to load the code into the editor. The code you are looking at is a copy of the exact same code used by Paspartout. It will look like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
<div id="portfolio_toolbar" class="portfolio-toolbar">
  <ul class="categories">
    <li class="title">{{ 'category.label' | t }}</li>
    
    {% for category in categories %}
      <li class="{{ category.class }}" id="category_{{ category.id }}">
        <a href="{{ category.url }}">{{ category.name }}</a>
      </li>
    {% endfor %}
    
    {% if category %}
      <li class="all">
        <a href="{{ page.url }}">{{ 'category.show_all' | t }}</a>
      </li>
    {% endif %}
  </ul>
</div>

<ul id="content" class="{{ content_class }}">
  
  {% for project in projects %}
    <li class="{{ project.class }}" id="project_{{ project.id }}">
      
      {% if project.thumb %}
        <a href="{{ project.url }}">
          <img src="{{ project.thumb }}" alt="{{ project.name }}">
        </a>
      {% else %}
        <a href="{{ project.url }}" class="image-replacement">&nbsp;</a>
      {% endif %}
      
      <div class="title">
        <a href="{{ project.url }}">{{ project.name }}</a>
      </div>
      
      <div class="categories">
        {% for category in project.categories %}
          <a href="{{ category.url }}">{{ category.name }}</a>{% unless forloop.last %},{% endunless %}
        {% endfor %}
      </div>
      
    </li>
  {% endfor %}
  
  <li class="clearer">&nbsp;</li>
  
</ul>

<div class="clearer"></div>

{{ pagination }}

Let's have a look at the code. The first part, the div with id "portfolio_toolbar", is hidden by default. It's a toolbar that can be visualised with CSS. But it is unimportant right now so you can delete that part completely:
1
2
3
<div id="portfolio_toolbar" class="portfolio-toolbar">
  ...
</div>
The next part, the div with id "content", is what we are looking for. This is the code visualising the projects on your portfolio page:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<ul id="content" class="{{ content_class }}">
  
  {% for project in projects %}
    <li class="{{ project.class }}" id="project_{{ project.id }}">
      
      {% if project.thumb %}
        <a href="{{ project.url }}">
          <img src="{{ project.thumb }}" alt="{{ project.name }}">
        </a>
      {% else %}
        <a href="{{ project.url }}" class="image-replacement">&nbsp;</a>
      {% endif %}
      
      <div class="title">
        <a href="{{ project.url }}">{{ project.name }}</a>
      </div>
      
      <div class="categories">
        {% for category in project.categories %}
          <a href="{{ category.url }}">{{ category.name }}</a>{% unless forloop.last %},{% endunless %}
        {% endfor %}
      </div>
      
    </li>
  {% endfor %}
  
  <li class="clearer">&nbsp;</li>
  
</ul>

On the first line of that part you wil notice that the class name is filled in with double brackets:

</code><ul id="content" class="{{ content_class }}"><code lang="html">

Here the term "content_class" will be filled in by Paspartout. It is a variabele that will be passed on by the system. Every template has a set of predefined variables that you can use but we will come back to that later on. In this case content_class will define the thumbs size selected in the layout section.
A bit further in you will see this line:

{% for project in projects %}


This is called a for loop. Basically what is does is iterate over a list of items, in this case the variabele "projects". All the HTML placed within the for loop will be generated for every item in the list, in this case every "project". If you created static HTML pages in the past you know you normally would have to write HTML for every project. With dynamic code that is not the case. The code within the for loop will be reused.
Go ahead and change the code by adding a piece of text. For example, I added "TITLE:" before the before the name of the project: 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{% for project in projects %}
  <li class="{{ project.class }}" id="project_{{ project.id }}">
    
    {% if project.thumb %}
      <a href="{{ project.url }}">
        <img src="{{ project.thumb }}" alt="{{ project.name }}">
      </a>
    {% else %}
      <a href="{{ project.url }}" class="image-replacement">&nbsp;</a>
    {% endif %}
    
    <div class="title">
      TITLE:
      <a href="{{ project.url }}">{{ project.name }}</a>
    </div>
    
    <div class="categories">
      {% for category in project.categories %}
        <a href="{{ category.url }}">{{ category.name }}</a>{% unless forloop.last %},{% endunless %}
      {% endfor %}
    </div>
    
  </li>
{% endfor %}


Now try that yourself and and have a look at the portfolio page on your site. You will see that piece of text appear on every project.

Before:

Medium-example-before

After:

Medium-example


Just the beginning

Of course this is just a fraction of the possibilities but it will give you a basic understanding of how HTML templates work in Paspartout. Don't hesitate to experiment and remember you can always go back by deleting the custom template.



related articles

HTML in Paspartout - 2. available variables HTML in Paspartout - 3. specific template HTML in Paspartout - 4. Images