Class: Abqari::RenderContext

Inherits:

Object

Object
Abqari::RenderContext

show all

Includes:: Helpers, CoverHelpers, PictureHelpers, PublicationHelpers

Defined in:: lib/abqari/render_context.rb,
lib/abqari/render_context/cover_helpers.rb,
lib/abqari/render_context/picture_helpers.rb,
lib/abqari/render_context/publication_helpers.rb

Overview

The binding ERB templates execute against. Holds references to the current page and site, includes shared helper mixins.

Decomposed for readability — the helpers split into:

- `Helpers`              : core scalar helpers (h, sanitized_url,
                          local_time, pluralize, truncate, link_to,
                          slugify, …). Engine-wide.
- `PublicationHelpers`   : publication/bundle/series accessors,
                          buy/cart buttons. Publisher-agnostic —
                          see lib/abqari/render_context/
                          publication_helpers.rb.
- `PictureHelpers`       : asset_path, icon, heroicon, picture_tag,
                          bundle_picture_tag, bundle_asset_url.

Templating-specific surface (render, render_layout, render_string, yield_content, get_binding) stays here.

Defined Under Namespace

Modules: CoverHelpers, PictureHelpers, PublicationHelpers

Constant Summary collapse

TEMPLATE_PUBLIC_IVARS = Instance variables intentionally exposed to templates via the binding ERB receives. Anything outside this set should use the @_ convention so a stray <%= @foo %> is clearly out-of- contract. The audit test RenderContextInternalIvarTest reads this list and fails if RenderContext grows an ivar that's neither in the allow-list nor @_-prefixed.

%i[@page @site].freeze

RESERVED_LOCALS = Local names that must never be shadowed by a render(..., key: v) local — doing so would silently replace the escaping function or a core API method for that partial. page is deliberately NOT here: rebinding it (render 'partials/card', page: item) is a supported pattern.

%i[h sanitized_url site render render_layout render_string
script_safe_json get_binding yield_content].freeze

Instance Attribute Summary collapse

#page ⇒ Object readonly
Returns the value of attribute page.
#site ⇒ Object readonly
Returns the value of attribute site.

Instance Method Summary collapse

#collection_index_label(target = page) ⇒ Object
Display label for the collection index — slug if set, canonical name otherwise.
#collection_index_url(target = page) ⇒ Object
Slug-aware "back to index" data for a show-view page.
#document_title ⇒ Object
The text: "Page · Site", except when the two are the same string — the home page usually titles itself after the site, and "Mysite · Mysite" reads like a bug in the browser tab.</div> </li> <li class="public "> <a href="#get_binding-instance_method" title="#get_binding (instance method)">#get_binding ⇒ Object </a> <div class='inline'></div> </li> <li class="public "> <a href="#initialize-instance_method" title="#initialize (instance method)">#initialize(page, site, locals = {}) ⇒ RenderContext </a> constructor <div class='inline'>A new instance of RenderContext.</div> </li> <li class="public "> <a href="#render-instance_method" title="#render (instance method)">#render(partial, **locals) ⇒ Object </a> <div class='inline'></div> </li> <li class="public "> <a href="#render_layout-instance_method" title="#render_layout (instance method)">#render_layout(name, seen = []) ⇒ Object </a> <div class='inline'>Render a layout, with optional chaining via the layout's own frontmatter.</div> </li> <li class="public "> <a href="#render_string-instance_method" title="#render_string (instance method)">#render_string(template) ⇒ Object </a> <div class='inline'>Render an ERB string against this context.</div> </li> <li class="public "> <a href="#series_url-instance_method" title="#series_url (instance method)">#series_url(term, target = page) ⇒ Object </a> <div class='inline'>URL of the series index that covers <code>target</code>'s collection.</div> </li> <li class="public "> <a href="#taxonomy_url-instance_method" title="#taxonomy_url (instance method)">#taxonomy_url(taxonomy_name, term) ⇒ Object </a> <div class='inline'>URL of a taxonomy term page, honouring the configured permalink so slug-aliasing works.</div> </li> <li class="public "> <a href="#yield_content-instance_method" title="#yield_content (instance method)">#yield_content ⇒ Object </a> <div class='inline'>The output of the inner layout, available inside a wrapping layout as <code><%== yield_content %></code>.</div> </li> </ul> <h3 class="inherited">Methods included from <a href="RenderContext/CoverHelpers.html" title="Abqari::RenderContext::CoverHelpers (module)">CoverHelpers</a></h3> <a href="RenderContext/CoverHelpers.html#balanced_word_partition-instance_method" title="Abqari::RenderContext::CoverHelpers#balanced_word_partition (method)">#balanced_word_partition</a>, <a href="RenderContext/CoverHelpers.html#cover_choice_for-instance_method" title="Abqari::RenderContext::CoverHelpers#cover_choice_for (method)">#cover_choice_for</a>, <a href="RenderContext/CoverHelpers.html#cover_image_path-instance_method" title="Abqari::RenderContext::CoverHelpers#cover_image_path (method)">#cover_image_path</a>, <a href="RenderContext/CoverHelpers.html#cover_mode_for-instance_method" title="Abqari::RenderContext::CoverHelpers#cover_mode_for (method)">#cover_mode_for</a>, <a href="RenderContext/CoverHelpers.html#cover_palette-instance_method" title="Abqari::RenderContext::CoverHelpers#cover_palette (method)">#cover_palette</a>, <a href="RenderContext/CoverHelpers.html#cover_svg_for-instance_method" title="Abqari::RenderContext::CoverHelpers#cover_svg_for (method)">#cover_svg_for</a>, <a href="RenderContext/CoverHelpers.html#enumerate_splits-instance_method" title="Abqari::RenderContext::CoverHelpers#enumerate_splits (method)">#enumerate_splits</a>, <a href="RenderContext/CoverHelpers.html#partition_by_sizes-instance_method" title="Abqari::RenderContext::CoverHelpers#partition_by_sizes (method)">#partition_by_sizes</a>, <a href="RenderContext/CoverHelpers.html#svg_title_font_size-instance_method" title="Abqari::RenderContext::CoverHelpers#svg_title_font_size (method)">#svg_title_font_size</a>, <a href="RenderContext/CoverHelpers.html#svg_wrap_title-instance_method" title="Abqari::RenderContext::CoverHelpers#svg_wrap_title (method)">#svg_wrap_title</a> <h3 class="inherited">Methods included from <a href="RenderContext/PictureHelpers.html" title="Abqari::RenderContext::PictureHelpers (module)">PictureHelpers</a></h3> <a href="RenderContext/PictureHelpers.html#asset_path-instance_method" title="Abqari::RenderContext::PictureHelpers#asset_path (method)">#asset_path</a>, <a href="RenderContext/PictureHelpers.html#bundle_asset_url-instance_method" title="Abqari::RenderContext::PictureHelpers#bundle_asset_url (method)">#bundle_asset_url</a>, <a href="RenderContext/PictureHelpers.html#bundle_asset_url_for-instance_method" title="Abqari::RenderContext::PictureHelpers#bundle_asset_url_for (method)">#bundle_asset_url_for</a>, <a href="RenderContext/PictureHelpers.html#bundle_picture_tag-instance_method" title="Abqari::RenderContext::PictureHelpers#bundle_picture_tag (method)">#bundle_picture_tag</a>, <a href="RenderContext/PictureHelpers.html#heroicon-instance_method" title="Abqari::RenderContext::PictureHelpers#heroicon (method)">#heroicon</a>, <a href="RenderContext/PictureHelpers.html#icon-instance_method" title="Abqari::RenderContext::PictureHelpers#icon (method)">#icon</a>, <a href="RenderContext/PictureHelpers.html#optional_asset_path-instance_method" title="Abqari::RenderContext::PictureHelpers#optional_asset_path (method)">#optional_asset_path</a>, <a href="RenderContext/PictureHelpers.html#picture_tag-instance_method" title="Abqari::RenderContext::PictureHelpers#picture_tag (method)">#picture_tag</a> <h3 class="inherited">Methods included from <a href="RenderContext/PublicationHelpers.html" title="Abqari::RenderContext::PublicationHelpers (module)">PublicationHelpers</a></h3> <a href="RenderContext/PublicationHelpers.html#bundle_for-instance_method" title="Abqari::RenderContext::PublicationHelpers#bundle_for (method)">#bundle_for</a>, <a href="RenderContext/PublicationHelpers.html#buy_button-instance_method" title="Abqari::RenderContext::PublicationHelpers#buy_button (method)">#buy_button</a>, <a href="RenderContext/PublicationHelpers.html#cart_button-instance_method" title="Abqari::RenderContext::PublicationHelpers#cart_button (method)">#cart_button</a>, <a href="RenderContext/PublicationHelpers.html#publication_card_data-instance_method" title="Abqari::RenderContext::PublicationHelpers#publication_card_data (method)">#publication_card_data</a>, <a href="RenderContext/PublicationHelpers.html#publication_for-instance_method" title="Abqari::RenderContext::PublicationHelpers#publication_for (method)">#publication_for</a>, <a href="RenderContext/PublicationHelpers.html#series_for-instance_method" title="Abqari::RenderContext::PublicationHelpers#series_for (method)">#series_for</a> <h3 class="inherited">Methods included from <a href="Helpers.html" title="Abqari::Helpers (module)">Helpers</a></h3> <a href="Helpers.html#excerpt-instance_method" title="Abqari::Helpers#excerpt (method)">#excerpt</a>, <a href="Helpers.html#external_http_url-instance_method" title="Abqari::Helpers#external_http_url (method)">#external_http_url</a>, <a href="Helpers.html#h-instance_method" title="Abqari::Helpers#h (method)">#h</a>, <a href="Helpers.html#link_to-instance_method" title="Abqari::Helpers#link_to (method)">#link_to</a>, <a href="Helpers.html#local_time-instance_method" title="Abqari::Helpers#local_time (method)">#local_time</a>, <a href="Helpers.html#markdown-instance_method" title="Abqari::Helpers#markdown (method)">#markdown</a>, <a href="Helpers.html#pluralize-instance_method" title="Abqari::Helpers#pluralize (method)">#pluralize</a>, <a href="Helpers.html#reading_time-instance_method" title="Abqari::Helpers#reading_time (method)">#reading_time</a>, <a href="Helpers.html#sanitized_url-instance_method" title="Abqari::Helpers#sanitized_url (method)">#sanitized_url</a>, <a href="Helpers.html#script_safe_json-instance_method" title="Abqari::Helpers#script_safe_json (method)">#script_safe_json</a>, <a href="Helpers.html#slugify-instance_method" title="Abqari::Helpers#slugify (method)">#slugify</a>, <a href="Helpers.html#time_ago-instance_method" title="Abqari::Helpers#time_ago (method)">#time_ago</a>, <a href="Helpers.html#time_until-instance_method" title="Abqari::Helpers#time_until (method)">#time_until</a>, <a href="Helpers.html#to_time-instance_method" title="Abqari::Helpers#to_time (method)">#to_time</a>, <a href="Helpers.html#truncate-instance_method" title="Abqari::Helpers#truncate (method)">#truncate</a>, <a href="Helpers.html#word_count-instance_method" title="Abqari::Helpers#word_count (method)">#word_count</a>, <a href="Helpers.html#years_since-instance_method" title="Abqari::Helpers#years_since (method)">#years_since</a> <div id="constructor_details" class="method_details_list"> <h2>Constructor Details</h2> <div class="method_details first"> <h3 class="signature first" id="initialize-instance_method"> #initialize(page, site, locals = {}) ⇒ <tt><a href="" title="Abqari::RenderContext (class)">RenderContext</a></tt> </h3><div class="docstring"> <div class="discussion"> Returns a new instance of RenderContext. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 52 53 54 55 56 57 58 59 60 61 62</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 52 def initialize(page, site, locals = {}) @page = page @site = site locals.each do |key, value| if <a href="#RESERVED_LOCALS-constant" title="Abqari::RenderContext::RESERVED_LOCALS (constant)">RESERVED_LOCALS</a>.include?(key.to_sym) raise ArgumentError, "render local #{key.inspect} would shadow the core helper of the same name — rename it" end define_singleton_method(key) { value } end end</pre> </td> </tr> </table> </div> </div> <div id="instance_attr_details" class="attr_details"> <h2>Instance Attribute Details</h2> <div class="method_details first"> <h3 class="signature first" id="page-instance_method"> #page ⇒ <tt>Object</tt> (readonly) </h3><div class="docstring"> <div class="discussion"> Returns the value of attribute page. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 34 35 36</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 34 def page @page end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="site-instance_method"> #site ⇒ <tt>Object</tt> (readonly) </h3><div class="docstring"> <div class="discussion"> Returns the value of attribute site. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 34 35 36</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 34 def site @site end</pre> </td> </tr> </table> </div> </div> <div id="instance_method_details" class="method_details_list"> <h2>Instance Method Details</h2> <div class="method_details first"> <h3 class="signature first" id="collection_index_label-instance_method"> #collection_index_label(target = page) ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> Display label for the collection index — slug if set, canonical name otherwise. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 170 171 172 173 174 175 176 177</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 170 def collection_index_label(target = page) name = target.is_a?(String) ? target : effective_collection_name(target) return nil unless name cfg = site.collection_config(name) slug = cfg['slug'].to_s slug.empty? ? name : slug end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="collection_index_url-instance_method"> #collection_index_url(target = page) ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> Slug-aware "back to index" data for a show-view page. Returns the URL of the page's collection index, honoring <code>slug:</code> aliasing — e.g. a post in the <code>posts</code> collection with <code>slug: stories</code> returns <code>/stories/</code>. Returns nil for pages outside any collection. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 155 156 157 158 159 160 161 162 163 164 165 166</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 155 def collection_index_url(target = page) # Accept either a Page (resolve via `effective_collection_name`) # or a collection name string directly — the latter is useful # from contexts that aren't in any collection (e.g. the home # page's photo modules linking to /photos/). name = target.is_a?(String) ? target : effective_collection_name(target) return nil unless name cfg = site.collection_config(name) slug = cfg['slug'].to_s "/#{slug.empty? ? name : slug}/" end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="document_title-instance_method"> #document_title ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> The <title> text: "Page · Site", except when the two are the same string — the home page usually titles itself after the site, and "Mysite · Mysite" reads like a bug in the browser tab. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 135 136 137 138 139 140 141</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 135 def document_title page_title = page.title.to_s site_title = site.config['title'].to_s return site_title if page_title.empty? || page_title == site_title "#{page_title} · #{site_title}" end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="get_binding-instance_method"> #get_binding ⇒ <tt>Object</tt> </h3><table class="source_code"> <tr> <td> <pre class="lines"> 205 206 207</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 205 def get_binding binding end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="render-instance_method"> #render(partial, **locals) ⇒ <tt>Object</tt> </h3><table class="source_code"> <tr> <td> <pre class="lines"> 64 65 66 67</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 64 def render(partial, **locals) context = <a href="" title="Abqari::RenderContext (class)">RenderContext</a>.<a href="#initialize-instance_method" title="Abqari::RenderContext#initialize (method)">new</a>(page, site, locals) site.compiled_template(partial_path(partial)).result(context.get_binding) end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="render_layout-instance_method"> #render_layout(name, seen = []) ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> Render a layout, with optional chaining via the layout's own frontmatter. A layout can declare <code>layout: <parent></code> at the top of its file (Jekyll-style); the engine renders the inner layout first, then wraps the result in the parent layout, and so on recursively until it reaches a layout with no parent. The wrapping layout reads the inner output via <code><%== yield_content %></code> (raw — the inner layout's output is already escaped HTML, escaping it again would render tags as text). <h2 id="Frontmatter_on_layouts_">Frontmatter on layouts:</h2> <h2 id="layout__application_________this_layout_extends_application_html_erb">layout: application # this layout extends application.html.erb</h2> </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 83 def render_layout(name, seen = []) # Cycle guard. A layout chain that loops (`a` extends `b` extends # `a`, or a layout that extends itself) would recurse forever and # blow the stack with a `SystemStackError` — which isn't a # `StandardError`, so it escapes the renderer's per-page rescue # and crashes a worker thread with no layout name attached. Fail # with the actual cycle instead. if seen.include?(name) raise "layout cycle detected: #{(seen + [name]).join(' -> ')}" end seen = seen + [name] # Layouts are hybrid: site override wins, engine version is the # fallback. Users override a layout by dropping their own copy # at `app/views/layouts/<name>.html.erb` in the site root. path = site.find_in_paths(File.join('app', 'views', 'layouts', "#{name}.html.erb")) unless File.exist?(path) raise "layout #{name.inspect} not found (searched site root then engine root: " \ "#{File.join('app', 'views', 'layouts', "#{name}.html.erb")})" end raw = File.read(path, encoding: 'UTF-8') layout_fm, body = parse_layout_frontmatter(raw) template = <a href="ErbiTemplate.html" title="Abqari::ErbiTemplate (class)">ErbiTemplate</a>.<a href="ErbiTemplate.html#initialize-instance_method" title="Abqari::ErbiTemplate#initialize (method)">new</a>(body, path) inner = template.result(get_binding) parent = layout_fm['layout'] return inner unless parent @_yielded_content = inner render_layout(parent.to_s, seen) end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="render_string-instance_method"> #render_string(template) ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> Render an ERB string against this context. Used by Page#rendered_body to support <code>erb: true</code> opt-in templating in markdown bodies. No template caching — these strings are one-off per build. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 146 147 148 149</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 146 def render_string(template) label = page.respond_to?(:source_path) && page.source_path ? "#{page.source_path} (erb body)" : '(erb body)' <a href="ErbiTemplate.html" title="Abqari::ErbiTemplate (class)">ErbiTemplate</a>.<a href="ErbiTemplate.html#initialize-instance_method" title="Abqari::ErbiTemplate#initialize (method)">new</a>(template, label).<a href="ErbiTemplate.html#result-instance_method" title="Abqari::ErbiTemplate#result (method)">result</a>(get_binding) end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="series_url-instance_method"> #series_url(term, target = page) ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> URL of the series index that covers <code>target</code>'s collection. Resolves the owning taxonomy first, so a layout shared between collections links each one to its own series index: <pre class="code ruby"><code class="ruby">series_url('Inside Abqari') → "/guides/series/inside-abqari/" series_url('Module 1', lesson_page) → "/lessons/module/module-1/" </code></pre> Returns nil when the page's collection has no series taxonomy configured — callers render the series name as plain text rather than linking it somewhere that was never built. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 200 201 202 203</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 200 def series_url(term, target = page) name = site.series_taxonomy_for(effective_collection_name(target)) name && taxonomy_url(name, term) end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="taxonomy_url-instance_method"> #taxonomy_url(taxonomy_name, term) ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> URL of a taxonomy term page, honouring the configured permalink so slug-aliasing works. Replaces hardcoded patterns like <code>"/tags/#{slugify(term)}/"</code> in show-view layouts. taxonomy_url('tags', 'fiction') → "/tags/fiction/" taxonomy_url('countries', 'Syria') → "/country/syria/" (per config) </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 184 185 186 187 188</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 184 def taxonomy_url(taxonomy_name, term) cfg = site.taxonomy_config(taxonomy_name.to_s) permalink = cfg['permalink'] || "/#{taxonomy_name}/:slug/" permalink.sub(':slug', slugify(term)) end</pre> </td> </tr> </table> </div> <div class="method_details "> <h3 class="signature " id="yield_content-instance_method"> #yield_content ⇒ <tt>Object</tt> </h3><div class="docstring"> <div class="discussion"> The output of the inner layout, available inside a wrapping layout as <code><%== yield_content %></code>. Returns '' at the leaf level (the layout being rendered direct from a page, with no inner layout wrapping it). The backing ivar is intentionally <code>@_yielded_content</code> (leading underscore = "internal, don't touch"). ERB templates get the full binding via <code>get_binding</code>, so every RenderContext ivar is one <code><%= @whatever %></code> typo away from being usable. The underscore convention plus the <code>RenderContextInternalIvarTest</code> audit pin the contract: only <code>page</code> and <code>site</code> are intended template- accessible state; helper method results carry the rest. </div> </div> <div class="tags"> </div><table class="source_code"> <tr> <td> <pre class="lines"> 128 129 130</pre> </td> <td> <pre class="code"># File 'lib/abqari/render_context.rb', line 128 def yield_content @_yielded_content.to_s end</pre> </td> </tr> </table> </div> </div> </div> <div id="footer"> Generated on Fri Aug 7 00:51:22 2026 by <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a> 0.9.45 (ruby-4.0.2). </div> </div> </body> </html>

Class: Abqari::RenderContext

Overview

Defined Under Namespace

Constant Summary collapse

Constants included from CoverHelpers

Constants included from PictureHelpers

Constants included from Helpers

Instance Attribute Summary collapse

Instance Method Summary collapse