cvs: peardoc /en/guide/migrating customtasks.xml

cellog Sun Sep 18 03:11:09 2005 EDT Modified files: /peardoc/en/guide/migrating customtasks.xml Log: add in missing docs for validateXml http://cvs.php.net/diff.php/peardoc/en/guide/migrating/customtasks.xml?r1=1.3&r2=1.4&ty=u Index: peardoc/en/guide/migrating/customtasks.xml diff -u peardoc/en/guide/migrating/customtasks.xml:1.3 peardoc/en/guide/migrating/customtasks.xml:1.4 --- peardoc/en/guide/migrating/customtasks.xml:1.3 Sun Sep 18 02:28:19 2005 +++ peardoc/en/guide/migrating/customtasks.xml Sun Sep 18 03:11:09 2005 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1" ?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <chapter id="guide.migrating.customtasks"> <chapterinfo> <author> <firstname>Gregory</firstname> <surname>Beaver</surname> </author> - <date>$Date: 2005/09/18 06:28:19 $</date> + <date>$Date: 2005/09/18 07:11:09 $</date> </chapterinfo> <title>Custom File Tasks</title> @@ -147,11 +147,152 @@ <paramdef>PEAR_PackageFile_v2 <parameter>$pkg</parameter></paramdef> <paramdef>string|array <parameter>$xml</parameter></paramdef> <paramdef>PEAR_Config <parameter>&amp;$config</parameter></paramdef> - <paramdef>array <parameter>$fileXml</parameter></paramdef> + <paramdef>array <parameter>$fileAttributes</parameter></paramdef> </funcprototype> </funcsynopsis> </para> <para> + This method is called upon package.xml validation and should be used to validate + the task's xml content. Upon error, a simple array of format + <literal>array(CODE, message)</literal> must be returned. The code must be one + of the following constants, as defined in <filename>PEAR/Task/Common.php</filename>: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <constant>PEAR_TASK_ERROR_NOATTRIBS</constant> - Attributes were expected, but + none were present. + </para> + </listitem> + <listitem> + <para> + <constant>PEAR_TASK_ERROR_MISSING_ATTRIB</constant> - A specific attribute is not + present. + </para> + </listitem> + <listitem> + <para> + <constant>PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE</constant> - The value of an attribute + is incorrect. + </para> + </listitem> + <listitem> + <para> + <constant>PEAR_TASK_ERROR_INVALID</constant> - Any other error in validation. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The error message should include the file name as defined by <literal>$fileAttributes['name']</literal>, and include as much useful information about the location + of the validation error as possible. + </para> + <para> + <variablelist> + <varlistentry> + <term> + PEAR_PackageFile_v2 <parameter>$pkg</parameter> + </term> + <listitem> + <para> + This is the package.xml object that contains the task. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + string|array <parameter>$xml</parameter> + </term> + <listitem> + <para> + The raw parsed content of the task's xml as parsed from package.xml. Tags + like &lt;tasks:windowseol&gt; that have no attributes or child elements will + be passed an empty string <literal>''</literal>. Otherwise, simple text content + will be a string, and nested tags/attributes will be passed in as an array. Here + is a list of sample xml and their parsed values: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <programlisting role="xml"> +<![CDATA[<tasks:blah/>]]> + </programlisting> + </para> + <para> + <literal>string(&quot;&quot;);</literal> + </para> + </listitem> + <listitem> + <para> + <programlisting role="xml"> +<![CDATA[ +<tasks:blah>hello +</tasks:blah>]]> + </programlisting> + </para> + <para> + <literal>string(&quot;hello&quot;);</literal> + </para> + </listitem> + <listitem> + <para> + <programlisting role="xml"> +<![CDATA[ +<tasks:blah>hello + <tasks:boo/> +</tasks:blah>]]> + </programlisting> + </para> + <para> + <literal><![CDATA[array('_content' => 'hello', 'tasks:boo' => string(''))]]></literal> + </para> + </listitem> + <listitem> + <para> + <programlisting role="xml"> +<![CDATA[ +<tasks:blah foo="one"> + <tasks:boo/> +</tasks:blah>]]> + </programlisting> + </para> + <para> + <literal><![CDATA[ +array('attribs' => array('foo' => 'one'), + 'tasks:boo' => string(''))]]></literal> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + PEAR_Config <parameter>$config</parameter> + </term> + <listitem> + <para> + This is the current configuration object + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + array <parameter>$fileAttributes</parameter> + </term> + <listitem> + <para> + The parsed attributes of the &lt;file&gt; tag that encloses this tag. This + is guaranteed to contain indices <literal>name</literal>, specifying the file name, + and <literal>role</literal>, specifying the file role. Other attributes like + <literal>baseinstalldir</literal> may be present but are not required, and so will + not be guaranteed to be present for every file. + </para> + </listitem> + </varlistentry> + </variablelist> </para> </sect2> <sect2 id="guide.migrating.customtasks.php.init">