1 Documentation of new HTML element creation functions
2 ────────────────────────────────────────────────────
4 Functions defined in src/common/include/html.php → available: always.
7 ‣ Element emission functions (do not echo anything)
10 • string html_eo(string $name, optional(empty) array $attrs)
15 html_eo('td', array('colspan' => 2))
18 html_eo('div', array('class' => array('ff', 'important')))
19 ⇒ '<div class="ff important">'
27 ⇒ '<img src="…" alt="">'
29 Generate an XHTML E̲lement O̲pen tag for $name, with attributes
30 defined by key/value pairs properly inserted. Attribute values
31 are coerced into strings from integers (by casting) or arrays
32 (by concatenating the array elements with spaces); if the value
33 is === false or an empty array (count($attrs[n]) == 0), the
34 attribute is not output at all, but for empty values it is; see
35 the img example (admittedly bad, you’d use html_e() for "img").
37 • string html_e(string $name, optional(empty) array $attrs,
38 optional(empty) string $content, optional(true) bool $shortform)
43 html_e('a', array('href' => '/foo.php?a=1&b=2'), 'täxt')
44 ⇒ '<a href="/foo.php?a=1&b=2">täxt</a>'
46 html_e('script', array(
47 'type' => 'text/javascript',
48 'src' => '/js/foo.js',
50 ⇒ '<script type="text/javascript" src="/js/foo.js"></script>'
51 /* needed because <script ... /> does not work */
53 html_e('tr', array(), html_e('td', array(), 'bla'))
54 ⇒ '<tr><td>bla</td></tr>'
56 As with html_eo() the first two arguments define the tag to open.
57 The third argument will be placed between the opening and closing
58 tags but – in contrast to attribute values – not entity-encoded.
59 If the third argument is empty, either a self-closing (default)
60 tag, or, if the fourth argument is false, an open-close sequence,
64 ‣ Autoclose stack functions
69 $s .= html_ao('strong');
71 $s .= html_ao('a', array('href' => '/'));
74 ⇒ '<p><strong><a href="/">somefuncreturnvalue</a></strong></p>'
75 ⇒ '<p><a href="/">somefuncreturnvalue</a></p>'
77 • integer html_ap(void)
79 Return the a̲utoclose stack’s current p̲osition.
81 • string html_ao(string $name, optional(empty) array $attrs)
83 Works the same as html_eo() but pushes $name onto the a̲utoclose
84 element stack when o̲pening it.
86 • string html_ac(integer $spos)
88 Return a set of closing elements until the a̲utoc̲lose stack
89 has reached the position it had when html_ap() returned $spos.
91 If $spos === false: an empty string is returned, for html_aonce().
93 If $spos < current stack position, an Exception is raised.
95 • string html_aonce(ByRef integer $sptr, string $name,
96 optional(empty) array $attrs)
99 foreach ($row in $rows) {
100 echo html_aonce('table');
101 echo html_e('tr', array(), html_e('td', array(),
102 util_html_secure($row['data'])));
105 ⇒ '' // if $rows is empty
106 ⇒ '<table><tr><td>content1</td></tr><tr><td>content2</td></tr></table>'
108 If $sptr is not false, do nothing. Otherwise, set it to
109 the current html_ap() then do html_ao($name, $attrs).
111 This function can easily be used to open an enclosing element
112 with mandatory inner elements, such as a table, only once except
113 if no table row were to be generated.
115 ‣ Autoclose stack copy functions
118 echo html_ao('tr', array('bgcolor' => '#FF0000'));
121 $scopy = html_a_copy($spos);
123 echo html_e('tr', array(), html_e('td', array(), "intermediate"));
124 echo html_a_apply($scopy);
127 echo html_a_apply($scopy);
131 ⇒ <tr bgcolor="#FF0000"><td>content 1</td></tr>
132 <tr><td>intermediate</td></tr>
133 <tr bgcolor="#FF0000"><td>content 2</td></tr>
134 <tr bgcolor="#FF0000"><td>content 3</td></tr>
136 • opaque html_a_copy(integer $spos)
137 • string html_a_apply(opaque $scopy)
139 Before autoclosing the stack down to a level $spos, you can
140 retrieve a copy of the stack in an opaque format, which can
141 later be used to (re-)open the same elements, with the same
142 attributes, even in a different nesting state.