Field options

The [Field options] section of the settings file lets you specify additional options for some fields. Depending of the field type, these options may be required or optional.

This section (if present) must appear AFTER the fields section.

Format

The format of the settings in this section is 

field_name = options

where field_name is a field previously defined in the fields section.

The format of options will vary depending on the type of the field field_name, as follows:

Type Options Remark
amount    min,max (optional) comma-separate minimum and maximum value allowed in the field
check label,default label is the text that will be shown next to the checkbox. default is either 1=ticked or 0=unticked. Example: Send brochure,1
date preset_date,years (optional) preset_date is any recognisable date, eg "22 may 2010" or "today" or "+2 weeks", but cannot include commas. When the form is first loaded, the field will be preset to this date.

years can be a number: how many future years to list (with the current year always included). For example
  2 would include this year and the next 2 years.
  0 would include only the current year.
Alternatively, years can be a dotdot-separated range of years. For example
  -1..4 would include last year, and up to 4 years in the future.
  0..2 would include this year, and 2 future years (this is the same as using just the number 2).
  2009..1 would include years from 2009 to next year.
datelist preset, first, last, interval, showformat, valueformat



or



phpfn:functionname		 Any of the six parts may be empty or missing, in which case defaults will be used.

preset is any recognisable date, eg "22 may 2010" or "today" or "+2 weeks", but cannot include commas. When the form is first loaded, the datelist field will be preset to this date. (default today).
first is the first date in the list (default today). Acceptable formats are the same as for preset.
last is the last date in the list (default +30 days). Acceptable formats are the same as for preset.
interval is the day step (default 1). For example use 7 to only list every 7th day
showformat is a format string (consistent with the PHP strftime() function) indicating how days are shown to the visitor. The default is %a %e %B %Y eg Wed 8 September 2010
valueformat is a format string (consistent with the PHP strftime() function) indicating how day values are submitted by the form. The default is %Y_%m_%d eg 2010_09_08

The alternative format specifies the name of a custom PHP function that returns the options (often from a database). The function will be called without parameters, and should return either an array, or a comma separated list of options as described above.
calendarpreset,years,options,format (optional) Any of the four parts may be empty or missing, in which case defaults will be used.

preset uses the same format as the preset_date option for date fields (see above)
years uses the same format as the years option for date fields (see above)
options can consist of one or more sub-options separated with a dash, for example SOM-NWE. The possible sub-options are:
  • NWE - no weekends. If this is present, the user won't be able to select a Saturday or Sunday from the calendar.
  • 12 - use 12 hour time (default is 24 hour time). This only applies if the date format (below) includes a time component.
  • SOM - show other months. If present, days belonging to overlapping months will be shown in the calendar.
  • NRO - not readonly. Normally the input field associated with a calendar is locked, so the user can only select a date by using the popup calendar. If this option is present, the user can manually type a date into the field without using the calendar. This also means that the field should be validated, to ensure that it is a valid date.
  • DNV - do not validate. If you are using the NRO setting, then adding DNV will cause the field to NOT be validated. This might be useful if your form is not in English or if you have an unusual format string, in which case the default validation may not work properly.
  • VAL - always validate, regardless of the NRO or DNV setting.
format is a string specifying how dates should be shown after being selected from the calendar. Special characters are used to insert different parts of the date (day, month, etc). For example, 22 Jun 2010, September 12, 2010 or 15/6/2010 4:30pm can be specified by using format strings %e %b %Y, %B %e, %Y or %e/%m/%Y %l:%M%P respectively. If format includes time components, the calendar will allow the user to select a time of day, in addition to the date. The special characters that can be used include:

%aabbreviated weekday name
%Afull weekday name
%babbreviated month name
%Bfull month name
%Ccentury number
%dthe day of the month ( 00 .. 31 )
%ethe day of the month ( 0 .. 31 )
%Hhour ( 00 .. 23 )
%Ihour ( 01 .. 12 )
%jday of the year ( 000 .. 366 )
%khour ( 0 .. 23 )
%lhour ( 1 .. 12 )
%mmonth ( 01 .. 12 )
%Mminute ( 00 .. 59 )
%pPM or AM
%Ppm or am
%Ssecond ( 00 .. 59 )
%Uthe week number (%W, %V also show the week number, but with different rules
about when the first week of the year actually starts!)
%uthe day of the week ( 1 .. 7, 1 = MON )
%wthe day of the week ( 0 .. 6, 0 = SUN )
%yyear without the century ( 00 .. 99 )
%Yyear including the century ( eg 2010 )
%%a literal % character

Additional HTML tags must be included in your page for the calendar to work (refer to the sample form.php for further information). You can change the colours in the calendar by selecting a different stylesheet in /calendar/css, or you can edit one of these to create your own colour theme.

The calendar plugin has many other options, which you can change by editing the calendar-setup.js file.
integer min,max (optional) comma-separate minimum and maximum value allowed in the field
note text Actual text to show on the form
number min,max (optional) comma-separated minimum and maximum value allowed in the field
radio option,option,... same as for select
radio1 option,option,... same as for select
select option,option,...

or

file:pathname

or

phpfn:functionname		 A comma-separated list of options, where each option can be in the form value=text or just text. The default option can be identified with an asterisk after the text.
Example 1: Yes,0=No*,Maybe (the field will return "Yes", "0" or "Maybe"
Example 2: 1=Yes please,0=No thanks,=undecided (the field will return 1, 0 or an empty string)
Example 3: none selected=,Blue,Yellow (the field will return "none selected", "Blue" or "Yellow")

The second format for select, radio and radio1 fields indicates a text file containing the list of options (separated by commas or newlines). The text file is easily edited using twzContact_options.php.

The third format for select, radio and radio1 fields specifies the name of a custom PHP function that returns the options (often from a database). The function will be called without parameters, and should return either an array, or a comma separated list of options as described above.
string text Actual text to show on the form
filemaxsize,allowedtypes (optional) Comma separated maximum upload file size (in bytes) and allowed file extensions.
If maxsize is missing or zero, there is no size limit (except that imposed by your server or php settings).
allowedtypes can be a single file extension, or a pipe-separated list of extensions. Eg jpg or doc|xls|pdf|txt If allowedtypes is missing or empty, any type of file can be uploaded.
captcha theme,width,height,numchar



or



src:pathname 		(optional) The most common setting here is to just specify a colour theme, eg red. Valid themes are blue (default), blue2, grey, gray, green, red, orange, yellow and purple. Any of the settings can be missing, in which case default values will be used. For example to specify a red theme with 5 characters, this setting would be red,,,5 Theme can also be a pipe-separated list of themes, and one will be selected randomly each time (eg blue|red|orange). If you want a specific theme to appear more often, just include it twice. For example if you want to use a blue theme but occasionally throw up a red one, try blue|blue|blue|blue|red.

The second format indicates an alternative source of the image tag. This is normally captcha.php, but if you prefer your image source to be a jpg rather than a php file you can use this format along with mod_rewrite. For example to use captcha.jpg as the source, set this option to src:captcha.jpg and insert the following in your .htaccess file: 
RewriteEngine On
RewriteBase /
RewriteRule ^captcha.jpg$ captcha.php [L,QSA]
If using this method, you can only alter the image properties by editing the captcha.php script directly.
fieldset text (optional) Legend for the fieldset
hidden phpfn:functionname Hidden fields can be used to add external information to the form. For example you may want to include a cart cookie, or the UserId of a logged in user in the submitted data. twzContact will call the named PHP function (if it exists) and put its return value into the hidden field. The function will be called without parameters, and should return a string or numeric value. Example: phpfn:getUserid

If this setting is a string NOT in the format phpfn:functionname, the string will simply be used as the hidden value. I have no idea why you would want to do this (but you never know!)

You could also populate this field depending on some other field or value entered by the user, by making use of the preprocessformdata function.

Example

[Fields]

month          = select
year           = select
send_brochure  = check
date_required  = date
help_text      = string
family_members = integer

[Field options]

month          = 1=Jan,2=Feb,3=Mar,4=Apr,5=May,6=Jun,7=Jul,8=Aug*,9=Sep,10=Oct,11=Nov,12=Dec
year           = 2007,2008,2009,2010*,other
send_brochure  = Please send me a brochure,0
date_required  = +2 weeks, 3
help_text      = Please call us if you are having trouble.
family_members = 1,12

In the example above,