[prev in list] [next in list] [prev in thread] [next in thread]
List: pear-doc
Subject: [PEAR-DOC] =?utf-8?q?svn:_/pear/peardoc/trunk/en/package/_html/html-common2/attributes.xml_html/html
From: Alexey_Borzov <avb () php ! net>
Date: 2010-10-19 18:36:00
Message-ID: svn-avb-1287513360-304513-1622920873 () svn ! php ! net
[Download RAW message or body]
avb Tue, 19 Oct 2010 18:36:00 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=304513
Log:
End-user docs for HTML_Common2
Changed paths:
A pear/peardoc/trunk/en/package/html/html-common2/
A pear/peardoc/trunk/en/package/html/html-common2/attributes.xml
A pear/peardoc/trunk/en/package/html/html-common2/options.xml
A pear/peardoc/trunk/en/package/html/html-common2/subclassing.xml
A pear/peardoc/trunk/en/package/html/html-common2.xml
U pear/peardoc/trunk/en/package/html-entities.xml
["svn-diffs-304513.txt" (text/x-diff)]
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>"\11"</literal> + </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>'linebreak'</literal></term>
+ <listitem><simpara>
+ string used to indicate linebreak, defaults to \
<literal>"\12"</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, "watched" 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' => '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><input \
/></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;
--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic