-----
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>