formitem.js

javascript 很酷的类库

    // @group basics
    // @visibility external
    //<    

    //> @attr formItem.defaultValue       (any : null : IRW)
	// Value used when no value is provided for this item. Note that whenever this item's value
    // is cleared by the user or set to <code>null</code> programatically, it will be reverted
    // to the <code>defaultValue</code>. Developers should use the +link{DynamicForm.values} 
    // object if their intention is to provide an initial value for a field in a form rather 
    // than a value to use in place of <code>null</code>.
    // 
    // @see method:defaultDynamicValue
    // @group basics
    // @visibility external
    // @example fieldEnableDisable
    //<
    

    //> @attr formItem.ID               (identifier : null : IRW)
	// Global identifier for referring to the formItem in JavaScript.  The ID property is
    // optional if you do not need to refer to the widget from JavaScript, or can refer to it
    // indirectly (for example, via <code>form.getItem("<i>itemName</i>")</code>).
    // <P>
    // An internal, unique ID will automatically be created upon instantiation for any formItem
    // where one is not provided.
    //
    // @group basics
    // @visibility external
    //<

    //> @attr formItem.emptyDisplayValue (string : "" : IRW)
    // Text to display when this form item has a null or undefined value.
    //
    // @group display_values
    // @visibility external
    //<
    emptyDisplayValue:"",
    
    
    // ValueMap
	// -----------------------------------------------------------------------------------------
        
	//>	@attr formItem.valueMap		(Array or Object: null : IRW)
    // In a form, valueMaps are used for FormItem types that allow the user to pick from a
    // limited set of values, such as a SelectItem.  The valueMap can be either an Array of
    // legal values or an Object where each property maps a stored value to a user-displayable
    // value.
    // <P>
    // To set the initial selection for a form item with a valueMap, use
    // +link{formItem.defaultValue}.
    // <P>
    // See also +link{dataSourceField.valueMap}.
    // 
	// @group valueMap
    // @visibility external
	//<
    
    // optionDataSource
    // ----------------------------------------------------------------------------------------

    //> @attr    FormItem.optionDataSource        (DataSource | String : null : IR)
	// If set, this FormItem will map stored values to display values as though a
    // +link{valueMap} were specified, by fetching records from the 
    // specified <code>optionDataSource</code> and extracting the
    // +link{formItem.valueField,valueField} and 
    // +link{formItem.displayField,displayField} in loaded records, to derive one
    // valueMap entry per record loaded from the optionDataSource.
    // <P>
    // Fetches will be initiated against the optionDataSource any time the FormItem has a
    // non-null value and no corresponding display value is available.  This includes when the
    // form is first initialized, as well as any subsequent calls to
    // +link{formItem.setValue()}, such as may happen when +link{DynamicForm.editRecord()} is
    // called.  Retrieved values are automatically cached by the FormItem.
    // <P>
    // Note that if a normal, static +link{formItem.valueMap,valueMap} is <b>also</b> specified for
    // the field (either directly in the form item or as part of the field definition in the
    // dataSource), it will be preferred to the data derived from the optionDataSource for
    // whatever mappings are present.
    // <P>
    // In a databound form, if +link{FormItem.displayField} is specified for a FormItem and 
    // <code>optionDataSource</code> is unset, <code>optionDataSource</code> will default to
    // the form's current DataSource 
    //
    // @group display_values
    // @visibility external
    // @getter FormItem.getOptionDataSource()
    // @example listComboBox
    //<
    
    //> @attr    FormItem.valueField  (string : null : IR)
    // If this form item maps data values to display values by retrieving the 
    // +link{FormItem.displayField} values from an 
    // +link{FormItem.optionDataSource,optionDataSource}, this property 
    // denotes the the field to use as the underlying data value in records from the 
    // optionDataSource.<br>
    // If unset, assumed to be the +link{FormItem.name} of this form item.
    // @group display_values
    // @visibility external
    // @getter FormItem.getValueFieldName()
    //<
    
    //> @attr   FormItem.displayField   (string : null : IR) 
    // Specifies an alternative field from which display values should be retrieved for this
    // item.<br>
    // If this item is not databound (+link{FormItem.optionDataSource} is unset), or bound 
    // to the same dataSource as the form as a whole, this is implemented by picking up the
    // value of the specified field from the Form's values object.<br>
    // Otherwise this item will attempt to map its underlying value to a display value
    // by retrieving a record from the +link{FormItem.optionDataSource} where the 
    // +link{FormItem.valueField} matches this item's value, and displaying the 
    // <code>displayField</code> value from that record.<br>
    // This essentially enables the specified <code>optionDataSource</code> to be used as
    // a server based +link{group:valueMap}.
    // @group display_values
    // @visibility external
    // @getter FormItem.getDisplayFieldName()
    //<
    
    //> @attr FormItem.fetchMissingValues   (boolean : true : IRWA)
    // If +link{FormItem.displayField} is specified for this item, should the item 
    // perform a fetch on the +link{FormItem.optionDataSource} to retrieve the display value
    // for the item when +link{FormItem.setValue()} is called with a value for which we
    // do not already have a mapped display value?
    // @group display_values
    // @visibility external
    //<
    fetchMissingValues:true,
    
    //> @attr FormItem.filterLocally (boolean : null : IRA)
    // If this form item is mapping data values to a display value by fetching them from a 
    // dataSource (see +link{FormItem.optionDataSource}, +link{FormItem.displayField} 
    // and +link{FormItem.fetchMissingValues}), setting this property to true ensures that when
    // the form item value is set, entire data-set from the dataSource is loaded at once and 
    // used as a valueMap, rather than just loading the display value for the current value.
    // This avoids the need to perform fetches each time setValue() is called with a new value.
    // <br>
    // See also +link{PickList.filterLocally} for behavior on form items such as SelectItems
    // that show pick-lists.
    //
    // @group display_values
    // @visibility external
    //<
        
    // Data Type Formatters
    // ---------------------------------------------------------------------------------------
    // Note: dateFormatter and timeFormatter provide a way to control format of date or 
    // time data in a generic form item such as a static text item.
    // Consistent name with ListGrid.dateFormatter / timeFormatter
    
    //>	@attr   formItem.dateFormatter  (DateDisplayFormat : null : [IRWA])
    // Display format to use for date type values within this formItem. Default is to use the
    // system-wide default short date format, configured via
    // +link{Date.setShortDisplayFormat()}.  Specify any valid +link{type:DateDisplayFormat} to 
    // change the format used by this item.<br>
    // Note: if both <code>dateFormatter</code> and +link{formItem.timeFormatter, timeFormatter}
    // are specified on an item, Date type values will be formatted as dates using 
    // <code>dateFormatter</code>.<br>
    // See also +link{DateItem.displayFormat} for formatting dates displayed in DateItems.
    // 
	// @group appearance
    // @visibility external
	//<
    //dateFormatter:null
    
    //>	@attr   formItem.timeFormatter  (TimeFormatter : null : [IRWA])
    // Time-format to apply to date type values within this formItem.  If specified, any
    // dates displayed in this item will be formatted as times using the appropriate format.<br>
    // Has no effect if +lilnk{formItem.dateFormatter} is also set.<br>
    // See also +link{TimeItem.displayFormat} for formatting values displayed in TimeItems.
    // 
	// @group appearance
    // @visibility external
	//<
    //timeFormatter:null
    
    // ValueIcons
    // ---------------------------------------------------------------------------------------
    //> @attr formItem.valueIcons   (Object : null : IRW)
    // A mapping of logical form item values to URLs.
    // If specified, when the form item is set to the value in question, an icon will be 
    // displayed with the appropriate source URL.
    // @group   valueIcons
    // @setter  formItem.setValueIcons()
    // @see     formItem.getValueIcon()
    // @visibility external
    //<

    //> @attr formItem.emptyValueIcon (string : null : IRW)
    // This property allows the developer to specify an icon to display when this item has
    // no value. It is configured in the same way as any other valueIcon 
    // (see +link{formItem.valueIcons})
    // @group valueIcons
    // @visibility external
    //<
    
    //> @attr formItem.showValueIconOnly (boolean : null : IRWA) 
    // If +link{FormItem.valueIcons} is set, this property may be set to show the valueIcon
    // only and prevent the standard form item element or text from displaying
    // @group valueIcons
    // @visibility external
    //<
    //> @attr formItem.suppressValueIcon (boolean : null : IRWA)
    // If +link{FormItem.valueIcons} is set, this property may be set to prevent the value
    // icons from showing up next to the form items value
    // @group valueIcons
    // @visibility external
    //<
    
    //> @attr formItem.valueIconWidth (number : null : IRW)
    // If +link{formItem.valueIcons} is specified, use this property to specify a width for
    // the value icon written out.
    // @see FormItem.valueIconHeight
    // @see FormItem.valueIconSize
    // @group valueIcons
    // @visibility external
    //<
    
    //> @attr formItem.valueIconHeight (number : null : IRW)
    // If +link{formItem.valueIcons} is specified, use this property to specify a height for the
    // value icon written out.
    // @see FormItem.valueIconWidth
    // @see FormItem.valueIconSize
    // @group valueIcons
    // @visibility external
    //<
    
    //> @attr formItem.valueIconSize (number : 16 : IRW)
    // If +link{formItem.valueIcons} is specified, this property may be used to specify both
    // the width and height of the icon written out.
    // Note that +link{FormItem.valueIconWidth} and +link{formItem.valueIconHeight} take
    // presidence over this value, if specified.
    // @see FormItem.valueIconWidth
    // @see FormItem.valueIconHeight
    // @group valueIcons
    // @visibility external
    //<
    valueIconSize:16,

    //> @attr formItem.valueIconLeftPadding (number : 0 :  IRW)
    // If we're showing a value icon, this attribute governs the amount of space between the 
    // icon and the left edge of the form item cell
    // @see FormItem.valueIcons
    // @visibility external
    // @group valueIcons
    //<
    valueIconLeftPadding:0,

    //> @attr formItem.valueIconRightPadding (number : 3 :  IRW)
    // If we're showing a value icon, this attribute governs the amount of space between the 
    // icon and the label of the form item
    // @see FormItem.valueIcons
    // @visibility external
    // @group valueIcons
    //<
    valueIconRightPadding:3,                           
                                       
    //> @attr formItem.imageURLPrefix (string : null : IRWA)
    // Prefix to apply to the beginning of any +link{FormItem.valueIcons} when determining the
    // URL for the image.
    // Will not be applied if the <code>valueIcon</code> URL is absolute.
    // @group valueIcons
    // @visibility external
    //<

    //> @attr formItem.imageURLSuffix (string : null : IRWA)
    // Suffix to apply to the end of any +link{FormItem.valueIcons} when determining the URL for
    // the image. A common usage would be to specify a suffix of <code>".gif"</code> in which
    // case the <code>valueIcons</code> property would map values to the names of images without
    // the <code>".gif"</code> extension.
    // @group valueIcons
    // @visibility external
    //<
            
    // Internal
    // ---------------------------------------------------------------------------------------

    //> @attr formItem.form     (DynamicForm : null : R)
	// A Read-Only pointer to this formItem's DynamicForm widget.
    // @visibility external
    //<
    // Handles values for the form item.  Also handles writing the item's HTML by default.
    
    //> @attr formItem.containerWidget  (Canvas : null : R)
	// A pointer to this formItem's "ContainerWidget".  This is the widget that handles writing
    // the HTML for the FormItem into the DOM.  By default this will be the DynamicForm 
    // widget containing this form item.
    // 
    // @visibility internal
    //<    
    

    // RelationItem
    // ---------------------------------------------------------------------------------------
    
   	//> @attr	formItem.dataSource		(DataSource or String : null : [IRWA])
    //
    // If this FormItem represents a foreignKey relationship into the dataSource of the form
    // containing this item, specify it here.
    //
    //  @visibility experimental
	//<


    // Picker
	// -----------------------------------------------------------------------------------------
    
    //> @attr formItem.showPickerIcon (boolean : false : [IRW])
    // Should we show a special 'picker' icon for this form item. Picker icons are customizeable
    // via +link{FormItem.pickerIconProperties}. By default they will be rendered inside the 
    // Form Item's "control box" area, and will call +link{FormItem.showPicker()} when clicked.
    //
    // @visibility pickerIcon
    //<
    
    //> @attr formItem.showFocusedPickerIcon (boolean : false : [IRW])
    // If +link{FormItem.showPickerIcon} is true for this item, should the picker icon show
    // a focused image when the form item has focus?
    // @visibility pickerIcon
    //<
    showFocusedPickerIcon:false,
    
    // We draw the icon into an exactly sized table cell - don't draw with any margin