all repos — h3rald @ 6b243ded05a7593922d198634c681075de1c12e2

The sources of https://h3rald.com

contents/glyph/book/extending/placeholders.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
-----
title: "Glyph - Using Placeholders"
content-type: page
-----
<nav class="navigation"><a href="/glyph/book/extending/bookmarks_headers.html">← Bookmarks and Headers</a> | <a
		href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/validators.html">Using Validators
		→</a></nav>
<p>Sometimes you may need to access some data that will not be available until the entire document has been fully parsed
	and analyzed. For example, in order to be able to validate internal links, it is necessary to know in advance if the
	bookmark ID referenced in the link exists or not, either before (that&#8217;s easy) or even <em>after</em> the link.
</p>
<p>Here&#8217;s the source code of the <a href="/glyph/book/macros/macros_inline.html#m_link"><code>link</code></a>
	macro:</p>
<div class="CodeRay">
	<div class="code">
		<pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>macro <span class="symbol">:link</span> <span class="keyword">do</span>
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span>  min_parameters <span class="integer">1</span>
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span>  max_parameters <span class="integer">2</span>
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span>  target = param <span class="integer">0</span> 
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span>  title = param <span class="integer">1</span> 
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span>  <span class="keyword">if</span> target.match <span class="regexp"><span class="delimiter">/</span><span class="content">^#</span><span class="delimiter">/</span></span> <span class="keyword">then</span>
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span>    <span class="instance-variable">@node</span>[<span class="symbol">:document</span>].links &lt;&lt; target 
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span>    anchor = target.gsub <span class="regexp"><span class="delimiter">/</span><span class="content">^#</span><span class="delimiter">/</span></span>, <span class="string"><span class="delimiter">'</span><span class="delimiter">'</span></span>
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span>    bmk = bookmark? anchor
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>    <span class="keyword">if</span> !bmk <span class="keyword">then</span>
<span class="line-numbers"><a href="#n11" name="n11">11</a></span>      placeholder <span class="keyword">do</span> |document|
<span class="line-numbers"><a href="#n12" name="n12">12</a></span>        bmk = document.bookmark?(anchor)
<span class="line-numbers"><a href="#n13" name="n13">13</a></span>        macro_error <span class="string"><span class="delimiter">&quot;</span><span class="content">Bookmark '</span><span class="inline"><span class="inline-delimiter">#{</span>anchor<span class="inline-delimiter">}</span></span><span class="content">' does not exist</span><span class="delimiter">&quot;</span></span> <span class="keyword">unless</span> bmk
<span class="line-numbers"><a href="#n14" name="n14">14</a></span>        bmk_title = title
<span class="line-numbers"><a href="#n15" name="n15">15</a></span>        bmk_title = bmk.title <span class="keyword">if</span> bmk_title.blank?
<span class="line-numbers"><a href="#n16" name="n16">16</a></span>        <span class="instance-variable">@data</span>[<span class="symbol">:target</span>] = bmk.link(<span class="instance-variable">@source_file</span>)
<span class="line-numbers"><a href="#n17" name="n17">17</a></span>        <span class="instance-variable">@data</span>[<span class="symbol">:title</span>] = bmk_title
<span class="line-numbers"><a href="#n18" name="n18">18</a></span>        render
<span class="line-numbers"><a href="#n19" name="n19">19</a></span>      <span class="keyword">end</span>
<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span>    <span class="keyword">else</span>
<span class="line-numbers"><a href="#n21" name="n21">21</a></span>      bmk_title = title
<span class="line-numbers"><a href="#n22" name="n22">22</a></span>      bmk_title = bmk.title <span class="keyword">if</span> bmk_title.blank?
<span class="line-numbers"><a href="#n23" name="n23">23</a></span>      <span class="instance-variable">@data</span>[<span class="symbol">:target</span>] = bmk.link(<span class="instance-variable">@source_file</span>)
<span class="line-numbers"><a href="#n24" name="n24">24</a></span>      <span class="instance-variable">@data</span>[<span class="symbol">:title</span>] = bmk_title
<span class="line-numbers"><a href="#n25" name="n25">25</a></span>      render
<span class="line-numbers"><a href="#n26" name="n26">26</a></span>    <span class="keyword">end</span>
<span class="line-numbers"><a href="#n27" name="n27">27</a></span>  <span class="keyword">else</span>
<span class="line-numbers"><a href="#n28" name="n28">28</a></span>    <span class="comment"># Code omitted...</span>
<span class="line-numbers"><a href="#n29" name="n29">29</a></span>  <span class="keyword">end</span>
<span class="line-numbers"><strong><a href="#n30" name="n30">30</a></strong></span><span class="keyword">end</span></pre>
	</div>
</div>

<p>If there&#8217;s already a bookmark stored in the current document, then it is possible to retrieve its title and use
	it as link text. Otherwise, it is necessary to wait until the entire document has been fully processed and then
	check if the bookmark exists. To do so, use the <code>placeholder</code> method. When called, this method returns an
	unique placeholder, which is then substituted with the value of the block, right before the document is finalized.
</p>
<p>Within the <code>placeholder</code> block, the <code>document</code> parameter is, by all means, the fully analyzed
	document.</p>
<nav class="navigation"><a href="/glyph/book/extending/bookmarks_headers.html">← Bookmarks and Headers</a> | <a
		href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/validators.html">Using Validators
		→</a></nav>