Class: Phlex::SGML

Inherits:
Object
  • Object
show all
Includes:
Helpers
Defined in:
lib/phlex/sgml.rb

Overview

**Standard Generalized Markup Language** for behaviour common to HTML and SVG.

Direct Known Subclasses

HTML, SVG

Defined Under Namespace

Modules: Elements, SafeObject Classes: SafeValue, State

Constant Summary collapse

UNSAFE_ATTRIBUTES = 
Set.new(%w[srcdoc sandbox http-equiv]).freeze
REF_ATTRIBUTES = 
Set.new(%w[href src action formaction lowsrc dynsrc background ping]).freeze
ERBCompiler = 
ERB::Compiler.new("<>").tap do |compiler|
  compiler.pre_cmd    = [""]
  compiler.put_cmd    = "@_state.buffer.<<"
  compiler.insert_cmd = "__implicit_output__"
  compiler.post_cmd   = ["nil"]

  def compiler.add_insert_cmd(out, content)
    out.push("#{@insert_cmd}((#{content}))")
  end
end

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.call ⇒ Object

Render the view to a String. Arguments are delegated to new.



23
24
25
 
# File 'lib/phlex/sgml.rb', line 23

def call(...)
  new(...).call
end

.erb(method_name, erb = nil, locals: nil, &block) ⇒ Object 



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
 
# File 'lib/phlex/sgml.rb', line 39

def erb(method_name, erb = nil, locals: nil, &block)
  loc = caller_locations(1, 1)[0]
  path = loc.path.delete_suffix(".rb")
  file = loc.path
  line = loc.lineno - 1

  unless erb
    method_path = "#{path}/#{method_name}.html.erb"
    sidecar_path = "#{path}.html.erb"

    if File.exist?(method_path)
      erb = File.read(method_path)
      file = method_path
      line = 1
    elsif method_name == :view_template && File.exist?(sidecar_path)
      erb = File.read(sidecar_path)
      file = sidecar_path
      line = 1
    else
      raise Phlex::RuntimeError.new("        No ERB template found for \#{method_name}\n      MESSAGE\n    end\n  end\n\n  code, _enc = ERBCompiler.compile(erb)\n\n  class_eval(<<~RUBY, file, line)\n    def \#{method_name} \#{locals}\n      \#{code}\n    end\n  RUBY\nend\n")

.new(*a, **k, &block) ⇒ Object

Note:

The block will not be delegated to #initialize. Instead, it will be sent to #view_template when rendering.

Create a new instance of the component.



29
30
31
32
33
34
35
36
37
 
# File 'lib/phlex/sgml.rb', line 29

def new(*a, **k, &block)
  if block
    object = super(*a, **k, &nil)
    object.instance_exec { @_content_block = block }
    object
  else
    super
  end
end

Instance Method Details

#cache(*cache_key, &content) ⇒ Object

Cache a block of content.

“‘ruby end “`



283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/phlex/sgml.rb', line 283

def cache(*cache_key, **, &content)
  location = caller_locations(1, 1)[0]

  full_key = [
    app_version_key,                                   # invalidates the key when deploying new code in case of changes
    self.class.name,                                   # prevents collisions between classes
    (self.class.object_id if enable_cache_reloading?), # enables reloading
    location.base_label,                               # prevents collisions between different methods
    location.lineno,                                   # prevents collisions between different lines
    cache_key,                                         # allows for custom cache keys
  ].freeze

  low_level_cache(full_key, **, &content)

  nil
end

#call(buffer = +"",, context: {}, fragments: nil) ⇒ Object 



86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/phlex/sgml.rb', line 86

def call(buffer = +"", context: {}, fragments: nil, &)
  state = Phlex::SGML::State.new(
    user_context: context,
    output_buffer: buffer,
    fragments: fragments&.to_set,
  )

  internal_call(parent: nil, state:, &)

  state.output_buffer << state.buffer
end

#capture(*args, &block) ⇒ Object

Capture the output of the block and returns it as a string.



211
212
213
214
215
216
217
218
219
 
# File 'lib/phlex/sgml.rb', line 211

def capture(*args, &block)
  return "" unless block

  if args.length > 0
    @_state.capture { __yield_content_with_args__(*args, &block) }
  else
    @_state.capture { __yield_content__(&block) }
  end
end

#comment ⇒ Object

Wrap the output in an HTML comment.

[MDN Docs](developer.mozilla.org/en-US/docs/Web/HTML/Comments)



181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/phlex/sgml.rb', line 181

def comment(&)
  state = @_state
  return unless state.should_render?

  buffer = state.buffer

  buffer << "<!-- "
  __yield_content__(&)
  buffer << " -->"

  nil
end

#context ⇒ Object 



136
137
138
139
140
141
142
143
144
 
# File 'lib/phlex/sgml.rb', line 136

def context
  if rendering?
    @_state.user_context
  else
    raise Phlex::ArgumentError.new("      You can\u2019t access the context before the component has started rendering.\n    MESSAGE\n  end\nend\n")

#flush ⇒ Object

Flush the current state to the output buffer.



243
244
245
 
# File 'lib/phlex/sgml.rb', line 243

def flush
  @_state.flush
end

#fragment(name) ⇒ Object

Define a named fragment that can be selectively rendered.



222
223
224
225
226
227
228
 
# File 'lib/phlex/sgml.rb', line 222

def fragment(name)
  state = @_state
  state.begin_fragment(name)
  yield
  state.end_fragment(name)
  nil
end

#internal_call(parent: nil, state: nil, &block) ⇒ Object 



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/phlex/sgml.rb', line 98

def internal_call(parent: nil, state: nil, &block)
  if @_state
    raise Phlex::DoubleRenderError.new(
      "You can't render a #{self.class.name} more than once."
    )
  end

  @_state = state

  return "" unless render?

  block ||= @_content_block

  Thread.current[:__phlex_component__] = [self, Fiber.current.object_id].freeze

  state.around_render(self) do
    before_template(&block)

    around_template do
      if block
        view_template do |*args|
          if args.length > 0
            __yield_content_with_args__(*args, &block)
          else
            __yield_content__(&block)
          end
        end
      else
        view_template
      end
    end

    after_template(&block)
  end
ensure
  Thread.current[:__phlex_component__] = [parent, Fiber.current.object_id].freeze
end

#json_escape(string) ⇒ Object 



335
336
337
 
# File 'lib/phlex/sgml.rb', line 335

def json_escape(string)
  ERB::Util.json_escape(string)
end

#low_level_cache(cache_key, **options, &content) ⇒ Object

Cache a block of content where you control the entire cache key. If you really know what you’re doing and want to take full control and responsibility for the cache key, use this method.

“‘ruby low_level_cache([Commonmarker::VERSION, Digest::MD5.hexdigest(@content)]) do

markdown(@content)

end “‘

Note: To allow you more control, this method does not take a splat of cache keys. If you need to pass multiple cache keys, you should pass an array.



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/phlex/sgml.rb', line 312

def low_level_cache(cache_key, **options, &content)
  state = @_state

  cached_buffer, fragment_map = cache_store.fetch(cache_key, **options) { state.caching(&content) }

  if state.should_render?
    fragment_map.each do |fragment_name, (offset, length, nested_fragments)|
      state.record_fragment(fragment_name, offset, length, nested_fragments)
    end
    state.buffer << cached_buffer
  else
    fragment_map.each do |fragment_name, (offset, length, nested_fragments)|
      if state.fragments.include?(fragment_name)
        state.fragments.delete(fragment_name)
        state.fragments.subtract(nested_fragments)
        state.buffer << cached_buffer.byteslice(offset, length)
      end
    end
  end

  nil
end

#plain(content) ⇒ Object

Output plain text.



153
154
155
156
157
158
159
 
# File 'lib/phlex/sgml.rb', line 153

def plain(content)
  unless __text__(content)
    raise Phlex::ArgumentError.new("You've passed an object to plain that is not handled by format_object. See https://rubydoc.info/gems/phlex/Phlex/SGML#format_object-instance_method for more information")
  end

  nil
end

#raw(content) ⇒ Object

Output the given safe object as-is. You may need to use ‘safe` to mark a string as a safe object.



195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/phlex/sgml.rb', line 195

def raw(content)
  case content
  when Phlex::SGML::SafeObject
    state = @_state
    return unless state.should_render?

    state.buffer << content.to_s
  when nil, "" # do nothing
  else
    raise Phlex::ArgumentError.new("You passed an unsafe object to `raw`.")
  end

  nil
end

#render(renderable = nil) ⇒ Object 



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/phlex/sgml.rb', line 247

def render(renderable = nil, &)
  case renderable
  when Phlex::SGML
    renderable.internal_call(state: @_state, parent: self, &)
  when Class
    if renderable < Phlex::SGML
      render(renderable.new, &)
    end
  when Enumerable
    renderable.each { |r| render(r, &) }
  when Proc, Method
    if renderable.arity == 0
      __yield_content_with_no_yield_args__(&renderable)
    else
      __yield_content__(&renderable)
    end
  when String
    plain(renderable)
  when nil
    __yield_content__(&) if block_given?
  else
    raise Phlex::ArgumentError.new("You can't render a #{renderable.inspect}.")
  end

  nil
end

#rendering? ⇒ Boolean

Returns ‘false` before rendering and `true` once the component has started rendering. It will not reset back to false after rendering.



148
149
150
 
# File 'lib/phlex/sgml.rb', line 148

def rendering?
  !!@_state
end

#safe(value) ⇒ Object Also known as: 🦺

Mark the given string as safe for HTML output.



231
232
233
234
235
236
237
238
 
# File 'lib/phlex/sgml.rb', line 231

def safe(value)
  case value
  when String
    Phlex::SGML::SafeValue.new(value)
  else
    raise Phlex::ArgumentError.new("Expected a String.")
  end
end

#to_proc ⇒ Object 



82
83
84
 
# File 'lib/phlex/sgml.rb', line 82

def to_proc
  proc { |c| c.render(self) }
end

#view_template ⇒ Object 



74
75
76
77
78
79
80
 
# File 'lib/phlex/sgml.rb', line 74

def view_template
  if block_given?
    yield
  else
    plain "Phlex Warning: Your `#{self.class.name}` class doesn't define a `view_template` method. If you are upgrading to Phlex 2.x make sure to rename your `template` method to `view_template`. See: https://beta.phlex.fun/guides/v2-upgrade.html"
  end
end

#whitespace ⇒ Object

Output a single space character. If a block is given, a space will be output before and after the block.



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/phlex/sgml.rb', line 162

def whitespace(&)
  state = @_state
  return unless state.should_render?

  buffer = state.buffer

  buffer << " "

  if block_given?
    __yield_content__(&)
    buffer << " "
  end

  nil
end