[evolvis-commits] r18424: sync renaming of files

mirabilos at evolvis.org mirabilos at evolvis.org
Wed May 23 17:17:51 CEST 2012


Author: mirabilos
Date: 2012-05-23 17:17:51 +0200 (Wed, 23 May 2012)
New Revision: 18424

Added:
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.EvolvisTable
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-elements
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-utils
Removed:
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-elements
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-utils
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.html:EvolvisTable
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.html:elements
   trunk/gforge_base/evolvisforge-5.1/src/docs/README.html:utils
Log:
sync renaming of files

XXX how do I get the correct file ID mapped?

Copied: trunk/gforge_base/evolvisforge-5.1/src/docs/README.EvolvisTable (from rev 18423, trunk/gforge_base/evolvisforge-5.1/src/docs/README.html:EvolvisTable)
===================================================================
--- trunk/gforge_base/evolvisforge-5.1/src/docs/README.EvolvisTable	                        (rev 0)
+++ trunk/gforge_base/evolvisforge-5.1/src/docs/README.EvolvisTable	2012-05-23 15:17:51 UTC (rev 18424)
@@ -0,0 +1,145 @@
+Documentation of new Evolvis table class
+────────────────────────────────────────
+
+Functions defined in common/include/EvolvisTable.class.php → require.
+
+See below for an example. Currently, colspan is supported but
+rowspan isn’t, as that would complicate the code enormously
+and was not needed when this was designed. This API is leaned
+on – but simplified from – the Prototype.js table/DOM API.
+
+
+‣ class EvolvisTable
+
+– integer ncols
+  Read-only: number of columns in this table.
+
+– array rows
+  Indexed list of table rows, for direct manipulation.
+
+• constructor EvolvisTable(array $title_arr, optional(false) array $links_arr,
+    optional(empty) array $param)
+
+  Prepare a new table instance. The indexed $title_arr contains the
+  titles (<th> in first <tr>) of each colum, and with that, defines
+  the table width. For a headless table, $title_arr[0] === false,
+  but it still m̲u̲s̲t̲ be filled in.
+
+  Members of $title_arr may be arrays themselves. If so, they must
+  be indexed and have two members, [0] being the text, [1] being
+  an array suitable for passing as HTML attributes to html_ao().
+  Default attributes will be applied to it but not overwrite the
+  supplied attributes; the default CSS class is prepended, no matter
+  whether unset, string or array, to $title_arr[$i][1]['class'].
+
+  If $links_arr is set, it’s expected to be of equal magnitude as
+  $title_arr and makes the <th> content be hyperlinks to the targets
+  respective. (See Theme.class.php $HTML->listTableTop() for info.)
+
+  The associative $param is passed to $HTML->listTableStart() after
+  amending with the title and links arrays and the topless attribute.
+
+• new[EvolvisTableRow] tr(optional(empty) array $attrs,
+    optional(-1) integer $pos)
+
+  Create a new subrow and insert it after position $pos or at the end.
+  $attrs is passed to the EvolvisTableRow constructor.
+
+• string emit(void)
+
+  Return a string rendering the entire <table>‥</table> or,
+  if no rows have been defined, an empty string. The table
+  rows have $HTML->boxGetAltRowStyle() applied, and the
+  $HTML->listTableStart() theme method is used.
+
+  If a row does not have exactly «ncols» columns, an Exception
+  is raised.
+
+
+‣ class EvolvisTableRow
+
+– array attrs
+  Attributes of the <tr> tag, passed to html_eo().
+
+– array cols
+  Indexed list of tablerow columns, for direct manipulation.
+
+• constructor EvolvisTableRow(optional(empty) array $attrs)
+
+  The $attrs argument is stored for later.
+
+• new[EvolvisTableColumn] th(optional(empty) array $attrs,
+    optional(-1) integer $atpos, optional(false) string $txt)
+• new[EvolvisTableColumn] td(optional(empty) array $attrs,
+    optional(-1) integer $atpos, optional(false) string $txt)
+
+  Create a new column as <th> or <td>, respectively, and insert
+  it after position $atpos or at the end. $attrs is passed to the
+  EvolvisTableColumn constructor. If $txt !== false, it is passed
+  to the EvolvisTableColumn->set() method immediately. (That method
+  HTML-encodes its argument!)
+
+• integer getncols(void)
+
+  Return width of all column childs, taking colspan into account.
+
+• string emit(void)
+
+  Return XHTML for <tr>‥</tr>.
+
+
+‣ class EvolvisTableColumn
+
+– string type
+  Type ('th' or 'td') of the cell.
+
+– array attrs
+  Attributes of the cell tag, passed to html_e().
+
+– string content
+  InnerHTML of the cell.
+
+• constructor EvolvisTableColumn(optional(empty) array $attrs,
+    optional('td') string $type)
+
+• string emit(void)
+
+• void set(string $to)
+• void append(string $me)
+
+  Set the InnerHTML to, or append to, the passed value after
+  HTML-encoding it.
+
+• void setraw(string $to)
+• void appendraw(string $me)
+
+  Set the InnerHTML to, or append to, the passed value.
+
+
+
+‣ Example
+
+$t = new EvolvisTable(array('ID', 'Title'));
+$r = $t->tr();
+$r->td()->setraw(html_e('tt', array(), $ath->getID()));
+$r->td()->set($ath->getSummary());
+$r = $t->tr();
+$t->td(array('colspan' => 2), -1, $somesummary);
+echo $t->emit();
+
+⇒ <table><tr>
+	<th>ID</th>
+	<th>Title</th>
+  </tr><tr bgcolor="#111111">
+	<td><tt>123</tt></td>
+	<td>Summary of Bug #123</td>
+  </tr><tr bgcolor="#222222">
+	<td colspan="2">Some Summary</td>
+  </tr></table>
+
+$t = new EvolvisTable(array(false));
+$t->tr()->td()->setraw(html_e('a', array('href' => '…'),
+    util_html_secure($somecontent)));
+echo $t->emit();
+
+⇒ <table><tr><td><a href="…">Some Content</a></td></tr></table>

Copied: trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-elements (from rev 18423, trunk/gforge_base/evolvisforge-5.1/src/docs/README.html:elements)
===================================================================
--- trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-elements	                        (rev 0)
+++ trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-elements	2012-05-23 15:17:51 UTC (rev 18424)
@@ -0,0 +1,142 @@
+Documentation of new HTML element creation functions
+────────────────────────────────────────────────────
+
+Functions defined in src/www/include/html.php → available: always.
+
+
+‣ Element emission functions (do not echo anything)
+
+
+• string html_eo(string $name, optional(empty) array $attrs)
+
+	html_eo('b')
+	⇒ '<b>'
+
+	html_eo('td', array('colspan' => 2))
+	⇒ '<td colspan="2">'
+
+	html_eo('div', array('class' => array('ff', 'important')))
+	⇒ '<div class="ff important">'
+
+	html_eo('img', array(
+		'src' => '…',
+		'ref' => false,
+		'class' => array(),
+		'alt' => "",
+	    ))
+	⇒ '<img src="…" alt="">'
+
+  Generate an XHTML E̲lement O̲pen tag for $name, with attributes
+  defined by key/value pairs properly inserted. Attribute values
+  are coerced into strings from integers (by casting) or arrays
+  (by concatenating the array elements with spaces); if the value
+  is === false or an empty array (count($attrs[n]) == 0), the
+  attribute is not output at all, but for empty values it is; see
+  the img example (admittedly bad, you’d use html_e() for "img").
+
+• string html_e(string $name, optional(empty) array $attrs,
+    optional(empty) string $content, optional(true) bool $shortform)
+
+	html_e('br')
+	⇒ '<br />'
+
+	html_e('a', array('href' => '/foo.php?a=1&b=2'), 'täxt')
+	⇒ '<a href="/foo.php?a=1&b=2">täxt</a>'
+
+	html_e('script', array(
+		'type' => 'text/javascript',
+		'src' => '/js/foo.js',
+	    ), "", false)
+	⇒ '<script type="text/javascript" src="/js/foo.js"></script>'
+	/* needed because <script ... /> does not work */
+
+	html_e('tr', array(), html_e('td', array(), 'bla'))
+	⇒ '<tr><td>bla</td></tr>'
+
+  As with html_eo() the first two arguments define the tag to open.
+  The third argument will be placed between the opening and closing
+  tags but – in contrast to attribute values – not entity-encoded.
+  If the third argument is empty, either a self-closing (default)
+  tag, or, if the fourth argument is false, an open-close sequence,
+  is emitted.
+
+
+‣ Autoclose stack functions
+
+	$spos = html_ap();
+	$s = html_ao('p');
+	if ($foo) {
+		$s .= html_ao('strong');
+	}
+	$s .= html_ao('a', array('href' => '/'));
+	$s .= somefunc();
+	$s .= html_ac($spos);
+	⇒ '<p><strong><a href="/">somefuncreturnvalue</a></strong></p>'
+	⇒ '<p><a href="/">somefuncreturnvalue</a></p>'
+
+• integer html_ap(void)
+
+  Return the a̲utoclose stack’s current p̲osition.
+
+• string html_ao(string $name, optional(empty) array $attrs)
+
+  Works the same as html_eo() but pushes $name onto the a̲utoclose
+  element stack when o̲pening it.
+
+• string html_ac(integer $spos)
+
+  Return a set of closing elements until the a̲utoc̲lose stack
+  has reached the position it had when html_ap() returned $spos.
+
+  If $spos === false: an empty string is returned, for html_aonce().
+
+  If $spos < current stack position, an Exception is raised.
+
+• string html_aonce(ByRef integer $sptr, string $name,
+    optional(empty) array $attrs)
+
+	$spos = false;
+	foreach ($row in $rows) {
+		echo html_aonce('table');
+		echo html_e('tr', array(), html_e('td', array(),
+		    util_html_secure($row['data'])));
+	}
+	echo html_ac($spos);
+	⇒ ''  // if $rows is empty
+	⇒ '<table><tr><td>content1</td></tr><tr><td>content2</td></tr></table>'
+
+  If $sptr is not false, do nothing. Otherwise, set it to
+  the current html_ap() then do html_ao($name, $attrs).
+
+  This function can easily be used to open an enclosing element
+  with mandatory inner elements, such as a table, only once except
+  if no table row were to be generated.
+
+‣ Autoclose stack copy functions
+
+	$spos = html_ap();
+	echo html_ao('tr', array('bgcolor' => '#FF0000'));
+	echo html_ao('td');
+	echo "content 1";
+	$scopy = html_a_copy($spos);
+	echo html_ac($spos);
+	echo html_e('tr', array(), html_e('td', array(), "intermediate"));
+	echo html_a_apply($scopy);
+	echo "content 2";
+	echo html_ac($spos);
+	echo html_a_apply($scopy);
+	echo "content 3";
+	echo html_ac($spos);
+
+	⇒ <tr bgcolor="#FF0000"><td>content 1</td></tr>
+	  <tr><td>intermediate</td></tr>
+	  <tr bgcolor="#FF0000"><td>content 2</td></tr>
+	  <tr bgcolor="#FF0000"><td>content 3</td></tr>
+
+• opaque html_a_copy(integer $spos)
+• string html_a_apply(opaque $scopy)
+
+  Before autoclosing the stack down to a level $spos, you can
+  retrieve a copy of the stack in an opaque format, which can
+  later be used to (re-)open the same elements, with the same
+  attributes, even in a different nesting state.

Copied: trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-utils (from rev 18423, trunk/gforge_base/evolvisforge-5.1/src/docs/README.html:utils)
===================================================================
--- trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-utils	                        (rev 0)
+++ trunk/gforge_base/evolvisforge-5.1/src/docs/README.html-utils	2012-05-23 15:17:51 UTC (rev 18424)
@@ -0,0 +1,132 @@
+Documentation of common HTML utility functions
+──────────────────────────────────────────────
+
+Please take note of the literature links at the bottom of this file.
+
+Functions defined in src/common/include/utils.php → available: always.
+
+
+• string util_html_encode(string $s)
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&b=2'        // HTML-encoded
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&amp;b=2'    // changed!
+
+  Encode a string for use in XHTML even if it is already encoded.
+
+• string util_html_secure(string $s)
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&b=2'    // HTML-encoded
+
+	util_html_secure('a=1&b=2')
+	⇒ 'a=1&b=2'    // unchanged
+
+  Encode a string for use in XHTML if it is not already encoded.
+  (So, if you use this for output sanitising, other than a slight
+  performance penalty no harm is done if the output was already
+  sane.)
+
+• string util_unconvert_htmlspecialchars(string $s)
+
+	util_unconvert_htmlspecialchars('a=1&b=2')
+	⇒ 'a=1&b=2'    // unchanged
+
+	util_unconvert_htmlspecialchars('a=1&b=2')
+	⇒ 'a=1&b=2'    // HTML-decoded
+
+  Undo util_html_encode; be careful, this can decode partially.
+
+
+• string util_gethref(optional(false) string $baseurl,
+    optional(empty) array $args, optional(true) bool $ashtml,
+    optional('&') string $sep)
+
+	util_gethref("/x.php", array(
+		'foo' => 'a+b&c',
+		'bar' => 'd+b&e',
+	    ));
+	⇒ "/x.php?foo=a%2Bb%26c&bar=d%2Bb%26e"
+
+	util_gethref("/x.php", array(
+		'foo' => 'a+b&c',
+		'bar' => 'd+b&e',
+	    ), false);
+	⇒ /x.php?foo=a%2Bb%26c&bar=d%2Bb%26e
+
+	util_gethref("/x.php", array(
+		'foo' => 'a+b&c',
+		'bar' => 'd+b&e',
+	    ), true, ';')
+	⇒ "/x.php?foo=a%2Bb%26c;bar=d%2Bb%26e"
+
+  Construct an URI for use with util_make_url, session_redirect,
+  html_e('a', array('href' => …)), and similar. The first argument
+  ($baseurl) is passed through as-is but, if falsy, defaults to
+  getStringFromServer('PHP_SELF'); the arguments (both keys and
+  values) are urlencoded (entries while values is false are not
+  emitted at all) and appended, with a question mark in front and
+  the $sep separator in between.
+
+  If $ashtml is true (default), the result will then be run through
+  util_html_encode; set this to false when using in html_e href as
+  value (since html_e will html-encode itself).
+
+• string util_make_url(string $path)
+
+	util_make_url('/foo.php?a=1&b=2')
+	⇒ 'https://forge.domain.com/fusionforge/foo.php?a=1&b=2'
+
+  Return an absolute URI for the path in question, containing the
+  system-defined protocol, hostname and (if defined) webroot prefix.
+
+  Both html-encoded and not html-encoded return values of util_gethref
+  are safe to pass as arguments, if their baseurl was only a path.
+
+• string util_tasktracker_links(string $s)
+
+  Convert references of the form [#123], [T456], [forum:789], [wiki:Foo]
+  to appropriate hyperlinks to, in this order, the task/tracker item
+  with the aid/tid 123 (defaulting to tracker if not unique), the task
+  item with the tid 456, the forum message with the msgid 789, the Wiki
+  page of the name Foo (phpwiki in FusionForge, MediaWiki in Evolvis).
+
+  Wiki page conversion needs the global variable $group_id set correctly.
+
+• string util_pwrap(string $encoded_string)
+• string util_ttwrap(string $encoded_string, optional('p') string $tag)
+
+  Wrap an already HTML-encoded string into <p>…</p> or
+  <p><tt>…</tt></p> blocks at Unix newline ("\n") boundaries.
+
+• integer|false util_nat0(ByRef string $s)
+
+  If and only if $s is the normalised positive integer (ℕ₀)
+  representation of a number, return that number; false otherwise.
+  Limited by system constraints, i.e. usually [0;2³¹-1].
+
+• void html_generic_fileheader(string $title)
+
+  Print (echo) a standard XHTML header, consisting of the XML declaration
+  if needed, the DOCTYPE, the html and head opening tags, the title tag,
+  and a few necessary meta tags. The title will be HTML-secured.
+
+
+‣ common non-HTML utility functions
+
+
+• mixed util_ifsetor(ByRef mixed $val, optional(false) mixed $default)
+
+  If isset($val), return $val, otherwise (no warning) $default.
+
+• string debug_string_backtrace(void)
+
+  Return the current debugging backtrace as string.
+
+
+Literature
+──────────
+
+• http://me.veekun.com/blog/2012/04/09/php-a-fractal-of-bad-design/



More information about the evolvis-commits mailing list