This file contains some functions related to static HTML generation and HTML processing. See also utils.php (which is included by html.php) for the most basic HTML functions. Here are the more complex and/or less frequently used ones.

Contents

Contents

1. Simple HTML generators

1.1. code()

2. HTML processing functions

2.1. html_to_text()

2.2. split_html()

3. Complex HTML generators

3.1. print_list()

3.2. gen_list()

3.3. print_num_list(), gen_num_list()

3.4. print_list_recursively()

3.5. print_toc_content()

3.6. print_toc()

1. Simple HTML generators

1.1. code()

function code (...$text);

Enclose $text in <code> HTML tags, and return the result.

Multiple arguments are concatenated to a single string.

2. HTML processing functions

2.1. html_to_text()

function html_to_text ($code);

Remove the HTML tags in $code, reduce the spaces, and return the result. All whitespace characters (newline, tab, space) are converted to spaces, and they are removed from the beginning and end of the string.

Example: html_to_text("\t<p> some <b>text</b> </p>\n") == "some text"

2.2. split_html()

function split_html ($text);

Split the HTML code into an array of text segments and tags.

Example: split_html("<p>some <b>text</b></p>") == ["<p>", "some ", "<b>", "text", "</b>", "</p>"]

Note: always implode(split_html($string)) == $string.

3. Complex HTML generators

3.1. print_list()

function print_list       ($items, $attrs = []);
function print_list ($lng, $items, $attrs = []);

Print an HTML bullet list (<ul>).

$items: array of list items. Each element can be:

• an HTML string, which is simply printed as it is;
• a string in the format of get_lng_text(), in which case $lng is mandatory;
• array of HTML strings, which are contatenated and printed;
• null, which is skipped (i.e. no <li> is produced).

$attrs: optional additional attributes of the <ul> element (see: attrs()).

$lng: optional language object for multi-language texts. It can be null or even omitted.

3.2. gen_list()

function gen_list       ($items, $attrs = []);
function gen_list ($lng, $items, $attrs = []);

Same as print_list(), but return the list HTML as a string instead of printing it.

3.3. print_num_list(), gen_num_list()

function print_num_list       ($items, $attrs = []);
function print_num_list ($lng, $items, $attrs = []);
function   gen_num_list       ($items, $attrs = []);
function   gen_num_list ($lng, $items, $attrs = []);

Same as print_list() and gen_list(), respectively, but they print/return a numbered list (<ol>) instead of a bullet list.

3.4. print_list_recursively()

function print_list_recursively       ($list);
function print_list_recursively ($lng, $list);

Print a multi-level HTML bullet list recursively from an array.

$list: an array containing the list elements as strings or arrays, recursively. It can be in one of the following two forms:

1. An array of strings and arrays. Each first-level list element is either a string (a simple list element), or a string followed by an array, where the string is the title, and the array contains the sub-elements (recursively in the same format). The strings can optionally be in the format of get_lng_text() (if $lng is given).
2. An array of arrays, where each element array describes a first-level list element, and it can contain strings and optionally an array, where the strings form the text content of the list element (concatenated), and the array is the sub-list (recursively in the same format).

$lng: optional language object for multi-language texts. It can be null or even omitted.

Example: both of the following lines produce the list below:

print_list_recursively(["First item", "Second", ["2A", "2B"], "Third"]);
print_list_recursively([["First ","item "], ["Second ", [["2A "], ["2B "]]], ["Third "]]);

• First item
• Second
  • 2A
  • 2B
• Third

3.5. print_toc_content()

function print_toc_content ($obj, $toc, $start = 1);

Generate table of contents (TOC) and the content itself.

For a simple example, see HTML generators. Also, this documentation page was generated using print_toc_content(), so see its source code (docs/html.php) for another example.

$obj: the object whose methods and constants are referenced by $toc for the section titles and contents.

$toc: array of sections, each is [$level, $cont] or [$level, $cont, $id], where:

• $level: the level of the heading, more precisely the number of the HTML heading element, e.g. 4 means <h4>. The numbering of the sections are deduced from these heading levels, e.g. the headings <h3>, <h5>, <h3> will produce the section numbers 1, 1.1 and 2, respectively.
• $cont: the method that generates the content of the section, either as a method name ($cont == $method) of the argument $obj above, or as an array $cont == [$obj, $method]. In both cases, $obj->$method() is called, which should print the content of the section.
  • The title of the section is determined by one of the following ways:
    • By default, the class constant "{$method}_title" of the same $obj is used as the section title.
    • Alternatively, the class constant name can be given as an additional array element in $cont, i.e. [$obj, $method, $title] or [$method, $title], so that the class constant $obj::$title is used as the section title.
    • In both cases, if $obj->lng_obj() is valid, then the title constant is first searched in the object $obj->lng_obj() (so it can be language-dependent), then in $obj itself.
  • If $method == "toc", then this section is actually the table of contents, in which case no method is called (but the title works in the same way, i.e. by the constant toc_title). This "toc" should be present in the list, usually at the beginning, otherwise the TOC is not printed!
  • The $method can be preceded by an asterisk ("*") to indicate that this section has no number (otherwise see $level above for how these numbers are generated). It is usually applied to the TOC, i.e. "*toc".
• $id (optional): the HTML id of the section, so it can be referred to by the URL xyz.html#id. By default, $id is the method name ($method) of $cont.

$start: the first section number, by default 1. (This is useful if the TOC is split into multiple parts.)

3.6. print_toc()

function print_toc ($obj, $toc, $start = 1);

Generate table of contents (TOC).

This works similarly to print_toc_content(), with the following differences:

• Only the table of contents is printed, not the actual content.
• The section title (<h*>) of the TOC is not printed.
• The "toc" section is not necessary (it determines only whether the TOC is listed inside the TOC).
• $obj->$method() does not need to exist ($method is only used for the title).
• The $id member of $toc can also be a URL (either internal or external) if it contains the character # (i.e. it can be either "id", "#id" or "other.html#id"). (This is useful if the TOC and the content are on separate pages.)