Internal API

The internal API includes implementation details, helper functions, and low-level utilities that power HypertextTemplates but are not intended for direct use. These APIs may change between minor versions without notice as we optimize performance or refactor internals. While these functions are documented for contributors and those needing to understand the implementation, you should avoid depending on them in production code. If you find yourself needing internal functionality, please open an issue - it might indicate a gap in the public API that we should address.

HypertextTemplates.MicroBatchWriter — Type

MicroBatchWriter <: IO

Internal writer that implements the micro-batching strategy. It acts as an intelligent buffer between the rendering code and the Channel, making decisions about when to send data based on size and time thresholds.

The writer follows these rules:

Large writes (≥ immediate_threshold) bypass buffering entirely
Small writes accumulate in a buffer until a threshold is reached
A timer ensures buffered data is flushed within maxbuffertime

source

HypertextTemplates.TemplateFileLookup — Method

TemplateFileLookup(handler)

This is a developer tool that can be added to an HTTP handler stack to allow the user to open the template file in their default editor by holding down the Ctrl key and clicking on the rendered template. This is useful for debugging navigating the template files instead of having to manually search through a codebase for the template file that renders a given item within a page.

HTTP.serve(router |> TemplateFileLookup, host, port)

Always add the TemplateFileLookup handler after the other handlers, since it needs to inject a script into the response to listen for clicks on the rendered template.

source

HypertextTemplates.create_flush_timer — Method

create_flush_timer(writer::MicroBatchWriter)

Create a Timer that periodically flushes the writer's buffer if data is present and enough time has passed since the last write.

The timer is crucial for bounded latency - without it, small writes that don't trigger size-based flushing could sit in the buffer indefinitely. This ensures that even a single character written will appear within maxbuffertime.

source

HypertextTemplates.escape_attr — Method

escape_attr(io::IO, value)

Write HTML attribute-escaped content to an IO stream.

This function escapes characters that have special meaning in HTML attributes, providing more comprehensive escaping than escape_html. It is automatically called for all attribute values unless wrapped in SafeString.

Escaped characters

& → &
< → <
> → >
" → "
' → '

Arguments

io::IO: The output stream to write to
value: The attribute value to escape (converted to string if not already)

Note

This function provides defense-in-depth but cannot prevent all attribute-based attacks. Always validate URLs and other sensitive attribute values at the application level.

See also: escape_html, SafeString

source

HypertextTemplates.escape_html — Method

escape_html(io::IO, value)

Write HTML-escaped content to an IO stream.

This function escapes HTML special characters to prevent XSS attacks when rendering user content. It is automatically called by HypertextTemplates for all string content unless wrapped in SafeString.

Escaped characters

& → &
< → <
> → >

Arguments

io::IO: The output stream to write to
value: The content to escape (converted to string if not already)

Examples

julia> using HypertextTemplates

julia> io = IOBuffer();

julia> HypertextTemplates.escape_html(io, "Hello <script>alert('XSS')</script>")

julia> String(take!(io))
"Hello &lt;script&gt;alert('XSS')&lt;/script&gt;"

julia> # SafeString content is not escaped
       io = IOBuffer();

julia> HypertextTemplates.escape_html(io, SafeString("<b>Bold</b>"))

julia> String(take!(io))
"<b>Bold</b>"

source

HypertextTemplates.render — Method

render([dst], component; properties...)

Render the component with the given properties to the optional dst. This is the functional version of @render.

source