Back again (sorry about the delay) with a new part in the SharePoint 2010 Ribbon Controls series (all parts available here). This time I’m going to show you an interesting control - the Spinner control.
What is a Spinner control?
The spinner is an up/down (increase/decrease) control with some smart abilities to handle different units. For instance it is used when setting image and table sizes in the default ribbon. The Spinner control has a value (number) and a unit (pixel, percent, points etc.) and three ways to modify the value; manual or using the up and down buttons.
Sample Spinner control
The following Server Ribbon XML can be used to define a Spinner control.
Spinner Id="Wictor.RibbonControls.Tab.SpinnerGroup.Spinner1"
Sequence="10"
AccelerationInterval="500"
AltDownArrow="Up"
AltUpArrow="Down"
Command="SpinnerCommand"
DefaultUnit="meter"
DefaultValue="100"
MultiplierInterval="2"
QueryCommand="SpinnerQueryCommand"
TemplateAlias="section2">
Unit Name="meter"
DecimalDigits="2"
Interval="1"
MaximumValue="1000"
MinimumValue="0">
UnitAbbreviation Sequence="1" Value="m"/>
Unit>
Unit Name="feet"
DecimalDigits="1"
Interval="1"
MaximumValue="3000"
MinimumValue="0">
UnitAbbreviation Sequence="1" Value="ft"/>
Unit>
Spinner>
Spinner control properties
Just as with the most of the other controls the Spinner controls shares some properties such as Id and Sequence. The control can have a tooltip which are used as in the TextBox control.
Property TemplateAlias
The TemplateAlias must match a group template with a display mode set to Medium.
Property AltDownArrow and AltUpArrow
The AltDownArrow and AltUpArrow properties are used as alternative texts for the down and up buttons in the control.
Property AccelerationInterval
The AccelerationInterval sets how many milliseconds it is between an increase or decrease of values when the up or down buttons are pressed.
Property MultiplierInterval
The MultiplierInterval specifies how fast the value increment/decrement is increased or decreased.
Property DefaultValue
The DefaultValue property specifies the default value of the Spinner control (not including the unit).
Property DefaultUnit
The DefaultUnit property specifies which unit is the default one. Units are defined as sub-elements to the Spinner control element (see example above). Each unit have a name and one or more abbreviations (the UnitAbbreviation sub-element), maximum and minimum values, the number of decimals and an increase/decrease interval.
Property QueryCommand
The QueryCommand property is used to specify the query command of the control. That is the command executed when the tab receives focus or when the Command UI is refreshed. The properties JavaScript object contains two properties Value and Unit, which can be used to set the default value. See later down for an example.
Property Command
The Command property declares the command that is called when the value changes either by manually entering a new value or when the up/down buttons are clicked. The properties JavaScript object has four different parameters:
- ChangedByMouse: set to true if the command is invoked from a mouse-click on the up/down buttons, otherwise false
- ChangeType: have three possible values: ‘manual’ - when a value is entered manually, ‘increase’ - the value is increased by the up button or pressing the up-arrow key and ‘decrease’ - click on down button or down-arrow key.
- Unit: the name of the current unit
- Value: the current value
For a better understanding of how it works with units - take a look at this sample. You all know that metric system is a broadly used standard - but as with all standards some invent their own (opening up for a bunch of Open Xml discussion here…). I have no problem with this, so assume I need to input height in a Spinner control. Limiting users to enter the value in meters is probably not a good solution if I’d like to sell it on a global market. So why not let users enter the height in feet as well. This sample always present the value in meters but allows users to enter the value in feet and automatically convert it correctly.
handleCommand: function (commandId, properties, sequence) {
switch (commandId) {
case 'SpinnerCommand':
if (properties.ChangeType == "manual" && properties.Unit == "feet") {
this.newSpinnerValue = properties.Value * 0.3048;
this.newSpinnerUnit = "meter";
RefreshCommandUI();
}
return true;
case 'SpinnerQueryCommand':
if (this.newSpinnerValue != null) {
properties.Unit = this.newSpinnerUnit;
properties.Value = this.newSpinnerValue;
this.newSpinnerUnit = null;
this.newSpinnerValue = null;
}
return;
}
return false;
},
newSpinnerValue: null,
newSpinnerUnit: null,
When a user changes the value the SpinnerCommand command is sent to handleCommand. Here I check if it is a manual entry and if the Unit is set to feet. If so the routine converts the value to meters and stores that in two Page Component local variables before it refreshes the command UI. When the Command UI is refreshed the query command for the Spinner control is fired and in that routine I see that the local variable is set and then update the Spinner control with the new value and unit.
Summary
The Spinner control is a very handy control which also gives you a really good way to work with number values and optionally units. This was the last post of the “easy” controls. Next up is the DropDown control which is used to create drop-downs and menu controls.