Live PHP form builder!

Check out our super-easy form creator application right now in your browser!

take it for a spin »

clonefish class properties

Properties

properties controlling behaviour

codepage, multibytesupport, multibytesetup

Proper string validation means that we also care about the codepage - just think of multibyte characters in UTF-8: checking length of these strings or using a byte-safe regexp needs attention! For this reason you must set the way Clonefish handles codepages:

$form->codepage         = 'utf-8';
$form->multibytesupport = 'multibyteutf8';

For the impatient: the best bet is $form->multibytesupport = 'multibyteutf8' - which is the default setting. It assumes you use UTF-8 in your application/website and have multibyte support enabled. This combination uses preg as regexp function (which supports UTF-8 encoded regular expressions). 

If you use other codepages or don't have multibyte support, you have the following built-in options:

$form->multibytesupport	when to use?	extension needed	strlen function call, preg function call, function call to set codepage
none	plain ascii text	-	strlen(%s) preg_match('%s', '%s') -
multibyte	any codepage (even multibyte) + ereg	multibyte	mb_strlen(%s) mb_ereg('%s','%s') mb_internal_encoding('%s')
multibyteci	any codepage (even multibyte) + case insensitive ereg	multibyte	mb_strlen(%s) mb_eregi('%s', '%s') mb_internal_encoding('%s')
multibyteutf8	best bet for UTF-8 with preg	multibyte	mb_strlen(%s) preg_match('%su', '%s') mb_internal_encoding('%s')
iconv	if mb_* is missing: SINGLE byte charsets only	iconv	iconv_strlen(%s) preg_match('%s', '%s') iconv_set_encoding('internal_encoding', '%s')
iconvutf8	if mb_* is missing: UTF-8 only	iconv	iconv_strlen(%s) preg_match('%su', '%s') iconv_set_encoding('internal_encoding', '%s')

 

These combinations seem to cover all the options available in PHP - however, you can still define your own settings in $form->multibytesetup.
 

js

$clonefish->js = 1;

If set to 1, clonefish will generate JavaScript validation code when getHTML() method is called. Default value: 1.

jsalert

$clonefish->jsalert = 1;
$clonefish->jsalertmessagecontainerlayout = '%s';
$clonefish->jsalertmessagelayout          = '- %s\n';

If set to 1, clonefish will use window.alert() to show error messages when the client side validation fails. The error messages will be rendered using the other two attributes.

jshtml

$clonefish->jshtml = 1;
$clonefish->jshtmlmessagecontainerlayout = '%s';
$clonefish->jshtmlmessagelayout          = '%s<br            />';

If set to 1, clonefish will attach the error messages to the input elements when the client side validation fails. The error messages will be rendered using the other two attributes.

To use this feature, you need to use the %errordiv% placeholder in $clonefish->layouts layout settings. During form HTML rendering the %errordiv% gets replaced by a HTML snippet of a hidden div for each element where the appropriate error message will be injected into.

jspath

$clonefish->jspath = 'clonefish/clonefish.js';

Path to the JavaScript code used by the validation procedure. The path will be written in the src parameter of the script tag, for example: <script src="clonefish/clonefish.js" type="text/javascript">, so you have to use either a relative or an absolute URI here.

onbeforesubmit

In case you need to run some JavaScript right after successful form validation but still before the data is submitted to the server, use this parameter. Your code will be injected in the validation function, right above the form.submit() call. It's very useful when you want to disable submit buttons once pressed to avoid repeated form submission.

dbtype

$clonefish->dbtype = 'adodb';

This property determines the database wrapper class to use. By default, clonefish provides the following wrappers:

• 'adodb' for AdoDB library
• 'peardb' for Pear DB library
• 'mysql' for the built-in PHP MySQL function
• 'pdo' for the built-in PHP PDO extension

These options cover virtually all RDBMS-es - however, you can easily create your own wrapper class by copying and modifying any existing class!

Being a frequently used setting you can also specify this attribute in the constructor of clonefish (together with a reference of a valid connection resource or connection object).

target

The target="" attribute of the form. Default to "_self". It's the %target% placeholder in the $clonefish->formopenlayout attribute.

configfilter

You can use simple text config files to store any attributes of the clonefish class (so it's meant to store form level settings, as element level settings are stored in PHP arrays). Sometimes you may want to use variables or placeholders in your config files for example to support multilingual sites or introduce some sitewide configuration variables: in such cases you can use the configfilter attribute to specify a function name which does the actual replacements.

properties controlling output/layout

formopenlayout, formcloselayout

$clonefish->formopenlayout = 
  "<form %onsubmit% " . 
        "enctype=\"multipart/form-data\" " . 
        "target=\"%target%\" " . 
        "name=\"%name%\" " .
        "action=\"%action%\" " . 
        "method=\"%method%\"" . 
  ">\n";
$clonefish->formcloselayout = '';

The form open/close tags. The form open layout has several placeholders, all of them are attributes of the clonefish class. The name, action and the method are required parameters of in the clonefish constructor.

The onsubmit placeholder is set by clonefish to the validation JavaScript function when JS validation is used. Form target is "_self" by default.

prefix, postfix

$clonefish->prefix  = '';
$clonefish->postfix = '';

Form prefix/postfix. Useful if you'd like to display some form information (eg. instructions, etc.) above or below the form. Contents will be place right before the <form> and after the </form> tags.

layout

$clonefish->layout = 'tabular';

To choose from the possible layouts definend in $clonefish->layouts, use an index of the $layouts  here.
The default value is tabular, resulting in a table based form.

layouts

$clonefish->layouts is an associative array containing arrays of HTML snippets. These snippets are used to render the form HTML when getHTML() is called.

You can choose the current layout using the $clonefish->layout attribute. There are two basic layouts: tabular and rowbyrow.
Feel free to set up new layouts - just create a new array, and use its array key in the layout property.

• The tabular layout is a container table, which includes one or more element rows and a buttonrow:
  
  

  %displayname%	%erroricon%	%prefix%%element%%postfix%%errordiv%
  		%button%

  
  A tabular form with a valid and an invalid row looks like this:

  Phone number:		(international format)
  Login name:

   
  The default configuration is:

  $clonefish->layouts = Array(
    'tabular' => Array( 
  
      'container' =>  
        // the container for the form elements, where %s is the content
        '<table cellpadding="5" cellspacing="0" border="0">' .
          "%s" .
        '</table>\n',
  
      'element' =>
        // the table row containing one element
        '<tr %errorstyle%>' .
        '  <td width="120" align="right">' .
        '    <label for="%id%">%displayname%</label>' .
        '  </td>' .
        '  <td width="15">' .
        '    %erroricon%' .
        '  </td>' .
        '  <td>' .
        '    %prefix%%element%%postfix%%errordiv%' .
        '  </td>' .
        '</tr>',
  
      'errordiv'   => 
        // the hidden DIV where JS injects error messages for each element
        '<div id="%divid%" style="visible: hidden; display: none;"></div>',
  
      'button'     => 
        // submit button
        '<input type=submit value="OK"            />',
  
      'buttonrow'  => 
        // the row container for the submit button
        '<tr><td colspan=2></td><td>%s</td></tr>',
    )
  );
  

• The rowbyrow layout is even simpler:

  %displayname% %erroricon%
%prefix%%element%%postfix%%errordiv%
%button%

  Example of a valid and an invalid row:

  Phone number:
  (international format)
  
  Login name:
  
  
  
   
  The default configuration is:

  $clonefish->layouts = Array(
  
    'rowbyrow' => Array(
      // the container for the form elements, where %s is the content
      'container'      => '%s',
  
      'element'        => 
        // the HTML snippet containing one element
        "<label for="%id%">%displayname%</label> %erroricon%<br>\n".
        "%prefix%%element%%postfix%%errordiv%\n".
        "<br><br>\n",
  
      'errordiv'   => 
        // the hidden DIV where JS injects error messages for each element
        '<div id="%divid%" style="visible: hidden; display: none;"></div>',
  
      'button'     => 
        // submit button
        '<input type=submit value="OK"            />',
  
      'buttonrow'  => 
        // the row container for the submit button
        '%s',
    )
  );
  

The placeholders provided during rendering the form HTML:

• %id% is the field id used with <label> to create accessible forms. %id% defaults to the field name, and may be configured for any element.
• %element% is the generated HTML snippet of an element.

Placeholders provided by form class attributes:

• %errorstyle% gets replaced by the $clonefish->errorstyle attribute. Used only if a field is invalid on the server side.
• %errordiv% is the container for JS-injected error messages if $clonefish->jshtml is used. This DIV should be hidden normally by default.

Placeholders provided by elements (your form configuration):

• %displayname%, %prefix%, %postfix%: element settings

layoutcleanup

$clonefish->layoutcleanup = true;

If you use the label tags in your layout to create accessible forms, empty label tag pairs might be created when there's no displayname specified for an element (for obvious reasons: <label for="%id%">%displayname%</label>). If this property is set to true, such empty tag pairs are removed. By default, it's set to true.

outputmessages 

$clonefish->outputmessages = 1;

If set to 1, clonefish will display error messages above the form in an unordered list. Default value: 1.

erroricon

$clonefish->erroricon = '<img src="images/erroricon.gif"            />';

A string displayed next to the form field names when server side validation fails. You'll find its %erroricon% placeholder counterpart in the layout arrays.

errorstyle

$clonefish->errorstyle = 'style="background-color: #e95724; "';

A string used in the output for an invalid input. You'll find its %errorstyle% placeholder counterpart in the layout arrays.

messageprefix, messagecontainerlayout, messagelayout, messagepostfix

When server side form validation fails, these attributes are used to format the error messages.

$clonefish->messagecontainerlayout = '<ul>%s</ul>';
  // %s: placeholder for 'messagelayout' rows

$clonefish->messagelayout  = '<li>%s</li>';
  // %s: placeholder for error messages
$clonefish->messageprefix  = FORM_ERRORS; 
  // 'messageprefix' is shown above the message container layout. 
  // FORM_ERRORS are defined in messages_en.php

$clonefish->messagepostfix = '';         // shown below error messages
  // 'messagepostfix' is shown below the message container layout.

showerroricon

Enable or disable displaying the error icon when server side form validation fails. Has the same effect as removing the %erroricon% placeholder from the $clonefish->layouts array.

submit

While creating multilingual websites or applications, you may need to easily change strings in your form - one of them is the text on the submit button represented by this attribute. To use this string, you can put the %s placeholder in the 'button' HTML snippet in your layout array. It's a simple way to change the button text, as you don't need to mess with the button's HTML code.

• The class
  • Properties
  • Layout overview
  • Methods
  • Element class
• Input types
• Validation types
• Features

• View docs in a single page

form validation for developers!

clonefish is a proven, mature form generator class that helps PHP developers to create, validate and process secure, flexible and easy-to-maintain forms
learn more