cvs: peardoc /en/package/html/html-css api.xml errorhandler.xml faq.xml whatsnew.xml
[email protected] ("Laurent Laville")
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <cvsfarell1198337756@cvsserver> |
farell Sat Dec 22 15:35:56 2007 UTC
Added files:
/peardoc/en/package/html/html-css api.xml errorhandler.xml faq.xml
whatsnew.xml
Log:
initial commit of HTML_CSS 1.4.0 manual
farell-20071222153556.txt
(text/plain, 38 KB)
http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-css/api.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-css/api.xml
+++ peardoc/en/package/html/html-css/api.xml
<!-- $Revision: 1.1 $ -->
<refentry id="package.html.html-css.api">
<refnamediv>
<refname>API</refname>
<refpurpose>Application Programming Interface</refpurpose>
</refnamediv>
<refsect1 id="package.html.html-css.api.init">
<title>Initialize parser/writer options</title>
<para>
With the class constructor, you have ability to set many options :
<itemizedlist>
<listitem><emphasis role="bold">xhtml</emphasis> option
defines whether element selectors should be automatically lowercased.
See also: <methodname>HTML_CSS::setXhtmlCompliance()</methodname>.
</listitem>
<listitem><emphasis role="bold">tab</emphasis> option
defines the string used to indent CSS text.
See also: <methodname>HTML_CSS::setTab()</methodname>.
</listitem>
<listitem><emphasis role="bold">filename</emphasis> option
allow to parse an external css file.
See also: <methodname>HTML_CSS::parseFile()</methodname>.
</listitem>
<listitem><emphasis role="bold">cache</emphasis> option
controls caching of the page.
See also: <methodname>HTML_CSS::setCache()</methodname>.
</listitem>
<listitem><emphasis role="bold">oneline</emphasis> option
defines whether to output all properties on one line.
See also: <methodname>HTML_CSS::setSingleLineOutput()</methodname>.
</listitem>
<listitem><emphasis role="bold">groupsfirst</emphasis> option
determines whether to output groups before elements.
See also: <methodname>HTML_CSS::setOutputGroupsFirst()</methodname>.
</listitem>
<listitem><emphasis role="bold">allowduplicates</emphasis> option
allow to have duplicate rules in selector.
</listitem>
</itemizedlist>
</para>
<para>
<tip>
HTML_CSS 1.4.0+ users may now set a single option directly like that:
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
$css = new HTML_CSS();
// with PHP5 only
$css->allowduplicates = true;
// with PHP4 use
$css->__set('allowduplicates', true);
?>
]]>
</programlisting>
</tip>
</para>
&package.html.html-css.html-css.html-css;
&package.html.html-css.html-css.setxhtmlcompliance;
&package.html.html-css.html-css.setcache;
&package.html.html-css.html-css.setsinglelineoutput;
&package.html.html-css.html-css.setoutputgroupsfirst;
</refsect1>
<refsect1 id="package.html.html-css.api.basic">
<title>Handle selector and property values</title>
<para>
Read and write single selector or even descendant selector is made easy with :
</para>
&package.html.html-css.html-css.getstyle;
&package.html.html-css.html-css.setstyle;
</refsect1>
<refsect1 id="package.html.html-css.api.group">
<title>Grouping selectors</title>
<para>
The most advanced/complex functions are those which handle group of selectors
</para>
&package.html.html-css.html-css.creategroup;
&package.html.html-css.html-css.unsetgroup;
&package.html.html-css.html-css.getgroupstyle;
&package.html.html-css.html-css.setgroupstyle;
&package.html.html-css.html-css.addgroupselector;
&package.html.html-css.html-css.removegroupselector;
&package.html.html-css.html-css.setsamestyle;
</refsect1>
<refsect1 id="package.html.html-css.api.parse">
<title>Parsing data sources</title>
<para>
Handle data sources are so easy than just one call of these three methods :
</para>
&package.html.html-css.html-css.parsestring;
&package.html.html-css.html-css.parsefile;
&package.html.html-css.html-css.parsedata;
</refsect1>
<refsect1 id="package.html.html-css.api.output">
<title id="package.html.html-css.api.output.caption">Output</title>
<para>
Send result directly to browser, send it to file or capture to a PHP variable,
you will certainly use one of them.
</para>
&package.html.html-css.html-css.toarray;
&package.html.html-css.html-css.toinline;
&package.html.html-css.html-css.tofile;
&package.html.html-css.html-css.tostring;
&package.html.html-css.html-css.display;
&package.html.html-css.html-css.getcontentdisposition;
&package.html.html-css.html-css.setcontentdisposition;
</refsect1>
<refsect1 id="package.html.html-css.api.grep">
<title>Searching for selectors and/or properties</title>
<para>
Ability to find if a selector or a property (with perl-compatible pattern)
is already defined.
<important>
This function is available since version 1.1.0
</important>
</para>
&package.html.html-css.html-css.grepstyle;
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-css/errorhandler.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-css/errorhandler.xml
+++ peardoc/en/package/html/html-css/errorhandler.xml
<!-- $Revision: 1.1 $ -->
<refentry id="package.html.html-css.errorhandler">
<refnamediv>
<refname>Error Handler</refname>
<refpurpose>Flexible error handler plug-in system</refpurpose>
</refnamediv>
<refsect1 id="package.html.html-css.errorhandler.init">
<title>Introduction</title>
<para>
The HTML_CSS package is implemented with a flexible error handler
plug-in system. You may use any error handler that you want. Using
<classname>PEAR_Error</classname> object (default), but also the
<classname>PEAR_ErrorStack</classname> package, or any other error
handler you might want to plug in.
</para>
<para>
Without any configuration, each HTML_CSS API error (basic or exception)
will raise a <classname>HTML_CSS_Error</classname> object that will
be return to call script (user script).
<tip>
Easy to distinct basic PEAR_Error from other PEAR packages to HTML_CSS errors,
even if there is a better and more robust solution:
<methodname>HTML_CSS::isError()</methodname>.
But also provide a unique way to retrieve the level of error
(warning, error, exception) with the <methodname>HTML_CSS_Error::getLevel()
</methodname> method.
</tip>
</para>
<para>
As usual you can use the PEAR error API as well.
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
$css = new HTML_CSS();
$result = $css->setStyle('div', 'color', 5);
if (PEAR::isError($result)) {
// do something when an error is raised
}
?>
]]>
</programlisting>
and output to screen will give something like :
</para>
<informalexample>
<screenco>
<screen>
Exception<co id="package.html.html-css.errorhandler.error.1.level"/>: invalid input, parameter #3 "$value" was expecting "string",
instead got "integer"<co id="package.html.html-css.errorhandler.error.1.message"/> in html_css->setstyle (file [path_to]\[filename] on line 6)<co id="package.html.html-css.errorhandler.error.1.context"/>
</screen>
<calloutlist>
<callout arearefs="package.html.html-css.errorhandler.error.1.level">
<para>
error level
</para>
</callout>
<callout arearefs="package.html.html-css.errorhandler.error.1.message">
<para>
message body with context informations
</para>
</callout>
<callout arearefs="package.html.html-css.errorhandler.error.1.context">
<para>
call context
</para>
</callout>
</calloutlist>
</screenco>
</informalexample>
<para>
Perhaps this standard behavior is not what you want. Don't worry, you can
change everything :
<itemizedlist>
<listitem>display or ignore the error </listitem>
<listitem>display or hide part of message (error level, body, context) </listitem>
</itemizedlist>
</para>
<para>
<important>
HTML_CSS obey at
<ulink url="&url.php;manual/en/ref.errorfunc.php#ini.display-errors">display_errors</ulink>
and
<ulink url="&url.php;manual/en/ref.errorfunc.php#ini.log-errors">log_errors</ulink>
protocol
</important>
</para>
</refsect1>
<refsect1 id="package.html.html-css.errorhandler.conf">
<title>Configuring a Handler</title>
<simpara>
A error handler's configuration is determined by the arguments used in its
construction. Here's an overview of these parameters.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
$errorConf = array('error_handler' => 'myErrorHandler',
'push_callback' => 'myError',
// ... more options
);
$css = new HTML_CSS(null, $errorConf);
?>
]]>
</programlisting>
<para>
<table><title>Error Handler configuration parameters</title>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>error_handler</entry>
<entry>callback</entry>
<entry>
A valid callback (function) to manage errors raised by the
<methodname>HTML_CSS::raiseError()</methodname> method.
Default is: <methodname>HTML_CSS::_errorHandler</methodname>
</entry>
</row>
<row>
<entry>push_callback</entry>
<entry>callback</entry>
<entry>
A valid callback (function) that decides to following action.
Default return: <constant>PEAR_ERROR_DIE</constant> if exception,
<constant>NULL</constant> otherwise.
</entry>
</row>
<row>
<entry>error_callback</entry>
<entry>callback</entry>
<entry>
A valid callback (function) that decides to call a real free user function.
Default call: none
</entry>
</row>
<row>
<entry>message_callback</entry>
<entry>callback</entry>
<entry>
A valid callback (function) to control message generation.
Default is: <methodname>HTML_CSS_Error::_msgCallback</methodname>
</entry>
</row>
<row>
<entry>context_callback</entry>
<entry>callback</entry>
<entry>
A valid callback (function) to control error context generation.
Default is: <methodname>HTML_CSS_Error::getBacktrace</methodname>
</entry>
</row>
<row>
<entry>handler</entry>
<entry>mixed</entry>
<entry>
any handler-specific settings
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</refsect1>
<refsect1 id="package.html.html-css.errorhandler.control">
<title>Controlling error generation</title>
<simpara>
There are many scenarios in which fine-grained control over error raising is
absolutely necessary.
</simpara>
<para>
The first level to control error generation is the &php.ini; directives
<emphasis>display_errors</emphasis> and <emphasis>log_errors</emphasis>.
When these directives are set to &true;, then browser and file outputs are
effective.
</para>
<para>
<tip>
If you want to ignore all errors raised (no display, no logs) and avoid to
include PEAR core class, then you should have something like :
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
function myErrorHandler()
{
return null;
}
$errorConf = array('error_handler' => 'myErrorHandler');
$css = new HTML_CSS(null, $errorConf);
// ...
?>
]]>
</programlisting>
</tip>
</para>
<para>
<note><title>Note for users of HTML_CSS 1.4.0 or greater</title>
You may want to decide to print (yes/no), log (yes/no) error messages
with a full free user function local to HTML_CSS
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
function myErrorAction($css_error)
{
// do what you want: print and/or log $css_error instance of HTML_CSS_Error object
}
$errorConf = array('error_callback' => 'myErrorAction');
$css = new HTML_CSS(null, $errorConf);
// ...
?>
]]>
</programlisting>
rather than using global PEAR error handler (PEAR::setErrorHandling,
PEAR::pushErrorHandling, PEAR::popErrorHandling).
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
function myErrorAction($css_error)
{
// do what you want: print and/or log $css_error instance of HTML_CSS_Error object
}
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'myErrorAction');
$css = new HTML_CSS();
// ...
?>
]]>
</programlisting>
</note>
</para>
<para>
With <emphasis role="bold">push_callback</emphasis> option, you can decides to
stop script execution (as done with exceptions by default:
returns <constant>PEAR_ERROR_DIE</constant> constant), or continue
without filtering (returns <constant>NULL</constant>).
</para>
<para>
If you want to write your own callback function for the <emphasis>push_callback</emphasis>
option, this one should have two arguments: first one will get the error code,
and second will get error level. These are all the necessary informations to do
a filtering. Example that follow show how to be aware that a script use wrong argument data type.
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
function myErrorFilter($code, $level)
{
if ($code === HTML_CSS_ERROR_INVALID_INPUT) {
error_log('script: '.__FILE__.' used wrong argument data type', 1, '[email protected]');
}
return null;
}
$errorConf = array('push_callback' => 'myErrorFilter');
$css = new HTML_CSS(null, $errorConf);
// ...
?>
]]>
</programlisting>
</para>
</refsect1>
<refsect1 id="package.html.html-css.errorhandler.context">
<title>Error Context Display</title>
<simpara>
In some cases, you may want to customize error generation. For instance,
for each error (basic/exception), it is useful to include file, line number,
and class/function context information in order to trace it. The default
option will be sufficient for most cases but you want perhaps customize the
output format (render) of context information.
</simpara>
<para>
With this example we will change display and log renders.
<programlisting role="php">
<![CDATA[
<?php
require_once 'HTML/CSS.php';
$displayConfig = array(
'lineFormat' => '<b>%1$s</b>: %2$s<br />%3$s',
'contextFormat' => '<b>File:</b> %1$s <br />'
. '<b>Line:</b> %2$s <br />'
. '<b>Function:</b> %3$s '
);
$logConfig = array(
'lineFormat' => '%1$s %2$s [%3$s] %4$s',
'timeFormat' => '%b'
);
$prefs = array(
'handler' => array('display' => $displayConfig,
'log' => $logConfig
));
$css = new HTML_CSS(null, $prefs);
// ...
$result = $css->setStyle('div', 'color', 5);
?>
]]>
</programlisting>
</para>
<simpara>
Display render will give something like:
</simpara>
<informalexample>
<screenco>
<screen>
Exception<co id="package.html.html-css.errorhandler.error.2.level"/>: invalid input, parameter #3 "$value" was expecting "string", instead got "integer"<co id="package.html.html-css.errorhandler.error.2.message"/>
File: [path_to]\[filename] <co id="package.html.html-css.errorhandler.error.2.context"/>
Line: 22 <coref linkend="error.2.context"/>
Function: html_css->setstyle <coref linkend="error.2.context"/>
</screen>
<calloutlist>
<callout arearefs="package.html.html-css.errorhandler.error.2.level">
<para>
error level
</para>
</callout>
<callout arearefs="package.html.html-css.errorhandler.error.2.message">
<para>
message body with context informations
</para>
</callout>
<callout arearefs="package.html.html-css.errorhandler.error.2.context">
<para>
call context (file, line, function)
</para>
</callout>
</calloutlist>
</screenco>
</informalexample>
<simpara>
Log render will give something like:
</simpara>
<informalexample>
<screenco>
<screen>
Jun 127.0.0.1<co id="package.html.html-css.errorhandler.error.3.context"/> [exception<co id="package.html.html-css.errorhandler.error.3.level"/>] invalid input, parameter #3 "$value" was expecting "string", instead got "integer"<co id="package.html.html-css.errorhandler.error.3.message"/>
</screen>
<calloutlist>
<callout arearefs="package.html.html-css.errorhandler.error.3.context">
<para>
client ip address and execution date
</para>
</callout>
<callout arearefs="package.html.html-css.errorhandler.error.3.level">
<para>
error level
</para>
</callout>
<callout arearefs="package.html.html-css.errorhandler.error.3.message">
<para>
message body with context informations
</para>
</callout>
</calloutlist>
</screenco>
</informalexample>
<note>
To have both display and log output, check the &php.ini;
<emphasis>display_errors</emphasis> and <emphasis>log_errors</emphasis> values :
must be set to &true;.
</note>
<para>
Let review, step by step, how to get such results.
</para>
<para>
Remember that with default classes, there are two drivers :
<emphasis>display</emphasis> and <emphasis>log</emphasis> that have both
their own configuration parameters.
You can override these parameters values with the <emphasis role="bold">handler</emphasis>
entry in the hash of second argument of the HTML_CSS class constructor.
</para>
<para>
We did it here with the <parameter>$prefs</parameter> variable; its a two keys
associative array. First key <emphasis>display</emphasis> defines the display driver
values, and the second key <emphasis>log</emphasis> defines the log driver values.
</para>
<para>
Review the <emphasis>display</emphasis> driver custom values. Only two keys:
<simplelist type='inline'>
<member>lineFormat</member>
<member>contextFormat</member>
</simplelist>
are redefined, thats means remains key
<simplelist type='inline'>
<member>eol</member>
</simplelist>
keep its default value. See table below.
</para>
<para>
<table><title>Display driver configuration parameters</title>
<tgroup cols="4">
<thead>
<row>
<entry>Parameter</entry>
<entry>Type</entry>
<entry>Default</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>eol</entry>
<entry>string</entry>
<entry><br />\n</entry>
<entry>The end-on-line character sequence </entry>
</row>
<row>
<entry>lineFormat</entry>
<entry>string</entry>
<entry><b>%1$s</b>: %2$s %3$s</entry>
<entry>Log line format specification:
<itemizedlist>
<listitem>1$ = error level</listitem>
<listitem>2$ = error message (body)</listitem>
<listitem>3$ = error context</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>contextFormat</entry>
<entry>string</entry>
<entry>
in <b>%3$s</b> (file <b>%1$s</b> on line <b>%2$s</b>)
</entry>
<entry>Context format (class, file, line) specification:
<itemizedlist>
<listitem>1$ = script file name </listitem>
<listitem>2$ = line in script file </listitem>
<listitem>3$ = class/method names </listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
<tip>
If you don't wish to see context information in the error message, then
remove the parameter %3$ in the <emphasis>lineFormat</emphasis> option
even if <emphasis>contextFormat</emphasis> is set.
</tip>
</para>
<para>
Review now the <emphasis>log</emphasis> driver custom values. Only two keys
<simplelist type='inline'>
<member>lineFormat</member>
<member>timeFormat</member>
</simplelist>
are redefined, thats means six remains keys
<simplelist type='inline'>
<member>eol</member>
<member>contextFormat</member>
<member>ident</member>
<member>message_type</member>
<member>destination</member>
<member>extra_headers</member>
</simplelist>
keep their default values. See table below.
</para>
<para>
<table><title>Log driver configuration parameters</title>
<tgroup cols="4">
<thead>
<row>
<entry>Parameter</entry>
<entry>Type</entry>
<entry>Default</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>eol</entry>
<entry>string</entry>
<entry>\n</entry>
<entry>The end-on-line character sequence </entry>
</row>
<row>
<entry>lineFormat</entry>
<entry>string</entry>
<entry>%1$s %2$s [%3$s] %4$s %5$s </entry>
<entry>Log line format specification:
<itemizedlist>
<listitem>$1 = time error</listitem>
<listitem>2$ = ident (client ip)</listitem>
<listitem>3$ = error level </listitem>
<listitem>4$ = error message (body) </listitem>
<listitem>5$ = error context </listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>contextFormat</entry>
<entry>string</entry>
<entry>in %3$s (file %1$s on line %2$s) </entry>
<entry>Context format (class, file, line) specification:
<itemizedlist>
<listitem>1$ = script file name </listitem>
<listitem>2$ = line in script file </listitem>
<listitem>3$ = class/method names </listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>timeFormat</entry>
<entry>string</entry>
<entry>%b %d %H:%M:%S </entry>
<entry>Time stamp format
used by <ulink url="&url.php.lookup;strftime">strftime</ulink>
</entry>
</row>
<row>
<entry>ident</entry>
<entry>string</entry>
<entry>REMOTE_ADDR </entry>
<entry>Client IP </entry>
</row>
<row>
<entry>message_type</entry>
<entry>string</entry>
<entry>3 </entry>
<entry>Destination type
used by <ulink url="&url.php.lookup;error_log">error_log</ulink>
</entry>
</row>
<row>
<entry>destination</entry>
<entry>string</entry>
<entry>html_css_error.log </entry>
<entry>Destination name
used by <ulink url="&url.php.lookup;error_log">error_log</ulink>
</entry>
</row>
<row>
<entry>extra_headers</entry>
<entry>string</entry>
<entry>&null; </entry>
<entry>Extra headers depending of destination type </entry>
</row>
</tbody>
</tgroup>
</table>
<tip>
If you don't wish to see context information in the error message, then
remove the parameter %5$ in the <emphasis>lineFormat</emphasis> option
even if <emphasis>contextFormat</emphasis> is set.
</tip>
</para>
</refsect1>
<refsect1 id="package.html.html-css.errorhandler.messages">
<title>Custom Error Message Generation</title>
<para>
There are two methods of <classname>HTML_CSS_Error</classname> designed for use with generating
error messages efficiently. To use them, you must set the options below in
the HTML_CSS class constructor (argument #2):
</para>
<refsect2>
<title>Option: message_callback</title>
<para>
The default message handling callback
(<methodname>HTML_CSS_Error::_getErrorMessage</methodname>)
get an array mapping error codes to error message templates, like so:
<programlisting role="php">
<![CDATA[
<?php
$messages = array(
HTML_CSS_ERROR_UNKNOWN =>
'unknown error',
HTML_CSS_ERROR_INVALID_INPUT =>
'invalid input, parameter #%paramnum% '
. '"%var%" was expecting '
. '"%expected%", instead got "%was%"'
);
?>
]]>
</programlisting>
Basically, if a variable name is enclosed in percent signs (%), it will be
replaced with the value passed in the associative array.
</para>
</refsect2>
<refsect2>
<title>Option: context_callback</title>
<para>
The default context handling callback
(<methodname>HTML_CSS_Error::getBackTrace</methodname>)
gets an array of execution functions and discovers where the error was generated.
</para>
</refsect2>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-css/faq.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-css/faq.xml
+++ peardoc/en/package/html/html-css/faq.xml
<!-- $Revision: 1.1 $ -->
<refentry id="package.html.html-css.faq">
<refnamediv>
<refname>FAQ</refname>
<refpurpose>Answers to most Frequently Asked Questions</refpurpose>
</refnamediv>
<refsect1 id="package.html.html-css.faq.content">
<title>HTML_CSS FAQ</title>
<qandaset>
<qandadiv><title>General questions</title>
<qandaentry>
<question>
<para>What does it cost ?</para>
</question>
<answer>
<para>
You can download and use it for free. But don't delete the copyright notice.
You can read terms of the
<ulink class="external" url="&url.license.bsd;">license</ulink>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Do you offer support ?</para>
</question>
<answer>
<para>
YES if there is no answer in this Guide and if you are ready to share
some informations such as : your configuration (platform Win *nix mac,
PHP version, PEAR packages installed) and perharps your script.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I found a bug, what shall I do ?</para>
</question>
<answer>
<para>
You can report it with the bug tracker at
<ulink url="&url.pear.package;HTML_CSS/bugs">PEAR</ulink>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What is CSS ?</para>
</question>
<answer>
<para>
CSS (an acronym for
<emphasis role="bold">C</emphasis>ascading
<emphasis role="bold">S</emphasis>tyle
<emphasis role="bold">S</emphasis>heets)
is a simple mechanism for adding style (e.g. fonts, colors, spacing) to Web documents.
</para>
<para>
<emphasis role="bold">HTML_CSS</emphasis> is a PEAR package that provides
methods for handling stylesheet declarations.
</para>
<para>
Version 1.0.0 does not offers yet methods to validate a style sheet.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What is PEAR ?</para>
</question>
<answer>
<para>
PEAR (an acronym for
<emphasis role="bold">P</emphasis>HP
<emphasis role="bold">E</emphasis>xtension and
<emphasis role="bold">A</emphasis>pplication
<emphasis role="bold">R</emphasis>epository)
is a framework and distribution system for reusable PHP components.
</para>
<para>
Don't forget to read also the <ulink url="&url.pear.manual;en">PEAR Manual</ulink>
and <ulink url="&url.pear.manual;en/faq.php">PEAR FAQ</ulink>.
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv><title>How to</title>
<qandaentry>
<question>
<para>I want to use HTML_CSS without PEAR. Is it possible ? </para>
</question>
<answer>
<para>
Yes it is. First, you need to download package
<ulink url="&url.pear.package;HTML_Common">PEAR::HTML_Common</ulink> version 1.2 or greater.
</para>
<para>
Extract content (<filename>common.php</filename> file) in same directory
<filename class='directory'>HTML/</filename> as <filename>CSS.php</filename> file.
</para>
<para>
Last, you should create your own error handler, or disable it. See chapter
<link linkend="package.html.html-css.errorhandler" endterm="package.html.html-css.errorhandler.caption" />
for details.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>I want to know property value of a selector, but it can not exist</para>
</question>
<answer>
<para>
With previous release than 1.1.0 it was not possible because
<methodname>HTML_CSS::getStyle()</methodname> require at least an existing property,
or it will return <constant>HTML_CSS_ERROR_NO_ELEMENT_PROPERTY</constant>.
</para>
<para>
With new function <methodname>HTML_CSS::grepStyle()</methodname> of version 1.1.0,
it's now possible.
</para>
<para>
<programlisting role="php">
<![CDATA[
01: <?php
02: require_once 'HTML/CSS.php';
03:
04: function myErrorHandler()
05: {
06: return PEAR_ERROR_PRINT; // always print all error messages
07: }
08:
09: $styles = '
10: h1, h2, h3, h4 { padding: 1em; }
11: .highlight p, .highlight ul { margin-left: .5em; }
12: #main p, #main ul { padding-top: 1em; }
13: ';
14:
15: $prefs = array(
16: 'push_callback' => 'myErrorHandler',
17: );
18: $attribs = null;
19:
20: $css = new HTML_CSS($attribs, $prefs);
21: $css->parseString($styles);
22:
23: $css->getStyle('.highlight p', 'color');
24:
25: $styles = $css->grepStyle('/highlight/', '/^color$/');
26: echo '<pre>'; var_dump($styles); echo '</pre>';
27: ?>
]]>
</programlisting>
</para>
<variablelist>
<varlistentry>
<term>
Lines 4-7, 15-17, 20 :
</term>
<listitem>
<para>
Custom error handler is defined to allow script to continue (print message),
when <methodname>HTML_CSS::getStyle()</methodname> will raise error at line 23.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Lines 9-13, 21 :
</term>
<listitem>
<para>
Stylesheet used is :
<programlisting role="css">
h1, h2, h3, h4 { padding: 1em; }..highlight p, .highlight ul { margin-left: .5em; }
#main p, #main ul { padding-top: 1em; }
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Lines 23, 25 :
</term>
<listitem>
<para>
While <methodname>HTML_CSS::getStyle()</methodname> will raise error (printed
by custom error handler), line 25 will return an empty array with no error raised.
</para>
<para>
Reason : <literal>color</literal> property does not exist for <literal>.highlight p</literal>
class selector.
</para>
</listitem>
</varlistentry>
</variablelist>
</answer>
</qandaentry>
</qandadiv>
</qandaset>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/html/html-css/whatsnew.xml?view=markup&rev=1.1
Index: peardoc/en/package/html/html-css/whatsnew.xml
+++ peardoc/en/package/html/html-css/whatsnew.xml
<!-- $Revision: 1.1 $ -->
<refentry id="package.html.html-css.whatsnew">
<refnamediv>
<refname>News</refname>
<refpurpose>What is New in version ?</refpurpose>
</refnamediv>
<refsect1 id="package.html.html-css.whatsnew.02x">
<title>Version 0.2.x</title>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Initial PEAR public release</emphasis>
occured at end of July 2003.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 id="package.html.html-css.whatsnew.03x">
<title>Version 0.3.x</title>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Added the ability to parse CSS from string</emphasis>
with <methodname>HTML_CSS::parseString()</methodname>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Added the ability to parse CSS from file</emphasis>
with <methodname>HTML_CSS::parseFile()</methodname>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Added the ability to generate CSS and store it
in a file</emphasis> with <methodname>HTML_CSS::toFile()</methodname>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Introduced error handling system</emphasis>
with PEAR_ErrorStack.
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Added unit tests with PHPUnit 1.x</emphasis> for
API and bugs.
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Retrieve the settings of individual properties</emphasis>
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 id="package.html.html-css.whatsnew.10x">
<title>Version 1.0.x</title>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Introduced a new error handling system:</emphasis>
PEAR_ErrorStack was replaced by a simple way to plug in any error handling
system you might want (default used PEAR_Error object)
</para>
</listitem>
<listitem>
<para><emphasis role="bold"><methodname>HTML_CSS::apiVersion()</methodname></emphasis>
returns now a string rather than a float; compatible with
<ulink url="&url.php.lookup;version_compare">php.version_compare()</ulink>.
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Added the ability to parse multiple data sources
(filename, string) at once</emphasis> with
<methodname>HTML_CSS::parseData()</methodname>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Added the ability to identify if HTML_CSS API output
returns an error</emphasis> with
<methodname>HTML_CSS::isError()</methodname>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Introduces package xml 2.0</emphasis> and drop support
of package xml 1.0
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Unified API arguments</emphasis> for all group functions
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Klaus Guenther</emphasis> (first package leader)
became inactive.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 id="package.html.html-css.whatsnew.11x">
<title>Version 1.1.x</title>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Added ability to search if an element/property
is defined or not</emphasis> with
<methodname>HTML_CSS::grepStyle()</methodname>
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 id="package.html.html-css.whatsnew.12x">
<title>Version 1.2.x</title>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">License changed</emphasis> from
<ulink url="&url.license.php;3_01.txt">PHP 3.01</ulink> to
<ulink url="&url.license.bsd;">BSD</ulink>.
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Manual license upgrades</emphasis> from
version 2.0 to 3.0 of
<ulink url="&url.license.cc;">Creative Commons</ulink>
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 id="package.html.html-css.whatsnew.13x">
<title>Version 1.3.x</title>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Prevent invalid CSS data source in to be parse</emphasis>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Add Content-Disposition to the headers in display()</emphasis>
Implement <ulink url="http://pear.php.net/bugs/bug.php?id=12195">request 12195</ulink>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Remove pointless NEWS file from distribution</emphasis>,
clone of ChangeLog.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 id="package.html.html-css.whatsnew.14x">
<title>Version 1.4.x</title>
<para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Upgrade requirement</emphasis> to
PHP 4.3.0 and PEAR 1.5.4 (to avoid security vulnerability)
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Coding Standard fixes:</emphasis>
(errors/warnings) following recommandation by
<ulink url="&url.pear.package;PHP_CodeSniffer">PHP_CodeSniffer</ulink>
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Unit test suites</emphasis> migrated from
PHPUnit 1.x to 3.x
</para>
</listitem>
<listitem>
<para><emphasis role="bold">API 1.4.0 introduces new setter/getter</emphasis>
PHP5 facility compatible (magic function __set, __get) for read/write CSS options.
</para>
</listitem>
<listitem>
<para><emphasis role="bold">Error handler</emphasis> allow now to use
PEAR_ERROR_CALLBACK (local to HTML_CSS) to customize action when an
error/exception is raised. No more need to use global PEAR::setErrorHandling.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->