contents/glyph/book/extending/layouts.html
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 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 |
-----
title: "Glyph – Layouts"
content-type: page
-----
<nav class="navigation"><a href="/glyph/book/extending/interpreting.html">← Interpreting Glyph Code</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/further_reading.html">Further Reading →</a></nav>
<p>When generating <a href="/glyph/book/text_editing/topics.html#topics">topic</a>-based outputs, Glyph uses <em>layouts</em> to render topics as standalone documents. By default, the following two layout are used:</p>
<ul>
<li><code>topic</code> — used to render standard topics.</li>
<li><code>index</code> — used to render the index page of your document.</li>
</ul>
<p>Layouts are nothing more than “fancy” Glyph macros defined using the Glyph language (i.e. by using <a href="/glyph/book/extending/interpreting.html#rewriting">macro rewriting</a>) within a single <code>.glyph</code> file.</p>
<section class="section">
<header><h1 id="h_96" class="toc">Topic Layout</h1></header>
<p>The default layout used to render all web topics (the layout used for web5 topics is very similar) is defined as follows:</p>
<div class="CodeRay">
<div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>document[
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> head[
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> style[default.css]
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> ]
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> body[
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> @class[topic]
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> section[
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> @title[{{title}}]
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> @id[{{id}}]
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> navigation[{{id}}]
<span class="line-numbers"><a href="#n11" name="n11">11</a></span>{{contents}}
<span class="line-numbers"><a href="#n12" name="n12">12</a></span> navigation[{{id}}]
<span class="line-numbers"><a href="#n13" name="n13">13</a></span> ]
<span class="line-numbers"><a href="#n14" name="n14">14</a></span> ]
<span class="line-numbers"><a href="#n15" name="n15">15</a></span>]</pre></div>
</div>
<p>Note that it takes the following attributes, passed automatically by Glyph when processing each topic:</p>
<ul>
<li><code>title</code> — the title of the topic.</li>
<li><code>id</code> — the ID of the topic.</li>
<li><code>contents</code> — the body of the topic.</li>
</ul>
</section>
<section class="section">
<header><h1 id="index_layout" class="toc">Index Layout</h1></header>
<p>The default layout used to render the web index page (the layout used for the web5 index is very similar) is defined as follows:</p>
<div class="CodeRay">
<div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>document[
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> head[
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> style[default.css]
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> ]
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> body[
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> @class[topic]
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> halftitlepage[
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> title[]
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> subtitle[]
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> author[]
<span class="line-numbers"><a href="#n11" name="n11">11</a></span> ]
<span class="line-numbers"><a href="#n12" name="n12">12</a></span> frontmatter[
<span class="line-numbers"><a href="#n13" name="n13">13</a></span> toc[]
<span class="line-numbers"><a href="#n14" name="n14">14</a></span> ]
<span class="line-numbers"><a href="#n15" name="n15">15</a></span> ]
<span class="line-numbers"><a href="#n16" name="n16">16</a></span>]</pre></div>
</div>
<p>Index layouts do not take any attribute or parameter (basically because they are used to produce only one page).</p>
</section>
<section class="section">
<header><h1 id="h_98" class="toc">Creating a Custom Layout</h1></header>
<p>To create a custom layout, proceed as follows:</p>
<ul>
<li>Create a <code>.glyph</code> file in the <code>lib/layouts</code> directory, within your project, e.g. <code>mytopic.glyph</code></li>
<li>Add the layout code, making sure (for topic layouts) that all the attributes (<code>title</code>, <code>id</code>, <code>contents</code>) are specified correctly.</li>
<li>Set the <code>output.*.layouts.topic</code> setting to the name of the new layout (<code>mytopic</code>).</li>
</ul>
<aside class="tip">
<span class="note-title">Tip</span>You can override which layout to use on a specific topic by specifying it in a <code>@layout</code> attribute.
</aside>
</section>
<nav class="navigation"><a href="/glyph/book/extending/interpreting.html">← Interpreting Glyph Code</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/further_reading.html">Further Reading →</a></nav>
|