_{Official ZPE/YASS documentation}HTMLBuilder object

Introduction

The HTMLBuilder object provides helper functions for generating HTML from common ZPE data structures such as lists and maps.

The object is designed to remove repetitive string concatenation by converting:

• Lists into HTML lists (<ul> / <ol>)
• Maps into HTML definition lists (<dl>)
• 2D lists into HTML tables (<table>)
• Lists of maps into HTML tables (record-style data)

This version of HTMLBuilder also supports:

• HTML escaping for safer output
• Attributes maps for adding classes/IDs/data attributes to generated tags
• Pretty-printing for readable HTML output
• Table headers, captions and structure (<thead>/<tbody>)
• Key sorting for stable definition list output

All functions exposed by this object require a permission level of 0.

HTMLBuilder object functions

The following is a list of internal functions the HTMLBuilder object exposes. All functions are ZPEObjectNativeFunctions therefore run in native code.

escape_html(string text) ⇒ string

Escapes special characters in a string so it can be safely inserted into HTML. This replaces characters such as <, >, &, quotes and apostrophes.

list_to_html_list(list array, boolean ordered, map attributes, boolean escape, boolean pretty, string indent) ⇒ string

Converts a list into an HTML list. If ordered is true, an ordered list (<ol>) is generated, otherwise an unordered list (<ul>) is generated.

Nested lists are supported: if an item within the list is itself a list, it will be converted recursively into a nested HTML list.

If attributes is provided, it is rendered as HTML attributes on the root list tag (e.g. class, id, data-*). If escape is true (recommended), all list item text is escaped.

If pretty is true, the generated HTML includes line breaks and indentation using indent.

map_to_html_definition_list(map array, map attributes, boolean sort_keys, boolean escape, boolean pretty, string indent) ⇒ string

Converts a map into an HTML definition list (<dl>), outputting each key as a <dt> and each value as a <dd>.

If sort_keys is true, keys are sorted alphabetically (based on their string value) before output is generated.

If attributes is provided, it is rendered as HTML attributes on the <dl> tag.

list_to_html_table(list array, map options) ⇒ string

Converts a 2D list (a list of rows, where each row is a list) into an HTML table. Table behaviour can be controlled using the options map. See Table options.

list_of_maps_to_html_table(list rows, list columns, map options) ⇒ string

Converts a list of maps into an HTML table. Each map is treated as a row.

If columns is provided, it defines the order of columns to output. If columns is omitted or empty, the columns are inferred from the keys of the first row map (note: map key order may not be deterministic unless sorting is enabled in options).

This is particularly useful for converting record-style or JSON-like data into a table.

Table options

The list_to_html_table and list_of_maps_to_html_table functions accept an options map to control how the table is generated. All keys are optional.

attributes ⇒ map

Attributes to place on the root <table> tag (e.g. class, id, data-*).

headers ⇒ list

A list of header labels. If provided, a header row is generated using <th>.

header_row ⇒ boolean

If true, the first row of the input data is treated as a header row and output using <th>.

caption ⇒ string

Adds a <caption> to the table.

thead ⇒ boolean

If true (default), header output is wrapped in <thead>.

tbody ⇒ boolean

If true (default), body rows are wrapped in <tbody>.

escape ⇒ boolean

If true (default), escapes all cell text before inserting into HTML.

pretty ⇒ boolean

If true, the output is formatted with new lines and indentation.

indent ⇒ string

The indentation string to use when pretty printing (default is two spaces).

sort_columns ⇒ boolean

Used by list_of_maps_to_html_table when columns are inferred. If true, inferred column keys are sorted.

header_from_columns ⇒ boolean

Used by list_of_maps_to_html_table. If true, the columns list is also used as a header row.

Examples

Converting a list into an unordered HTML list:

$b = new HTMLBuilderObject()

$items = ["One", "Two", "Three"]

print($b->list_to_html_list($items, false, null, true, false, "  "))

Nested lists are supported:

$b = new HTMLBuilderObject()

$nested = [
  "Top",
  ["A", "B"],
  "Bottom"
]

print($b->list_to_html_list($nested, false, null, true, true, "  "))

Adding attributes (such as a class) to a list:

$b = new HTMLBuilderObject()

$attrs = [=>]
$attrs["class"] = "navigation"

print($b->list_to_html_list(["Home", "Docs"], false, $attrs, true, false, "  "))

Converting a map into a definition list:

$b = new HTMLBuilderObject()

$m = [=>]
$m["CPU"] = "Ryzen"
$m["RAM"] = "16GB"

print($b->map_to_html_definition_list($m, null, true, true, true, "  "))

Building a table with headers and caption:

$b = new HTMLBuilderObject()

$rows = [
  ["Jamie", "Edinburgh"],
  ["Willie", "Dunbar"]
]

$opts = [=>]
$opts["headers"] = ["Name", "City"]
$opts["caption"] = "People"
$opts["pretty"] = true

print($b->list_to_html_table($rows, $opts))

Converting a list of maps into a table:

$b = new HTMLBuilderObject()

$rows = [
  [=> "name" : "Jamie", "role" : "Teacher"],
  [=> "name" : "Pete", "role" : "Assistant"]
]

$cols = ["name", "role"]

$opts = [=>]
$opts["header_from_columns"] = true
$opts["pretty"] = true

print($b->list_of_maps_to_html_table($rows, $cols, $opts))