|
| 1 | +.. title: Creating a Custom Page |
| 2 | +.. slug: creating-a-custom-page |
| 3 | +.. date: 2015-09-12 16:20:30 UTC |
| 4 | +.. tags: tutorial |
| 5 | +.. type: text |
| 6 | +.. author: Roberto Alsina |
| 7 | +
|
| 8 | +The Nikola team tries very hard to make Nikola be simple, in a very specific way: |
| 9 | + |
| 10 | +Once the user has things setup, doing the same thing again should take no work. |
| 11 | +So, if you have done one image gallery, doing a second one should be just creating |
| 12 | +a folder and putting images in it. If you have written a blog post, writing a new |
| 13 | +one is running one command and editing the text you want to publish. And so on. |
| 14 | + |
| 15 | +But sometimes, you don't want to do the same thing you have been doing. Sometimes you |
| 16 | +want to make a one-off, a special thing, and Nikola should not get in the way |
| 17 | +of you doing that, either, and should let you get your hands as dirty as you want. |
| 18 | + |
| 19 | +So, this tutorial is about how to do a page that is totally different from all the |
| 20 | +other pages in your site. A custom page. |
| 21 | + |
| 22 | +Our goal for today is to make a page where it's nice to read a book. Specifically, |
| 23 | +a book of late victorian fiction called "Dr. Nikola's Vendetta" [1]_ because, how |
| 24 | +could we resist using that one, right? And to make it maintain, within reason, |
| 25 | +the "style" of the original book. |
| 26 | + |
| 27 | +It's the first in a series of five books about Dr. Nikola, one of the first |
| 28 | +recognizable archvillains, and ... well, they are not all that great, but they |
| 29 | +are available at `Project Gutenberg <http://www.gutenberg.org/ebooks/author/3587>`__ |
| 30 | +and `Open Library <https://openlibrary.org/search?q=guy+boothby>`__ if you |
| 31 | +want to read them. |
| 32 | + |
| 33 | +The Open Library has `a lovely scan <https://archive.org/stream/bidforfortunenov00bootiala#page/n9/mode/2up>`__ |
| 34 | +of the original book we can use for some design guidance. On the other hand, |
| 35 | +Project Gutenberg has `the text <http://www.gutenberg.org/ebooks/21640>`__ |
| 36 | +we can use for actual content! |
| 37 | + |
| 38 | +So, I took the prologue of the book, did some very light editing to turn it into |
| 39 | +reStructured Text, added a picture of Dr. Nikola himself I fund in Wikipedia, |
| 40 | +and put it here for display. `Behold! <link://slug/dr-nikola-v1>`__ |
| 41 | + |
| 42 | +That is very... bad? While Nikola does the job, the default template is simply not |
| 43 | +meant for this sort of thing. |
| 44 | + |
| 45 | +The problems are many, from a book-reading point of view: |
| 46 | + |
| 47 | +1) The column is too wide |
| 48 | +2) The typesetting is all wrong |
| 49 | +3) The sans-serif font is a very wrong idea for book material |
| 50 | +4) it's so ... long! |
| 51 | + |
| 52 | +So, let's fix them! |
| 53 | + |
| 54 | +Custom Template |
| 55 | +--------------- |
| 56 | + |
| 57 | +Like all pages, that one is shown using ``story.tmpl``: |
| 58 | + |
| 59 | +.. listing:: story.tmpl html+mako |
| 60 | + |
| 61 | +That has a lot of code in it that we don't really need. We know there will be no math here, and |
| 62 | +I don't want comments on a book. Also, I saw a `nice tutorial about columns in CSS <https://css-tricks.com/guide-responsive-friendly-css-columns/>`__ so I want to style things up a little. |
| 63 | + |
| 64 | +So, I will create a ``templates/book.tmpl`` in my site, and make this story use that by setting the |
| 65 | +template metadata in the page to use it:: |
| 66 | + |
| 67 | + .. template:: book.tmpl |
| 68 | + |
| 69 | +Here is my new ``book.tmpl``: |
| 70 | + |
| 71 | + |
| 72 | +.. listing:: book1.tmpl html+mako |
| 73 | + |
| 74 | +And here is `the resulting page <link://slug/dr-nikola-v2>`__ |
| 75 | + |
| 76 | +What has changed? |
| 77 | + |
| 78 | +1) I added a ``extra_head`` block. That goes, surprisingly, inside the ``HEAD`` element of the page, so |
| 79 | + it's a good place to add CSS that's specific to this page. |
| 80 | + |
| 81 | +2) I removed unneeded parts of the content block, and moved the content around a little. |
| 82 | + |
| 83 | +3) To create the nice responsive 1-or-2 column layout, I had to wrap the content in a few divs, one |
| 84 | + with columns, one that scrolls, one that has overflow hidden. |
| 85 | + |
| 86 | +It's better, but it's far from awesome. So, let's continue! |
| 87 | + |
| 88 | +Typesetting |
| 89 | +----------- |
| 90 | + |
| 91 | +Paragraph layout: Fiction books that are not fully justified feel wrong to me. So we should set |
| 92 | +``text-align: justified`` in the CSS. But to achieve proper justification, you also need hyphenation. |
| 93 | +To have that in Nikola, you need to either enable it for the whole site (maybe not a great idea) or |
| 94 | +just for this page using the hyphenate metadata:: |
| 95 | + |
| 96 | + .. hyphenate: yes |
| 97 | + |
| 98 | +Also, the original book has no space between paragraphs, and has bleeding in the first line, so more |
| 99 | +CSS tweaks. |
| 100 | + |
| 101 | +Proper quotes! Nice, curly quotes are a must. Nikola has the typogrify filter to achieve that. Again, |
| 102 | +you can enable it for your whole site, or just for this page using metadata:: |
| 103 | + |
| 104 | + .. filters: filters.typogrify |
| 105 | + |
| 106 | +Choosing the right font for a page or a site is an art. One I suck at, so I just went with a font that |
| 107 | +was similar to the one used in the original book. There are a number of those, but I chose |
| 108 | +`Gentium Basic <https://www.google.com/fonts/specimen/Gentium+Basic>`__. You can, of course, choose whatever |
| 109 | +you want. Using it via Google Fonts is very simple. |
| 110 | + |
| 111 | +Even with the nicer font, and the dual columns, the font size is too small, there is too many letters |
| 112 | +per line. We *could* tweak that using CSS font sizes, but let's go crazy and use a Javascript solution: |
| 113 | +`FlowType.JS <http://simplefocus.com/flowtype/>`__ |
| 114 | + |
| 115 | +Why FlowType.JS? It dynamically adjust the font size so that columns always have the right font size for |
| 116 | +their width. That's just nice. To do that, we need to add JQuery and run a little JS in a ``<script>`` |
| 117 | +tag at the end of the template. |
| 118 | + |
| 119 | +Figures: figures and multicolumn layout don't go along very well, they may even get split between columns! |
| 120 | +The easiest solution is to make them fit in a "page", so, some more CSS for that. |
| 121 | + |
| 122 | +Also, minor things like styling titles, subtitles, making the 1st word in the section smallcaps, and so on, |
| 123 | +but hey, this is just CSS tweaking, we could do this forever. |
| 124 | + |
| 125 | +So, here is our second attempt at a "book-like" template: |
| 126 | + |
| 127 | +.. listing:: book2.tmpl html+mako |
| 128 | + |
| 129 | +And here's our `much more nicely typeset book <link://slug/dr-nikola-v3>`__. |
| 130 | + |
| 131 | +Interaction |
| 132 | +----------- |
| 133 | + |
| 134 | +Pages are not just text anymore. They need to interact with the user in the right way. |
| 135 | +In this case, the scrolling horizontally to read another page is horrible: |
| 136 | + |
| 137 | +* It's hard to stop at the right place |
| 138 | +* You end up between pages 99% of the time |
| 139 | + |
| 140 | +So, let's fix that with a little more JS at the end of the template: |
| 141 | + |
| 142 | +.. code:: javascript |
| 143 | +
|
| 144 | + $('#scrolling-cont').flowtype({ |
| 145 | + minimum: 500, |
| 146 | + maximum: 1200, |
| 147 | + minFont: 20, |
| 148 | + maxFont: 40, |
| 149 | + fontRatio: 50 |
| 150 | + }); |
| 151 | + $(document).ready(function() { |
| 152 | + var elem = $('#scrolling-cont'); |
| 153 | + elem.click(function(event) { |
| 154 | + var x1 = elem.position().left; |
| 155 | + var pw = elem.width() + 20; |
| 156 | + var x2 = event.pageX; |
| 157 | + if (x2 - x1 < pw / 2) { |
| 158 | + pw = -pw; |
| 159 | + } |
| 160 | + elem.animate({ |
| 161 | + scrollLeft: '+=' + pw |
| 162 | + }, 500) |
| 163 | + }); |
| 164 | + }); |
| 165 | +
|
| 166 | +If you click on the right half of the book, it moves 2 pages to the right. If you click on the left half |
| 167 | +it moves two pages to the left. Improvements are left as exercise to the reader, but please share! |
| 168 | + |
| 169 | +And here's the final result: `A Bid For Fortune; Or; Dr. Nikola's Vendetta <link://slug/dr-nikola-final>`__ |
| 170 | + |
| 171 | +------------ |
| 172 | + |
| 173 | +.. [1] Sadly, the title is actually "A Bid For Fortune" and "Dr. Nikola's Vendetta" |
| 174 | + is the subtitle, but it works for me. |
0 commit comments