Mixin: SC.Control
Extends
SC.ContentValueSupport.
A Control is a view that also implements some basic state functionality. Apply this mixin to any view that you want to have standard control functionality including showing a selected state, enabled state, focus state, etc.
About Values and Content
Controls typically are used to represent a single value, such as a number, boolean or string. The value a control is managing is typically stored in a "value" property. You will typically use the value property when working with controls such as buttons and text fields in a form.
An alternative way of working with a control is to use it to manage some specific aspect of a content object. For example, you might use a label view control to display the "name" property of a Contact record. This approach is often necessary when using the control as part of a collection view.
You can use the content-approach to work with a control by setting the "content" and "contentValueKey" properties of the control. The "content" property is the content object you want to manage, while the "contentValueKey" is the name of the property on the content object you want the control to display.
The default implementation of the Control mixin will essentially map the
contentValueKey of a content object to the value property of the
control. Thus if you are writing a custom control yourself, you can simply
work with the value property and the content object support will come for
free. Just write an observer for the value property and update your
view accordingly.
If you are working with a control that needs to display multiple aspects
of a single content object (for example showing an icon and label), then
you can override the contentValueDidChange() method instead of observing
the value property. This method will be called anytime any property
on the content object changes. You should use this method to check the
properties you care about on the content object and update your view if
anything you care about has changed.
Delegate Support
Controls can optionally get the contentDisplayProperty from a
displayDelegate, if it is set. The displayDelegate is often used to
delegate common display-related configurations such as which content value
to show. Anytime your control is shown as part of a collection view, the
collection view will be automatically set as its displayDelegate.
Defined in: control.js
- Since:
- SproutCore 1.0
Field Summary
Field Detail
controlSize StringThe control size. This will set a CSS style on the element that can be used by the current theme to vary the appearance of the control.
Some controls will default to SC.AUTO_CONTROL_SIZE, which will allow you
to simply size the control, and the most appropriate control size will
automatically be picked; be warned, though, that if you don't specify
a height, performance will be impacted as it must be calculated; if you do
this, a warning will be issued. If you don't care, use SC.CALCULATED_CONTROL_SIZE.
- Default value:
- SC.REGULAR_CONTROL_SIZE
The human readable label for this control for use in error strings. This property is computed dynamically using the following rules:
If the fieldLabel is defined, that property is localized and returned.
Otherwise, if the keyField is defined, try to localize using the string
"ErrorLabel.{fieldKeyName}". If a localized name cannot be found, use a
humanized form of the fieldKey.
Try to localize using the string "ErrorLabel.{ClassName}". Return a humanized form of the class name.
The name of the property this control should display if it is part of an
SC.FormView.
If you add a control as part of an SC.FormView, then the form view will
automatically bind the value to the property key you name here on the
content object.
- Default value:
- null
The human readable label you want shown for errors. May be a loc string.
If your field fails validation, then this is the name that will be shown
in the error explanation. If you do not set this property, then the
fieldKey or the class name will be used to generate a human readable name.
- Default value:
- null
Set to YES when the item is currently active. Usually this means the
mouse is current pressed and hovering over the control, however the
specific implementation my vary depending on the control.
Changing this property value by default will cause the Control mixin to add/remove an 'active' class name to the root element.
- Default value:
- NO
- Default value:
- YES
The selected state of this control. Possible values:
YESNOSC.MIXED_STATE.
- Default value:
- NO