Class: MF_Widget
- Package: saf.MailForm
- Author: John Luxford <lux@simian.ca>
- Copyright: Copyright (C) 2001-2003, Simian Systems Inc.
- License: http://www.sitellite.org/index/license Simian Open Software License
- Version: 2.8, 2003-11-07, $Id: Widget.php,v 1.7 2007/10/06 00:06:30 lux Exp $
- Access: public
The base class for creating form widgets. Used only for extending.
Rules for creating custom widgets:
- must define some field (can be a blank hidden field) with their own $w->name
- must extend MF_Widget and must call parent::MF_Widget in their constructor method
- must use other widgets to create "compound" or custom widgets from, and must
handle the task of collecting the values of those internal widgets to expose
a singular $w->data_value when requested (this is simplified, don't worry :)
- must dynamically load any other widgets called, using the $GLOBALS['loader']
object to do so.
New in 1.2:
- Made some clarifications in the docs regarding setValues() and setValue(),
which are rather ambiguous. How to remember the difference: setValues as in
ALL possible values (pleural), setValue as in THE actual value (singular).
New in 1.4:
- Changed var $value; to var $value = array ();, so that empty fields of certain
types don't show errors.
- Added a setDefault() method which is handy for other widgets to inherit, since
setting the default value might not always be as simple as setting the
$default_value property.
New in 1.6:
- Added a new $passover_isset property. Read below for details.
New in 1.8:
- Deprecated the validation() method in favour of an addRule() method, which
allows a widget to have more than one validation rule. This also allows
each rule to have its own error message.
- Added a validate() method which is called by the MailForm->invalid()
method.
- Validation rules are now their own class, called MailFormRule, which are
accessed indirectly through this class. For more info, see
saf.MailForm.Rule.
New in 2.0:
- Added new methods: addRule() and validate().
- Added new properties: $type and $rules.
- Deprecated one method, validation(), and one property, $rule.
New in 2.2:
- Added an $_attrs property and three new methods, attr(), unsetAttr(), and getAttrs().
- Deprecated the $extra property in favour of the new property and methods just
added. Note: Migration to these new methods is not complete in all of the widgets
just yet, and $extra will still work for some time, so the $extra method should
still be used right now, however new widgets may or may not support the $extra
property.
New in 2.4:
- Added a $label_template property.
New in 2.6:
- Added an $invalid property and an invalid() method.
New in 2.8:
- Added docs for the implied $nullable property, and made getValue() return null
properly according to the $nullable setting.
Usage Example
<?php
$widget = new MF_Widget ('name');
$widget->addRule ('is "foo"', 'You must enter "foo" to pass!');
$widget->setValue ('foo');
?>
Return to Top
Properties
$invalid_field = ''
Contains the name of the widget that did not validate during
the last call to the invalid () method.
$method
The value of the method attribute of the HTML form tag.
$method is actually an alias for $_attrs['method'].
$action
The value of the action attribute of the HTML form tag.
$action is actually an alias for $_attrs['action'].
$widgets = array ()
An array of form widgets.
$template
The template to display.
$title = false
$message
The initial message to be displayed at the top of the form.
$extra = ''
A way to pass extra parameters to the HTML form tag, for
example 'enctype="multipart/formdata"'.
$error_message
The error message to display in place of the form message if this
widget is invalid. This property is is not used to set the error messages,
see saf.MailForm.Rule for that, but it is still used internally by
saf.MailForm.
$error_mode = 'single'
Determines the way in which error messages are displayed.
The default ('single') is to display the error message for the first
invalid field only. The other ('all') is to display a list of all
invalid fields with their corresponding error messages. Please note
that $error_mode 'all' assumes that a custom error message is provided
for every rule.
$invalid = false
Whether this field is invalid. Used in the display() method
to set class="invalid" on the field label.
$submitted = false
Contains a true or false value as to whether the form has been
submitted successfully or not. An invalid form will contain false.
This value is used internally by the setValues() method.
$name
The name of the widget. $name is actually an alias for
$_attrs['name'].
$_attrs = array ()
This contains a list of attributes of the HTML tag.
$sendTo
The email address to send the form to in the default handler.
$sendFrom = ''
The email address to send the form from in the default handler.
$sendExtra = ''
Any extra parameters for the mail() function in the default handler.
$sendSubject = 'Mail Form'
The subject line of the email to send from the default handler.
$screenReply = 'Thank you. Your form has been sent.'
The response to return upon a successfully submitted form in the
default handler. Defaults to "Thank you. Your form has been sent."
$handler
The function or object method to use to handle the submitted form.
This function or method will be called by the run() method. Use the
setHandler() method to change this setting.
$uploadFiles = true
Whether to upload files automatically or to leave them for a custom
saving mechanism.
$verify_sender = false
Whether to verify the REQUEST_METHOD and HTTP_REFERER headers to make
it more difficult (although not impossible) for spammers to abuse your
form. Note that this can be enabled in a form's settings file under
the [Form] block via: verify_sender = yes
$clean_input = false
Whether to strip all HTML and PHP tags/code from all input parameters.
This is off by default because it would break forms with the Xed editor
by default, so it must be enabled as needed. Note that this can be
enabled in a form's settings file under the [Form] block via:
clean_input = yes
$blacklist = true
Whether to verify the remote address of the form submitter against
a list of invalid IP addresses in the database table
sitellite_form_blacklist so as to prevent repeated abuse from a single
source.
$verify_session = true
Whether to verify that the submitter can accept session data, which
helps ensure they are a legitimate human user. Passing session
verification requires cookies to be enabled for the submitter, which
may help prevent abuse in combination with the other abuse-prevention
techniques because a spambot may ignore the cookie, however this
restricts forms for legitimate visitors who have cookies disabled
in their browser (only a very small number of users disable cookies,
but some do). To disable for a single form, add verify_session = no
to its settings.php form.
$autosave = false
Whether this form should tie into Sitellite's autosave capabilities.
Please note that the autosave handler is only available to authenticated
users and not to anonymous forms.
$rule
The validation rule for this widget. Note: This property is
deprecated in favour of the new $rules property.
$msg
The error message for this rule.
$type
Contains the widget type name (ie. 'textarea' for a MF_Widget_textarea
object). Used only by saf.Database.Table to keep track of things in the
_makeWidget() method.
$value = array ()
The possible values of the widget. Can be a string or hash.
$negated = false
If a 'not' is present at the start of the rule, this will be
set to true, otherwise false.
$allowed = array ()
The statuses the user is allowed to access.
$nullable = false
Determines whether an empty value should be returned as NULL or as an
empty string by getValue(). Default is the empty string, since it is
common to specify NOT NULL on database tables.
$tables = array ()
The list of elements that are to be displayed.
$allow_all_text = 'Allow All'
The text to display for the first element, which defaults to 'Allow All'.
$size = false
Set this property to the number of options to display.
$addLink = 'addAttachment.php'
This is the link to send the 'Add' button to. Defaults to
'addAttachment.php'.
$removeLink = 'removeAttachment.php'
This is the link to send the 'Remove' button to. Defaults to
'removeAttachment.php'.
$format = '%Y-%m-%d'
This determines the format of the date stored in the hidden
field, and also the format submitted by the form widget.
$displayFormat = '%a, %e %b, %Y'
This determines the format of the date displayed to the user.
$lang = 'en'
This determines the language file to load for the calendar
user interface. See the folder /js/calendar/lang for a list
of available languages.
$style = 'sitellite'
This determines the stylesheet to load for the calendar
user interface. See the CSS files in the folder /js/calendar
for a list of available stylesheets, or information on
writing your own.
$showsTime = false
Determines whether to show the time selection options under the
calendar.
$timeFormat = '12'
Sets the display time to 24 hours, or 12 hours with AM/PM option.
The default is 12 hours.
$fieldset = true
Set this to false if you don't want the fieldset and legend tags.
$align = 'vertical'
This determines the alignment of the buttons. The default is vertical,
which puts each button on its own row. Setting this to horizontal will put
the buttons all on the same row.
$_vertical_template = ' <tr>
<td colspan="2">
{if obj.fieldset}
<fieldset>
<legend{filter none}{invalid}{end filter}>{display_value}</legend>
{end if}
{loop obj.value}
<input
type="radio"
{filter none}{attrstr}{end filter}
value="{loop/_key}"
id="{name}_{loop/_key}"
{if obj.data_value eq loop._key}checked="checked"{end if}
{filter none}{extra}{end filter}
/>
<label for="{name}_{loop/_key}">{loop/_value}</label><br />
{end loop}
{if obj.fieldset}
</fieldset>
{end if}
</td>
</tr>
'
$_horizontal_template = ' <tr>
<td colspan="2">
<table width="100%"><tr><td width="35%" valign="top">
<span{filter none}{invalid}{end filter}>{display_value}</span>
</td>
{loop obj.value}
<td valign="top"><input
type="radio"
{filter none}{attrstr}{end filter}
value="{loop/_key}"
id="{name}_{loop/_key}"
{if obj.data_value eq loop._key}checked="checked"{end if}
{filter none}{extra}{end filter}
/>
<label for="{name}_{loop/_key}">{loop/_value}</label></td>
{end loop}
</tr></table>
</td>
</tr>
'
$year
Unused and deprecated.
$month
Unused and deprecated.
$day
Unused and deprecated.
$lowest_year
The lowest year to be displayed in the year select box. Set to a
default value of 25 years ago by the constructor method.
$highest_year
The highest year to be displayed in the year select box. Set to a
default value of one year into the future by the constructor method.
$date
Unused and deprecated.
$time
Unused and deprecated.
$extensions = array ()
Contains a list of valid file extensions to display from the
directory.
$directory = 'inc/rte'
The directory to find richedit.html in. Defaults to 'inc/rte'.
$data_value_DIRLIST
Contains the data value of this widget.
$show_viewbutton
Determines whether or not to display a 'view' link next to
the select box, which will pop up a view of the item from the list.
$web_path = ''
The web path to the directory in which to place the uploaded file.
$formname = false
The name of the form. Note: If this is not the first form
on the page, then a form name is required (must also set the $name
property of the MailForm object).
$recursive
Whether or not the list should display recursively into sub-directories.
$path = false
Base directory path under which all images must be kept. If $setPath is
set to true and this is given a value, it will set a session variable
called "imagechooser_path" which will be used by the imagechooser app.
If no value is given for this, the default path used by the imagechooser
app is "/pix".
$mode = false
Specifies a mode to chmod() the newly uploaded file to during
the move() method. The mode is also known as the permissions of the
file. Must be set as a 4-digit octal value with the first digit on
the left being a zero (0), for example 0755. See the PHP documentation
for the chmod() function for more information.
$user = false
Specifies a user to chown() the newly uploaded file to during
the move() method. This is not likely to work on most systems, but
it exists for the few strange (and highly suspect) configurations
where it will. See the PHP documentation for the chown() function
for more information.
$group = false
Specifies a group to chgrp() the newly uploaded file to during
the move() method. Can only be changed to any group that the PHP user
belongs to. See the PHP documentation for the chgrp() function for
more information.
$clear = false
This determines whether to provide a "Clear" button when a file exists
in an edit form, so that the current value can be reset without being
replaced.
$hideInSearches = true
This allows you to specify whether or not you want this widget to
show in search results (used primarily in the Sitellite CMS database manager)
so that it can be hidden in the form, but not everywhere. Defaults to
true, as in "yes, hide it everywhere".
$field = ''
The field to use to determine the key in the key/value $set property.
$setPath = true
Tells imagechooser whether or not to set the session variable
"imagechooser_path" upon display() of this widget.
$filter = false
A filter function to apply to the value before displaying it. Note that
htmlentities_compat() is still called afterwards.
$filter_import = false
A library to import which contains the filter function.
$htmlentities = true
Set this to false to skip calling htmlentities_compat() on the displayed
data.
$table = 'sitellite_category'
This is the database table to get the list of items from.
$self_ref
Whether or not this widget is self-referencial.
$primary_key
The column in the other table that is the primary key.
$display_column
The column in the other table that should be shown in the select box.
$ref_column
The column in the current table that refers to the other table.
$addblank
Whether or not to add a blank line to the list. $addblank is
useful in the Sitellite CMS because cms.Versioning.Rev returns the
column value as NULL if $nullable is set to true, and getData() is
called automatically by display(), so there's no chance to add a
blank array element at the bottom of the list.
$popup
If true, this will prompt a popup to occur at $popup_limit number of options
in the Ref, so that they all aren't loaded at once into the select box. This is true
by default. It is good for references to large tables. This feature is Sitellite
Content Manager specific.
$popup_limit
This determines the limit at which a popup occurs instead of a select box,
if $popup is set to true.
$buttons = array ()
A list of "inner" radio buttons, which are MF_Widget_radio
objects.
$ignoreEmpty = true
Determines whether or not this password field should be ignored
if left blank. This is useful for situations where a password change
field may be present in a form but is not required to be filled out to
change it since the current value cannot or should not be sent
back to the browser. Defaults to true.
$headers = array ()
A list of headers, which are displayed above the radio buttons.
$height = 400
The height of the widget.
$width = 600
The width of the widget.
$rows = 16
The height of the textarea widget in rows.
$cols = 60
The width of the textarea widget in columns.
$options = array (
'history' => 'off',
'dragdrop' => 'on',
'source' => 'yes',
'style' => 'yes',
'font' => 'no',
'fontSize' => 'no',
'colour' => 'yes',
)
The list of RichText configuration options, including 'history',
'dragdrop', 'source', 'style', 'font', 'fontSize', and 'colour'. Please
refer to the help docs for more information.
$js = '<script language="JavaScript">
function rt_copyValue () {
// this assumes your form is named mainform
mainform.{name}.innerText = document.getElementById (\'rt_{name}\').docHtml;
}
</script>
<script language="JavaScript" event="onload" for="window">
document.getElementById (\'rt_{name}\').options = "{options_formatted}";
document.getElementById (\'rt_{name}\').docHtml = mainform.{name}.innerText;
</script>'
$bold = true
Set this to false if you don't want the text to be bolded.
$verify_method = 'figlet'
This is the method to use to verify the user is human. The default
is 'figlet' which renders random letters and numbers using a combination
of ascii symbols on several lines. This technique is less typical
than other form security techniques, which may increase its security
slightly, but it is also text-based and therefore less secure in that
regard. It is the default because it requires no special PHP extensions
to use.
The alternative is 'turing' which generates an image of random letters
and numbers, making it a slightly more effective security precaution.
This requires PHP's GD extension however, which is not available on all
systems. Check your phpinfo() output to determine compatibility.
Turing tests are also known as CAPTCHA tests. Their purpose is to
verify that the user is human by having them perform a test that would
be difficult for a computer to pass.
$key = 'id'
This is the primary key of the list table.
$multiple = false
If you want this to be a multiple-select widget, set this property
to true.
$addAction = 'cms/selector/add'
Name of the box that adds the new item or items to the database
table underlying the selector.
$removeAction = 'cms/selector/remove'
Name of the box that removes the specified item or items from the
database table underlying the selector.
$labelPosition = 'top'
This is the position of the label for the textarea. It may
be set to 'top' (the default), or 'left' to be pushed to the side.
$collection
$data = array ()
The data to pass to the template.
$submitButtons = array ()
If you define any submit buttons that are meant to actually
submit the form (ie. not stopped in their tracks via the
onclick handler) within your template, then you need to specify
those here, so that MailForm knows the form was submitted.
$tie = false
The name of the field to be "tied" to.
$jsFile = false
The path to the tie.js JavaScript file, which contains
the JavaScript components to this widget. This is determined
automatically in the constructor.
$ties = array ()
This is the list of values to display for each value of
the widget this widget is tied to. Ordinary select widgets simply
have a $values associative array, but the tie widget has this which
is a $values array for each value of the other widget.
$hour
These properties are deprecated. All properties except $extra
that are not inherited from MF_Widget are private.
$minute
These properties are deprecated. All properties except $extra
that are not inherited from MF_Widget are private.
$second
These properties are deprecated. All properties except $extra
that are not inherited from MF_Widget are private.
$isHtml = true
$_template_left = '
<tr>
<td class="label" valign="top">
<label for="{name}" id="{name}-label" {invalid}>{label}</label>
</td>
<td class="field">
<textarea {attrstr} rows="{rows}" cols="{cols}" {extra} class="tinyarea">{data_value}</textarea>
</td>
</tr>'
$_template_top = '
{if not empty (obj.alt)}
<tr>
<td class="label" colspan="2">
<label for="{name}" id="{name}-label" {invalid}>{label}</label>
</td>
</tr>
{end if}
<tr>
<td class="field" colspan="2">
<textarea {attrstr} rows="{rows}" cols="{cols}" {extra} class="tinyarea">{data_value}</textarea>
</td>
</tr>'
$_template_no_table = '<textarea {attrstr} rows="{rows}" cols="{cols}" {extra} class="tinyarea">{data_value}</textarea>'
$tinyButtons1 = 'bold,italic,underline,separator,strikethrough,justifyleft,justifycenter,justifyright,justifyfull,bullist,numlist,undo,redo,link,unlink,emotions,separator,formatselect'
$tinyButtons2 = ''
$tinyButtons3 = ''
$tinyPlugins = 'emotions'
$tinyValidElements = 'a[name|href|target|title|onclick],img[class|src|border=0|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name],hr[class|width|size|noshade],font[face|size|color|style],span[class|align|style]'
$function
A function to call to get the value of this widget. This
function must act on a $cgi object.
$query
A database query to execute to get the value of this widget.
$bindValues = array ()
A list of bind values to pass to the database query.
$column
A column that will be returned from the database query. If this
column is specified, then instead of returning an object or array, the
getValue() method will return the value of this column from the first
result returned from the database.
$error
If the database query fails, this will contain the error message.
$display_value
The display text of the widget.
$default_value
The default value of the widget.
$data_value
The actual value of the widget. Could be user input value or
same as $default_value.
$passover_isset = false
This indicates to the MailForm validation routine whether or not to
skip checking if isset() on this widget. This is useful for checkboxes, file
uploads, reset buttons, multiple-choice select boxes, pseudo widgets (see
the Hiddenswitch widget for an example of this), and sub-classes of these
(for example, the Allow widget is a sub-class of the Checkbox widget). This
is set to false by default.
$rules = array ()
Contains a list of rules to apply to this widget. See saf.MailForm.Rule
for more information.
$label_template = '{display_value}'
Template to use to display the label value of the widget when
$generate_html is set to true (referring the parameter of the display()
method). Defaults to '##display_value##', which will output exactly
what the display value contains. Note to widget developers: The
templates should be evaluated for substitutions only, so that this
doesn't introduce much overhead for large forms.
$form = false
When a widget is attached to a form (via addWidget()), which is
not always necessarily the case, then this will contain a reference to
that form object.
$advanced = false
If this is set to true, the widget will be automatically hidden from
users whose 'browse_level' preference isn't set to 'advanced'.
$reference = false
Reference shows on the right in an added table column for things like
translating from an original document.
Return to Top
Methods
MF_Widget ($name)
Constructor Method.
validation ($rule)
Sets the validation $rule for this widget. Note: This method is
deprecated and only wraps around the addRule() method anyway. Please use
addRule() instead, since this method will be removed in a near-future
release.
addRule ($rule, $msg = '')
- Access: public
- Return: boolean
Adds a validation rule to the list of $rules.
validate ($value, $form, $cgi)
- Access: public
- Return: boolean
Validates the widget against its set of $rules. Returns false
on failure to pass any rule.
setValues ($key, $value = '')
Sets the *POSSIBLE* values for this widget. If $value
is given, sets $this->value as a hash, otherwise, as a string.
Please Note: No simple arrays allowed, or the numeric keys will
be used as the value property in the HTML output.
setValue ($value = '', $inner_component = '')
Sets the *ACTUAL* value for this widget. An optional second
parameter can be passed, which is unused here, but can be used in
complex widget types to assign parts of a value and piece it together
from multiple physical form fields.
getValue ($cgi = '')
- Access: public
- Return: string
Fetches the actual value for this widget.
setDefault ($value)
Sets the default value for the widget.
display ($generate_html = 0)
- Access: public
- Return: string
Returns the display HTML for this widget. The optional
parameter determines whether or not to automatically display the widget
nicely, or whether to simply return the widget (for use in a template).
attr ($key, $value = false)
- Access: public
- Return: string
This is the accessor method for setting and getting the value of
any attribute of the tag, including 'method' and 'action'. This will
replace the $extra property, which is henceforth deprecated. If you call
this method and provide no $value, you are using it as a 'getter', as in
you are getting the current value. If you provide a value, the new value
will be set, so you are acting as a 'setter'. If you simply specify that
the $value be true, then it will appear filled with its own name (useful
for things like the checked="checked" attribute of a checkbox input field).
unsetAttr ($key)
- Access: public
- Return: string
Use this method to remove an attribute from the tag
attribute list. Use this instead of passing a false value to attr(),
because a false value essentially means "return the current value"
in that method. This method returns the old value of the attribute
being unset.
getAttrs ()
- Access: public
- Return: string
Returns a list of all of the attributes of this object's HTML tag
in a string ready to be concatenated into the actual rendered tag output.
invalid ()
- Access: public
- Return: string
Returns a ' class="invalid"' string if the widget's $invalid
property is set to true, or an empty string otherwise.
changeType ($newType, $extra = array ())
Return to Top