Package Documentation

Object: TEXT-FORM-CONTROL (The :GWL Package)
Mixins: BASE-FORM-CONTROL, VANILLA-MIXIN

Author

Dave Cooper, Genworks

Description

This represents a INPUT TYPE=TEXT or TEXTAREA form control tag.


Input Slots (optional)

ACCEPT [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ACCESSKEY [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


AJAX-SUBMIT-ON-CHANGE? [from BASE-FORM-CONTROL] boolean

If set to non-nil, this field's value will be sent to server upon change. Default is nil.


AJAX-SUBMIT-ON-ENTER? [from BASE-FORM-CONTROL] boolean

If set to non-nil, this field's value will be sent to server upon enter. Default is nil.


ALIGN [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ALLOW-INVALID-TYPE? [from BASE-FORM-CONTROL] boolean

If non-nil, then values which fail the type test will still be allowed to be the value. Default is nil.


ALLOW-INVALID? [from BASE-FORM-CONTROL] boolean

If non-nil, then values which fail the type or validation test will still be allowed to be the value. Default is t.


ALLOW-NIL? [from BASE-FORM-CONTROL] boolean

Regardless of :domain, if this is non-nil, nil values will be accepted. Defaults to t if (the default) is nil, otherwise defaults to nil.


ALT [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


APPEND-ERROR-STRING? [from BASE-FORM-CONTROL] boolean

Determines whether a default error string is appended to string ouput-function for html-format (and therefore html-string computed-slot as well). Defaults to t.


BASHEE [from SKELETON-UI-ELEMENT] gdl object

Object to have its settable computed-slots and/or query-plist set from the fields on the form upon submission. Defaults to self.


CLASS [from SKELETON-FORM-CONTROL] string

You can use this to specify a user-defined class for the form-control. Defaults to nil, which means no class attribute will be generated.


COLS integer

The number of columns for a TEXTAREA (if rows is > 1). Defaults to (the size).


DEFAULT [from BASE-FORM-CONTROL] lisp value of a type compatible with (the domain)

This is the initial default value for the control. This must be specified by user code, or an error will result.


DISABLED? [from BASE-FORM-CONTROL] boolean

Maps to HTML form control attribute of the same name. Default is nil.


DOM-ID [from SKELETON-UI-ELEMENT] string

This is the auto-computed dom-id which should be used for rendering this section. If you use the main-div HTML string for rendering this object as a page section, then you do not have to generate the :div tag yourself - the main-div will be a string of HTML which is wrapped in the correct :div tag already.


DOMAIN [from BASE-FORM-CONTROL] keyword symbol, one of :number, :keyword, :list-of-strings, :list-of-anything, or :string

. This specifies the expected and acceptable type for the submitted form value. If possible, the submitted value will be coerced into the specified type. The default is based upon the Lisp type of (the default) provided as input to this object. If the default is nil, the domain will default to :string


FIELD-NAME [from SKELETON-FORM-CONTROL] keyword symbol

The name of this field. Computed from the object name within the tree.


FORCE-VALIDATION-FOR [from SKELETON-UI-ELEMENT] list of gdl objects of type form-control

The validation-function will be forced on these objects when a form is submitted, even if the object's html form-control does not happen to be included in the values submitted with the form. Defaults to nil.


HIDDEN? [from VANILLA-MIXIN*] boolean

Indicates whether the object should effectively be a hidden-object even if specified in :objects. Default is nil.


HTML-SECTIONS [from SKELETON-UI-ELEMENT]

List of HTML sections to be scanned and possibly replaced in response to GDL Ajax calls. Override this slot at your own risk. The default is all sections who are most recently laid out on the respondent sheet, and this is set programmatically every time the sheet section's main-div is demanded.


HTML-SECTIONS-VALID [from SKELETON-UI-ELEMENT]

List of valid HTML sections to be scanned and possibly replaced in response to GDL Ajax calls. Override this slot at your own risk. The default is all sections who are most recently laid out on the respondent sheet, and this is set programmatically every time the sheet section's main-div is demanded.


ID [from SKELETON-FORM-CONTROL] keyword symbol

The ID attribute for this tag. Defaults to (the field-name).


INNER-HTML [from SKELETON-UI-ELEMENT] string

This can be used with (str .) [in cl-who] or (:princ .) [in htmlGen] to output this section of the page, without the wrapping :div tag [so if you use this, your code would be responsible for wrapping the :div tag with :id (the dom-id).]


ISMAP? [from BASE-FORM-CONTROL] boolean

Maps to HTML form control attribute of the same name. Default is nil.


JS-TO-EVAL [from SKELETON-UI-ELEMENT] string of valid javascript

This Javascript will be send with the Ajax response, and evaluated after the innerHTML for this section has been replaced.


LABEL-POSITION [from BASE-FORM-CONTROL] keyword symbol or nil

Specifies where the label tag goes, if any. Can be :table-td (label goes in a td before the form control), :table-td-append (label goes in a td after the form control),

prepend:
(label tag wraps around form control and label text comes before form control),
append:
(label tag wraps around form control and label text comes after form control),
table-with-class:
(like :table-td, but adds a class "form-control" to the table), or
as-div:
(puts label and control inside a div of class "form-control"). Default is :as-div

LANG [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


MAXLENGTH [from BASE-FORM-CONTROL] number or nil

Maps to HTML form control attribute of the same name. Default is nil.


NULLIFY-EMPTY-STRING? [from BASE-FORM-CONTROL] boolean

Regardless of :domain, if this is non-nil, empty strings will convert to nil. Defaults to (the allow-nil?)


NUMBER? boolean

Specifies whether this should be a number form control with support for numerical input. Defaults to nil. Use number-form-control to get a default of t.


ONBLUR [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONCHANGE [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil, unless ajax-submit-on-change? is non-nil, in which case it calls ajax to set current form value.


ONCLICK [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONDBLCLICK [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONENTER [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil, unless ajax-submit-on-enter? is non-nil, in which case it calls ajax to set current form value.


ONFOCUS [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONKEYDOWN [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONKEYPRESS [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONKEYUP [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONMOUSEDOWN [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONMOUSEMOVE [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONMOUSEOUT [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONMOUSEOVER [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONMOUSEUP [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ONSELECT [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


ORDERED-FORM-CONTROLS [from SKELETON-UI-ELEMENT] list of gdl objects, which should be of type 'base-form-control

.

[Note -- this slot is not really necessary for protecting out-of-bounds sequence references anymore, the form-control processor protects against this by itself now].

These objects are validated and bashed first, in the order given. If the cardinality of one form-control depends on another as in the example below, then you should list those dependent objects first. Default is nil.

examples:
 
...
  
  :computed-slots ((number-of-nozzles (the number-of-nozzles-form value))
	    (ordered-form-controls 
	     (append (list-elements (the inner-flange-form))
		     (list (the number-of-nozzles-form)))))
  
  :objects
  ((inner-flange-form
    :type 'menu-form-control 
    :choice-plist (list :hey "hey" :now "now")
    :default :hey
    :sequence (:size (the number-of-nozzles)))
   (number-of-nozzles-form
    :type 'text-form-control 
    :prompt "Number of Shell Nozzles Required: "
    :domain :number     
    :default 0)

PASSWORD? boolean

Specifies whether this should be a password form control with obscured screen text. Note that this does not automatically give encrypted transmission to the server - you need SSL for that. Defaults to nil. Use password-form-control to get a default of t.


PLACEHOLDER [from BASE-FORM-CONTROL] string

Text to place in the field by default, overwritten as soon as the field is selected. Works only in HTML5. Default is nil.


POSSIBLE-NILS [from SKELETON-UI-ELEMENT] list of keyword symbols

Messages corresponding to form fields which could be missing from form submission (e.g. checkbox fields). Defaults to the names of any children or hidden-children of type menu-form-control or checkbox-form-control.


PRESET-ALL? [from SKELETON-UI-ELEMENT] boolean

This switch determines whether all form-controls should be preset before the final setting, in order to allow any interdependencies to be detected for validation or detecting changed values. If this is specified as a non-nil value, then any nil values of (the preset?) on individual form controls will be ignored. If this is specified as nil, then (the preset?) of individual form-controls (default of these is also nil) will be respected. Default is nil.


PRESET? [from BASE-FORM-CONTROL] boolean

This switch determines whether this form-control should be preset before the final setting, in order to allow any interdependencies to be detected for validation or detecting changed values. Default is nil.


PRIMARY? [from SKELETON-FORM-CONTROL] boolean

Set this to t if the form-control should always occur first in an outputted snapshot file. Defaults to nil.


PROMPT [from BASE-FORM-CONTROL] string

The prompt used in the label.


READONLY? [from BASE-FORM-CONTROL] boolean

Maps to HTML form control attribute of the same name. Default is nil.


ROOT [from VANILLA-MIXIN*] gdl instance

The root-level node in this object's ``tree'' (instance hierarchy).


ROWS integer

The number of rows. If more than 1, this will be a TEXTAREA. Defaults to 1.


SAFE-CHILDREN [from VANILLA-MIXIN*] list of gdl instances

All objects from the :objects specification, including elements of sequences as flat lists. Any children which throw errors come back as a plist with error information


SIZE [from BASE-FORM-CONTROL] number or nil

Maps to HTML form control attribute of the same name. Default is nil.


SRC [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


STRINGS-FOR-DISPLAY [from VANILLA-MIXIN*] string or list of strings

Determines how the name of objects of this type will be printed in most places. This defaults to the name-for-display (generally the part's name as specified in its parent), followed by an index number if the part is an element of a sequence.


STYLE [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


TABINDEX [from BASE-FORM-CONTROL] integer or nil

Maps to HTML form control attribute of the same name. Default is nil.


TITLE [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


USEMAP [from BASE-FORM-CONTROL] string or nil

Maps to HTML form control attribute of the same name. Default is nil.


VALIDATION-FUNCTION [from BASE-FORM-CONTROL] function of one argument

The argument will be the submitted form value converted to the proper type. The return value from this function can be nil, any non-nil value, or a plist with keys :validated-value and :error. The following behavior applies:

  • If the function returns nil, error is set to :unspecified-validation-fail.
  • If the function returns a plist with keys :validated-value and :error, and if :error is non-nil, it means the value is not acceptable, the form-controls error message is set to this error (usually a keyword symbol), and the error string will be appended to the html-string by default.
  • If the function returns any other value, then the properly typed submitted form value is considered valid and is used.
In the case of an error, the form-control's failed-value message is set to the properly typed submitted form value. If allow-invalid? is non-nil, then the form-control's value message is also set to this value (i.e. the invalid value is still accepted, even though a non-nil error is present). Default is (list :validated-value value :error nil).


VISIBLE-CHILDREN [from VANILLA-MIXIN*] list of gdl instances

Additional objects to display in Tatu tree. Typically this would be a subset of hidden-children. Defaults to NIL.



Input Slots (optional, defaulting)

RESPONDENT [from SKELETON-UI-ELEMENT] gdl object

Object to respond to the form submission. Defaults to self.


Examples

Please see base-form-control for all the examples.

Package Documentation