<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="faq.html" xmlns="http://docbook.org/ns/docbook">
  <title>PHP and HTML</title>
  <titleabbrev>PHP and HTML</titleabbrev>

  <para>
   PHP and HTML interact a lot: PHP can generate HTML, and HTML
   can pass information to PHP.  Before reading these faqs, it's
   important you learn how to retrieve <link linkend="language.variables.external">
   variables from external sources</link>.  The manual page on
   this topic includes many examples as well.
  </para>

  <qandaset>
   <qandaentry xml:id="faq.html.encoding">
    <question>
     <para>
      What encoding/decoding do I need when I pass a value through a form/URL?
     </para>
    </question>
    <answer>
     <para>
      There are several stages for which encoding is important. Assuming that
      you have a <type>string</type> <varname>$data</varname>, which contains
      the string you want to pass on in a non-encoded way, these are the
      relevant stages:
      <itemizedlist>
       <listitem>
        <para>
         HTML interpretation. In order to specify a random string, you
         <emphasis>must</emphasis> include it in double quotes, and 
         <function>htmlspecialchars</function> the whole value.
        </para>
       </listitem>
       <listitem>
        <para>
         URL: A URL consists of several parts. If you want your data to be
         interpreted as one item, you <emphasis>must</emphasis> encode it with
         <function>urlencode</function>.
        </para>
       </listitem>
      </itemizedlist>
     </para>
     <para>
      <example>
       <title>A hidden HTML form element</title>
        <programlisting role="php">
<![CDATA[
<?php
    echo '<input type="hidden" value="' . htmlspecialchars($data) . '" />'."\n";
?>
]]>
        </programlisting>
      </example>
      <note>
       <simpara>
        It is wrong to <function>urlencode</function>
        <varname>$data</varname>, because it's the browsers responsibility to
        <function>urlencode</function> the data. All popular browsers do that
        correctly. Note that this will happen regardless of the method (i.e.,
        GET or POST). You'll only notice this in case of GET request though,
        because POST requests are usually hidden.
       </simpara>
      </note>
      <example>
       <title>Data to be edited by the user</title>
        <programlisting role="php">
<![CDATA[
<?php
    echo "<textarea name='mydata'>\n";
    echo htmlspecialchars($data)."\n";
    echo "</textarea>";
?>
]]>
        </programlisting>
      </example>
      <note>
       <simpara>
        The data is shown in the browser as intended, because the browser will
        interpret the HTML escaped symbols.
       </simpara>
       <simpara>
        Upon submitting, either via GET or POST, the data will be urlencoded
        by the browser for transferring, and directly urldecoded by PHP. So in
        the end, you don't need to do any urlencoding/urldecoding yourself,
        everything is handled automagically.
       </simpara>
      </note>
      <example>
       <title>In a URL</title>
        <programlisting role="php">
<![CDATA[
<?php
    echo '<a href="' . htmlspecialchars("/nextpage.php?stage=23&data=" .
        urlencode($data)) . '">'."\n";
?>
]]>
        </programlisting>
      </example>
      <note>
       <simpara>
        In fact you are faking a HTML GET request, therefore it's necessary to
        manually <function>urlencode</function> the data.
       </simpara>
      </note>
      <note>
       <simpara>
        You need to <function>htmlspecialchars</function> the whole URL, because the
        URL occurs as value of an HTML-attribute. In this case, the browser
        will first un-<function>htmlspecialchars</function> the value, and then pass
        the URL on. PHP will understand the URL correctly, because you
        <function>urlencode</function>d the data.
       </simpara>
       <simpara>
        You'll notice that the <literal>&amp;</literal> in the URL is replaced
        by <literal>&amp;amp;</literal>. Although most browsers will recover
        if you forget this, this isn't always possible. So even if your URL is
        not dynamic, you <emphasis>need</emphasis> to
        <function>htmlspecialchars</function> the URL.
       </simpara>
      </note>
     </para>
     <!-- TODO: a note about addgpcslashes? -->
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.html.form-image">
    <question>
     <para>
      I'm trying to use an &lt;input type="image"&gt; tag, but 
      the <varname>$foo.x</varname> and <varname>$foo.y</varname> variables
      aren't available.  <varname>$_GET['foo.x']</varname> isn't existing
      either.  Where are they?  
     </para>
    </question>
    <answer>
     <para>
      When submitting a form, it is possible to use an image instead of
      the standard submit button with a tag like:
      <programlisting role="html">
<![CDATA[
<input type="image" src="image.gif" name="foo" />
]]>
      </programlisting>
      When the user clicks somewhere on the image, the accompanying form
      will be transmitted to the server with two additional variables:
      <varname>foo.x</varname> and <varname>foo.y</varname>.
     </para>
     <para>
      Because <varname>foo.x</varname> and <varname>foo.y</varname> would
      make invalid variable names in PHP, they are automagically converted to
      <varname>foo_x</varname> and <varname>foo_y</varname>. That is, the
      periods are replaced with underscores.  So, you'd access these variables
      like any other described within the section on retrieving 
      <link linkend="language.variables.external">variables from external 
      sources</link>.  For example, <varname>$_GET['foo_x']</varname>.
      <note>
       <para>
         Spaces in request variable names are converted to underscores.
       </para>
      </note>
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.html.arrays">
    <question>
     <para>How do I create arrays in a HTML &lt;form&gt;?</para>
    </question>
    <answer>
     <para>
      To get your &lt;form&gt; result sent as an 
      <link linkend="language.types.array">array</link> to your PHP script
      you name the &lt;input&gt;, &lt;select&gt; or &lt;textarea&gt;
      elements like this:
      <programlisting role="html">
<![CDATA[
<input name="MyArray[]" />
<input name="MyArray[]" />
<input name="MyArray[]" />
<input name="MyArray[]" />
]]>
      </programlisting>
      Notice the square brackets after the variable name, that's what
      makes it an array. You can group the elements into different arrays
      by assigning the same name to different elements:
      <programlisting role="html">
<![CDATA[
<input name="MyArray[]" />
<input name="MyArray[]" />
<input name="MyOtherArray[]" />
<input name="MyOtherArray[]" />
]]>
      </programlisting>
      This produces two arrays, MyArray and MyOtherArray, that gets sent
      to the PHP script.  It's also possible to assign specific keys
      to your arrays:
      <programlisting role="html">
<![CDATA[
<input name="AnotherArray[]" />
<input name="AnotherArray[]" />
<input name="AnotherArray[email]" />
<input name="AnotherArray[phone]" />
]]>
      </programlisting>
      The AnotherArray array will now contain the keys 0, 1, email and phone.
      </para>
      <para>
       <note>
        <para>
         Specifying array keys is optional in HTML.  If you do not specify
         the keys, the array gets filled in the order the elements appear in
         the form.  Our first example will contain keys 0, 1, 2 and 3.
        </para>
       </note>
      </para>
      <para>
      See also
      <link linkend="ref.array">Array Functions</link> and
      <link linkend="language.variables.external">Variables From External
      Sources</link>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.html.select-multiple">
    <question>
     <para>
      How do I get all the results from a select multiple HTML tag?
     </para>
    </question>
    <answer>
     <para>
      The select multiple tag in an HTML construct allows users to
      select multiple items from a list. These items are then passed
      to the action handler for the form. The problem is that they
      are all passed with the same widget name. I.e.
      <programlisting role="html">
<![CDATA[
<select name="var" multiple="yes">
]]>
      </programlisting>
      Each selected option will arrive at the action handler as:
      <programlisting>
var=option1
var=option2
var=option3
      </programlisting>
      Each option will overwrite the contents of the previous
      <varname>$var</varname> variable. The solution is to use
      PHP's "array from form element" feature. The following
      should be used:
      <programlisting role="html">
<![CDATA[
<select name="var[]" multiple="yes">
]]>
      </programlisting>
      This tells PHP to treat <varname>$var</varname> as an array and
      each assignment of a value to var[] adds an item to the array.
      The first item becomes <varname>$var[0]</varname>, the next
      <varname>$var[1]</varname>, etc. The <function>count</function>
      function can be used to determine how many options were selected,
      and the <function>sort</function> function can be used to sort
      the option array if necessary.
     </para>
     <para>
      Note that if you are using JavaScript the <literal>[]</literal>
      on the element name might cause you problems when you try to
      refer to the element by name. Use it's numerical form element
      ID instead, or enclose the variable name in single quotes and
      use that as the index to the elements array, for example:
      <programlisting>
variable = document.forms[0].elements['var[]'];
      </programlisting>
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.html.javascript-variable">
    <question>
     <para>
      How can I pass a variable from Javascript to PHP?
     </para>
    </question>
    <answer>
     <para>
      Since Javascript is (usually) a client-side technology, and
      PHP is (usually) a server-side technology, and since HTTP is a
      "stateless" protocol, the two languages cannot directly share
      variables.
     </para>
     <para>
      It is, however, possible to pass variables between the two.
      One way of accomplishing this is to generate Javascript code
      with PHP, and have the browser refresh itself, passing specific
      variables back to the PHP script. The example below shows
      precisely how to do this -- it allows PHP code to capture screen
      height and width, something that is normally only possible on
      the client side.
     </para>
     <para>
      <example>
       <title>Generating Javascript with PHP</title>
       <programlisting role="php">
<![CDATA[
<?php
if (isset($_GET['width']) AND isset($_GET['height'])) {
  // output the geometry variables
  echo "Screen width is: ". $_GET['width'] ."<br />\n";
  echo "Screen height is: ". $_GET['height'] ."<br />\n";
} else {
  // pass the geometry variables
  // (preserve the original query string
  //   -- post variables will need to handled differently)

  echo "<script language='javascript'>\n";
  echo "  location.href=\"${_SERVER['SCRIPT_NAME']}?${_SERVER['QUERY_STRING']}"
            . "&width=\" + screen.width + \"&height=\" + screen.height;\n";
  echo "</script>\n";
  exit();
}
?>
]]>
       </programlisting>
      </example>
     </para>
    </answer>
   </qandaentry>

  </qandaset>
 </chapter>

<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/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
-->