NAME:

    Formtool - a Smarty plugin library for automating various javascript tasks,
    such as check/uncheck, select/unselect, move items up/down, move items from
    one list to another, etc.

AUTHOR:
    Monte Ohrt <monte [AT] ispi [DOT] net>

LATEST VERSION:
    1.3 (Dec 2, 2004)

SYNOPSIS (template source):

    {formtool_checkall name="colors[]"}
    {html_checkboxes name="colors" values=$colors output=$colors separator="<br />"}

    {formtool_selectall name="colors2[]"}<br />
    <select name="colors2[]" multiple size="10">
    {html_options values=$colors output=$colors}
    </select>


DESCRIPTION
-----------

    Formtool is a collection of Smarty plugin functions that automate
    javascript functionality such as select all/none checkboxes, moving items
    up/down in a select list, or moving items from one select list to another.


INSTALLATION
------------

    1) drop the plugins/function.*.php files into your Smarty plugins directory.
    2) drop the javascripts/formtool.js file into your document root somewhere,
       such as DOCUMENT_ROOT/javascripts/formtool.js


USING FORMTOOL
--------------

    formtool_init
    -------------

    This must be called at the top of the template that will be using the form
    tools. It loads the javascript file. Supply a path relative to your web
    server DOCUMENT_ROOT.

    example:

    {formtool_init src="/javascripts/formtool.js"}

    formtool_checkall
    -----------------

    formtool_checkall is used for checking all or none of an array of
    checkboxes. Supply the name of the checkbox in the form. Be sure to include
    brackets [] in the checkbox name if they are present the HTML source.
    Automatically created names from functions such as {html_checkboxes ...}
    will have them.

    - accepts optional parameters, "class" and "style" for custom CSS styling.

    example:

    {formtool_checkall name="colors[]"}
    {html_checkboxes name="colors" values=$colors output=$colors separator="<br />"}


    formtool_selectall
    ------------------

    formtool_selectall is used for selecting/unselecting all items of a
    multi-select box. Supply the name of the select box in the form.

    - accepts optional parameters, "class" and "style" for custom CSS styling.

    example:

    {formtool_selectall name="colors2[]"}
    <select name="colors2[]" multiple size="10">
        {html_options values=$colors output=$colors}
    </select>


    formtool_moveup, formtool_movedown
    ----------------------------------

    This is used for moving items in a multi-select box up and down. The
    "save" parameter is the name of a hidden field in the form that the new
    order is saved into, comma separated.

    - accepts optional parameters, "class" and "style" for custom CSS styling.

    example:

    {formtool_moveup save="colors3_save" name="colors3[]"}<br />
    <select name="colors3[]" multiple size="10">
    {html_options values=$colors output=$colors}
    </select><br />
    {formtool_movedown save="colors3_save" name="colors3[]"}
    <input type="hidden" name="colors3_save">

    formtool_rename
    ---------------

    This is used for renaming items in a multi-select box. The "save" parameter
    is the name of a hidden field in the form that the new names are saved into,
    comma separated.

    - accepts optional parameters, "class" and "style" for custom CSS styling.

    example:

    <select name="colors4[]" multiple size="10">
    {html_options values=$colors output=$colors}
    </select><br />
    <input type="text" name="rename_text" size="10">{formtool_rename name="colors4[]" from="rename_text" save="colors4_save"}<br />
    <input type="hidden" name="colors4_save">


    formtool_move, formtool_moveall
    -------------------------------

    This is used to move items between multi-select boxes. The "save_from"
    and "save_to" parameters are the names of a hidden fields in the form that
    the new orders are saved into, comma separated. The optional boolean
    parameter "all" will move all items when set to "true".

    - accepts optional parameters, "class" and "style" for custom CSS styling.
    - accepts optional parameters "count_to" and "count_from" which are the names
      of input fields in the form which are used to display the current size of
      the "to" and "from" lists.
    - formtool_moveall is deprecated. Use 'all=true' on formtool_move instead.

    example:

    <table border=1>
      <tr>
      <td valign="top">
         <select name="colors5[]" multiple size="10">
         {html_options values=$colors output=$colors}
         </select>
         <input type="hidden" name="colors5_save">
      </td>
      <td align="center">
         {formtool_move all=true from="colors5[]" to="colors6[]" button_text="&gt&gt;"
            save_from="colors5_save" save_to="colors6_save"}<br />
         {formtool_move from="colors5[]" to="colors6[]" button_text="&gt;"
            save_from="colors5_save" save_to="colors6_save"}<br />
         {formtool_move from="colors6[]" to="colors5[]" button_text="&lt;"
            save_from="colors5_save" save_to="colors6_save"}<br />
         {formtool_moveall from="colors6[]" to="colors5[]" button_text="&lt&lt;"
            save_from="colors5_save" save_to="colors6_save"}
      </td>
      <td valign="top">
         <select name="colors6[]" multiple size="10">
         </select>
         <input type="hidden" name="colors6_save">
      </td>
      </tr>
   </table>


    formtool_copy
    -------------

    This is used to copy items between multi-select boxes. Similar to
    formtool_move except that items are not removed from the source list and
    duplicates in the destination are ignored. The "save" parameter is the name
    of a hidden field in the form that the new order is saved into, comma
    separated. The optional boolean parameter "all" will copy all items when set
    to "true".

    - accepts optional parameters, "class" and "style" for custom CSS styling.
    - accepts optional parameters "counter" which is the name of a field in the
      form which is used to display the current size of destination list.

    example:

    <table border=1>
      <tr>
      <th>Available <input type="text" value="{$colors|@count}" style="width:40;" disabled="disabled"/>
      </th>
      <th></th>
      <th>Selected <input name="colors8_counter" type="text" value="0" style="width:40;" disabled="disabled"/>
      </th>
      </tr>
      <tr>
      <td valign="top">
         <select name="colors7[]" multiple size="10">
         {html_options values=$colors output=$colors}
         </select>
      </td>
      <td align="center">
         {formtool_copy all=true from="colors7[]" to="colors8[]" button_text="&gt&gt;"
            save="colors8_save" counter="colors8_counter"}<br />
         {formtool_copy from="colors7[]" to="colors8[]" button_text="&gt;"
            save="colors8_save" counter="colors8_counter"}<br />
      </td>
      <td valign="top">
         <select name="colors8[]" multiple size="10">
         </select>
         <input type="hidden" name="colors8_save">
      </td>
      </tr>
   </table>


    formtool_remove
    ---------------

    This is used to remove items from a multi-select box. The "save" parameter
    is the name of a hidden field in the form that the new order is saved into,
    comma separated. The optional boolean parameter "all" will remove all items
    when set to "true".

    - accepts optional parameters, "class" and "style" for custom CSS styling.
    - accepts optional parameters "counter" which is the name of a field in the
      form which is used to display the current size of destination list.

    example:

    <table border=1>
      <tr>
      <th>Available <input name="colors9_counter" type="text" value="{$colors|@count}" style="width:40;" disabled="disabled"/>
      </th>
      <th></th>
      </tr>
      <tr>
      <td valign="top">
         <select name="colors9[]" multiple size="10">
         {html_options values=$colors output=$colors}
         </select>
      </td>
      <td align="center">
         {formtool_remove from="colors9[]" save="colors9_save" counter="colors9_counter" style="width:100;"}<br />
         {formtool_remove all=true from="colors9[]" save="colors9_save" counter="colors9_counter" style="width:100;"}<br />
         <input type="hidden" name="colors9_save">
      </td>
      </tr>
   </table>


   formtool_count_chars
   --------------------

   This is used to proactively count characters entered into a text area, and
   pop up an alert when the limit has been reached. The "limit" parameter sets
   the character limit. Optionally, you can pass alert=false/true to indicate
   whether you want the alert message to show when the limit is reached.

   NOTE: it is a known issue that holding down a key will go beyond the limit,
   but then jump back upon key-up. I have not found a better way to handle it,
   so javascript gurus feel free to supply a better solution ;)

   example:

   <textarea name="mytext" rows="4" cols="40" wrap="yes" {formtool_count_chars
   name="mytext" limit="90" alert=true}></textarea><br />
    limit: <input type="text" name="mytext_limit" size="3" value="90">


    formtool_save
    -------------

    This is used for initializing a "save" field when a form is first
    displayed. This will populate the save field with the current values of a
    form field so if the field is not changed, the correct values will be
    submitted in the save field (instead of being empty.) It is recommended to
    place this after the </form> element.

    Since this function is not within the context of the form, the form name
    must be passed as a parameter. Be sure your form has a name.

    example:

    <form name="myform" method="post" action="index.php">
      {formtool_moveup name="foo[]" save="foo_save"}
      <select name="foo[]" multiple="yes" size="5">
         <option value="1">one</option>
         <option value="2">two</option>
         <option value="3">three</option>
      </select>
      {formtool_movedown name="foo[]" save="foo_save"}
      <input type="hidden name="foo_save">
    </form>
    {* initialize foo_save to "1,2,3" *}
    {formtool_save form="myform" name="foo[]" save="foo_save"}


CREDITS:

    Thanks to the people who have submitted bug reports, suggestions, etc.

    boots (from forums)
    kills (from forums)
    carnalito (from forums)

    Anyone I missed, let me know!


COPYRIGHT:
    Copyright(c) 2004 ispi. All rights reserved.

    This library is free software; you can redistribute it and/or modify it
    under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation; either version 2.1 of the License, or (at
    your option) any later version.

    This library is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
    License for more details.
