CHANGES:
NEWS
DOWNLOAD:
SmartyFormtool-1.3.tar.gz
DEMO:
demo of the following examples
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=">>"
save_from="colors5_save" save_to="colors6_save"}<br />
{formtool_move from="colors5[]" to="colors6[]" button_text=">"
save_from="colors5_save" save_to="colors6_save"}<br />
{formtool_move from="colors6[]" to="colors5[]" button_text="<"
save_from="colors5_save" save_to="colors6_save"}<br />
{formtool_moveall from="colors6[]" to="colors5[]" button_text="<<"
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=">>"
save="colors8_save" counter="colors8_counter"}<br />
{formtool_copy from="colors7[]" to="colors8[]" button_text=">"
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.
OTHER PROJECTS:
View Monte's other projects