
package com.smartgwt.client.docs;

/**
 * <h3>FormItem classes for databound component fields</h3>
 * {@link com.smartgwt.client.widgets.form.DynamicForm DynamicForms} and subclasses are
 * responsible for choosing the appropriate {@link
 * com.smartgwt.client.widgets.form.fields.FormItem} type (or subclass) for their fields. This is
 * true for standalone instances of <code>DynamicForm</code> or <code>SearchForm</code> and
 * embedded forms used by editable components such as the {@link
 * com.smartgwt.client.widgets.grid.ListGrid}. <P> The {@link
 * com.smartgwt.client.widgets.form.DynamicForm#getEditorType DynamicForm.getEditorType()} method
 * is responsible for determining what form item class to create for any field. This may be
 * overridden by subclasses such as {@link com.smartgwt.client.widgets.form.SearchForm}, or by
 * custom logic in dataBoundComponents with an editable view such as the ListGrid which provides
 * {@link com.smartgwt.client.widgets.grid.ListGrid#getEditorType ListGrid.getEditorType()} and
 * {@link com.smartgwt.client.widgets.grid.ListGrid#getFilterEditorType
 * ListGrid.getFilterEditorType()}. <P> At the component field level, the item type may be
 * specified via an explicit <code>editorType</code> or <code>filterEditorType</code> property. 
 * For non-filter components such as standard DynamicForms or editable ListGrids, 
 * <code>field.editorType</code> may be used to specify the desired editor type for the field.<br>
 * For filter components, including {@link com.smartgwt.client.widgets.form.SearchForm} and {@link
 * com.smartgwt.client.widgets.grid.ListGrid#getShowFilterEditor ListGrid filter editors}
 * <code>filterEditorType</code> is used. If <code>filterEditorType</code> is unset but
 * <code>editorType</code> is set, filter components will use <code>editorType</code>. <P> The
 * default formItem class can also be specified at the {@link
 * com.smartgwt.client.data.DataSourceField} level or the  {@link
 * com.smartgwt.client.data.SimpleType} level for custom data types. See the
 * <code>editorType</code>, <code>filterEditorType</code> and <code>readOnlyEditorType</code>
 * attributes for those classes of objects. <P> If no explicit FormItem type was specified, the
 * default formItem for a field will vary by data type and other properties. The following
 * overview outlines most of the cases you'll encounter.  This is intended as an orientation only,
 * not a definitive list of every default FormItem-subclass  for every combination of field
 * settings. <P> In general, if a named "data-type item" exists it will be used by default for the
 * data type. So fields of  type <code>"text"</code> (which is also the default for fields with no
 * explicit type) render in a {@link com.smartgwt.client.widgets.form.fields.TextItem} by default,
 * fields of type "integer" render in an {@link
 * com.smartgwt.client.widgets.form.fields.IntegerItem}, and so on. This is described  in the
 * {@link com.smartgwt.client.types.FormItemType} overview. However there are many exceptions to
 * this rule of thumb. <P> Fields with a {@link
 * com.smartgwt.client.data.DataSourceField#getValueMap valueMap} will render as a {@link
 * com.smartgwt.client.widgets.form.fields.SelectItem} in editing interfaces - {@link
 * com.smartgwt.client.widgets.form.DynamicForm} or {@link
 * com.smartgwt.client.widgets.grid.ListGrid#getCanEdit editable ListGrid} - by default.<br> In
 * filtering interfaces - {@link com.smartgwt.client.widgets.form.SearchForm}, {@link
 * com.smartgwt.client.widgets.grid.ListGrid#getShowFilterEditor ListGrid filterEditor} - they
 * will render as a {@link com.smartgwt.client.widgets.form.fields.SelectItem#getMultiple
 * multi-select} for small sets of options, or the specified {@link
 * com.smartgwt.client.widgets.form.DynamicForm#getLargeValueMapFilterEditorType
 * DynamicForm.largeValueMapFilterEditorType} for {@link
 * com.smartgwt.client.widgets.form.DynamicForm#getLargeValueMapFilterEditorThreshold large sets
 * of options}. This is the {@link com.smartgwt.client.widgets.form.fields.SetFilterItem} by
 * default, with intelligent logic in place to back off to the default SelectItem if the target
 * dataSource does not support <code>"inSet"</code> criterion operators. <P> Fields which derive
 * their options from an optionDataSource will behave like large valueMaps, rendering as a 
 * SelectItem in editing interfaces and a SetFilterItem in filtering interfaces. This includes
 * fields with a {@link com.smartgwt.client.data.DataSourceField#getForeignKey foreignKey
 * relationship}, with the exception of multi-FK relationships  (fields with
 * <code>multiple:true</code> representing one-to-many relationships as described in  {@link
 * com.smartgwt.client.docs.DataSourceRelations the relations overview}). These fields will render
 * a {@link com.smartgwt.client.widgets.form.fields.MultiPickerItem} in editing interfaces by
 * default. <P> Text fields with {@link com.smartgwt.client.data.DataSourceField#getLength
 * DataSourceField.length} greater than {@link
 * com.smartgwt.client.widgets.form.DynamicForm#getLongTextEditorThreshold
 * DynamicForm.longTextEditorThreshold} will render in a TextAreaItem by default. See {@link
 * com.smartgwt.client.widgets.form.DynamicForm#getLongTextEditorType
 * DynamicForm.longTextEditorType}.  Note that for {@link
 * com.smartgwt.client.widgets.grid.ListGrid#getCanEdit editable ListGrids} long text fields will
 * render a pop-up with a text-area in it for better presentation to the user. <P> Fields of type
 * <code>date</code> and <code>datetime</code> will render in editing interfaces using the 
 * DateItem and DateTimeItem by default. In filtering interfaces they will render as {@link
 * com.smartgwt.client.widgets.form.fields.DateRangeItem} in a standalone SearchForm, or {@link
 * com.smartgwt.client.widgets.form.fields.MiniDateRangeItem} within ListGrid filterEditors. <P>
 * Most binary fields in DynamicForms are rendered as {@link
 * com.smartgwt.client.widgets.form.fields.FileItem} or the {@link
 * com.smartgwt.client.widgets.FileDropZone FileDropZone-based} {@link
 * com.smartgwt.client.widgets.form.fields.FileUploadItem} depending on the value of {@link
 * com.smartgwt.client.widgets.form.DynamicForm#getUseFileUploadItem
 * DynamicForm.useFileUploadItem}.<br> See the {@link com.smartgwt.client.docs.Upload} and {@link
 * com.smartgwt.client.docs.BinaryFields} overviews for more information about binary  fields in
 * Smart GWT.
 */
public interface FormItemTypeSelection {
}
