Class: Coradoc::Html::TemplateLocator

Inherits:
Object
  • Object
show all
Defined in:
lib/coradoc/html/template_locator.rb

Overview

Locates Liquid templates from filesystem with fallback support

This class implements a template lookup algorithm:

  1. Check user’s template directories in order (first match wins)

  2. Fall back to default templates if not found

  3. Return nil if no template found (caller decides fallback)

Examples:

Basic usage

locator = TemplateLocator.new(
  user_dirs: ["/path/to/templates"],
  default_dir: "/default/templates"
)
locator.find("bibliography") # => "/path/to/templates/bibliography.liquid"

Constant Summary collapse

CORE_MODEL_DIR =

Default template subdirectory within each template root

'core_model'
DEFAULT_TEMPLATE_DIR =

Canonical default template directory within the gem

Pathname.new(File.join(File.dirname(__FILE__), 'templates', CORE_MODEL_DIR)).freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(user_dirs: [], default_dir: nil) ⇒ TemplateLocator

Initialize the locator

Parameters:

  • user_dirs (Array<String>) (defaults to: []) —

    User template directories (checked first)

  • default_dir (String) (defaults to: nil) —

    Default templates directory (fallback)



35
36
37
38
39
 
# File 'lib/coradoc/html/template_locator.rb', line 35

def initialize(user_dirs: [], default_dir: nil)
  @user_dirs = Array(user_dirs).map { |d| Pathname.new(d) }
  @default_dir = default_dir ? Pathname.new(default_dir) : default_template_dir
  @cache = {}
end

Instance Attribute Details

#default_dir ⇒ Object (readonly)

Returns the value of attribute default_dir.



29
30
31
 
# File 'lib/coradoc/html/template_locator.rb', line 29

def default_dir
  @default_dir
end

#user_dirs ⇒ Object (readonly)

Returns the value of attribute user_dirs.



29
30
31
 
# File 'lib/coradoc/html/template_locator.rb', line 29

def user_dirs
  @user_dirs
end

Instance Method Details

#available_templates ⇒ Array<String>

Get all available template types

Returns:

  • (Array<String>) —

    List of available template names



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/coradoc/html/template_locator.rb', line 83

def available_templates
  types = Set.new

  # Collect from user directories (root and core_model/ subdir)
  @user_dirs.each do |dir|
    [dir, dir / CORE_MODEL_DIR].each do |scan_dir|
      next unless scan_dir.exist? && scan_dir.directory?

      scan_dir.glob('*.liquid') do |f|
        types.add(f.basename('.liquid').to_s)
      end
    end
  end

  # Collect from default directory
  if @default_dir&.exist? && @default_dir.directory?
    @default_dir.glob('*.liquid') do |f|
      types.add(f.basename('.liquid').to_s)
    end
  end

  types.to_a.sort
end

#clear_cache ⇒ Object

Clear the template cache (useful when template directories change)



115
116
117
 
# File 'lib/coradoc/html/template_locator.rb', line 115

def clear_cache
  @cache.clear
end

#default_template_dir ⇒ Pathname

Get the default template directory path

Returns:

  • (Pathname) —

    Path to default templates



110
111
112
 
# File 'lib/coradoc/html/template_locator.rb', line 110

def default_template_dir
  DEFAULT_TEMPLATE_DIR
end

#exists?(type_name) ⇒ Boolean

Check if a template exists (without loading it)

Parameters:

  • type_name (String) —

    The template type

Returns:

  • (Boolean) —

    True if template exists



76
77
78
 
# File 'lib/coradoc/html/template_locator.rb', line 76

def exists?(type_name)
  !find(type_name).nil?
end

#find(type_name) ⇒ Pathname?

Find a template by type name

Parameters:

  • type_name (String) —

    The template type (e.g., “bibliography”, “section”)

Returns:

  • (Pathname, nil) —

    Path to template file or nil if not found



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
 
# File 'lib/coradoc/html/template_locator.rb', line 45

def find(type_name)
  return @cache[type_name] if @cache.key?(type_name)

  # First check user directories (core_model/ subdir, then root)
  @user_dirs.each do |dir|
    %W[#{dir}/#{CORE_MODEL_DIR}/#{type_name}.liquid #{dir}/#{type_name}.liquid].each do |template_path|
      path = Pathname.new(template_path)
      if path.exist?
        @cache[type_name] = path
        return path
      end
    end
  end

  # Then check default directory
  if @default_dir
    template_path = @default_dir / "#{type_name}.liquid"
    if template_path.exist?
      @cache[type_name] = template_path
      return template_path
    end
  end

  @cache[type_name] = nil
  nil
end