svn: /pear/peardoc/trunk/en/package/ html/html-common2/attributes.xml html/html-common2/options.xml html/html-common2/subclassing.xml html/html-common2.xml html-entities.xml

Added: pear/peardoc/trunk/en/package/html/html-common2/attributes.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-common2/attributes.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-common2/attributes.xml	2010-10-19 18:36:00 UTC (rev 304513)
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet" xml:id="package.html.html-common2.attributes">
+ <refnamediv>
+  <refname>Attributes</refname>
+  <refpurpose>Working with HTML attributes.</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-common2.attributes.overview">
+  <info>
+   <title>Methods for Attributes Handling</title>
+  </info>
+  <para>
+   <classname>HTML_Common2</classname> class is intended as a parent class for classes representing
+   HTML elements and its main purpose is to allow easy attribute handling for instances of these
+   child classes. </para>
+  <para> Inividual attribute values can be set by <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::setAttribute"/> and read by <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::getAttribute"/> methods. Use <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::removeAttribute"/> to remove an attribute, calling
+    <function>setAttribute</function> without explicitly giving a new attribute value serves a
+   different purpose: <programlisting role="php"><![CDATA[
+// these calls are identical
+$html->setAttribute('checked');
+$html->setAttribute('checked', 'checked');
+    ]]></programlisting></para>
+  <para> You can completely replace attributes of <classname>HTML_Common2</classname> instance by
+   using <phd:pearapi phd:package="HTML_Common2" phd:linkend="HTML_Common2::setAttributes"/> method
+   and add/replace several new attributes at once by using <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::mergeAttributes"/>. By default <phd:pearapi
+    phd:package="HTML_Common2" phd:linkend="HTML_Common2::__construct">constructor</phd:pearapi> of
+    <classname>HTML_Common2</classname> calls <function>mergeAttributes</function>, so that some
+   default attributes can be provided by a subclass and only overridden if needed. Note that both of
+   the above methods can accept either a string of HTML attributes or an array of these.</para>
+  <para>Finally, <phd:pearapi phd:package="HTML_Common2" phd:linkend="HTML_Common2::getAttributes"/>
+   method returns the values of all the instance's attributes. Those can be returned either as an
+   associative array or a string. As the package is intended for <acronym>XHTML</acronym>-compliant
+   output, attribute names will always be lowercased and quotes will be used around attribute values
+   when outputting the attribute string.</para>
+ </refsection>
+ <refsection xml:id="package.html.html-common2.attributes.class">
+  <info>
+   <title>Working with CSS Classes</title>
+  </info>
+  <para>
+   <classname>HTML_Common2</classname> contains several methods to easily handle
+    <literal>'class'</literal> attribute of HTML tags: <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::addClass"/>, <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::removeClass"/> and <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::hasClass"/>. Their behaviour should be easily deducable from their
+   names: <programlisting role="php"><![CDATA[
+$html->setAttribute('class', 'foo bar');
+$html->removeClass('foo');
+if (!$html->hasClass('foo')) {
+    $html->addClass('notFoo');
+}
+echo $html->getAttribute('class');
+]]></programlisting> will output <screen><![CDATA[
+bar notFoo
+    ]]></screen></para>
+ </refsection>
+ <refsection xml:id="package.html.html-common2.attributes.example">
+  <info>
+   <title>Usage Example</title>
+  </info>
+  <para> The following example shows a somewhat minimal subclass of
+    <classname>HTML_Common2</classname> and possible ways to change its attributes.</para>
+  <example>
+   <title>Methods available for attribute handling</title>
+   <programlisting role="php"><![CDATA[
+// a non-abstract subclass of HTML_Common2
+class HTML_Tag_Foo extends HTML_Common2
+{
+    // some predefined attributes, won't be overwritten
+    protected $attributes = array('class' => 'pretty');
+
+    // basic implementation of magic __toString() method
+    public function __toString()
+    {
+        return '<foo' . $this->getAttributes(true) . ' />';
+    }
+}
+
+$foo = new HTML_Tag_Foo(array('size' => 'small', 'align' => 'top left corner',
+                              'foo' => 'foo value'));
+// note how the attributes from this string will be handled
+$foo->mergeAttributes("bar LEVEL=0 value='Whatever'");
+$foo->removeAttribute('align');
+$foo->setAttribute('size', 'smaller');
+
+echo $foo;
+]]></programlisting>
+   <simpara>The above code will output:</simpara>
+   <screen><![CDATA[
+<foo class="pretty" size="smaller" foo="foo value" bar="bar" level="0" value="Whatever" />
+]]></screen>
+  </example>
+ </refsection>
+</refentry>

Added: pear/peardoc/trunk/en/package/html/html-common2/options.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-common2/options.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-common2/options.xml	2010-10-19 18:36:00 UTC (rev 304513)
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.html.html-common2.options"
+ >
+ <refnamediv>
+  <refname>Options</refname>
+  <refpurpose>Setting document-wide options.</refpurpose>
+ </refnamediv>
+
+ <refsection xml:id="package.html.html-common2.options.overview">
+  <info><title>Overview</title></info>
+  <para>
+   <classname>HTML_Common2</classname> provides static <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::setOption" /> and <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::getOption" /> methods for defining the document-wide configuration.
+   Predefined options in <classname>HTML_Common2</classname> are:
+   <variablelist>
+    <varlistentry>
+     <term><literal>'charset'</literal></term>
+     <listitem><simpara>
+      Charset parameter to use in <link xmlns:xlink="http://www.w3.org/1999/xlink"
+       xlink:href="&url.php.lookup;htmlspecialchars"><function>htmlspecialchars</function></link>
+      calls, defaults to <literal>'ISO-8859-1'</literal>
+     </simpara></listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><literal>'indent'</literal></term>
+     <listitem><simpara>
+      string used to indent HTML elements, defaults to <literal>&quot;\11&quot;</literal>
+     </simpara></listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><literal>'linebreak'</literal></term>
+     <listitem><simpara>
+      string used to indicate linebreak, defaults to <literal>&quot;\12&quot;</literal>
+     </simpara></listitem>
+    </varlistentry>
+   </variablelist>
+   It is suggested that child classes of <classname>HTML_Common2</classname> use the above
+   parameters when generating HTML.
+  </para>
+  <para>
+   Note that <function>setOption</function> and <function>getOption</function> allow any option
+   names so packages depending on HTML_Common2 may add their own configuration:
+   <programlisting role="php"><![CDATA[
+HTML_Common2::setOption('my_option_name', 'My option value');
+// ...
+if (HTML_Common2::getOption('my_option_name')) {
+    // do something
+}
+]]></programlisting>
+  </para>
+  <note><simpara><function>getOption</function> will return &null; for an unknown option name, it
+   will return an array of all options and their values if option name is omitted.</simpara></note>
+ </refsection>
+</refentry>
+

Added: pear/peardoc/trunk/en/package/html/html-common2/subclassing.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-common2/subclassing.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-common2/subclassing.xml	2010-10-19 18:36:00 UTC (rev 304513)
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet" xml:id="package.html.html-common2.subclassing">
+ <refnamediv>
+  <refname>Subclassing <classname>HTML_Common2</classname></refname>
+  <refpurpose> Protected methods, output formatting, &quot;watched&quot; attributes. </refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.html.html-common2.subclassing.overview">
+  <info>
+   <title>Output formatting</title>
+  </info>
+  <para>
+   <classname>HTML_Common2</classname> does not generate any HTML itself, except for a HTML
+   attribute string. However, it provides several methods and configuration parameters that can be
+   used by child classes to format their output. </para>
+  <para> It is possible to specify indentation level of the current tag via <phd:pearapi
+    phd:package="HTML_Common2" phd:linkend="HTML_Common2::setIndentLevel"/> and HTML comment to
+   output beside tag via <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::setComment"/>. These methods have corresponding getters <phd:pearapi
+    phd:package="HTML_Common2" phd:linkend="HTML_Common2::getIndentLevel"/> and <phd:pearapi
+    phd:package="HTML_Common2" phd:linkend="HTML_Common2::getComment"/>. </para>
+  <para>There is also a protected <phd:pearapi phd:package="HTML_Common2"
+   phd:linkend="HTML_Common2::getIndent"/> method that returns a string to indent the current tag
+   based on indent level and <literal>'indent'</literal> configuration parameter.</para>
+ </refsection>
+ <refsection xml:id="package.html.html-common2.subclassing.protected">
+  <info>
+   <title>Protected Methods</title>
+  </info>
+  <para> Child classes may take advantage of protected static methods for handling of attributes
+   strings and arrays: <variablelist>
+    <varlistentry>
+     <term><phd:pearapi phd:package="HTML_Common2" phd:linkend="HTML_Common2::getAttributesString"
+      /></term>
+     <listitem>
+      <simpara>Creates a HTML attribute string from a given attribute array.</simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><phd:pearapi phd:package="HTML_Common2" phd:linkend="HTML_Common2::parseAttributes"
+      /></term>
+     <listitem>
+      <simpara>Parses a given attribute string into an attribute array, properly handles non-XHTML
+       strings.</simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><phd:pearapi phd:package="HTML_Common2" phd:linkend="HTML_Common2::prepareAttributes"
+      /></term>
+     <listitem>
+      <simpara>Creates a proper attribute array from given array or string. Attribute names are
+       lowercased, integer-based keys are converted to <literal>('value' =&gt; 'value')</literal>. This
+       is the preferred method to handle incoming attributes.</simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist></para>
+ </refsection>
+ <refsection xml:id="package.html.html-common2.subclassing.watched">
+  <info>
+   <title>Monitoring Changes to Specific Attributes</title>
+  </info>
+  <para> It is sometimes necessary either to prevent changing some attribute of a HTML tag (e.g.
+    <literal>type</literal> attribute of <literal>&lt;input /&gt;</literal> element) or monitor
+   changes to an attribute to do some additional processing (e.g. on changing element's
+    <literal>id</literal> attribute we should also update some references to that attribute). </para>
+  <para>
+   <classname>HTML_Common2</classname> provides means to do this additional processing in the form
+   of <phd:pearapi phd:package="HTML_Common2" phd:linkend="HTML_Common2::$watchedAttributes"/>
+   property and <phd:pearapi phd:package="HTML_Common2"
+    phd:linkend="HTML_Common2::onAttributeChange"/> method. When a change of an attribute with name
+   in <varname>$watchedAttributes</varname> array is attempted,
+    <function>onAttributeChange</function> is called instead of performing the attempted change. It
+   is up to the programmer implementing the method to decide what to do with the attribute. </para>
+ </refsection>
+ <refsection xml:id="package.html.html-common2.subclassing.example">
+  <info>
+   <title>Usage Example</title>
+  </info>
+  <para> The following code prevents setting <literal>type</literal> attribute except via
+   constructor and to update the <literal>value</literal> attribute when <literal>name</literal>
+   attribute changes. It also shows how to use methods provided by
+   <classname>HTML_Common2</classname> to format the resultant HTML. </para>
+  <example>
+   <title>Complex subclass of HTML_Common2</title>
+   <programlisting role="php"><![CDATA[
+$_REQUEST = array(
+    'foo' => 'Foo value',
+    'bar' => 'Bar value'
+);
+
+class HTML_Tag_Input extends HTML_Common2
+{
+    protected $watchedAttributes = array('name', 'type');
+
+    public function __construct($type, $name, $attributes = null)
+    {
+        $this->attributes['type'] = (string)$type;
+        $this->setName($name);
+        parent::__construct($attributes);
+    }
+
+    public function setName($name)
+    {
+        $this->attributes['name'] = (string)$name;
+        if (!empty($_REQUEST[$name])) {
+            $this->attributes['value'] = $_REQUEST[$name];
+        }
+    }
+
+    protected function onAttributeChange($name, $value)
+    {
+        if ('type' == $name) {
+            throw new Exception("Attribute 'type' is read-only");
+        } elseif ('name' == $name) {
+            if (null === $value) {
+                throw new Exception("Required attribute 'name' cannot be removed");
+            }
+            $this->setName($value);
+        }
+    }
+
+    public function __toString()
+    {
+        return ($this->getComment()
+                ? $this->getIndent() . '<!-- ' . $this->getComment() . ' -->' . HTML_Common2::getOption('linebreak')
+                : '')
+               . $this->getIndent() . '<input' . $this->getAttributes(true) . ' />';
+    }
+}
+
+$input = new HTML_Tag_Input('text', 'foo');
+
+echo $input . "\n";
+try {
+    $input->setAttribute('type', 'file');
+} catch (Exception $e) {
+    echo $e->getMessage() . "\n";
+}
+$input->setAttribute('name', 'bar')
+      ->setIndentLevel(1)
+      ->setComment('Simplified version of HTML_QuickForm2_Element_Input');
+echo $input;
+]]></programlisting>
+   <simpara> The above code will produce the following output: </simpara>
+   <screen><![CDATA[
+<input type="text" name="foo" value="Foo value" />
+Attribute 'type' is read-only
+        <!-- Simplified version of HTML_QuickForm2_Element_Input -->
+        <input type="text" name="bar" value="Bar value" />
+]]></screen>
+  </example>
+ </refsection>
+</refentry>

Added: pear/peardoc/trunk/en/package/html/html-common2.xml
===================================================================
--- pear/peardoc/trunk/en/package/html/html-common2.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/html/html-common2.xml	2010-10-19 18:36:00 UTC (rev 304513)
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<book
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.html.html-common2"
+ >
+ <info>
+  <title>HTML_Common2</title>
+  <abstract>
+   <para>
+    The <classname>HTML_Common2</classname> package provides methods for <acronym>HTML</acronym>
+    attributes handling and setting document-wide options. It is quite helpful as a building block
+    for packages generating HTML and is used as such by <phd:pearapi phd:package="HTML_QuickForm2"
+    /> package. Main features:
+    <itemizedlist>
+     <listitem><simpara>
+      Allows easy setting, removing, merging of <link
+       linkend="package.html.html-common2.attributes">HTML attributes</link>, working with
+      <acronym>CSS</acronym> classes;
+     </simpara></listitem>
+     <listitem><simpara>
+      Provides means to parse and generate HTML attribute strings;
+     </simpara></listitem>
+     <listitem><simpara>
+      Global document options: charset, linebreak and indentation characters;
+     </simpara></listitem>
+     <listitem><simpara>
+      Methods to handle indentation and HTML comments (useful in subclasses).
+     </simpara></listitem>
+    </itemizedlist>
+   </para>
+   <para>
+    Note that <classname>HTML_Common2</classname> is an abstract class, so you would probably
+    <link linkend="package.html.html-common2.subclassing">subclass it</link> and use a instance
+    of a child class rather than <classname>HTML_Common2</classname> itself. One notable exception
+    is using its static methods to get and set
+    <link linkend="package.html.html-common2.options">global document options</link>.
+   </para>
+  </abstract>
+ </info>
+ <chapter>
+  &package.html.html-common2.attributes;
+  &package.html.html-common2.options;
+  &package.html.html-common2.subclassing;
+ </chapter>
+</book>

Modified: pear/peardoc/trunk/en/package/html-entities.xml
===================================================================
--- pear/peardoc/trunk/en/package/html-entities.xml	2010-10-19 11:42:19 UTC (rev 304512)
+++ pear/peardoc/trunk/en/package/html-entities.xml	2010-10-19 18:36:00 UTC (rev 304513)
@@ -1,3 +1,4 @@
+&package.html.html-common2;
 &package.html.html-crypt;
 &package.html.html-css;
 &package.html.html-form;